API reference › Resources
Agents
Create, list, configure and delete agents.
The Agent object#
{
"id": "agt_8f3a2b1c9d0e",
"name": "CRM Analyst",
"description": "Answers questions about the sales pipeline",
"emoji": "📊",
"color": "azul",
"avatar": "05",
"department": "Sales",
"provider": "openrouter",
"model": "openrouter/auto",
"effort": "medium",
"instructions": "You are the CRM analyst for the sales team…",
"abilities": { "webSearch": true, "webFetch": true, "files": true, "scheduling": true, "selfEdit": false },
"skillIds": ["skl_3e8f1a2b4c5d"],
"connectorIds": ["con_1f3e5d7c9b2a"],
"knowledgeIds": ["kno_2c4e6a8b0d1f"],
"subagentIds": [],
"starterPrompts": ["How is the pipeline looking this month?"],
"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"
}| Field | Description |
|---|---|
provider, model | The agent's model. openrouter + openrouter/auto is DoubleX Auto, which picks the model for each message. |
effort | Reasoning effort: low, medium or high. |
abilities | Built-in abilities: web search, reading web pages, files on the agent's computer, triggers created by the agent itself, and editing its own instructions. |
skillIds, connectorIds, knowledgeIds | Skills, connectors and Brain documents this agent uses. |
subagentIds | Direct team: the other agents this one prefers to consult. It can consult any agent the person chatting can see and leave them messages (see Agents that work together). |
ownerId | The agent's owner: can edit it and gets the budget alerts by email. |
budget | Monthly budget in credits ({ "monthlyCredits": 500 }); missing = no limit. See Budget. |
color, avatar | The agent's color and robot. See Create. |
scope, teamId | Who sees and uses the agent. See Scopes. |
GET/api/agents#
Lists the agents you can see. Each item also includes canEdit (you can edit it), taskCount (conversations you can see), triggerCount (active triggers) and lastTaskAt.
| Query | Description |
|---|---|
mine=1 | Only your agents and the ones shared with you. Without it, admins get every agent in the organization. |
curl "https://doublex.ai/api/agents?mine=1" -H "Authorization: Bearer $DOUBLEX_API_KEY"Response: { "agents": [Agent, ...] }.
POST/api/agents#
Creates an agent in the Personal scope, with you as the owner. To share it, use the agent's page in the app.
| Field | Type | Description |
|---|---|---|
name | string, 1 to 60 | Required. |
description | string, up to 300 | |
instructions | string, up to 20,000 | What the agent does and how. |
emoji | string | Default 🤖. |
color | string | One of the preset colors (roxo, indigo, azul, ciano, turquesa, verde, lima, amarelo, laranja, vermelho, rosa, grafite) or a #rrggbb hex. Default roxo. |
avatar | string | The agent's robot, from "01" to "26". Without it, the agent uses the default robot. The robot always appears in the agent's color. |
curl -X POST https://doublex.ai/api/agents \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "CRM Analyst",
"description": "Answers questions about the sales pipeline",
"instructions": "You are the CRM analyst for the sales team. Use HubSpot to answer.",
"emoji": "📊",
"color": "azul"
}'Response 201: { "agent": Agent }.
The agent starts with the organization's default model, medium effort and every ability turned on. To choose the model, effort, skills and connectors, send a PATCH right after.
From a template. Send only { "templateKey": "<key>" }. Available keys: assistente, briefing-diario, pesquisa-concorrentes, gerador-leads, redator-conteudo, analista-dados, triagem-suporte and recrutador.
GET/api/agents/{id}#
Returns the agent, its conversations that you can see (without the messages), its triggers and whether you can edit it.
{ "agent": { "...": "..." }, "tasks": [], "triggers": [], "canEdit": true }Error 404 if the agent doesn't exist or you can't see it.
PATCH/api/agents/{id}#
Changes the agent. Send only the fields that change. Requires edit permission.
| Field | Type | Description |
|---|---|---|
name, description, emoji, color, avatar | Same as when creating. | |
department | string, up to 80 | The agent's department (groups the app's sidebar). |
provider | string | anthropic, openai, google, deepseek, xai, groq, mistral, openrouter, ollama or custom. |
model | string | The model ID at the provider. For DoubleX Auto: provider: "openrouter", model: "openrouter/auto". |
effort | low, medium, high | Reasoning effort. |
instructions | string, up to 20,000 | |
abilities | object | The five fields: webSearch, webFetch, files, scheduling, selfEdit. |
skillIds, connectorIds, knowledgeIds, subagentIds | array of IDs | Replace the whole list. |
starterPrompts | array, up to 8 | Suggestions shown in an empty chat (up to 200 characters each). |
ownerId | string | Changes the owner. Must be someone in the organization; they become able to edit the agent. For a personal agent, it becomes theirs only. |
budget | object or null | { "monthlyCredits": 500 } sets the monthly limit (whole number from 1); null removes the limit. |
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"]
}'Response: { "agent": Agent }. Errors: 400 with an ownerId outside the organization; 403 if you can see the agent but can't edit it; 404 if you can't see it.
Agent budget#
Each agent can have a monthly credit limit (the calendar month, in the São Paulo time zone). The usage of the agent's conversations, routines and webhooks counts toward it; when another agent consults it, that spend also counts toward its budget.
- At 80% and when the limit is reached, the owner (
ownerId) gets an email, once a month. - Once the limit is reached, a conversation already in progress finishes, but the next one fails and routines and webhooks wait (
402 agent_budget) until the month turns over or the limit goes up. - Budgets apply only on DoubleX credit plans.
GET/api/agents/{id}/governance#
Owner, limit and this month's spend. If you can edit the agent, you also get members, the people in the organization who can become owners.
{
"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]" }]
}Agents that work together#
Every agent knows the other agents that the person chatting can see (in routines and webhooks, the agent's owner) and works with them in two ways:
- Ask and wait for the answer: the agent hands over the task with all the context and uses the colleague's answer in its own.
- Leave a message: the colleague works in the background and the result shows up in Tasks, as a conversation with source
subagent. Up to 3 messages per turn.
The colleague runs with its own instructions, knowledge and connectors, always with the access of the person chatting: it never reaches an agent or data that person can't see. Agents in subagentIds are the direct team, which the agent prefers. Delegation goes two levels deep (a colleague can consult another one, and it stops there).
DELETE/api/agents/{id}#
Deletes the agent, along with its conversations, triggers and the files on its computer. It's also removed from other agents' subagent lists. Requires edit permission.
Response: { "ok": true }.