Build agents by capability

An Agents API agent gets exactly the tools you list. This page builds up one agent at a time, each adding a capability: chat, research, knowledge, data work and media. Every example creates the agent with your API key; start sessions and send messages as the Agents API shows.

POST /v1/agents

Everything an agent does is Dexto Cloud usage of your key’s Cloud project: it is paid from your organization’s credits and counts toward the monthly spend limits on the project, the key and the agent. A refused tool call (insufficient_credits or spend_limit_reached) comes back to the model as an error and the run goes on.

1. Chat

A model and instructions, no tools.

{
    "name": "Acme concierge",
    "instructions": "You answer questions about Acme's products. Be brief and friendly."
}

curl -X POST https://api.dexto.ai/v1/agents \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme concierge","instructions":"You answer questions about Acme'"'"'s products. Be brief and friendly."}'

With the Cloud SDK, inside a Site, Worker or Function you built in Dexto:

import { createCapabilitiesClient } from "@dexto-cloudflare/capabilities-client";

const dexto = createCapabilitiesClient({ apiKey: env.DEXTO_API_KEY });
const agent = await dexto.agents.create({
    name: "Acme concierge",
    instructions: "You answer questions about Acme's products. Be brief and friendly.",
    tools: [],
});

Cost: the model’s tokens at its price, per run. Metered as model usage.

2. Research: search and read the web

Add web_search and web_fetch, so the agent finds pages and reads them.

{
    "name": "Market researcher",
    "instructions": "Research the question on the web. Cite every source by URL.",
    "tools": [{ "type": "web_search" }, { "type": "web_fetch" }]
}

curl -X POST https://api.dexto.ai/v1/agents \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Market researcher","instructions":"Research the question on the web. Cite every source by URL.","tools":[{"type":"web_search"},{"type":"web_fetch"}]}'

Cost: model tokens, plus each search (about $0.019 for 8 results) and each fetched page (about $0.00125), at the provider’s cost plus 25%. Metered as Cloud requests; see Search and fetch.

3. Knowledge: answer from your files

Upload your documents to the project’s files under a prefix, then give the agent a read-only files tool on that prefix. It gets glob_files and search_files to find documents, and read_file and read_media_file to read them, and nothing else. It sees the prefix as /, so knowledge/returns-policy.md is /returns-policy.md to it.

curl -X POST "https://api.dexto.ai/v1/files?path=knowledge/returns-policy.md" \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @returns-policy.md

{
    "name": "Policy assistant",
    "instructions": "Answer only from the documents under knowledge/. Say which document you used.",
    "tools": [{ "type": "files", "prefix": "knowledge/", "read_only": true }]
}

curl -X POST https://api.dexto.ai/v1/agents \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Policy assistant","instructions":"Answer only from the documents under knowledge/. Say which document you used.","tools":[{"type":"files","prefix":"knowledge/","read_only":true}]}'

Cost: model tokens, plus storage of your files: $0.000625 per GB a day, charged to the project once a day. Reading and searching are free. Metered as Cloud storage; see Files.

4. Data: work on files in a sandbox

Give the agent a files tool and a sandbox. Its sandbox tool then copies files into the sandbox (copy_from_files), runs code on them, and saves results back (copy_to_files), all within the files tool’s prefix. The files tool’s own tools (glob_files, read_file, write_file, edit_file and the rest) work on the project’s files directly, for small changes that need no sandbox.

{
    "name": "Data analyst",
    "instructions": "Copy the CSVs under data/ into /workspace/data, analyse them with Python, and save a report to data/reports/.",
    "tools": [
        { "type": "files", "prefix": "data/" },
        { "type": "sandbox", "sandbox": { "type": "session", "size": "large" } }
    ]
}

curl -X POST https://api.dexto.ai/v1/agents \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Data analyst","instructions":"Copy the CSVs under data/ into /workspace/data, analyse them with Python, and save a report to data/reports/.","tools":[{"type":"files","prefix":"data/"},{"type":"sandbox","sandbox":{"type":"session","size":"large"}}]}'

Your own code can do the same copies with /v1/sandboxes/{id}/files/import and /files/export.

Cost: model tokens, the sandbox’s running time (paused when idle, so idle time is free), and storage of the files the agent saves. Copies are free. Metered as compute and Cloud storage.

5. Creative: generate media and keep it

Give the agent a media tool and a files tool. It lists media models, estimates a generation and generates it; with the files tool, its generate call takes save_to, so what it makes is saved in the project’s files under the files tool’s prefix, and each saved output comes back with the exact file_path it was saved at. Each output also comes back with a url, a download link the agent can share right away. Outputs are deleted 24 hours after they are made; the saved files stay until you delete them.

{
    "name": "Ad studio",
    "instructions": "Make product images for the brief. Estimate before generating, stay under $1 per brief, and save every image under ads/<brief name>/.",
    "tools": [
        { "type": "media", "kinds": ["image"], "require_approval": true },
        { "type": "files", "prefix": "ads/" }
    ]
}

curl -X POST https://api.dexto.ai/v1/agents \
  -H "Authorization: Bearer $DEXTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ad studio","instructions":"Make product images for the brief. Estimate before generating, stay under $1 per brief, and save every image under ads/<brief name>/.","tools":[{"type":"media","kinds":["image"],"require_approval":true},{"type":"files","prefix":"ads/"}]}'

kinds limits the agent to image, audio or video, all three when left out, and require_approval pauses each generation for your OK. A read-only files tool can’t save, and a save_to outside its prefix is refused. To hand a saved image to someone, the agent’s share_file creates a download link that lasts up to a day. Read what the agent made with GET /v1/files?prefix=ads/; your own code can save outputs the same way with save_to.

Cost: model tokens, each generation at the price its estimate shows (see Media), and storage of the saved images. Metered as media and Cloud storage.

Combine them

Tools add up: a research agent with a files tool can save what it found; a data agent with web_fetch can pull a dataset first. The Cloud SDK types every tool kind on this page from the API’s OpenAPI document.