Skip to main content
An agent is a saved setup on a model you already launched. Create and edit it in the dashboard, or delete it with DELETE /v1/agent/{agent_id}. Run it from the API. Request tools do not add capabilities — tools, MCP, knowledge bases, and the system prompt always come from the stored agent.

Deploy in the dashboard

Open Deploy agent (optional ?model_id=).
1

Setup

Display name and the deployed model. The agent calls that model through /v1/chat/completions.
2

Instructions

System prompt inserted ahead of the conversation.
3

Capabilities

Built-in tools, knowledge bases, MCP servers (name, url, optional headers). Optional: compress context, max steps (1–500), store requests, extra JSON config.
4

Review

Confirm and deploy.
Built-in tools: web_search, http_fetch (public URLs only), run_python (sandbox), calculator, delegate_task. Knowledge bases add search_knowledge_base and retrieve_knowledge_base_content automatically — they are not in the tool picker. MCP uses streamable_http or sse. Stdio MCP is off unless the deployment explicitly allows it. After deploy, tabs: Overview, Usage, Prompt, Tools, Knowledge, MCP, Runtime, Data. Try the agent playground.

Run an agent

POST /v1/agent/{agent_id}/run returns text/event-stream. The API key must be allowed to call the agent’s model. Limit: 20 runs/minute by default.
The SDK accepts strings, dicts, or AgentMessage objects and fills threadId / runId when omitted. JSON uses AG-UI camelCase. The response header X-Run-Id is the id to resume with. Closing the connection does not stop the run. state may override max_steps and compress_context for that run only.

Resume a run

A run keeps executing after the client disconnects. Use the same runId to pick it up on the server that is still running it. When the run ends, the in-memory copy is dropped. Events are kept only in the data-store record saved for that agent or model, and only if Store requests is on. GET and the resume stream read that record. A client still connected when the run ends receives the remaining events and the stream closes. after is the last seq you already have. Each event in the JSON snapshot includes seq. There is no second event log: resume follows the in-process run while it is still going, then the data-store row written when the run finishes. With store requests off, a finished run is gone.
Posting /run again with the same runId attaches to a run that is still going, or replays it from the data store when one was saved. It does not start a second execution, and it does not count as another agent run for the rate limit.

Events

Billing and data

Inner model calls go through /v1/chat/completions, so model usage and rate limits apply. Enable Store requests on the agent to keep runs on the Data tab.

Next steps

Knowledge bases · Playground · Integrations (call the agent from your backend; do not expose keys in the browser)