Back to agents

Integrate a published agent into any system

Every published agent exposes its own HTTP API. Generate the key on the agent's publish screen (Publish tab → API publishing) and use the two endpoints below to query the agent and talk to it.

Authentication

Every call requires the X-Agent-API-Key header with the key generated for the agent. Treat this key as a production credential: it gives direct access to running the agent and consumes your company's credits.

X-Agent-API-Key: dda_live_…
  • The key can only be generated once the agent has a published version.
  • Generating a new key does not invalidate previous ones; save the full value — it is shown only once.
  • Without the header (or with an invalid key) the API responds with 401 Unauthorized.

Query the agent

GEThttps://api.deepagents.com.br/api/agent-api/agents/{agentId}

Returns the published version's metadata: name, model, version number, initial greeting and enabled tools. Use it to validate the integration before the first execution.

curl -X GET "https://api.deepagents.com.br/api/agent-api/agents/YOUR_AGENT_ID" \
  -H "X-Agent-API-Key: YOUR_API_KEY"

Run a conversation

POSThttps://api.deepagents.com.br/api/agent-api/agents/{agentId}/execute

Sends a message to the agent and returns the full response, including tokens consumed, retrieved context chunks (RAG) and tool executions.

curl -X POST "https://api.deepagents.com.br/api/agent-api/agents/YOUR_AGENT_ID/execute" \
  -H "Content-Type: application/json" \
  -H "X-Agent-API-Key: YOUR_API_KEY" \
  -d '{
    "conversationId": "conversation-123",
    "actorName": "Customer",
    "message": "Hi! Can you help me?",
    "history": []
  }'
  • conversationId (required): the conversation identifier in your system — groups interactions in the agent's panel.
  • message (required): the user's message.
  • history (optional): previous turns in the format [{"role":"user","content":"…"},{"role":"assistant","content":"…"}].
  • actorName and source (optional): the speaker's name and the conversation's source, shown in interactions.
  • visualAttachments (optional): images as data URLs ({"fileName","contentType","dataUrl"}) — requires the vision tool enabled and a vision-capable model.

Execution response

{
  "agentId": "…",
  "agentVersionId": "…",
  "agentVersionNumber": 3,
  "agentName": "Support agent",
  "provider": "openrouter",
  "model": "openai/gpt-4.1-mini",
  "outputText": "Of course! How can I help?",
  "inputTokens": 320,
  "outputTokens": 45,
  "totalTokens": 365,
  "executedAtUtc": "2026-07-22T18:00:00Z",
  "retrievedContextChunks": [],
  "toolExecutions": []
}

Errors and limits

  • 400 Bad Request — invalid payload (e.g. an empty message). The body includes {"message":"…"} with the reason.
  • 401 Unauthorized — missing X-Agent-API-Key header or invalid key for the agent.
  • 429 Too Many Requests — per-key call limit exceeded. Wait for the indicated interval before retrying.
  • 502 Bad Gateway — temporary failure at the AI provider. Retry the call with backoff.
  • API executions respect the credit quota configured on the publish screen (Credit quotas → API key quota).