DoubleX AgentesDocs

Referência da API › Recursos

Conversas

Converse com agentes em streaming, continue conversas, leia o histórico e cancele execuções.

Uma conversa (task) guarda as mensagens trocadas com um agente. Cada mensagem nova gera uma resposta em streaming, e o histórico fica no servidor: para continuar, você manda só a mensagem nova e o ID da conversa. As conversas aparecem na tela Tarefas do app.

POST/api/agents/{id}/chat#

Manda uma mensagem ao agente e devolve a resposta em NDJSON. Basta poder ver o agente.

CampoTipoDescrição
messagestring, 1 a 100.000Obrigatório. A mensagem.
taskIdstringContinua uma conversa existente do mesmo agente. Sem ele, cria uma conversa nova.
curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \
  -H "Authorization: Bearer $DOUBLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "O que os concorrentes lançaram esta semana?"}'
NDJSON
{"type":"task","taskId":"task_5d2c9a3e1f07"}
{"type":"tool_start","id":"toolu_01","name":"pesquisar_web","label":"Pesquisando na web"}
{"type":"tool_end","id":"toolu_01","ok":true}
{"type":"text","delta":"Encontrei 3 lançamentos. "}
{"type":"text","delta":"O mais relevante é…"}
{"type":"done","status":"completed"}

Eventos do streaming#

typeCamposQuando
tasktaskIdPrimeiro evento: o ID da conversa criada ou continuada. Guarde-o.
textdeltaUm pedaço do texto da resposta. Junte os delta na ordem.
thinkingdeltaUm pedaço do raciocínio do modelo, quando o modelo o expõe.
tool_startid, name, labelO agente começou a usar uma ferramenta. label é um nome legível.
tool_endid, okA ferramenta terminou. ok: false se falhou.
noticemessageAviso que não interrompe: conector que precisa ser reconectado, modelo reserva usado, conversa cancelada.
errormessageFalha que interrompe a resposta.
donestatusÚltimo evento: completed ou failed.

Trate sempre o fim pelo evento done. Alguns problemas aparecem só no streaming, com status HTTP 200, antes mesmo do evento task: créditos esgotados, modelo sem chave configurada ou conversa ainda respondendo à mensagem anterior. Nesses casos você recebe error seguido de done com failed.

NDJSON
{"type":"error","message":"Os créditos da organização acabaram."}
{"type":"done","status":"failed"}

Continuar uma conversa#

Terminal
curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \
  -H "Authorization: Bearer $DOUBLEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Monte uma tabela comparando com os nossos produtos", "taskId": "task_5d2c9a3e1f07"}'

Uma conversa responde uma mensagem por vez. Para trabalhar em paralelo, abra conversas diferentes.

Se a conexão cair#

Fechar a conexão não para o agente: ele termina o trabalho no servidor e salva a resposta na conversa. Para recuperar o resultado, use GET /api/tasks/{id}. Para parar de verdade, use cancel.

GET/api/tasks#

Lista as conversas que você pode ver, das mais novas para as mais antigas, sem as mensagens.

QueryDescrição
agentIdSó as conversas de um agente.
statusprocessing, completed ou failed.
sourceOrigem: chat, trigger, webhook ou subagent.
curl "https://doublex.ai/api/tasks?agentId=agt_8f3a2b1c9d0e&status=failed" -H "Authorization: Bearer $DOUBLEX_API_KEY"
JSON
{
  "tasks": [
    {
      "id": "task_5d2c9a3e1f07",
      "agentId": "agt_8f3a2b1c9d0e",
      "agentName": "Analista de CRM",
      "title": "Lançamentos dos concorrentes",
      "source": "chat",
      "status": "completed",
      "unread": false,
      "usage": { "inputTokens": 18234, "outputTokens": 912, "cacheReadTokens": 12000, "costUsd": 0.041 },
      "createdAt": "2026-10-27T13:01:12.000Z",
      "updatedAt": "2026-10-27T13:01:58.000Z"
    }
  ]
}

Conversas que falharam trazem error e, quando for o caso, errorCode: cancelled (interrompida) ou refused (o modelo recusou). Conversas criadas por gatilho trazem triggerId.

GET/api/tasks/{id}#

Devolve a conversa, as mensagens e se o agente ainda está trabalhando.

JSON
{
  "task": { "id": "task_5d2c9a3e1f07", "status": "completed", "...": "..." },
  "items": [
    { "kind": "user", "text": "O que os concorrentes lançaram esta semana?" },
    { "kind": "tool", "id": "toolu_01", "name": "pesquisar_web", "ok": true },
    { "kind": "assistant", "text": "Encontrei 3 lançamentos…" }
  ],
  "running": false
}

items[].kind pode ser user, assistant, thinking ou tool. Para esperar o fim de uma conversa sem streaming, consulte esta rota até running ser false.

PATCH/api/tasks/{id}#

Renomeia a conversa ou muda a marcação de não lida.

CampoTipo
titlestring, 1 a 120
unreadboolean

Resposta: { "ok": true }.

POST/api/tasks/{id}/cancel#

Interrompe o agente. A conversa termina como failed, com errorCode: "cancelled". O que já foi processado é cobrado.

curl -X POST https://doublex.ai/api/tasks/task_5d2c9a3e1f07/cancel -H "Authorization: Bearer $DOUBLEX_API_KEY"

Resposta: { "cancelled": true }. Erro 409 se a conversa não está rodando.

DELETE/api/tasks/{id}#

Apaga a conversa e o histórico dela. Resposta: { "ok": true }.