Referencia de la API › Recursos
Agentes
Crea, lista, configura y borra agentes.
El objeto Agent#
{
"id": "agt_8f3a2b1c9d0e",
"name": "Analista de CRM",
"description": "Responde preguntas sobre el embudo de ventas",
"emoji": "📊",
"color": "azul",
"avatar": "05",
"department": "Ventas",
"provider": "openrouter",
"model": "openrouter/auto",
"effort": "medium",
"instructions": "Eres el analista de CRM del equipo de ventas…",
"abilities": { "webSearch": true, "webFetch": true, "files": true, "scheduling": true, "selfEdit": false },
"skillIds": ["skl_3e8f1a2b4c5d"],
"connectorIds": ["con_1f3e5d7c9b2a"],
"knowledgeIds": ["kno_2c4e6a8b0d1f"],
"subagentIds": [],
"starterPrompts": ["¿Cómo va el embudo de este mes?"],
"ownerId": "usr_1a2b3c4d5e6f",
"budget": { "monthlyCredits": 500 },
"scope": "team",
"teamId": "team_9c8b7a6d5e4f",
"createdAt": "2026-10-21T12:00:00.000Z",
"updatedAt": "2026-10-27T09:30:00.000Z"
}| Campo | Descripción |
|---|---|
provider, model | Modelo del agente. openrouter + openrouter/auto es DoubleX Auto, que elige el modelo en cada mensaje. |
effort | Esfuerzo de razonamiento: low, medium o high. |
abilities | Habilidades nativas: búsqueda en la web, lectura de páginas, archivos en la computadora del agente, disparadores creados por el propio agente y edición de sus propias instrucciones. |
skillIds, connectorIds, knowledgeIds | Skills, conectores y documentos del Brain que usa este agente. |
subagentIds | Equipo directo: los otros agentes que este prefiere consultar. Puede consultar a cualquier agente que ve la persona que conversa y dejarles recados (consulta Agentes que trabajan juntos). |
ownerId | Responsable del agente: puede editarlo y recibe por correo los avisos de presupuesto. |
budget | Presupuesto mensual en créditos ({ "monthlyCredits": 500 }); ausente = sin límite. Consulta Presupuesto. |
color, avatar | Color y robot del agente. Consulta Crear. |
scope, teamId | Quién ve y usa el agente. Consulta Alcances. |
GET/api/agents#
Lista los agentes que puedes ver. Cada elemento también trae canEdit (puedes editarlo), taskCount (conversaciones que ves), triggerCount (disparadores activados) y lastTaskAt.
| Query | Descripción |
|---|---|
mine=1 | Solo tus agentes y los compartidos contigo. Sin esto, los administradores reciben todos los agentes de la organización. |
curl "https://doublex.ai/api/agents?mine=1" -H "Authorization: Bearer $DOUBLEX_API_KEY"Respuesta: { "agents": [Agent, ...] }.
POST/api/agents#
Crea un agente en el alcance Personal, contigo como dueño. Para compartirlo, usa la pantalla del agente.
| Campo | Tipo | Descripción |
|---|---|---|
name | string, de 1 a 60 | Obligatorio. |
description | string, hasta 300 | |
instructions | string, hasta 20.000 | Qué hace el agente y cómo. |
emoji | string | Predeterminado: 🤖. |
color | string | Uno de los colores predefinidos (roxo, indigo, azul, ciano, turquesa, verde, lima, amarelo, laranja, vermelho, rosa, grafite) o un hex #rrggbb. Predeterminado: roxo. |
avatar | string | Robot del agente, de "01" a "26". Sin él, el agente usa el robot predeterminado. El robot siempre aparece en el color del agente. |
curl -X POST https://doublex.ai/api/agents \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Analista de CRM",
"description": "Responde preguntas sobre el embudo de ventas",
"instructions": "Eres el analista de CRM del equipo de ventas. Usa HubSpot para responder.",
"emoji": "📊",
"color": "azul"
}'Respuesta 201: { "agent": Agent }.
El agente se crea con el modelo predeterminado de la organización, esfuerzo medium y todas las habilidades activadas. Para elegir modelo, esfuerzo, skills y conectores, haz un PATCH justo después.
A partir de una plantilla. Envía solo { "templateKey": "<clave>" }. Claves disponibles: assistente, briefing-diario, pesquisa-concorrentes, gerador-leads, redator-conteudo, analista-dados, triagem-suporte y recrutador.
GET/api/agents/{id}#
Devuelve el agente, sus conversaciones que puedes ver (sin los mensajes), los disparadores y si puedes editarlo.
{ "agent": { "...": "..." }, "tasks": [], "triggers": [], "canEdit": true }Error 404 si el agente no existe o no puedes verlo.
PATCH/api/agents/{id}#
Cambia el agente. Envía solo los campos que cambian. Requiere permiso de edición.
| Campo | Tipo | Descripción |
|---|---|---|
name, description, emoji, color, avatar | Como en la creación. | |
department | string, hasta 80 | Área del agente (agrupa la barra lateral de la app). |
provider | string | anthropic, openai, google, deepseek, xai, groq, mistral, openrouter, ollama o custom. |
model | string | ID del modelo en el proveedor. Para DoubleX Auto: provider: "openrouter", model: "openrouter/auto". |
effort | low, medium, high | Esfuerzo de razonamiento. |
instructions | string, hasta 20.000 | |
abilities | objeto | Los cinco campos: webSearch, webFetch, files, scheduling, selfEdit. |
skillIds, connectorIds, knowledgeIds, subagentIds | array de IDs | Reemplazan la lista completa. |
starterPrompts | array, hasta 8 | Sugerencias que aparecen en el chat vacío (hasta 200 caracteres cada una). |
ownerId | string | Cambia el responsable. Debe ser alguien de la organización; pasa a poder editar el agente. En un agente personal, el agente pasa a ser solo suyo. |
budget | objeto o null | { "monthlyCredits": 500 } define el límite del mes (entero desde 1); null quita el límite. |
curl -X PATCH https://doublex.ai/api/agents/agt_8f3a2b1c9d0e \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "anthropic",
"model": "claude-sonnet-5-5",
"effort": "high",
"skillIds": ["skl_3e8f1a2b4c5d"],
"connectorIds": ["con_1f3e5d7c9b2a"]
}'Respuesta: { "agent": Agent }. Errores: 400 con un ownerId de fuera de la organización; 403 si ves el agente pero no puedes editarlo; 404 si no lo ves.
Presupuesto del agente#
Cada agente puede tener un límite de créditos por mes (el mes calendario, en la zona horaria de São Paulo). El consumo de las conversaciones, rutinas y webhooks del agente cuenta para él; cuando otro agente lo consulta, ese gasto también entra en su presupuesto.
- Al pasar del 80% y al alcanzar el límite, el responsable (
ownerId) recibe un correo, una vez por mes. - Alcanzado el límite, la conversación que ya empezó termina, pero la siguiente responde con error y las rutinas y webhooks esperan (
402 agent_budget) hasta que cambie el mes o suba el límite. - El presupuesto solo vale en los planes con créditos de DoubleX.
GET/api/agents/{id}/governance#
Responsable, límite y gasto del mes. Si puedes editar el agente, recibes también members, las personas de la organización que pueden ser responsables.
{
"platform": true,
"period": "2026-11",
"spent": 312.4,
"monthlyCredits": 500,
"owner": { "id": "usr_1a2b3c4d5e6f", "name": "Ana Lima", "email": "[email protected]" },
"canEdit": true,
"members": [{ "id": "usr_1a2b3c4d5e6f", "name": "Ana Lima", "email": "[email protected]" }]
}Agentes que trabajan juntos#
Cada agente conoce a los otros agentes que puede ver la persona que conversa (en rutinas y webhooks, el dueño del agente) y trabaja con ellos de dos formas:
- Consultar y esperar la respuesta: el agente pasa la tarea con todo el contexto y usa la respuesta del colega en la suya.
- Dejar un recado: el colega trabaja en segundo plano y el resultado aparece en Tareas, como conversación con origen
subagent. Hasta 3 recados por mensaje.
El colega se ejecuta con sus propias instrucciones, conocimiento y conectores, siempre con el acceso de la persona que conversa: nunca alcanza un agente o dato que esa persona no ve. Los agentes en subagentIds son el equipo directo, que el agente prefiere. La delegación llega hasta dos niveles (un colega puede consultar a otro, y ahí se detiene).
DELETE/api/agents/{id}#
Borra el agente y, con él, las conversaciones, los disparadores y los archivos de su computadora. También sale de la lista de subagentes de otros agentes. Requiere permiso de edición.
Respuesta: { "ok": true }.