Referencia de la API › Recursos
Conversaciones
Conversa con agentes en streaming, continúa conversaciones, lee el historial y cancela ejecuciones.
Una conversación (task) guarda los mensajes intercambiados con un agente. Cada mensaje nuevo genera una respuesta en streaming, y el historial queda en el servidor: para continuar, envías solo el mensaje nuevo y el ID de la conversación. Las conversaciones aparecen en la pantalla Tareas de la app.
POST/api/agents/{id}/chat#
Envía un mensaje al agente y devuelve la respuesta en NDJSON. Basta con poder ver el agente.
| Campo | Tipo | Descripción |
|---|---|---|
message | string, de 1 a 100.000 | Obligatorio. El mensaje. |
taskId | string | Continúa una conversación existente del mismo agente. Sin él, crea una conversación nueva. |
curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "¿Qué lanzaron los competidores esta semana?"}'{"type":"task","taskId":"task_5d2c9a3e1f07"}
{"type":"tool_start","id":"toolu_01","name":"pesquisar_web","label":"Buscando en la web"}
{"type":"tool_end","id":"toolu_01","ok":true}
{"type":"text","delta":"Encontré 3 lanzamientos. "}
{"type":"text","delta":"El más relevante es…"}
{"type":"done","status":"completed"}Eventos del streaming#
type | Campos | Cuándo |
|---|---|---|
task | taskId | Primer evento: el ID de la conversación creada o continuada. Guárdalo. |
text | delta | Un fragmento del texto de la respuesta. Une los delta en orden. |
thinking | delta | Un fragmento del razonamiento del modelo, cuando el modelo lo expone. |
tool_start | id, name, label | El agente empezó a usar una herramienta. label es un nombre legible. |
tool_end | id, ok | La herramienta terminó. ok: false si falló. |
notice | message | Aviso que no interrumpe: conector que hay que volver a conectar, modelo de respaldo usado, conversación cancelada. |
error | message | Falla que interrumpe la respuesta. |
done | status | Último evento: completed o failed. |
Detecta siempre el final por el evento done. Algunos problemas aparecen solo en el streaming, con estado HTTP 200, incluso antes del evento task: créditos agotados, modelo sin clave configurada o conversación que todavía responde al mensaje anterior. En esos casos recibes error seguido de done con failed.
{"type":"error","message":"La organización se quedó sin créditos."}
{"type":"done","status":"failed"}Continuar una conversación#
curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message": "Arma una tabla que compare con nuestros productos", "taskId": "task_5d2c9a3e1f07"}'Una conversación responde un mensaje a la vez. Para trabajar en paralelo, abre conversaciones distintas.
Si se cae la conexión#
Cerrar la conexión no detiene al agente: termina el trabajo en el servidor y guarda la respuesta en la conversación. Para recuperar el resultado, usa GET /api/tasks/{id}. Para detenerlo de verdad, usa cancel.
GET/api/tasks#
Lista las conversaciones que puedes ver, de las más nuevas a las más antiguas, sin los mensajes.
| Query | Descripción |
|---|---|
agentId | Solo las conversaciones de un agente. |
status | processing, completed o failed. |
source | Origen: chat, trigger, webhook o 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": "Lanzamientos de los competidores",
"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"
}
]
}Las conversaciones que fallaron traen error y, cuando corresponde, errorCode: cancelled (interrumpida) o refused (el modelo se negó). Las conversaciones creadas por un disparador traen triggerId.
GET/api/tasks/{id}#
Devuelve la conversación, los mensajes y si el agente todavía está trabajando.
{
"task": { "id": "task_5d2c9a3e1f07", "status": "completed", "...": "..." },
"items": [
{ "kind": "user", "text": "¿Qué lanzaron los competidores esta semana?" },
{ "kind": "tool", "id": "toolu_01", "name": "pesquisar_web", "ok": true },
{ "kind": "assistant", "text": "Encontré 3 lanzamientos…" }
],
"running": false
}items[].kind puede ser user, assistant, thinking o tool. Para esperar el final de una conversación sin streaming, consulta esta ruta hasta que running sea false.
PATCH/api/tasks/{id}#
Cambia el nombre de la conversación o su marca de no leída.
| Campo | Tipo |
|---|---|
title | string, de 1 a 120 |
unread | boolean |
Respuesta: { "ok": true }.
POST/api/tasks/{id}/cancel#
Interrumpe al agente. La conversación termina como failed, con errorCode: "cancelled". Lo que ya se procesó se cobra.
curl -X POST https://doublex.ai/api/tasks/task_5d2c9a3e1f07/cancel -H "Authorization: Bearer $DOUBLEX_API_KEY"Respuesta: { "cancelled": true }. Error 409 si la conversación no se está ejecutando.
DELETE/api/tasks/{id}#
Borra la conversación y su historial. Respuesta: { "ok": true }.