Integre um agente publicado em qualquer sistema

Todo agente publicado expõe uma API HTTP própria. Gere a chave na tela de publicação do agente (aba Publicar → Publicação por API) e use os dois endpoints abaixo para consultar o agente e conversar com ele.

Autenticação

Todas as chamadas exigem o header X-Agent-API-Key com a chave gerada para o agente. Trate essa chave como uma credencial de produção: ela dá acesso direto à execução do agente e consome os créditos da sua empresa.

X-Agent-API-Key: dda_live_…

A chave só pode ser gerada depois que o agente tem uma versão publicada.
Gerar uma nova chave não invalida as anteriores; guarde o valor completo — ele é exibido uma única vez.
Sem o header (ou com chave inválida) a API responde 401 Unauthorized.

Consultar o agente

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

Retorna os metadados da versão publicada: nome, modelo, número da versão, saudação inicial e ferramentas ativas. Use para validar a integração antes da primeira execução.

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

Executar uma conversa

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

Envia uma mensagem para o agente e recebe a resposta completa, incluindo tokens consumidos, trechos de contexto recuperados (RAG) e ferramentas executadas.

curl -X POST "https://api.deepagents.com.br/api/agent-api/agents/SEU_AGENT_ID/execute" \
  -H "Content-Type: application/json" \
  -H "X-Agent-API-Key: SUA_CHAVE_DE_API" \
  -d '{
    "conversationId": "conversa-123",
    "actorName": "Cliente",
    "message": "Olá! Pode me ajudar?",
    "history": []
  }'

conversationId (obrigatório): identificador da conversa no seu sistema — agrupa as interações no painel do agente.
message (obrigatório): a mensagem do usuário.
history (opcional): turnos anteriores no formato [{"role":"user","content":"…"},{"role":"assistant","content":"…"}].
actorName e source (opcionais): nome de quem fala e origem da conversa, exibidos nas interações.
visualAttachments (opcional): imagens em data URL ({"fileName","contentType","dataUrl"}) — exige a ferramenta de visão ativa e um modelo com capacidade de visão.

Resposta da execução

{
  "agentId": "…",
  "agentVersionId": "…",
  "agentVersionNumber": 3,
  "agentName": "Agente de atendimento",
  "provider": "openrouter",
  "model": "openai/gpt-4.1-mini",
  "outputText": "Claro! Como posso ajudar?",
  "inputTokens": 320,
  "outputTokens": 45,
  "totalTokens": 365,
  "executedAtUtc": "2026-07-22T18:00:00Z",
  "retrievedContextChunks": [],
  "toolExecutions": []
}

Erros e limites

400 Bad Request — payload inválido (por exemplo, mensagem vazia). O corpo traz {"message":"…"} com o motivo.
401 Unauthorized — header X-Agent-API-Key ausente ou chave inválida para o agente.
429 Too Many Requests — limite de chamadas por chave excedido. Aguarde o intervalo indicado antes de tentar novamente.
502 Bad Gateway — falha temporária no provedor de IA. Repita a chamada com backoff.
As execuções por API respeitam a cota de créditos configurada na tela de publicação (Cotas de créditos → Cota da API key).