Referência da API › Recursos
Agentes
Crie, liste, configure e apague agentes.
O objeto Agent#
{
"id": "agt_8f3a2b1c9d0e",
"name": "Analista de CRM",
"description": "Responde perguntas sobre o funil de vendas",
"emoji": "📊",
"color": "azul",
"avatar": "05",
"department": "Vendas",
"provider": "openrouter",
"model": "openrouter/auto",
"effort": "medium",
"instructions": "Você é o analista de CRM do time comercial…",
"abilities": { "webSearch": true, "webFetch": true, "files": true, "scheduling": true, "selfEdit": false },
"skillIds": ["skl_3e8f1a2b4c5d"],
"connectorIds": ["con_1f3e5d7c9b2a"],
"knowledgeIds": ["kno_2c4e6a8b0d1f"],
"subagentIds": [],
"starterPrompts": ["Como está o funil deste mês?"],
"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 | Descrição |
|---|---|
provider, model | Modelo do agente. openrouter + openrouter/auto é o DoubleX Auto, que escolhe o modelo a cada mensagem. |
effort | Esforço de raciocínio: low, medium ou high. |
abilities | Habilidades nativas: busca na web, leitura de páginas, arquivos no computador do agente, gatilhos criados pelo próprio agente e edição das próprias instruções. |
skillIds, connectorIds, knowledgeIds | Skills, conectores e documentos do Brain que este agente usa. |
subagentIds | Time direto: os outros agentes que este prefere consultar. Ele pode consultar qualquer agente que quem conversa vê e deixar recados para eles (veja Agentes que trabalham juntos). |
ownerId | Responsável pelo agente: pode editá-lo e recebe por e-mail os avisos de orçamento. |
budget | Orçamento mensal em créditos ({ "monthlyCredits": 500 }); ausente = sem limite. Veja Orçamento. |
color, avatar | Cor e robô do agente. Veja Criar. |
scope, teamId | Quem vê e usa o agente. Veja Escopos. |
GET/api/agents#
Lista os agentes que você pode ver. Cada item traz também canEdit (você pode editar), taskCount (conversas que você vê), triggerCount (gatilhos ligados) e lastTaskAt.
| Query | Descrição |
|---|---|
mine=1 | Só os seus agentes e os compartilhados com você. Sem isso, administradores recebem todos os agentes da organização. |
curl "https://doublex.ai/api/agents?mine=1" -H "Authorization: Bearer $DOUBLEX_API_KEY"Resposta: { "agents": [Agent, ...] }.
POST/api/agents#
Cria um agente no escopo Pessoal, com você como dono. Para compartilhar, use a tela do agente.
| Campo | Tipo | Descrição |
|---|---|---|
name | string, 1 a 60 | Obrigatório. |
description | string, até 300 | |
instructions | string, até 20.000 | O que o agente faz e como. |
emoji | string | Padrão 🤖. |
color | string | Uma das cores prontas (roxo, indigo, azul, ciano, turquesa, verde, lima, amarelo, laranja, vermelho, rosa, grafite) ou um hex #rrggbb. Padrão roxo. |
avatar | string | Robô do agente, de "01" a "26". Sem ele, o agente usa o robô padrão. O robô sempre aparece na cor do 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 perguntas sobre o funil de vendas",
"instructions": "Você é o analista de CRM do time comercial. Use o HubSpot para responder.",
"emoji": "📊",
"color": "azul"
}'Resposta 201: { "agent": Agent }.
O agente nasce com o modelo padrão da organização, esforço medium e todas as habilidades ligadas. Para escolher modelo, esforço, skills e conectores, faça um PATCH logo depois.
A partir de um template. Mande só { "templateKey": "<chave>" }. Chaves disponíveis: assistente, briefing-diario, pesquisa-concorrentes, gerador-leads, redator-conteudo, analista-dados, triagem-suporte e recrutador.
GET/api/agents/{id}#
Devolve o agente, as conversas dele que você vê (sem as mensagens), os gatilhos e se você pode editá-lo.
{ "agent": { "...": "..." }, "tasks": [], "triggers": [], "canEdit": true }Erro 404 se o agente não existe ou você não pode vê-lo.
PATCH/api/agents/{id}#
Altera o agente. Mande só os campos que mudam. Exige permissão de edição.
| Campo | Tipo | Descrição |
|---|---|---|
name, description, emoji, color, avatar | Como na criação. | |
department | string, até 80 | Área do agente (agrupa a barra lateral do app). |
provider | string | anthropic, openai, google, deepseek, xai, groq, mistral, openrouter, ollama ou custom. |
model | string | ID do modelo no provedor. Para o DoubleX Auto: provider: "openrouter", model: "openrouter/auto". |
effort | low, medium, high | Esforço de raciocínio. |
instructions | string, até 20.000 | |
abilities | objeto | Os cinco campos: webSearch, webFetch, files, scheduling, selfEdit. |
skillIds, connectorIds, knowledgeIds, subagentIds | array de IDs | Substituem a lista inteira. |
starterPrompts | array, até 8 | Sugestões que aparecem no chat vazio (até 200 caracteres cada). |
ownerId | string | Troca o responsável. Precisa ser alguém da organização; ele passa a poder editar o agente. Num agente pessoal, o agente passa a ser só dele. |
budget | objeto ou null | { "monthlyCredits": 500 } define o limite do mês (inteiro a partir de 1); null tira o limite. |
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"]
}'Resposta: { "agent": Agent }. Erros: 400 com ownerId de fora da organização; 403 se você vê o agente mas não pode editá-lo; 404 se não o vê.
Orçamento do agente#
Cada agente pode ter um limite de créditos por mês (o mês do calendário, no fuso de São Paulo). O consumo de cada conversa, rotina e webhook do agente conta para ele; quando outro agente o consulta, o gasto também entra no orçamento dele.
- Ao passar de 80% e ao atingir o limite, o responsável (
ownerId) recebe um e-mail, uma vez por mês. - Atingido o limite, a conversa que já começou termina, mas a próxima responde com erro e as rotinas e webhooks esperam (
402 agent_budget) até o mês virar ou o limite subir. - O orçamento só vale no plano com créditos da DoubleX.
GET/api/agents/{id}/governance#
Responsável, limite e gasto do mês. Quem pode editar o agente recebe também members, as pessoas da organização que podem virar responsáveis.
{
"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 trabalham juntos#
Todo agente conhece os outros agentes que a pessoa que conversa pode ver (nas rotinas e webhooks, o dono do agente) e trabalha com eles de dois jeitos:
- Consultar e esperar a resposta: o agente passa a tarefa com todo o contexto e usa a resposta do colega na dele.
- Deixar um recado: o colega trabalha em segundo plano e o resultado aparece em Tarefas, como conversa de origem
subagent. Até 3 recados por mensagem.
O colega roda com as próprias instruções, conhecimento e conectores, sempre com o acesso de quem conversa: nunca alcança um agente ou dado que essa pessoa não vê. Os agentes em subagentIds são o time direto, que o agente prefere. A delegação vai até dois níveis (um colega pode consultar outro, e para aí).
DELETE/api/agents/{id}#
Apaga o agente e, junto, as conversas, os gatilhos e os arquivos do computador dele. Ele também sai da lista de subagentes de outros agentes. Exige permissão de edição.
Resposta: { "ok": true }.