Integra un agente publicado en cualquier sistema

Todo agente publicado expone una API HTTP propia. Genera la clave en la pantalla de publicación del agente (pestaña Publicar → Publicación por API) y usa los dos endpoints abajo para consultar el agente y conversar con él.

Autenticación

Todas las llamadas requieren el header X-Agent-API-Key con la clave generada para el agente. Trata esta clave como una credencial de producción: da acceso directo a la ejecución del agente y consume los créditos de tu empresa.

X-Agent-API-Key: dda_live_…

La clave solo puede generarse después de que el agente tenga una versión publicada.
Generar una nueva clave no invalida las anteriores; guarda el valor completo — se muestra una única vez.
Sin el header (o con clave inválida) la API responde 401 Unauthorized.

Consultar el agente

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

Devuelve los metadatos de la versión publicada: nombre, modelo, número de versión, saludo inicial y herramientas activas. Úsalo para validar la integración antes de la primera ejecución.

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

Ejecutar una conversación

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

Envía un mensaje al agente y recibe la respuesta completa, incluyendo tokens consumidos, fragmentos de contexto recuperados (RAG) y herramientas ejecutadas.

curl -X POST "https://api.deepagents.com.br/api/agent-api/agents/TU_AGENT_ID/execute" \
  -H "Content-Type: application/json" \
  -H "X-Agent-API-Key: TU_CLAVE_DE_API" \
  -d '{
    "conversationId": "conversacion-123",
    "actorName": "Cliente",
    "message": "¡Hola! ¿Puedes ayudarme?",
    "history": []
  }'

conversationId (obligatorio): identificador de la conversación en tu sistema — agrupa las interacciones en el panel del agente.
message (obligatorio): el mensaje del usuario.
history (opcional): turnos anteriores en el formato [{"role":"user","content":"…"},{"role":"assistant","content":"…"}].
actorName y source (opcionales): nombre de quien habla y origen de la conversación, mostrados en las interacciones.
visualAttachments (opcional): imágenes en data URL ({"fileName","contentType","dataUrl"}) — requiere la herramienta de visión activa y un modelo con capacidad de visión.

Respuesta de la ejecución

{
  "agentId": "…",
  "agentVersionId": "…",
  "agentVersionNumber": 3,
  "agentName": "Agente de atención",
  "provider": "openrouter",
  "model": "openai/gpt-4.1-mini",
  "outputText": "¡Claro! ¿Cómo puedo ayudarte?",
  "inputTokens": 320,
  "outputTokens": 45,
  "totalTokens": 365,
  "executedAtUtc": "2026-07-22T18:00:00Z",
  "retrievedContextChunks": [],
  "toolExecutions": []
}

Errores y límites

400 Bad Request — payload inválido (por ejemplo, mensaje vacío). El cuerpo trae {"message":"…"} con el motivo.
401 Unauthorized — header X-Agent-API-Key ausente o clave inválida para el agente.
429 Too Many Requests — límite de llamadas por clave excedido. Espera el intervalo indicado antes de reintentar.
502 Bad Gateway — falla temporal en el proveedor de IA. Repite la llamada con backoff.
Las ejecuciones por API respetan la cuota de créditos configurada en la pantalla de publicación (Cuotas de créditos → Cuota de la API key).