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.
| Campo | Tipo | Descrição |
|---|---|---|
message | string, 1 a 100.000 | Obrigatório. A mensagem. |
taskId | string | Continua 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?"}'{"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#
type | Campos | Quando |
|---|---|---|
task | taskId | Primeiro evento: o ID da conversa criada ou continuada. Guarde-o. |
text | delta | Um pedaço do texto da resposta. Junte os delta na ordem. |
thinking | delta | Um pedaço do raciocínio do modelo, quando o modelo o expõe. |
tool_start | id, name, label | O agente começou a usar uma ferramenta. label é um nome legível. |
tool_end | id, ok | A ferramenta terminou. ok: false se falhou. |
notice | message | Aviso que não interrompe: conector que precisa ser reconectado, modelo reserva usado, conversa cancelada. |
error | message | Falha que interrompe a resposta. |
done | status | Ú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.
{"type":"error","message":"Os créditos da organização acabaram."}
{"type":"done","status":"failed"}Continuar uma conversa#
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.
| Query | Descrição |
|---|---|
agentId | Só as conversas de um agente. |
status | processing, completed ou failed. |
source | Origem: chat, trigger, webhook ou subagent. |
curl "https://doublex.ai/api/tasks?agentId=agt_8f3a2b1c9d0e&status=failed" -H "Authorization: Bearer $DOUBLEX_API_KEY"{
"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.
{
"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.
| Campo | Tipo |
|---|---|
title | string, 1 a 120 |
unread | boolean |
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 }.