DoubleX AgentesDocs

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.

CampoTipoDescripción
messagestring, de 1 a 100.000Obligatorio. El mensaje.
taskIdstringContinú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?"}'
NDJSON
{"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#

typeCamposCuándo
tasktaskIdPrimer evento: el ID de la conversación creada o continuada. Guárdalo.
textdeltaUn fragmento del texto de la respuesta. Une los delta en orden.
thinkingdeltaUn fragmento del razonamiento del modelo, cuando el modelo lo expone.
tool_startid, name, labelEl agente empezó a usar una herramienta. label es un nombre legible.
tool_endid, okLa herramienta terminó. ok: false si falló.
noticemessageAviso que no interrumpe: conector que hay que volver a conectar, modelo de respaldo usado, conversación cancelada.
errormessageFalla que interrumpe la respuesta.
donestatusÚ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.

NDJSON
{"type":"error","message":"La organización se quedó sin créditos."}
{"type":"done","status":"failed"}

Continuar una conversación#

Terminal
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.

QueryDescripción
agentIdSolo las conversaciones de un agente.
statusprocessing, completed o failed.
sourceOrigen: chat, trigger, webhook o 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": "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.

JSON
{
  "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.

CampoTipo
titlestring, de 1 a 120
unreadboolean

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 }.