# DoubleX Agentes > Documentação para integrar com o DoubleX Agentes: chaves de API, referência da API HTTP e a CLI doublex. --- # Introdução Leve os agentes do DoubleX Agentes para os seus sistemas, scripts e para o terminal. O DoubleX Agentes é onde sua empresa cria, compartilha e controla agentes de IA. Tudo o que você faz na tela também pode ser feito fora dela: um script que conversa com um agente, um sistema que dispara um agente quando chega um pedido, um job que sobe documentos para o Brain toda noite ou um agente de programação que usa os seus conectores. Há três formas de integrar: | Forma | Para quê | Comece por | | --- | --- | --- | | **API HTTP** | Sistemas e scripts em qualquer linguagem. É a mesma API que o app usa. | [Visão geral da API](/docs/api/visao-geral) | | **CLI `doublex`** | Terminal, automações em shell, CI e agentes de programação (Claude Code, Codex, Cursor). | [DoubleX no terminal](/docs/cli/visao-geral) | | **Webhooks de gatilho** | Outro serviço (formulário, CRM, Stripe, GitHub) roda um agente chamando um endereço. Não precisa de chave de API. | [Webhooks](/docs/webhooks) | ## Conceitos | Conceito | O que é | | --- | --- | | **Agente** | Um assistente de IA com modelo, instruções, conectores, skills, documentos do Brain e subagentes. | | **Conversa** | Uma sessão com um agente. Cada mensagem gera uma resposta em streaming e fica no histórico da tela **Tarefas**. Na CLI, as conversas se chamam `sessions`. | | **Conector** | Um app ligado à plataforma (Gmail, Google Agenda, Slack, HubSpot, bancos de dados, servidores MCP). Os agentes usam as ferramentas dele, e você também pode chamá-las direto. | | **Brain** | A base de conhecimento: documentos que os agentes consultam (PDF, Word, Excel e texto). | | **Skill** | Um conjunto de instruções reutilizável, no formato `SKILL.md`, que você anexa a qualquer agente. | | **Criação** | Um arquivo que o agente criou no computador dele (relatório, planilha, apresentação, página HTML) ou um painel ou app ao vivo. Tudo fica na tela **Criações**. | | **Gatilho** | Faz o agente trabalhar sozinho: num horário (cron), uma única vez, quando chega um webhook ou quando algo acontece num app. | | **Escopo** | Quem vê e usa cada item: **Pessoal** (só você), **Time** ou **Organização**. A API respeita os mesmos escopos da tela. | ## Endereço Todos os exemplos usam o endereço deste app: ```text https://doublex.ai ``` As rotas da API ficam em `https://doublex.ai/api/...` e o instalador da CLI em `https://doublex.ai/cli/install.sh`. ## Permissões Uma chave de API age **como a pessoa dona dela**. Ela vê e altera só o que essa pessoa vê e altera na tela, segundo o escopo de cada item e o papel na organização. Não existe chave com mais poder do que o usuário dono. > [!TIP] > Quer só testar? O [Início rápido](/docs/inicio-rapido) leva cinco minutos: instala a CLI, entra pelo navegador e conversa com um agente. ## Para agentes de IA Se você usa um agente de programação, ele pode ler esta documentação inteira de uma vez: - [`/docs/llms.txt`](https://doublex.ai/docs/llms.txt): índice de todas as páginas. - [`/docs/llms-full.txt`](https://doublex.ai/docs/llms-full.txt): todo o conteúdo num só arquivo de texto. Cada página também tem o botão **Copiar página**, que copia o conteúdo em Markdown. --- # Início rápido Instale a CLI, entre pelo navegador e converse com um agente em cinco minutos. Depois, faça a mesma coisa pela API. ## 1. Instale a CLI A CLI precisa do Node.js 18 ou mais novo e roda no macOS e no Linux. ```bash curl -fsSL https://doublex.ai/cli/install.sh | sh ``` O instalador coloca o comando `doublex` em `~/.doublex` e cria um atalho em `~/.local/bin`. Ele não usa `sudo` e já grava o endereço deste app como padrão. Confira: ```bash doublex --version ``` > [!NOTE] > Se o terminal disser que não achou o comando, adicione `~/.local/bin` ao `PATH` (o instalador mostra a linha certa para o seu shell) e abra um terminal novo. ## 2. Entre ```bash doublex login ``` O navegador abre na tela de autorização. Confira o nome do computador e clique em **Permitir**. Pronto: a CLI guarda uma chave só deste terminal no chaveiro do sistema. Para conferir quem está conectado: ```bash doublex whoami ``` ## 3. Converse com um agente Liste os agentes que você pode usar: ```bash doublex agents list ``` ```text ID NOME MODELO ESCOPO CONVERSAS EDITA agt_8f3a2b1c9d0e 🤖 Assistente openrouter/auto personal 12 sim agt_2b7e4c6a1f3d 📊 Analista de CRM anthropic/claude-sonnet-5-5 team 4 não ``` Pegue um ID e mande uma mensagem. A resposta aparece enquanto o agente escreve, e as ferramentas que ele usa aparecem com `›`: ```bash doublex sessions create agt_8f3a2b1c9d0e --input "Qual é a nossa política de reembolso?" ``` No fim, a CLI mostra o ID da conversa. Para continuar a mesma conversa: ```bash doublex sessions send task_5d2c9a3e1f07 --input "Resuma isso num e-mail curto para o cliente" ``` ## 4. Faça o mesmo pela API Gere uma chave em **Configurações › Perfil › Acesso pela API › Gerar chave de API** e guarde-a numa variável de ambiente: ```bash export DOUBLEX_API_KEY="dbx_..." ``` Liste os agentes: ```bash curl https://doublex.ai/api/agents \ -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` Mande uma mensagem. A resposta chega como NDJSON, um evento JSON por linha: ```bash curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Qual é a nossa política de reembolso?"}' ``` ```ndjson {"type":"task","taskId":"task_5d2c9a3e1f07"} {"type":"tool_start","id":"toolu_01","name":"buscar_conhecimento","label":"Buscando na base de conhecimento"} {"type":"tool_end","id":"toolu_01","ok":true} {"type":"text","delta":"Pela política atual, o reembolso vale por 30 dias "} {"type":"done","status":"completed"} ``` ## Próximos passos - [Chaves de API](/docs/chaves-de-api): tipos de chave, onde gerar e como guardar. - [Conversas pela API](/docs/api/conversas): todos os eventos do streaming e como cancelar. - [Webhooks](/docs/webhooks): rode um agente quando outro sistema chamar um endereço. - [Agentes de programação](/docs/cli/plugin): ensine o Claude Code ou o Codex a usar a CLI. --- # Avisos (agente proativo) O agente proativo acompanha o e-mail, a agenda e o que o assistente fez por você, e só fala quando muda o que você deveria fazer, dentro da conversa. Tudo fica em Avisos. **Avisos** é onde trabalha o agente proativo do DoubleX Agentes. Ele não espera uma pergunta nem precisa de gatilho: conecte o e-mail e a agenda e ele passa a acompanhar sozinho. Ele não repete cada e-mail ou mudança na agenda; isso você já vê nos seus apps. Ele junta o que sabe e só fala quando isso muda o que você deveria fazer, como um chefe de gabinete: > Um detalhe para a reunião das 16h: o Guilherme comentou hoje que teria disponibilidade limitada depois das 15h, e ele e o Antônio ainda não responderam ao convite. Quer que eu confirme com o Guilherme? A mensagem entra na conversa com o assistente (a mesma em que ele marcou a reunião, ou a conversa de avisos do dia), e você responde ali mesmo. No celular, ela chega como notificação e abre a conversa. O histórico fica em **Avisos**: abra pelo bloco Avisos na tela **Início** (o número de avisos não lidos aparece em **Início**, na barra lateral). ## Como funciona 1. **Sensores, sem IA.** A cada poucos minutos, o agente compara o e-mail e a agenda com a consulta anterior e acha o que mudou: e-mail novo, reunião criada, remarcada ou cancelada, convite sem resposta, sobreposição de horário. Entre 15 e 75 minutos antes de cada reunião com outras pessoas, ele também confere a reunião. 2. **Pensa com o contexto todo.** Quando há novidade, a IA olha junto a agenda das próximas 24 horas (com quem já respondeu cada convite), os e-mails recentes, o que o assistente fez por você nos últimos dias (reuniões marcadas, e-mails enviados) e o que o próprio agente já disse. Na maioria das vezes, a conclusão é ficar quieto. 3. **Fala uma vez, ligando os pontos.** Quando vale falar, é uma mensagem só por situação: uma remarcação, o choque que ela cria e o convite pendente viram uma mensagem, não três. Newsletters, notificações automáticas, sobreposições do dia a dia (dailies, blocos longos) e o que ele já disse ficam de fora. 4. **Você responde na conversa.** "Sim, pergunta pra ele" e o assistente faz. No aviso, há também **Aceitar** e **Recusar** o convite e **Abrir** o e-mail ou o evento. 5. **Aprende.** **Não me avise disso** silencia aquele remetente ou aquele assunto, e o que você dispensa pesa nas próximas decisões. Em **Ajustes › O que importa para você**, escreva suas prioridades. ## O que o agente acompanha | Fonte | Quando ele fala | | --- | --- | | Gmail, Outlook | Quando um e-mail afeta um compromisso seu, é resposta a algo que o assistente enviou ou alguém espera uma decisão sua e a demora custa. | | Google Agenda, calendário do Outlook | Quando uma mudança atrapalha algo que importa, e antes de reuniões com outras pessoas, se houver algo útil para saber (quem não confirmou, um e-mail relacionado, uma mudança). | | Conversas com o assistente | Acompanha o que ele fez por você (reuniões marcadas, e-mails enviados) e volta na mesma conversa quando algo muda. | | Qualquer app conectado | O que você definir num [monitor](#monitores). | As suas contas de e-mail e agenda entram sozinhas. Em **Ajustes**, desligue as que não quer acompanhar, ligue o **horário de silêncio** (os urgentes passam) e os **avisos urgentes por e-mail**. ## Resumo do dia Todo dia, às 8h (você muda dias e horário em **Início › Resumo do dia**), chega o seu dia em 30 segundos: por notificação, se ela estiver ativada, ou por e-mail. Se a notificação não chegar a nenhum aparelho, ele vai por e-mail. É o único aviso previsível do dia. Ele lê o seu e-mail e a sua agenda, quando conectados, os arquivos mexidos no Google Drive e o que aconteceu na DoubleX: conversas, rotinas que rodaram ou falharam, ações do assistente e notas salvas. Sem e-mail conectado, ele sai mesmo assim, com o que aconteceu na plataforma. Para quem ainda não está usando, ele traz ideias para começar hoje: perguntar ao assistente o que ele pode fazer, passar uma tarefa, criar uma landing page ou conversar com a Lumi. Ele traz: - **O essencial** do dia em duas ou três frases. - **O que percebi**: uma observação que liga os pontos entre e-mails, agenda e o que o agente vem acompanhando. - **Destaques** com **Resolver**: um toque abre o assistente com o pedido pronto (por exemplo, um rascunho de resposta). - **Para amanhã ficar melhor**: uma sugestão, como automatizar algo que se repete, que o assistente monta com um toque. - **Placar** das últimas 24 h: e-mails acompanhados, interrupções e ações do assistente por você. Dispensar um destaque ensina o que não precisa voltar. Se a IA estiver fora do ar ou os créditos acabarem, sai um resumo rápido, e **Gerar de novo** faz o completo. ## Monitores Um monitor consulta um app conectado de tempos em tempos e avisa quando uma condição acontece. Exemplos: o CPA de uma campanha, negócios parados no CRM, pagamentos recusados, menções no Slack ou uma métrica do banco de dados. - Ele chama só **ferramentas de leitura**: nunca envia, posta, altera nem apaga nada. - A IA só entra quando o resultado muda, e não avisa duas vezes a mesma situação. - Com **Avisar e acionar um agente**, o agente escolhido age quando o monitor dispara, por exemplo analisando as campanhas e sugerindo o que pausar. Crie em **Avisos › Monitores › Novo monitor**: escolha a conexão, a consulta e a condição e use **Testar consulta** para ver os dados. Ou peça ao assistente, por exemplo "me avise se o CPA de alguma campanha passar de R$ 50", e ele monta o monitor. ## Regras Uma regra faz um agente agir sozinho quando chega um e-mail ou muda algo na agenda que bate com a condição. Por exemplo: "quando chegar um e-mail de cliente pedindo orçamento, o agente de vendas prepara a proposta e deixa um rascunho". O aviso mostra o link para a conversa do agente. ## Pelo ChatGPT e pelo Claude Pelo [servidor MCP](/docs/chatgpt-e-claude), o ChatGPT e o Claude leem os seus avisos (`list_radar_alerts`) e criam monitores pela conversa (`list_monitor_tools` e `create_monitor`). ## Custo e limites - Os Avisos só usam IA quando há algo novo (e-mail, mudança na agenda ou reunião prestes a começar), e o consumo entra em **Uso e créditos** como "Avisos". - Cada pessoa tem um teto diário de análises com IA. Depois dele, e também sem plano ou sem créditos, só remarcação ou cancelamento de reunião nas próximas horas continua avisando, com texto pronto, e a tela Avisos mostra o motivo. --- # Chaves de API Gere, use, troque e revogue as chaves que dão acesso à API e à CLI. Toda chamada à API, exceto os [webhooks de gatilho](/docs/webhooks), precisa de uma chave. As chaves começam com `dbx_` e agem **como a pessoa dona delas**: veem e alteram só o que essa pessoa vê e altera na tela. ## Tipos de chave | Tipo | Onde nasce | Quantas | Use para | | --- | --- | --- | --- | | **Chave pessoal** | **Configurações › Perfil › Acesso pela API** | Uma por pessoa. Gerar de novo troca a anterior. | Scripts, sistemas e integrações que você mantém. | | **Chave de terminal** | Criada pelo `doublex login`, uma por computador | Uma por login | A CLI daquele computador. Ela fica no chaveiro do sistema e você nunca precisa vê-la. | As duas funcionam da mesma forma na API. A diferença é como nascem e como são revogadas. ## Gerar a chave pessoal 1. Entre no app e abra **Configurações › Perfil**. 2. Na seção **Acesso pela API**, clique em **Gerar chave de API**. 3. Copie a chave na hora. Por segurança, ela aparece uma única vez. A tela mostra depois só o final da chave (`dbx_••••••••••••a1b2`), a data de criação e o último uso. > [!WARNING] > Gerar e revogar chaves só funciona pelo navegador, com e-mail e senha. Uma chave vazada não consegue criar outra chave para si nem autorizar novos terminais. ## Usar a chave Envie a chave no cabeçalho `Authorization` com o esquema `Bearer`: ```bash title="curl" curl https://doublex.ai/api/me \ -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```js title="JavaScript" const res = await fetch("https://doublex.ai/api/me", { headers: { Authorization: `Bearer ${process.env.DOUBLEX_API_KEY}` }, }); const me = await res.json(); ``` ```python title="Python" import os, requests res = requests.get( "https://doublex.ai/api/me", headers={"Authorization": f"Bearer {os.environ['DOUBLEX_API_KEY']}"}, ) me = res.json() ``` ```bash title="CLI" export DOUBLEX_API_KEY="dbx_..." doublex whoami ``` Sem a chave, ou com uma chave inválida ou revogada, a API responde `401`. ## Trocar e revogar | Ação | Como | Efeito | | --- | --- | --- | | Trocar a chave pessoal | **Perfil › Acesso pela API › ⋯ › Gerar nova chave** | A chave antiga para de funcionar na hora. Atualize tudo que a usa. | | Revogar a chave pessoal | **Perfil › Acesso pela API › ⋯ › Revogar chave** | Tudo que usa a chave para de funcionar. | | Desconectar um terminal | **Perfil › Terminal (CLI) › Terminais conectados › Desconectar** | A CLI daquele computador precisa de um novo `doublex login`. | | Sair pelo terminal | `doublex logout` | Revoga a chave daquele terminal no servidor e a apaga do chaveiro. Se você entrou com a chave pessoal (`--api-key`), ela só sai do chaveiro e continua valendo. | Quando uma pessoa sai da organização, as chaves dela deixam de funcionar. Trocar ou redefinir a senha revoga todas as suas chaves (a pessoal e as dos terminais): gere a pessoal de novo e rode `doublex login` nos terminais. A chave de um terminal parado por 90 dias também deixa de valer. ## O que a chave pode fazer A chave tem as mesmas permissões da pessoa: - vê os agentes, skills, documentos do Brain e conectores do escopo dela (Pessoal, dos times dela e da Organização); - edita só o que a pessoa pode editar na tela; - usa os créditos da organização, como o uso pelo app. Algumas ações só funcionam no navegador, mesmo com uma chave válida: - gerar, trocar ou revogar a chave pessoal; - autorizar o login de um terminal; - adicionar créditos à organização. ## Boas práticas - Guarde a chave como uma senha: num cofre de segredos ou numa variável de ambiente, nunca no código nem no Git. - Use a chave de terminal (`doublex login`) no seu computador e a chave pessoal só em servidores e automações. - Se uma chave vazar, revogue-a no Perfil. Nada que ela fez antes é desfeito, mas ela para de funcionar na hora. - O prefixo `dbx_` existe para os scanners de segredos (como o do GitHub) reconhecerem uma chave publicada por engano. ## Próximos passos - [Visão geral da API](/docs/api/visao-geral): formato das requisições, erros e streaming. - [Autenticação na CLI](/docs/cli/autenticacao): login pelo navegador, servidores sem navegador e CI. --- # ChatGPT e Claude (MCP) Conecte o ChatGPT, o Claude e outros apps compatíveis com MCP para migrar e usar seus agentes direto da conversa. O DoubleX Agentes tem um servidor MCP. Depois de conectado, o ChatGPT, o Claude ou outro app compatível consegue criar agentes aqui, subir o conhecimento deles para o Brain e conversar com eles, tudo a partir da conversa. O uso mais comum é a **migração**: a IA lê as instruções e os arquivos do seu assistente (um Projeto do Claude, um GPT personalizado) e recria tudo no DoubleX Agentes, organizado em pastas. | Item | Valor | | --- | --- | | **Endereço do servidor** | `https://doublex.ai/api/mcp` | | **Login** | OAuth: você entra com a sua conta DoubleX e clica em **Permitir**. | | **Permissões** | As suas. O app vê e altera só o que você vê e altera na tela. | O endereço também aparece em **Configurações › Perfil › Apps conectados**, com um botão para copiar. ## Conectar no Claude 1. No Claude, abra **Configurações › Conectores** e clique em **Adicionar conector personalizado**. 2. Dê um nome (por exemplo, `DoubleX Agentes`) e cole o endereço `https://doublex.ai/api/mcp`. 3. Clique em **Conectar**. Uma janela do DoubleX Agentes abre: entre, se ainda não entrou, e clique em **Permitir**. 4. Numa conversa, ligue o conector no menu de ferramentas. Nos planos Team e Enterprise do Claude, quem administra a conta adiciona o conector primeiro. Depois, cada pessoa conecta a própria conta. **No Claude Code**, adicione pelo terminal e autorize com `/mcp`: ```bash claude mcp add --transport http doublex https://doublex.ai/api/mcp ``` ## Conectar no ChatGPT 1. No ChatGPT, abra **Configurações › Apps › Configurações avançadas** e ligue o **modo desenvolvedor**. 2. Clique em **Criar app** (ou **Criar conector**), dê um nome e cole o endereço `https://doublex.ai/api/mcp`. 3. Escolha a autenticação **OAuth** e confirme. 4. Na janela do DoubleX Agentes, entre e clique em **Permitir**. 5. Numa conversa, escolha o app no menu **+**. > [!NOTE] > Os nomes dos menus mudam de tempos em tempos e variam por plano. Procure por "Apps", "Conectores" ou "modo desenvolvedor" nas configurações. ## Outros apps Qualquer cliente MCP com transporte HTTP funciona (Cursor, VS Code e outros). Use o endereço `https://doublex.ai/api/mcp` com OAuth. Se o app não tiver OAuth, mande a [chave pessoal](/docs/chaves-de-api) no cabeçalho: ```json title="mcp.json" { "mcpServers": { "doublex": { "url": "https://doublex.ai/api/mcp", "headers": { "Authorization": "Bearer dbx_SUA_CHAVE" } } } } ``` ## Migrar um agente **De um Projeto do Claude.** Abra o projeto, comece uma conversa com o conector ligado e peça: > Migre este projeto para o DoubleX Agentes, com as instruções e todos os arquivos. Dentro do projeto, o Claude enxerga as instruções e os arquivos. No Claude, o pedido pronto **migrate_assistant** do conector faz o mesmo. **De um GPT personalizado.** O ChatGPT não lê a configuração dos seus GPTs. Abra o GPT em **Editar › Configurar**, copie as instruções e baixe os arquivos de conhecimento. Depois, numa conversa comum com o app do DoubleX Agentes, cole as instruções, anexe os arquivos e peça a migração. **De qualquer outro assistente.** Cole as instruções (o "prompt de sistema") e anexe os arquivos. A IA nunca inventa instruções: se faltar algo, ela pergunta. O que a migração cria: | No assistente antigo | No DoubleX Agentes | | --- | --- | | Instruções | As instruções do agente, copiadas sem resumo nem tradução. | | Arquivos de conhecimento | Uma nota por arquivo no Brain, na pasta `Importados/`, ligadas ao agente. | | Procedimentos reutilizáveis | [Skills](/docs/api/skills) ligadas ao agente. | | Sugestões de conversa | As sugestões que aparecem no chat do agente. | | Apps usados | Os conectores que você já tem são ligados. Os que faltam aparecem com o link para conectar. | | Rotina recorrente | Um [gatilho](/docs/api/gatilhos) agendado, criado **desligado** para você revisar e ligar. | Se já existir um agente com o mesmo nome, a IA pergunta se deve atualizar o existente ou criar uma cópia. ## Ferramentas | Ferramenta | O que faz | | --- | --- | | `get_account` | Mostra a conta, a empresa, os times e o saldo de créditos. | | `list_agents` / `get_agent` | Lista os agentes e mostra a configuração completa de um. | | `import_agent` | Cria o agente com instruções, notas, skills, conectores e rotina, numa chamada. | | `update_agent` | Muda o agente e liga mais notas, skills ou conectores. | | `list_brain` / `search_brain` / `read_brain_note` | Lista, busca e lê o Brain. | | `save_brain_note` | Cria ou atualiza uma nota, opcionalmente ligando a um agente. | | `list_skills` / `create_skill` | Lista e cria skills. | | `list_connectors` | Mostra os apps conectados e o catálogo, com os IDs usados na migração. | | `create_trigger` | Cria um gatilho agendado, único ou por webhook. | | `run_agent` / `get_agent_run` | Conversa com um agente e acompanha a resposta. | | `list_radar_alerts` | Lê os avisos recentes (tela [Avisos](/docs/radar)). | | `list_monitor_tools` / `create_monitor` | Mostra as consultas de leitura de uma conexão e cria um monitor em Avisos. | Ferramentas que gravam dados vêm marcadas como escrita: o ChatGPT e o Claude pedem a sua confirmação antes de usá-las. ## Limites - **Arquivos passam como texto.** A IA envia o conteúdo de cada arquivo como Markdown. PDFs escaneados, planilhas grandes e arquivos binários sobem melhor pela tela do [Brain](/docs/api/brain), direto na pasta do agente. - **Instruções têm até 20.000 caracteres.** Material de referência longo vai para notas do Brain. - **Até 50 notas e 20 skills por migração.** Para mais, a IA chama `save_brain_note` em seguida. - **Conectar um app exige o seu login nele**, na tela de Conectores. A IA só liga os que já estão conectados. - **`run_agent` usa créditos** e espera até 45 segundos (até 120, se pedido). Conversas mais longas continuam rodando e a IA acompanha com `get_agent_run`. ## Segurança e desconexão - O login usa OAuth 2.1 com PKCE. O app recebe um token que vale uma hora e é renovado sozinho, nunca a sua senha. - Para cortar o acesso, abra **Configurações › Perfil › Apps conectados** e clique em **Desconectar**. Os tokens daquele app param de valer na hora. - Trocar ou redefinir a senha desconecta todos os apps. --- # Webhooks Rode um agente quando outro sistema chamar um endereço, sem chave de API e sem esperar a resposta. Um gatilho do tipo **webhook** dá ao agente um endereço próprio. Qualquer sistema que consiga fazer um `POST` roda o agente: um formulário do site, o CRM, o Stripe, o GitHub, um job agendado. O corpo da requisição vira o contexto da tarefa. ## 1. Crie o gatilho Escolha uma das formas: - **Na tela:** abra o agente, vá em **Gatilhos › Adicionar gatilho › Webhook**, dê um nome e escreva o que o agente deve fazer. - **Na CLI:** ```bash doublex triggers create agt_8f3a2b1c9d0e --name "Novo lead do site" --webhook \ --prompt "Chegou um lead: {{nome}} ({{email}}). Pesquise a empresa {{empresa}} e mande um resumo no Slack do comercial." ``` - **Na API:** `POST /api/triggers` com `"type": "webhook"` (veja [Gatilhos](/docs/api/gatilhos)). A resposta traz o endereço e o **segredo** do webhook: ```text trg_4c1e9a7b2d5f Endereço do webhook: https://doublex.ai/api/webhooks/trg_4c1e9a7b2d5f Envie o segredo no cabeçalho x-webhook-secret: 3f9a…c21e ``` ## 2. Chame o endereço Mande o segredo no cabeçalho `x-webhook-secret`: ```bash curl -X POST https://doublex.ai/api/webhooks/trg_4c1e9a7b2d5f \ -H "x-webhook-secret: $WEBHOOK_SECRET" \ -H "Content-Type: application/json" \ -d '{"nome": "Ana Souza", "email": "ana@empresa.com", "empresa": "Empresa SA"}' ``` ```json { "accepted": true } ``` O agente começa na hora, em segundo plano. A resposta `202` não traz o resultado: acompanhe a execução na tela **Tarefas** (origem **Webhook**) ou com `doublex sessions list --agent `. Se você precisa do resultado em outro sistema, peça no prompt para o agente entregar por um conector (Slack, e-mail, planilha, banco de dados). > [!WARNING] > O segredo é a credencial do webhook: quem tem o endereço e o segredo roda o seu agente. Guarde-o como uma senha. Para trocar o segredo, apague o gatilho e crie outro. ## Como o corpo chega ao agente | Corpo | O que o agente recebe | | --- | --- | | JSON, e o prompt cita campos como `{{email}}` ou `{{cliente.nome}}` | O prompt com os campos preenchidos. `{{__RAW_JSON__}}` coloca o JSON inteiro. | | JSON, e o prompt não cita nenhum campo | O prompt, seguido dos dados recebidos em JSON. | | Texto, formulário ou outro formato | O prompt, seguido do texto recebido. | | Gatilho com **Enviar o JSON bruto em vez de um prompt** ligado (`passRawData`) | Só o JSON recebido, sem prompt. | O corpo pode ter até 200.000 caracteres; o que passar disso é cortado. ## Respostas | Status | Quando | | --- | --- | | `202` | Aceito. O agente está rodando. | | `404` | Gatilho inexistente, segredo errado ou gatilho que não é webhook. A resposta é a mesma nos três casos, de propósito. | | `409` | O gatilho está desligado, ou a execução anterior ainda não terminou (tente de novo em instantes). | | `402` | A empresa está sem plano ativo (`plan_required`) ou sem créditos (`no_credits`), ou o agente atingiu o orçamento do mês (`agent_budget`). O evento não roda; reenvie depois. | | `503` | O agente não tem um modelo de IA disponível. | ## Quem paga e com que conta - O agente roda com a conta de **quem criou o gatilho**: usa os conectores e as permissões dessa pessoa. - O consumo sai dos créditos da organização. Se os créditos acabarem, o webhook ainda responde `202`, mas a tarefa falha e aparece como **Falhou** em **Tarefas**. ## Exemplos de uso - **Formulário do site → qualificação de lead:** o formulário chama o webhook, e o agente pesquisa a empresa, registra no CRM e avisa o vendedor. - **Pagamento confirmado → onboarding:** o provedor de pagamentos chama o webhook, e o agente manda o e-mail de boas-vindas e cria a pasta do cliente no Drive. - **Erro em produção → triagem:** o monitoramento chama o webhook, e o agente lê o erro, procura o histórico no Brain e abre um resumo para o time. --- # Erros e limites Códigos de status, formato dos erros, créditos, idioma das mensagens e limites da API. ## Formato dos erros Quando algo dá errado, a API responde com um status HTTP de erro e um JSON com a mensagem em `error`: ```json { "error": "Agente não encontrado." } ``` Alguns erros têm também um `code` estável. Use o `code` (e não o texto) para decidir o que fazer: | `code` | Status | Significado | | --- | --- | --- | | `no_credits` | `402` | Os créditos da organização acabaram. Um administrador precisa adicionar mais em **Configurações › Uso e créditos**. | | `plan_required` | `402` | A organização ainda não tem plano: só o primeiro diagnóstico é gratuito. O dono escolhe o plano em **Configurações › Plano e cobrança**. | | `agent_budget` | `402` | O agente atingiu o orçamento do mês. O responsável pode aumentar o limite nas configurações do agente; senão, ele volta quando o mês virar. | | `no_provider` | `400` ou `409` | Não há modelo de IA disponível para você. | | `model_unavailable` | `400` | O modelo pedido não está no catálogo ou não está liberado para você. | | `provider_error` | `502` | O provedor do modelo falhou. Tente de novo. | ## Códigos de status | Status | Quando acontece | | --- | --- | | `200` / `201` | Deu certo. `201` quando algo foi criado. | | `202` | Aceito e rodando em segundo plano (webhooks e `triggers/{id}/run`). | | `400` | Corpo inválido: campo faltando, tamanho fora do limite, JSON malformado. A mensagem diz qual campo. | | `401` | Sem chave, ou chave inválida ou revogada. | | `402` | Sem créditos (`no_credits`), sem plano (`plan_required`) ou agente sem orçamento no mês (`agent_budget`). | | `403` | Você vê o item mas não pode alterá-lo, ou a ação só funciona pelo navegador. | | `404` | O item não existe **ou você não tem acesso a ele**. A API não diferencia os dois casos, para não revelar o que existe. | | `409` | Conflito de estado: a conversa já está rodando, o gatilho está desligado ou o conector precisa ser reconectado. | | `413` | Arquivo grande demais (o Brain aceita até 20 MB por arquivo). | | `422` | O arquivo ou o texto chegou, mas não deu para usar: formato não suportado, PDF sem texto, frase que não vira um horário. | | `5xx` | Falha do servidor ou do provedor de IA. Tente de novo com espera crescente. | ## Erros durante o streaming As rotas que respondem em streaming (conversa com agente e chat direto com modelo) já começaram a responder com `200` quando o problema aparece. Nesses casos o erro chega como um evento no meio do fluxo: ```ndjson {"type":"error","message":"Os créditos da organização acabaram."} {"type":"done","status":"failed"} ``` Sempre trate o evento `error` e o `done` com `status: "failed"`. Os detalhes estão em [Conversas](/docs/api/conversas) e [Chat](/docs/api/chat). ## Créditos Quando a organização usa os modelos da plataforma, cada resposta consome créditos pelo custo do modelo. O consumo pela API e pela CLI sai do mesmo saldo do app. - Antes de um uso grande, consulte o saldo com `GET /api/credits` ou `doublex credits`. - Sem saldo, o chat direto e a conversão de texto em horário respondem `402 no_credits`. A conversa com agente responde com o evento `error` no streaming. - Uma conversa cancelada ou que falhou no meio também cobra o que já foi processado. ## Idioma das mensagens As mensagens de erro saem no idioma da pessoa dona da chave (um dos 14 do app, como Português, English, Español, Français ou 日本語), o mesmo escolhido no app. Para mudar pela API, use `PATCH /api/me` com `{"language": "en"}`. Se a pessoa ainda não escolheu um idioma, vale o cabeçalho `Accept-Language` da requisição e, sem ele, o idioma padrão da organização. As mensagens de validação de formato (por exemplo, `name: Too small`) podem sair em inglês. ## Limites | O quê | Limite | | --- | --- | | Mensagem para um agente | 100.000 caracteres | | Tempo de uma resposta de agente | 800 segundos por mensagem | | Conversas ao mesmo tempo | Uma resposta por conversa. Para rodar em paralelo, use conversas diferentes. | | Arquivo no Brain | 20 MB por arquivo; texto acima de 2 milhões de caracteres é dividido em partes | | Arquivo baixado de Criações | 2 MB | | Resultado de ferramenta de conector | 20.000 caracteres | | Gatilho agendado | No mínimo a cada 5 minutos | | Corpo de webhook | 200.000 caracteres | Não há limite de requisições por minuto, mas use o bom senso: prefira poucas chamadas maiores a muitas pequenas e não faça varreduras em laço. ## Listas e paginação As listas (`GET /api/agents`, `GET /api/tasks`, `GET /api/skills` etc.) devolvem tudo o que você pode ver, sem paginação. Filtre no seu código ou use os filtros de cada rota. --- # Visão geral da API Endereço, autenticação, formato das requisições e respostas, streaming e convenções da API HTTP. A API do DoubleX Agentes é a mesma que o app usa. Com ela você cria e configura agentes, conversa com eles em streaming, chama modelos direto, usa as ferramentas dos conectores, alimenta o Brain, gerencia skills e gatilhos e baixa os arquivos de Criações. ## Endereço ```text https://doublex.ai/api ``` Todas as rotas desta referência são relativas a esse endereço: `GET /api/agents` é `GET https://doublex.ai/api/agents`. ## Autenticação Mande uma [chave de API](/docs/chaves-de-api) no cabeçalho `Authorization`: ```bash curl https://doublex.ai/api/me -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` A chave age como a pessoa dona dela. Cada rota aplica as mesmas regras de acesso da tela: você só vê e altera o que essa pessoa vê e altera. ## Requisições - Corpos em **JSON**, com `Content-Type: application/json`. A exceção é o envio de arquivos para o Brain, em `multipart/form-data`. - Textos em **UTF-8**. - Campos que a rota não conhece são ignorados. - Datas em **ISO 8601**, em UTC (`2026-10-27T14:03:11.482Z`). ## Respostas As respostas de sucesso são JSON com o recurso dentro de uma chave com o nome dele: ```json { "agent": { "id": "agt_8f3a2b1c9d0e", "name": "Analista de CRM", "...": "..." } } ``` As listas vêm num array com o nome no plural (`{ "agents": [...] }`) e trazem tudo o que você pode ver, sem paginação. Ações sem conteúdo para devolver respondem `{ "ok": true }`. Novos campos podem aparecer nas respostas a qualquer momento. Ignore os que você não conhece. Os erros têm o formato `{ "error": "mensagem" }`, às vezes com um `code` estável. Veja [Erros e limites](/docs/erros). ## Streaming (NDJSON) As rotas que geram texto com IA podem responder em partes, no formato **NDJSON**: um objeto JSON por linha, separado por `\n`, com `Content-Type: application/x-ndjson`. Leia linha a linha: ```js title="JavaScript" const res = await fetch("https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat", { method: "POST", headers: { Authorization: `Bearer ${process.env.DOUBLEX_API_KEY}`, "Content-Type": "application/json" }, body: JSON.stringify({ message: "Resuma as vendas de ontem" }), }); const reader = res.body.pipeThrough(new TextDecoderStream()).getReader(); let buffer = ""; for (;;) { const { value, done } = await reader.read(); if (done) break; buffer += value; let nl; while ((nl = buffer.indexOf("\n")) >= 0) { const line = buffer.slice(0, nl).trim(); buffer = buffer.slice(nl + 1); if (!line) continue; const event = JSON.parse(line); if (event.type === "text") process.stdout.write(event.delta); } } ``` ```python title="Python" import json, os, requests res = requests.post( "https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat", headers={"Authorization": f"Bearer {os.environ['DOUBLEX_API_KEY']}"}, json={"message": "Resuma as vendas de ontem"}, stream=True, ) for line in res.iter_lines(): if not line: continue event = json.loads(line) if event["type"] == "text": print(event["delta"], end="", flush=True) ``` ```bash title="curl" curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Resuma as vendas de ontem"}' ``` ## IDs Os IDs são textos com um prefixo que diz o tipo do recurso: | Prefixo | Recurso | | --- | --- | | `agt_` | Agente | | `task_` | Conversa (na CLI, `session`) | | `trg_` | Gatilho | | `con_` | Conector | | `kno_` | Documento do Brain | | `skl_` | Skill | | `team_` | Time | | `usr_` | Pessoa | | `key_` | Chave de API | ## Escopos e permissões Agentes, skills, documentos do Brain e conectores têm um escopo: | Escopo | Quem vê e usa | Quem edita | | --- | --- | --- | | `personal` | Só o dono | O dono e os administradores da organização | | `team` | Os membros do time (`teamId`) | O dono, os administradores do time e os da organização | | `organization` | Todas as pessoas da organização | O dono e os administradores da organização | Itens que você não pode ver respondem `404`, como se não existissem. Itens que você vê mas não pode editar respondem `403` (ou `404` em algumas rotas) quando você tenta alterá-los. Os campos `canEdit` das respostas dizem o que você pode editar. ## Recursos | Recurso | Rotas | | --- | --- | | [Conta](/docs/api/conta) | Quem você é, idioma, chaves de API | | [Agentes](/docs/api/agentes) | Criar, listar, configurar e apagar agentes | | [Conversas](/docs/api/conversas) | Conversar em streaming, continuar, cancelar e ler o histórico | | [Chat](/docs/api/chat) | Chamar um modelo direto, sem agente | | [Modelos e créditos](/docs/api/modelos-e-creditos) | Catálogo de modelos, saldo e consumo | | [Conectores](/docs/api/conectores) | Listar conexões e executar ferramentas | | [Brain](/docs/api/brain) | Notas, pastas, links e busca no Brain | | [Skills](/docs/api/skills) | Instruções reutilizáveis | | [Criações](/docs/api/artefatos) | Arquivos criados pelos agentes | | [Gatilhos](/docs/api/gatilhos) | Agendamentos, webhooks e eventos de apps | | [Times](/docs/api/times) | Times da organização | --- # Conta Quem é a pessoa dona da chave, preferências de idioma e as chaves de API dela. ## GET /api/me Devolve a pessoa dona da chave, o papel dela na organização e os times de que participa. Bom para conferir se a chave funciona. ```bash title="curl" curl https://doublex.ai/api/me -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex whoami --json ``` ```json { "user": { "id": "usr_1a2b3c4d5e6f", "email": "ana@empresa.com", "firstName": "Ana", "lastName": "Souza", "language": "pt", "timezone": "America/Sao_Paulo", "createdAt": "2026-10-20T13:02:44.120Z" }, "role": "admin", "isAdmin": true, "organization": { "id": "org_7f6e5d4c3b2a", "name": "Empresa SA" }, "teams": [{ "id": "team_9c8b7a6d5e4f", "name": "Comercial", "role": "admin" }] } ``` | Campo | Descrição | | --- | --- | | `role` | Papel na organização: `owner`, `admin` ou `member`. | | `isAdmin` | `true` para `owner` e `admin`. | | `teams[].role` | Papel no time: `admin` ou `member`. | ## PATCH /api/me Atualiza o perfil. Todos os campos são opcionais. | Campo | Tipo | Descrição | | --- | --- | --- | | `firstName` | string, 1 a 30 | Nome | | `lastName` | string, até 30 | Sobrenome | | `timezone` | string, até 60 | Fuso IANA, por exemplo `America/Sao_Paulo` | | `language` | `pt`, `en`, `es`, `fr`, `de`, `it`, `nl`, `ja`, `ko`, `zh`, `id`, `tr`, `pl`, `ru` | Idioma do app, das mensagens de erro da API, dos e-mails e das respostas dos agentes. Docs, guias e termos existem em `pt`, `en` e `es`; nos outros idiomas, aparecem em inglês. | ```bash curl -X PATCH https://doublex.ai/api/me \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"language": "en"}' ``` Resposta: `{ "ok": true }`. ## GET /api/me/api-keys Lista a chave pessoal e as chaves de terminal da pessoa. O valor da chave nunca é devolvido, só o final. ```json { "personal": { "id": "key_0a1b2c3d4e5f", "kind": "personal", "last4": "a1b2", "createdAt": "2026-10-21T10:00:00.000Z", "lastUsedAt": "2026-10-27T13:58:02.000Z" }, "cli": [ { "id": "key_6f7e8d9c0b1a", "kind": "cli", "name": "MacBook-da-Ana", "last4": "9z8y", "createdAt": "2026-10-25T18:20:00.000Z" } ] } ``` ## DELETE /api/me/api-keys/{id} Revoga uma chave da própria pessoa: a pessoal ou a de um terminal. Ela para de funcionar na hora. Resposta: `{ "ok": true }`. Erro `404` se a chave não existe ou não é sua. > [!NOTE] > Gerar ou trocar a chave pessoal (`POST /api/me/api-keys`) só funciona pelo navegador, logado com e-mail e senha. Com uma chave de API, a rota responde `403`. Assim, uma chave vazada não consegue criar outra. --- # Agentes Crie, liste, configure e apague agentes. ## O objeto Agent ```json { "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](#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](#orcamento-do-agente). | | `color`, `avatar` | Cor e robô do agente. Veja [Criar](#post-api-agents). | | `scope`, `teamId` | Quem vê e usa o agente. Veja [Escopos](/docs/api/visao-geral#escopos-e-permissoes). | ## 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. | ```bash title="curl" curl "https://doublex.ai/api/agents?mine=1" -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex agents list --mine --json ``` 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. | ```bash title="curl" 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" }' ``` ```bash title="CLI" doublex agents create --name "Analista de CRM" --instructions-file instrucoes.md --emoji 📊 ``` 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`](#patch-api-agents-id) logo depois. **A partir de um template.** Mande só `{ "templateKey": "" }`. 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. ```json { "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. | ```bash title="curl" 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"] }' ``` ```bash title="CLI" doublex agents update agt_8f3a2b1c9d0e --model anthropic/claude-sonnet-5-5 --effort high \ --args-json '{"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ê. > [!TIP] > Para acrescentar uma skill sem perder as outras, leia o agente com `GET`, junte o novo ID à lista e mande a lista completa. ## 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. ```json { "platform": true, "period": "2026-11", "spent": 312.4, "monthlyCredits": 500, "owner": { "id": "usr_1a2b3c4d5e6f", "name": "Ana Lima", "email": "ana@empresa.com" }, "canEdit": true, "members": [{ "id": "usr_1a2b3c4d5e6f", "name": "Ana Lima", "email": "ana@empresa.com" }] } ``` ## 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 }`. --- # Conversas Converse com agentes em streaming, continue conversas, leia o histórico e cancele execuções. Uma conversa (`task`) guarda as mensagens trocadas com um agente. Cada mensagem nova gera uma resposta em streaming, e o histórico fica no servidor: para continuar, você manda só a mensagem nova e o ID da conversa. As conversas aparecem na tela **Tarefas** do app. ## POST /api/agents/{id}/chat Manda uma mensagem ao agente e devolve a resposta em [NDJSON](/docs/api/visao-geral#streaming-ndjson). Basta poder ver o agente. | Campo | Tipo | Descrição | | --- | --- | --- | | `message` | string, 1 a 100.000 | **Obrigatório.** A mensagem. | | `taskId` | string | Continua uma conversa existente do mesmo agente. Sem ele, cria uma conversa nova. | ```bash title="curl" curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "O que os concorrentes lançaram esta semana?"}' ``` ```bash title="CLI" doublex sessions create agt_8f3a2b1c9d0e --input "O que os concorrentes lançaram esta semana?" --json ``` ```ndjson {"type":"task","taskId":"task_5d2c9a3e1f07"} {"type":"tool_start","id":"toolu_01","name":"pesquisar_web","label":"Pesquisando na web"} {"type":"tool_end","id":"toolu_01","ok":true} {"type":"text","delta":"Encontrei 3 lançamentos. "} {"type":"text","delta":"O mais relevante é…"} {"type":"done","status":"completed"} ``` ### Eventos do streaming | `type` | Campos | Quando | | --- | --- | --- | | `task` | `taskId` | Primeiro evento: o ID da conversa criada ou continuada. Guarde-o. | | `text` | `delta` | Um pedaço do texto da resposta. Junte os `delta` na ordem. | | `thinking` | `delta` | Um pedaço do raciocínio do modelo, quando o modelo o expõe. | | `tool_start` | `id`, `name`, `label` | O agente começou a usar uma ferramenta. `label` é um nome legível. | | `tool_end` | `id`, `ok` | A ferramenta terminou. `ok: false` se falhou. | | `notice` | `message` | Aviso que não interrompe: conector que precisa ser reconectado, modelo reserva usado, conversa cancelada. | | `error` | `message` | Falha que interrompe a resposta. | | `done` | `status` | Último evento: `completed` ou `failed`. | Trate sempre o fim pelo evento `done`. Alguns problemas aparecem só no streaming, com status HTTP `200`, antes mesmo do evento `task`: créditos esgotados, modelo sem chave configurada ou conversa ainda respondendo à mensagem anterior. Nesses casos você recebe `error` seguido de `done` com `failed`. ```ndjson {"type":"error","message":"Os créditos da organização acabaram."} {"type":"done","status":"failed"} ``` ### Continuar uma conversa ```bash curl -N https://doublex.ai/api/agents/agt_8f3a2b1c9d0e/chat \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"message": "Monte uma tabela comparando com os nossos produtos", "taskId": "task_5d2c9a3e1f07"}' ``` Uma conversa responde uma mensagem por vez. Para trabalhar em paralelo, abra conversas diferentes. ### Se a conexão cair Fechar a conexão **não** para o agente: ele termina o trabalho no servidor e salva a resposta na conversa. Para recuperar o resultado, use [`GET /api/tasks/{id}`](#get-api-tasks-id). Para parar de verdade, use [`cancel`](#post-api-tasks-id-cancel). ## GET /api/tasks Lista as conversas que você pode ver, das mais novas para as mais antigas, sem as mensagens. | Query | Descrição | | --- | --- | | `agentId` | Só as conversas de um agente. | | `status` | `processing`, `completed` ou `failed`. | | `source` | Origem: `chat`, `trigger`, `webhook` ou `subagent`. | ```bash title="curl" curl "https://doublex.ai/api/tasks?agentId=agt_8f3a2b1c9d0e&status=failed" -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex sessions list --agent agt_8f3a2b1c9d0e --status failed --json ``` ```json { "tasks": [ { "id": "task_5d2c9a3e1f07", "agentId": "agt_8f3a2b1c9d0e", "agentName": "Analista de CRM", "title": "Lançamentos dos concorrentes", "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" } ] } ``` Conversas que falharam trazem `error` e, quando for o caso, `errorCode`: `cancelled` (interrompida) ou `refused` (o modelo recusou). Conversas criadas por gatilho trazem `triggerId`. ## GET /api/tasks/{id} Devolve a conversa, as mensagens e se o agente ainda está trabalhando. ```json { "task": { "id": "task_5d2c9a3e1f07", "status": "completed", "...": "..." }, "items": [ { "kind": "user", "text": "O que os concorrentes lançaram esta semana?" }, { "kind": "tool", "id": "toolu_01", "name": "pesquisar_web", "ok": true }, { "kind": "assistant", "text": "Encontrei 3 lançamentos…" } ], "running": false } ``` `items[].kind` pode ser `user`, `assistant`, `thinking` ou `tool`. Para esperar o fim de uma conversa sem streaming, consulte esta rota até `running` ser `false`. ## PATCH /api/tasks/{id} Renomeia a conversa ou muda a marcação de não lida. | Campo | Tipo | | --- | --- | | `title` | string, 1 a 120 | | `unread` | boolean | Resposta: `{ "ok": true }`. ## POST /api/tasks/{id}/cancel Interrompe o agente. A conversa termina como `failed`, com `errorCode: "cancelled"`. O que já foi processado é cobrado. ```bash title="curl" curl -X POST https://doublex.ai/api/tasks/task_5d2c9a3e1f07/cancel -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex sessions cancel task_5d2c9a3e1f07 ``` Resposta: `{ "cancelled": true }`. Erro `409` se a conversa não está rodando. ## DELETE /api/tasks/{id} Apaga a conversa e o histórico dela. Resposta: `{ "ok": true }`. --- # Chat Chame um modelo de IA direto, sem agente, com resposta inteira ou em streaming. ## POST /api/chat/completions Manda mensagens direto para um modelo, sem instruções de agente, conectores ou histórico salvo. Use para classificar, resumir, extrair dados ou gerar texto dentro dos seus sistemas. > [!NOTE] > O formato é próprio: parecido com o de outras APIs de chat, mas não igual. O sistema vai em `system`, o limite em `maxTokens` e o streaming é NDJSON. | Campo | Tipo | Descrição | | --- | --- | --- | | `messages` | array, 1 a 200 | **Obrigatório.** Itens `{ "role": "user" \| "assistant", "content": "texto" }`. | | `model` | string | `provedor/modelo`, por exemplo `anthropic/claude-sonnet-5.5`. Sem ele, usa o padrão: o DoubleX Auto (`openrouter/auto`) nas organizações com créditos da plataforma. Veja os IDs em [Modelos](/docs/api/modelos-e-creditos). | | `system` | string | Instrução de sistema. | | `maxTokens` | número, 1 a 128.000 | Limite de tokens da resposta. | | `temperature` | número, 0 a 2 | | | `stream` | boolean | `true` para receber em partes. Padrão `false`. | ### Resposta inteira ```bash title="curl" curl -X POST https://doublex.ai/api/chat/completions \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "system": "Responda só com Positivo, Negativo ou Neutro.", "messages": [{ "role": "user", "content": "Adorei o atendimento, resolveram rápido." }] }' ``` ```python title="Python" import os, requests res = requests.post( "https://doublex.ai/api/chat/completions", headers={"Authorization": f"Bearer {os.environ['DOUBLEX_API_KEY']}"}, json={ "system": "Responda só com Positivo, Negativo ou Neutro.", "messages": [{"role": "user", "content": "Adorei o atendimento, resolveram rápido."}], }, ) res.raise_for_status() print(res.json()["text"]) ``` ```bash title="CLI" doublex chat "Adorei o atendimento, resolveram rápido." \ -s "Responda só com Positivo, Negativo ou Neutro." --no-stream --json ``` ```json { "provider": "openrouter", "model": "openrouter/auto", "servedModel": "google/gemini-3.8-flash", "text": "Positivo", "usage": { "inputTokens": 31, "outputTokens": 2, "costUsd": 0.00002 } } ``` `servedModel` é o modelo que de fato respondeu (útil com o DoubleX Auto). ### Streaming Com `"stream": true`, a resposta chega em NDJSON: ```ndjson {"type":"delta","text":"Posi"} {"type":"delta","text":"tivo"} {"type":"done","provider":"openrouter","model":"openrouter/auto","servedModel":"google/gemini-3.8-flash","text":"Positivo","usage":{"inputTokens":31,"outputTokens":2,"costUsd":0.00002}} ``` | `type` | Campos | | --- | --- | | `delta` | `text`: o próximo pedaço da resposta. | | `done` | A resposta completa, com `text`, `usage` e o modelo usado. | | `error` | `error`: a mensagem de erro. | Se você fechar a conexão no meio, a chamada ao modelo também é cancelada. ### Erros | Status | `code` | Quando | | --- | --- | --- | | `400` | `no_provider` | Não há modelo disponível para você. | | `400` | `model_unavailable` | O modelo pedido não está no catálogo ou não está liberado. | | `402` | `no_credits` | Os créditos da organização acabaram. | | `402` | `plan_required` | A organização ainda não escolheu um plano. | | `502` | `provider_error` | O provedor do modelo falhou. No streaming, chega como evento `error`. | Cada chamada consome créditos pelo custo do modelo e aparece no relatório de **Uso e créditos** com origem **Terminal (CLI)**. --- # Modelos e créditos Catálogo de modelos com preço em créditos, provedores disponíveis, saldo e consumo da organização. ## GET /api/models/catalog Catálogo dos modelos da plataforma, com o preço de cada um em créditos. ```bash title="curl" curl https://doublex.ai/api/models/catalog -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex models list --json ``` ```json { "platform": true, "ready": true, "autoModel": "openrouter/auto", "policy": { "autoAllowed": ["anthropic/*", "openai/*", "google/*"], "autoCostTier": "medium" }, "models": [ { "id": "anthropic/claude-sonnet-5.5", "name": "Claude Sonnet 5.5", "vendor": "anthropic", "contextLength": 1000000, "inputCreditsPerMillion": 300, "outputCreditsPerMillion": 1500, "description": "…" } ] } ``` | Campo | Descrição | | --- | --- | | `platform` | `true` quando a organização usa os modelos da plataforma, cobrados em créditos. Se for `false`, a instalação usa chaves próprias de provedor: veja [`GET /api/providers`](#get-api-providers). | | `autoModel` | O ID do **DoubleX Auto**, que escolhe o modelo a cada mensagem. | | `policy` | As famílias e a faixa de custo que o DoubleX Auto pode usar, definidas pela organização na tela **Modelos**. | | `models[].id` | O valor para usar em `model` no [Chat](/docs/api/chat) e nos [gatilhos](/docs/api/gatilhos). | | `models[].inputCreditsPerMillion`, `outputCreditsPerMillion` | Preço em créditos por milhão de tokens de entrada e de saída. | Para usar um modelo do catálogo num agente, mande `provider: "openrouter"` e `model` com o ID do catálogo no [`PATCH` do agente](/docs/api/agentes#patch-api-agents-id), ou use `doublex agents update --model `. ## GET /api/providers Nas instalações em que cada organização usa as próprias chaves de provedor, lista os provedores, se cada um está pronto para você e os modelos disponíveis. Nunca devolve as chaves. ```json { "providers": [ { "id": "anthropic", "label": "Anthropic", "ready": true, "scope": "organization", "models": [{ "id": "claude-sonnet-5-5", "label": "Claude Sonnet 5.5" }], "suggestedModels": [] } ] } ``` Use `id` do provedor e `id` do modelo juntos (`anthropic/claude-sonnet-5-5`) no Chat e nos agentes. ## GET /api/credits Saldo e consumo de créditos. | Query | Descrição | | --- | --- | | `month` | Mês no formato `AAAA-MM`. Padrão: o mês atual. | | `agent` | Só o consumo de um agente. | | `source` | Só o consumo de uma origem (por exemplo, `cli`). | ```bash title="curl" curl "https://doublex.ai/api/credits?month=2026-10" -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex credits --month 2026-10 --json ``` ```json { "platform": true, "month": "2026-10", "balance": 48210, "spent": 1790, "byAgent": [{ "id": "agt_8f3a2b1c9d0e", "name": "Analista de CRM", "credits": 920, "count": 41 }], "bySource": [], "byModel": [], "daily": [], "entries": [] } ``` | Campo | Descrição | | --- | --- | | `balance` | Saldo atual da organização. | | `spent` | Créditos consumidos no período. | | `byAgent`, `bySource`, `byModel`, `daily` | Consumo agrupado. | | `entries` | Lançamentos do período, 20 por página (parâmetro `page`). | Membros veem só o próprio consumo; administradores veem o da organização. Se `platform` for `false`, a instalação não usa créditos. Créditos só são adicionados pelo app, em **Configurações › Uso e créditos**. --- # Conectores Liste as conexões com apps e execute as ferramentas delas sem passar por um agente. Conectar um app novo exige login no provedor (OAuth) e é feito pela tela **Conectores**. Pela API você lista as conexões que já existem e usa as ferramentas delas. ## GET /api/connectors Lista as conexões que você pode ver, com as ferramentas de cada uma. Nenhum segredo é devolvido. ```bash title="curl" curl https://doublex.ai/api/connectors -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex mcp list --json ``` ```json { "connectors": [ { "id": "con_7a9b1c3d5e2f", "catalogId": "gmail", "name": "Gmail", "status": "connected", "accountLabel": "ana@empresa.com", "scope": "personal", "ownerId": "usr_1a2b3c4d5e6f", "tools": [ { "name": "search_emails", "description": "Busca e-mails no Gmail com a mesma sintaxe da caixa de pesquisa…", "readOnly": true }, { "name": "send_email", "description": "Envia um e-mail…", "readOnly": false } ], "canEdit": true } ] } ``` | Campo | Descrição | | --- | --- | | `catalogId` | O app no catálogo (`gmail`, `slack`, `hubspot`, `postgres`…). Conectores MCP personalizados não têm. | | `status` | `connected`, `needs_auth` (reconecte na tela Conectores) ou `error`. | | `tools[].readOnly` | `true` se a ferramenta só consulta; `false` se altera algo no app. | | `scope` | Quem usa a conexão: `personal`, `team` ou `organization`. | A resposta traz também o catálogo de apps disponíveis (`catalog`) e as categorias. ## GET /api/connectors/{id} Devolve uma conexão: `{ "connector": {...} }`. Erro `404` se ela não existe ou você não pode vê-la. ## POST /api/connectors/{id}/call Executa uma ferramenta da conexão. | Campo | Tipo | Descrição | | --- | --- | --- | | `tool` | string | **Obrigatório.** Nome da ferramenta, como aparece em `tools[].name`. | | `arguments` | objeto | Argumentos da ferramenta. Padrão `{}`. | ```bash title="curl" curl -X POST https://doublex.ai/api/connectors/con_7a9b1c3d5e2f/call \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"tool": "search_emails", "arguments": {"query": "is:unread newer_than:1d", "max_results": 5}}' ``` ```bash title="CLI" doublex mcp call gmail search_emails --args-json '{"query": "is:unread newer_than:1d", "max_results": 5}' --json ``` ```json { "text": "5 e-mails encontrados:\n1. De: …", "isError": false } ``` O resultado vem como texto em `text` (até 20.000 caracteres). Quando a própria ferramenta falha (argumento errado, item inexistente no app), a resposta é `200` com `"isError": true` e a explicação em `text`. | Status | Quando | | --- | --- | | `404` | A conexão não existe ou você não pode usá-la. | | `409` | A conexão precisa ser reconectada (`status` diferente de `connected`). | | `400` | Argumentos inválidos para uma ferramenta de banco de dados. | ### Quem pode usar | Escopo | Quem usa | | --- | --- | | `personal` | Só quem conectou. Nem administradores usam a conta pessoal de outra pessoa. | | `team` | Os membros do time. | | `organization` | Todos da organização. | > [!WARNING] > Ferramentas com `readOnly: false` agem nas contas de verdade: enviam e-mails, criam eventos, alteram registros. Valide os argumentos antes de chamar. --- # Brain Notas em Markdown ligadas por [[links]], em pastas, no estilo Obsidian. Crie, edite, mova, busque e suba arquivos. O Brain funciona como um cofre do Obsidian: cada documento é uma **nota** com um caminho (`pasta/nome`), e as notas se ligam com `[[Nome da nota]]`. Arquivos enviados (PDF, Word, Excel) viram notas com o texto extraído. | Sintaxe | O que faz | | --- | --- | | `[[Nota]]`, `[[Pasta/Nota]]` | Link para outra nota. Sem pasta, vale o nome (a nota da mesma pasta tem preferência). | | `[[Nota#Título]]`, `[[Nota\|texto]]` | Link para um título da nota, ou com outro texto. | | `![[Nota]]`, `![[Nota#Título]]` | Mostra o conteúdo da outra nota (ou da seção) dentro desta. | | `#tag`, `#tag/subtag` | Tag. Também vale `tags:` nas propriedades. | | `---` no topo | Propriedades (front matter YAML), como `tags`, `aliases` e campos livres. | ## GET /api/knowledge Lista as notas que você pode ver e as pastas, sem o texto completo. ```json { "docs": [ { "id": "kno_2c4e6a8b0d1f", "title": "Política de reembolso", "name": "Política de reembolso", "folder": "Comercial", "path": "Comercial/Política de reembolso", "attachment": false, "size": 18420, "preview": "Clientes podem pedir reembolso em até 30 dias…", "tags": ["comercial"], "aliases": ["Reembolso"], "links": ["kno_7e9f1a3b5c2d"], "unresolved": ["Plano de expansão"], "scope": "organization", "ownerId": "usr_1a2b3c4d5e6f", "canEdit": true, "usedBy": [{ "id": "agt_8f3a2b1c9d0e", "name": "Suporte" }], "createdAt": "2026-10-22T11:00:00.000Z", "updatedAt": "2026-10-29T15:20:00.000Z" } ], "folders": ["Clientes", "Comercial", "Produto/Guias"] } ``` | Campo | Descrição | | --- | --- | | `name` | O título sem `.md`. É o nome usado nos links. | | `path` | `pasta/nome`, a chave completa dos links. | | `attachment` | `true` para arquivos enviados (PDF, Word, Excel, CSV, JSON, texto). | | `links` | IDs das notas para onde esta aponta. | | `unresolved` | Links para notas que ainda não existem. | | `size` | Tamanho do texto em caracteres. | | `usedBy` | Agentes que consultam a nota. | ## POST /api/knowledge Cria uma nota a partir de texto ou Markdown. | Campo | Tipo | Descrição | | --- | --- | --- | | `title` | string, 1 a 160 | **Obrigatório.** `/ \ [ ] # ^ \|` saem do nome. Se já existir uma nota com esse nome na pasta, ganha um número (`Reunião 1`). | | `content` | string, até 2 milhões de caracteres | Texto da nota. Padrão: vazio. | | `folder` | string | Pasta, como `Clientes/Reuniões`. Padrão: a raiz. | | `scope`, `teamId` | | `personal` (padrão), `team` ou `organization`. `organization` exige ser administrador. | ```bash curl -X POST https://doublex.ai/api/knowledge \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"title": "Tabela de preços 2026", "folder": "Comercial", "content": "Plano Básico: R$ 99/mês. Ver [[Política de reembolso]]."}' ``` Resposta `201`: `{ "doc": { "id": "...", "title": "Tabela de preços 2026", "folder": "Comercial" } }`. ## GET /api/knowledge/{id} Devolve a nota com o texto completo em `doc.content` e o que o painel lateral mostra: | Campo | Descrição | | --- | --- | | `properties` | As propriedades do topo da nota. | | `headings` | Os títulos (`level`, `text`, `line`). | | `outgoing` | Links de saída: `target` como escrito e `id` da nota (`null` se ainda não existe). | | `backlinks` | Notas que linkam para esta, com as linhas do link em `snippets`. | | `unlinked` | Notas que citam o nome (ou um alias) sem link. | ## PATCH /api/knowledge/{id} Edita, renomeia ou move uma nota. Exige permissão de edição. | Campo | Descrição | | --- | --- | | `content` | Novo texto. | | `title` | Novo nome. | | `folder` | Nova pasta (`""` é a raiz). | | `updateLinks` | Padrão `true`: ao renomear ou mover, os links nas outras notas que você pode editar acompanham. | ```bash curl -X PATCH https://doublex.ai/api/knowledge/kno_2c4e6a8b0d1f \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"title": "Política de reembolso e cancelamento"}' ``` Resposta: `{ "doc": { ... }, "updatedLinks": 4, "updatedNotes": 3 }`. Se já existir uma nota no caminho novo, a resposta é `409`. ## Pastas Pastas vêm das notas. Uma pasta vazia fica guardada só para quem a criou. | Rota | O que faz | | --- | --- | | `GET /api/knowledge/folders` | Lista as pastas: `{ "folders": [...] }`. | | `POST /api/knowledge/folders` | Cria uma pasta vazia: `{ "path": "Clientes/Reuniões" }`. | | `PATCH /api/knowledge/folders` | Renomeia ou move uma pasta com as subpastas: `{ "from": "Comercial", "to": "Vendas/Comercial" }`. Os links acompanham. Notas que você não pode editar ficam onde estão e entram em `skipped`. | | `DELETE /api/knowledge/folders?path=Arquivo` | Apaga uma pasta vazia. Com notas dentro, a resposta é `409`. | | `POST /api/knowledge/delete` | Exclui de uma vez notas e pastas inteiras (com subpastas e as notas de dentro): `{ "ids": ["kno_..."], "folders": ["Arquivo"], "expected": 14 }`. Não há lixeira: é definitivo. Só saem as notas que você pode editar; as outras ficam onde estão e entram em `kept`. As notas excluídas saem dos agentes que as usavam. Com `expected` (quantas notas você confirmou), a resposta é `409` se o Brain mudou nesse meio-tempo. Resposta: `{ "deleted": 14, "kept": 0, "detachedAgents": 1, "folders": [...] }`. | ## POST /api/knowledge/upload Sobe um arquivo. O texto é extraído no servidor. Corpo em `multipart/form-data`: | Campo | Descrição | | --- | --- | | `file` | **Obrigatório.** PDF, Word (`.docx`), Excel (`.xlsx`), CSV, JSON, Markdown ou texto. Até 20 MB. | | `title` | Nome. Padrão: o nome do arquivo. Nome repetido na pasta ganha um número. | | `folder` | Pasta de destino. | | `replace` | ID de uma nota existente: troca o texto dela pelo do arquivo e mantém o ID, o nome, a pasta e os agentes ligados. | | `scope` | `personal` (padrão), `team` ou `organization`. `organization` exige ser administrador. | | `teamId` | O time, quando `scope` é `team`. Você precisa ser membro. | ```bash title="curl" curl -X POST https://doublex.ai/api/knowledge/upload \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -F "file=@politica-de-reembolso.pdf" \ -F "folder=Comercial" \ -F "scope=organization" ``` ```bash title="CLI" doublex brain upload politica-de-reembolso.pdf --folder Comercial --scope organization ``` Resposta `201`: `{ "doc": { "id": "kno_2c4e6a8b0d1f", "title": "politica-de-reembolso.pdf" }, "chars": 18420 }`. Com `replace`, a resposta é `200` e traz `"replaced": true`. | Status | Quando | | --- | --- | | `413` | Arquivo maior que 20 MB. | | `422` | Formato não suportado, arquivo vazio ou corrompido, PDF só com imagens, arquivo protegido por senha. | | `403` | Você não pode criar nesse escopo. | | `404` | A nota de `replace` não existe ou você não pode editá-la. | ## GET /api/knowledge/search Busca nas notas que você pode ver. | Query | Descrição | | --- | --- | | `q` | **Obrigatório.** De 2 a 300 caracteres. | | `limit` | Quantos trechos devolver, de 1 a 50. Padrão 8. | A busca aceita os operadores do Obsidian: | Operador | Exemplo | Filtra | | --- | --- | --- | | `tag:` | `tag:#cliente` | Notas com a tag (ou uma subtag dela). | | `path:` | `path:Comercial` | Notas cujo caminho contém o texto. | | `file:` | `file:reunião` | Notas cujo nome contém o texto. | | `"..."` | `"prazo de reembolso"` | A frase exata. | | `-` | `-rascunho` | Tira as notas com a palavra. | ```bash title="curl" curl "https://doublex.ai/api/knowledge/search?q=prazo%20path%3AComercial&limit=3" -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex brain search "prazo path:Comercial" --limit 3 --json ``` ```json { "results": [ { "docId": "kno_2c4e6a8b0d1f", "title": "Política de reembolso", "score": 1, "text": "…o cliente pode pedir reembolso em até 30 dias…" } ], "notes": [ { "id": "kno_2c4e6a8b0d1f", "name": "Política de reembolso", "path": "Comercial/Política de reembolso", "score": 2, "matches": [{ "line": 2, "text": "Clientes podem pedir reembolso em até 30 dias." }] } ] } ``` `results` são trechos pontuados, a mesma busca que os agentes usam. `notes` agrupa por nota, com as linhas encontradas. Sem acentos nem maiúsculas fazendo diferença; palavras com até duas letras são ignoradas em `results`. ## DELETE /api/knowledge/{id} Apaga a nota e a tira dos agentes que a usavam. Exige permissão de edição; sem ela, a resposta é `404`. Resposta: `{ "ok": true }`. > [!TIP] > Para um agente consultar uma nota, inclua o ID em `knowledgeIds` do agente (veja [Agentes](/docs/api/agentes#patch-api-agents-id)). O agente busca trechos e também abre a nota inteira pelo nome, seguindo os `[[links]]` entre as notas anexadas. --- # Skills Crie e mantenha instruções reutilizáveis para anexar a qualquer agente. ## O objeto Skill ```json { "id": "skl_3e8f1a2b4c5d", "name": "Proposta comercial", "description": "Monta propostas comerciais no padrão da empresa, com escopo, prazos e preço.", "instructions": "# Proposta comercial\n\n1. Comece pelo problema do cliente…", "scope": "team", "teamId": "team_9c8b7a6d5e4f", "ownerId": "usr_1a2b3c4d5e6f", "canEdit": true, "usedBy": [{ "id": "agt_8f3a2b1c9d0e", "name": "Analista de CRM" }], "createdAt": "2026-10-23T09:00:00.000Z", "updatedAt": "2026-10-26T17:45:00.000Z" } ``` ## GET /api/skills Lista as skills que você pode ver: `{ "skills": [Skill, ...] }`. Para ler uma skill, filtre a lista pelo `id`. ```bash title="curl" curl https://doublex.ai/api/skills -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex skills list --json ``` ## POST /api/skills | Campo | Tipo | Descrição | | --- | --- | --- | | `name` | string, 2 a 80 | **Obrigatório.** | | `description` | string, 2 a 1024 | **Obrigatório.** Quando o agente deve usar a skill. | | `instructions` | string, 2 a 30.000 | **Obrigatório.** As instruções, em Markdown. | | `scope` | `personal`, `team`, `organization` | Padrão `personal`. | | `teamId` | string | O time, quando `scope` é `team`. | ```bash title="curl" curl -X POST https://doublex.ai/api/skills \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Proposta comercial", "description": "Monta propostas comerciais no padrão da empresa.", "instructions": "# Proposta comercial\n\n1. Comece pelo problema do cliente…" }' ``` ```bash title="CLI" doublex skills create SKILL.md ``` Resposta `201`: `{ "skill": Skill }`. ## PATCH /api/skills/{id} Altera `name`, `description` e `instructions` (todos opcionais, com os mesmos limites). Os agentes que usam a skill passam a usar a versão nova na próxima mensagem. Exige permissão de edição; sem ela, a resposta é `404`. Resposta: `{ "skill": Skill }`. ## DELETE /api/skills/{id} Apaga a skill e a tira dos agentes que a usavam. Resposta: `{ "ok": true }`. > [!TIP] > Para anexar uma skill a um agente, inclua o ID em `skillIds` do agente (veja [Agentes](/docs/api/agentes#patch-api-agents-id)). ## Pacotes de skills Além de nome, descrição e instruções, uma skill pode ter `command` (sem `/`), `invocation` (`auto`, `manual` ou `both`), `dependencyIds`, `files` e `actions`. Skills relacionadas são procedimentos carregados pelo mesmo agente; a delegação para subagentes continua separada. No assistente geral, as skills visíveis podem ser descobertas automaticamente; agentes especializados usam as anexadas e suas dependências. Arquivos novos usam `{ path, mediaType, encoding: "utf8" | "base64", content }`. Para manter um arquivo numa atualização, envie sua metadata (`path`, `mediaType`, `size`, `sha256`), que só pode referenciar arquivos já pertencentes à própria skill. Limites: 100 arquivos, 2 MB por arquivo, 10 MB por pacote; referências não consomem o limite das instruções. - `GET /api/skills/:id`: lê a skill e os índices de arquivos e ações. - `GET /api/skills/:id/files?path=references/exemplo.md`: baixa um arquivo autorizado. - `GET /api/skills/:id/package`: exporta `.skill` com `SKILL.md`, anexos e manifesto `doublex.skill.json`. Ações têm `id`, `name`, `description`, `enabled` e `kind`. Com `kind: "script"`, informe `path` e `runtime` (`python`, `node` ou `shell`). Com `kind: "connector"`, informe `connectorId` e `tool`. A ação de conexão precisa estar disponível no agente e para quem executa, respeitando também os bloqueios gerais e por agente. Importar uma skill não concede acesso a contas. Scripts recebem um objeto JSON na entrada padrão e devolvem texto ou JSON pela saída padrão. O pacote fica disponível em `/skill`, somente para leitura. A execução isolada não tem rede nem credenciais do servidor; aceita até 64 KB de entrada, limita memória a 128 MB, CPU a meio núcleo, processos a 32 e tempo a 35 segundos. Python oferece a biblioteca padrão e Node.js, seus módulos nativos; bibliotecas adicionais não são instaladas durante a execução. Há no máximo duas execuções simultâneas no servidor. No chat, `/comando pedido` chama a skill para o pedido atual. As ferramentas `listar_skills`, `usar_skill`, `ler_arquivo_skill` e `executar_acao_skill` permitem descoberta e leitura sob demanda. Cada chamada revalida acesso; dependências em círculo são rejeitadas. A conversa registra as skills, arquivos e ações usados. Skills antigas continuam funcionando. --- # Criações Liste e baixe os arquivos que os agentes criaram no computador deles. ## GET /api/artifacts Lista os arquivos dos agentes que você pode ver, mais os que foram compartilhados com você, dos mais recentes para os mais antigos. | Query | Descrição | | --- | --- | | `agentId` | Só os arquivos de um agente. | ```bash title="curl" curl "https://doublex.ai/api/artifacts?agentId=agt_8f3a2b1c9d0e" -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex artifacts list --agent agt_8f3a2b1c9d0e --json ``` ```json { "artifacts": [ { "agentId": "agt_8f3a2b1c9d0e", "agentName": "Analista de CRM", "path": "relatorios/pedidos-outubro.md", "kind": "documento", "size": 4821, "modifiedAt": "2026-10-27T09:12:00.000Z", "share": { "scope": "agent" }, "canEdit": true } ] } ``` `kind` pode ser `documento`, `planilha`, `apresentacao`, `dashboard`, `codigo` ou `outro`. `share.scope` diz quem vê o arquivo: `agent` (interno: quem vê o agente), `team` (com `teamId`), `organization` ou `public` (com `url`, o caminho do link público). `canEdit` indica se você pode editar o agente, e portanto compartilhar e apagar o arquivo. ## GET /api/artifacts/file Devolve o conteúdo de um arquivo. | Query | Descrição | | --- | --- | | `agentId` | **Obrigatório.** | | `path` | **Obrigatório.** O caminho que aparece na lista. | | `download` | Se presente, a resposta vem como anexo (`Content-Disposition: attachment`). | ```bash title="curl" curl -G https://doublex.ai/api/artifacts/file \ --data-urlencode "agentId=agt_8f3a2b1c9d0e" \ --data-urlencode "path=relatorios/pedidos-outubro.md" \ -H "Authorization: Bearer $DOUBLEX_API_KEY" -o pedidos-outubro.md ``` ```bash title="CLI" doublex artifacts download agt_8f3a2b1c9d0e relatorios/pedidos-outubro.md ``` O `Content-Type` segue a extensão (`text/html`, `text/csv`, `application/json`, `text/markdown`, `image/svg+xml`, planilhas `.xlsx`, `application/pdf`; o resto vai como texto). Páginas HTML são servidas numa área isolada, sem acesso à rede. Arquivos de texto têm até 2 MB; planilhas `.xlsx` e PDFs, até 10 MB. ## GET /api/pdf Gera o PDF (A4) de um documento `.md`, de uma página `.html` ou de uma tabela `.csv` do computador do agente, ou de uma criação viva com os dados atuais. Vale a mesma permissão de ver o arquivo ou a criação; cada PDF novo consome créditos como o navegador na nuvem, e o mesmo conteúdo sai do cache sem custo. | Query | Descrição | | --- | --- | | `agentId` + `path` | Um arquivo da lista. | | `live` | Ou o id de uma criação viva (`live_…`). | ```bash title="curl" curl -G https://doublex.ai/api/pdf \ --data-urlencode "agentId=agt_8f3a2b1c9d0e" \ --data-urlencode "path=relatorios/pedidos-outubro.md" \ -H "Authorization: Bearer $DOUBLEX_API_KEY" -o pedidos-outubro.pdf ``` ## DELETE /api/artifacts/file Apaga um arquivo do computador do agente. Recebe `agentId` e `path` na query e exige permissão de edição do agente. Resposta: `{ "ok": true }`. Apagar o arquivo também desliga o link público dele. ## PUT /api/artifacts/share Muda quem pode ver um arquivo. Exige permissão de edição do agente. | Campo | Descrição | | --- | --- | | `agentId` | **Obrigatório.** | | `path` | **Obrigatório.** O caminho que aparece na lista. | | `scope` | **Obrigatório.** `agent` (interno), `team`, `organization` ou `public`. | | `teamId` | Obrigatório com `team`. Você precisa participar do time. | ```bash title="curl" curl -X PUT https://doublex.ai/api/artifacts/share \ -H "Authorization: Bearer $DOUBLEX_API_KEY" -H "Content-Type: application/json" \ -d '{"agentId":"agt_8f3a2b1c9d0e","path":"dashboards/funil.html","scope":"public"}' ``` ```json { "share": { "scope": "public", "url": "/compartilhado/Q39iOloCAPMHVs4giIb69TxY" } } ``` Time e organização abrem só o arquivo, não o agente. Com `public`, qualquer pessoa com o link vê o arquivo sem login, sempre na versão mais recente; a página e o conteúdo bruto (`/api/public/artifacts/`, com `?download` para baixar) não são indexados por buscadores. Ao trocar `public` por outro alcance, o link para de funcionar; publicar de novo gera um link novo. --- # Gatilhos Agende agentes, crie webhooks e reaja a eventos de apps. Um gatilho roda um agente sem ninguém mandar mensagem. Cada execução cria uma conversa com origem `trigger` ou `webhook`. Para criar, alterar, rodar ou apagar, você precisa poder editar o agente. O gatilho roda com a conta de **quem o criou**. ## O objeto Trigger ```json { "id": "trg_6a2c4e8b1d3f", "agentId": "agt_8f3a2b1c9d0e", "name": "Briefing das 8h", "type": "schedule", "schedule": { "kind": "cron", "expression": "0 8 * * 1-5" }, "timezone": "America/Sao_Paulo", "prompt": "Gere o briefing diário de hoje e mande no meu e-mail.", "model": null, "enabled": true, "lastRunAt": "2026-10-27T11:00:04.000Z", "nextRunAt": "2026-10-28T11:00:00.000Z", "mine": true, "createdAt": "2026-10-20T15:00:00.000Z" } ``` | `type` | Campos próprios | | --- | --- | | `schedule` | `schedule`, `timezone` | | `once` | `runAt`, `timezone` | | `webhook` | `webhookSecret` (só para quem criou o gatilho ou pode editar o agente) | | `app` | `app: { event, connectorId, params }` | ## GET /api/triggers Lista os gatilhos dos agentes que você pode ver. | Query | Descrição | | --- | --- | | `agentId` | Só os gatilhos de um agente. | Resposta: `{ "triggers": [Trigger, ...] }`. ## POST /api/triggers | Campo | Tipo | Descrição | | --- | --- | --- | | `agentId` | string | **Obrigatório.** | | `type` | `schedule`, `once`, `webhook`, `app` | **Obrigatório.** | | `name` | string, 1 a 80 | **Obrigatório.** | | `prompt` | string, até 4.000 | O que o agente deve fazer. Obrigatório, exceto com `passRawData`. Pode citar campos do evento: `{{email}}`, `{{cliente.nome}}`. | | `model` | string ou `null` | Modelo só deste gatilho (`openrouter/auto` é o DoubleX Auto). Sem ele, vale o modelo do agente. | | `timezone` | string | Fuso IANA para `schedule` e `once`. Padrão `America/Sao_Paulo`. | | `passRawData` | boolean | `webhook` e `app`: o agente recebe só o JSON do evento, sem prompt. | | `schedule` | objeto | Para `schedule`. Veja abaixo. | | `runAt` | data ISO 8601 | Para `once`. Precisa estar no futuro. | | `app` | objeto | Para `app`: `{ "event", "connectorId", "params" }`. | ### Agendado `schedule` aceita uma destas formas: | Forma | Exemplo | | --- | --- | | Cron (5 campos, intervalo mínimo de 5 minutos) | `{ "kind": "cron", "expression": "0 8 * * 1-5" }` | | Intervalo em minutos (5 a 10.080) | `{ "kind": "interval", "minutes": 30 }` | | Diário | `{ "kind": "daily", "time": "08:00" }` | | Semanal (`weekday` de 0, domingo, a 6) | `{ "kind": "weekly", "weekday": 1, "time": "09:30" }` | ```bash title="curl" curl -X POST https://doublex.ai/api/triggers \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agentId": "agt_8f3a2b1c9d0e", "type": "schedule", "name": "Briefing das 8h", "prompt": "Gere o briefing diário de hoje e mande no meu e-mail.", "schedule": { "kind": "cron", "expression": "0 8 * * 1-5" }, "timezone": "America/Sao_Paulo" }' ``` ```bash title="CLI" doublex triggers create agt_8f3a2b1c9d0e --name "Briefing das 8h" \ --prompt "Gere o briefing diário de hoje e mande no meu e-mail." --cron "0 8 * * 1-5" ``` ### Webhook ```json { "agentId": "agt_8f3a2b1c9d0e", "type": "webhook", "name": "Novo lead", "prompt": "Qualifique o lead {{nome}} ({{email}})." } ``` A resposta traz o `webhookSecret`. O endereço é `https://doublex.ai/api/webhooks/`. Veja como chamar em [Webhooks](/docs/webhooks). ### Evento de app ```json { "agentId": "agt_2b7e4c6a1f3d", "type": "app", "name": "Pedido por e-mail", "prompt": "Chegou um pedido de {{from}}: {{subject}}. Registre na planilha de pedidos.", "app": { "event": "gmail.new_email", "connectorId": "con_7a9b1c3d5e2f", "params": { "query": "subject:pedido" } } } ``` | `event` | Parâmetros | Campos para o prompt | | --- | --- | --- | | `gmail.new_email` | `query` | `from`, `to`, `subject`, `date`, `snippet`, `body`, `attachments`, `labels` | | `google-calendar.new_event` | `calendar_id` | `title`, `start`, `end`, `location`, `description`, `organizer`, `attendees`, `link` | | `google-calendar.event_starting` | `calendar_id`, `minutes_before` | os da agenda e `minutes_until` | | `google-drive.new_file` | `folder` | `name`, `mime_type`, `link`, `created_time`, `owner` | | `google-sheets.new_row` | `spreadsheet` (obrigatório), `sheet` | `row_number`, `row`, `sheet` | O conector precisa ser do mesmo serviço do evento e você precisa poder usá-lo. A plataforma consulta o app a cada dois minutos; a primeira consulta só marca o ponto de partida. Resposta `201`: `{ "trigger": Trigger }`. Os erros `400` explicam o problema: cron inválido ou frequente demais, data no passado, fuso inválido, evento ou parâmetro desconhecido, conector errado. ## GET /api/triggers/apps Os eventos de app disponíveis, com parâmetros e campos, e as suas contas Google que podem ser usadas: ```json { "events": [{ "id": "gmail.new_email", "service": "gmail", "params": [{ "name": "query", "type": "text" }], "fields": ["from", "subject", "..."] }], "accounts": [{ "id": "con_7a9b1c3d5e2f", "service": "gmail", "label": "ana@empresa.com", "status": "connected", "mine": true }] } ``` ## POST /api/triggers/generate-cron Converte uma frase em cron. | Campo | Tipo | | --- | --- | | `description` | string, 2 a 300. Por exemplo, `"toda sexta às 17h30"`. | | `timezone` | string, opcional | ```json { "cron": "30 17 * * 5", "description": "Toda sexta-feira às 17:30" } ``` Se `description` já for um cron válido, ele volta direto. Senão, um modelo de IA faz a conversão e consome créditos. Erros: `422` se a frase não vira um horário válido, `402` sem créditos. ## PATCH /api/triggers/{id} Altera `name`, `prompt`, `model` (`null` volta ao modelo do agente), `passRawData`, `timezone`, `enabled`, `schedule`, `runAt` ou `app`. O `type` não muda: para trocar, apague e crie outro. ```bash curl -X PATCH https://doublex.ai/api/triggers/trg_6a2c4e8b1d3f \ -H "Authorization: Bearer $DOUBLEX_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": false}' ``` Resposta: `{ "trigger": Trigger }`. ## POST /api/triggers/{id}/run Roda o gatilho agora, em segundo plano. - Gatilhos `schedule`, `once` e `webhook`: resposta `202` `{ "started": true }`. Acompanhe a execução em [`GET /api/tasks?agentId=...`](/docs/api/conversas#get-api-tasks). - Gatilhos `app`: consulta o app na hora e responde `200` `{ "checked": true, "found": 2 }`. Erros: `402` sem plano ativo (`plan_required`), sem créditos (`no_credits`) ou com o agente sem orçamento no mês (`agent_budget`); `409` se a execução anterior ainda não terminou; `503` se o agente não tem modelo disponível. ## DELETE /api/triggers/{id} Resposta: `{ "ok": true }`. ## POST /api/webhooks/{id} O endereço público dos gatilhos `webhook`. Não usa chave de API: o segredo vai no cabeçalho `x-webhook-secret`. Responde `202` `{ "accepted": true }`. Veja [Webhooks](/docs/webhooks). --- # Times Liste os times da organização, os membros e o seu papel em cada um. ## GET /api/teams Lista todos os times da organização. ```bash title="curl" curl https://doublex.ai/api/teams -H "Authorization: Bearer $DOUBLEX_API_KEY" ``` ```bash title="CLI" doublex teams list --json ``` ```json { "teams": [ { "id": "team_9c8b7a6d5e4f", "name": "Comercial", "emoji": "💼", "color": "azul", "isDefault": false, "myRole": "admin", "members": [ { "userId": "usr_1a2b3c4d5e6f", "name": "Ana Souza", "email": "ana@empresa.com", "role": "admin", "joinedAt": "2026-10-20T13:10:00.000Z" } ], "resources": { "agents": 4, "skills": 2, "knowledge": 11 }, "createdAt": "2026-10-20T13:05:00.000Z" } ] } ``` | Campo | Descrição | | --- | --- | | `myRole` | O seu papel no time: `admin`, `member` ou `null` se você não participa. | | `resources` | Quantos agentes, skills e documentos do Brain estão no escopo do time. | Use o `id` do time como `teamId` ao criar itens com `scope: "team"`. Criar times, mudar membros e convidar pessoas é feito pelo app, em **Configurações › Times**. --- # Visão geral Use agentes, conversas, modelos, conectores, Brain, skills, criações e gatilhos direto do shell. `doublex` é a linha de comando do DoubleX Agentes. Você entra uma vez e, a partir daí, conversa com agentes, chama modelos, usa as ferramentas dos conectores, alimenta o Brain e gerencia skills e gatilhos pelo terminal. Todo comando tem a opção `--json`, para você encadear o resultado em scripts, cron jobs ou qualquer outra ferramenta. ## Instalação ```bash curl -fsSL https://doublex.ai/cli/install.sh | sh ``` O instalador: - confere se o Node.js 18 ou mais novo está instalado (a CLI é um único arquivo JavaScript, sem dependências); - coloca o comando em `~/.doublex/bin` e cria o atalho `~/.local/bin/doublex`, sem `sudo`; - grava o endereço deste app como padrão em `~/.config/doublex/config.json`. Instalar de novo a partir de outro endereço troca o padrão, e o `doublex login --base-url` também. Confira a instalação e mantenha a CLI atualizada: ```bash doublex --version doublex update # baixa a versão mais nova deste servidor ``` | Variável do instalador | Padrão | Para quê | | --- | --- | --- | | `DOUBLEX_HOME` | `~/.doublex` | Pasta da instalação | | `DOUBLEX_BIN_DIR` | `~/.local/bin` | Onde fica o atalho `doublex` | ### Sistemas suportados A CLI roda no **macOS** e no **Linux**. No Windows, use o [WSL](https://learn.microsoft.com/windows/wsl/install) e instale dentro da distribuição Linux. A chave fica no chaveiro do sistema: no macOS, as **Chaves (Keychain)**, que já vêm instaladas; no Linux, o Secret Service, pelo comando `secret-tool`: ```bash sudo apt install libsecret-tools gnome-keyring # Debian e Ubuntu sudo dnf install libsecret gnome-keyring # Fedora ``` Em servidores e contêineres sem chaveiro, não use o `doublex login`: passe a chave pela variável `DOUBLEX_API_KEY` (veja [Autenticação](/docs/cli/autenticacao#variaveis-de-ambiente)). ## Entrar ```bash doublex login ``` O navegador abre na tela de autorização do app. Clique em **Permitir** e volte para o terminal. Os detalhes, inclusive como entrar num servidor remoto, estão em [Autenticação](/docs/cli/autenticacao). ## Primeiro comando ```bash doublex agents list ``` Escolha um agente e converse: ```bash doublex sessions create agt_8f3a2b1c9d0e --input "Quais reuniões eu tenho amanhã?" ``` Todo comando segue o formato `doublex `. Use `--help` em qualquer grupo para ver as opções: ```bash doublex triggers --help ``` ## Comandos | Comando | O que faz | | --- | --- | | [`doublex login` / `logout` / `whoami`](/docs/cli/autenticacao) | Entra, sai e mostra quem está conectado. | | [`doublex agents`](/docs/cli/agentes) | Lista, mostra, cria, edita e apaga agentes. | | [`doublex sessions`](/docs/cli/conversas) | Conversa com agentes: cria, continua, mostra, cancela e apaga conversas. | | [`doublex chat`](/docs/cli/chat) | Chama um modelo direto, sem agente. | | [`doublex models` / `credits`](/docs/cli/modelos-e-creditos) | Lista os modelos e mostra o saldo e o consumo de créditos. | | [`doublex mcp`](/docs/cli/conectores) | Lista os conectores e as ferramentas deles, e executa ferramentas. | | [`doublex brain`](/docs/cli/brain) | Cria, edita, move, busca, sobe e apaga notas do Brain. | | [`doublex skills`](/docs/cli/skills) | Baixa e sobe skills como arquivos `SKILL.md`. | | [`doublex artifacts`](/docs/cli/artefatos) | Lista e baixa os arquivos que os agentes criaram. | | [`doublex triggers`](/docs/cli/gatilhos) | Cria e gerencia gatilhos agendados, únicos, por webhook e de apps. | | [`doublex teams`](/docs/cli/times) | Lista os times e os IDs deles. | | [`doublex plugin`](/docs/cli/plugin) | Ensina o Claude Code e o Codex a usar a CLI. | | `doublex update` | Atualiza a CLI para a versão do servidor. | ## Opções globais | Opção | Variável | Para quê | | --- | --- | --- | | `--json` | — | Saída em JSON (ou NDJSON, nos comandos com streaming). Use sempre que outro programa for ler a saída. | | `--base-url ` | `DOUBLEX_BASE_URL` | Endereço do app. O padrão é o do instalador. | | `-h`, `--help` | — | Ajuda do grupo. | | `-V`, `--version` | — | Versão da CLI. | | — | `DOUBLEX_API_KEY` | Chave de API. Tem prioridade sobre a chave do chaveiro. | | — | `DOUBLEX_LANG` | Idioma da CLI: `pt`, `en` ou `es`. Sem ela, a CLI segue `LANG`. | A ordem para descobrir o endereço é: `--base-url`, depois `DOUBLEX_BASE_URL`, depois o arquivo `~/.config/doublex/config.json` e, por fim, `https://doublex.ai`. ## Entrada e saída - **Tabelas para pessoas, JSON para programas.** Sem `--json`, a CLI mostra tabelas alinhadas e corta textos longos. Com `--json`, mostra tudo. - **Mensagens de progresso vão para o stderr.** O stdout fica só com o resultado, então `doublex ... --json > saida.json` grava um JSON limpo. - **Textos longos pelo stdin.** As opções que recebem texto aceitam `-` para ler do stdin (`--input -`, `--instructions -`, `--args -`). ```bash cat relatorio.md | doublex sessions create agt_8f3a2b1c9d0e --input - doublex agents list --json | jq -r '.agents[] | select(.scope == "team") | .id' ``` ## Códigos de saída | Código | Significado | | --- | --- | | `0` | Deu certo. | | `1` | Erro no comando ou na requisição (opção faltando, item não encontrado, sem permissão, JSON inválido). | | `2` | Sem credencial: não entrou, chave inválida ou sem chaveiro no sistema. | | `3` | Não deu para falar com o servidor, ou o servidor respondeu com erro `5xx`. | | `130` | Interrompido com Ctrl+C. | ## Use com agentes de programação O Claude Code, o Codex e o Cursor podem usar a CLI por você. Um comando instala as instruções: ```bash doublex plugin install ``` Veja [Agentes de programação](/docs/cli/plugin). --- # Autenticação Entre pelo navegador ou com uma chave de API. A CLI guarda a credencial no chaveiro do sistema, nunca num arquivo de texto. A CLI usa uma [chave de API](/docs/chaves-de-api) para falar com o app. Você tem duas formas de entregar essa chave: | Forma | Como | Use quando | | --- | --- | --- | | **Login pelo navegador** (recomendado) | `doublex login` | No seu computador. A CLI recebe uma chave só deste terminal, que você desconecta pelo Perfil quando quiser. | | **Chave pessoal** | `doublex login --api-key -` ou a variável `DOUBLEX_API_KEY` | Servidores, contêineres, CI e máquinas sem navegador. | ## Login pelo navegador ```bash doublex login ``` O que acontece: 1. A CLI abre um servidor local, só para esta etapa, em `http://127.0.0.1:8765`. 2. O navegador abre a página **Permitir acesso pelo terminal?** do app, com o nome deste computador e o que a CLI vai poder fazer. Se você não estiver logado, o app pede o login antes. 3. Você clica em **Permitir**. O navegador volta para o servidor local com um código de uso único. 4. A CLI troca o código por uma chave de terminal (com verificação PKCE: o código não serve para mais ninguém), confere a chave e a grava no chaveiro. ```text Abrindo o navegador para você permitir o acesso… Esperando a confirmação no navegador (até 5 minutos)… Conectado como Ana Souza (ana@empresa.com) · Empresa SA. ``` A chave de terminal aparece em **Configurações › Perfil › Terminal (CLI) › Terminais conectados**, com o nome do computador e o último uso. | Opção | Padrão | Para quê | | --- | --- | --- | | `--no-browser` | desligada | Mostra o endereço de autorização em vez de abrir o navegador. | | `--callback-port ` | `8765` | Troca a porta do servidor local, se a 8765 estiver em uso. | | `--base-url ` | o do instalador | Entra em outro endereço do app. | ### Num computador remoto (SSH) O navegador precisa conseguir voltar para a porta local da máquina onde a CLI está rodando. Encaminhe a porta pelo SSH e use `--no-browser`: ```bash ssh -L 8765:127.0.0.1:8765 voce@servidor doublex login --no-browser ``` Abra o endereço que a CLI mostrar no navegador do seu computador e clique em **Permitir**. ## Entrar com uma chave Gere a chave pessoal em **Configurações › Perfil › Acesso pela API** e passe-a pelo stdin, para ela não ficar no histórico do shell nem na lista de processos: ```bash echo "$DOUBLEX_API_KEY" | doublex login --api-key - ``` A CLI confere a chave no servidor antes de gravar. Se ela for inválida, nada é gravado. ## Verificar ```bash doublex whoami ``` ```text Ana Souza id: usr_1a2b3c4d5e6f org: Empresa SA (admin) times: Comercial, Operações url: https://doublex.ai ``` Com `--json`, o `whoami` devolve o mesmo objeto de `GET /api/me`. ## Sair ```bash doublex logout ``` O `logout` revoga a chave do terminal no servidor e a apaga do chaveiro. Se você entrou com a chave pessoal, ela só sai do chaveiro e continua valendo: revogue-a no Perfil se precisar. Você também pode desconectar qualquer terminal pela tela **Perfil**, sem acesso ao computador. ## Variáveis de ambiente As variáveis valem só para o comando em que aparecem e têm prioridade sobre o que está gravado. São o caminho para CI, contêineres e servidores sem chaveiro. | Variável | Para quê | | --- | --- | | `DOUBLEX_API_KEY` | Chave de API. Quando existe, a CLI não consulta o chaveiro. | | `DOUBLEX_BASE_URL` | Endereço do app. | | `DOUBLEX_LANG` | Idioma da CLI: `pt`, `en` ou `es`. | | `XDG_CONFIG_HOME` | Muda a pasta do arquivo de configuração (padrão `~/.config`). | ```bash title="GitHub Actions" - name: Atualizar o Brain com a documentação do produto env: DOUBLEX_API_KEY: ${{ secrets.DOUBLEX_API_KEY }} DOUBLEX_BASE_URL: https://doublex.ai run: | curl -fsSL https://doublex.ai/cli/install.sh | sh ~/.local/bin/doublex brain upload docs/*.md --scope organization ``` ## Onde a CLI guarda a credencial | Sistema | Onde | | --- | --- | | macOS | Chaves (Keychain), item `doublex-cli`, uma entrada por endereço do app | | Linux | Secret Service (GNOME Keyring ou KWallet), pelo `secret-tool`, serviço `doublex-cli` | O arquivo `~/.config/doublex/config.json` guarda só o endereço do app, nunca a chave. Com a chave no chaveiro, você pode ter logins em mais de um endereço (por exemplo, produção e um ambiente de testes) e escolher com `--base-url`. --- # Agentes de programação Ensine o Claude Code, o Codex e outros agentes de programação a usar o DoubleX Agentes pela CLI. Agentes de programação como o Claude Code, o Codex e o Cursor rodam comandos no terminal. Com a CLI instalada e uma skill de instruções, eles conseguem conversar com seus agentes, buscar no Brain, chamar ferramentas dos conectores e criar gatilhos enquanto trabalham no seu código. ## Instalar ```bash doublex plugin install ``` O comando grava a skill `doublex-cli` nas pastas de skills dos agentes de programação que encontrar no seu computador: | Agente | Pasta | | --- | --- | | Claude Code | `~/.claude/skills/doublex-cli/SKILL.md` | | Codex | `~/.codex/skills/doublex-cli/SKILL.md` | Reinicie o agente (ou abra uma sessão nova) para ele carregar a skill. A partir daí, ele usa a CLI sempre que uma tarefa envolver o DoubleX Agentes. | Opção | Para quê | | --- | --- | | `--force` | Troca a skill se ela já existir (por exemplo, depois de `doublex update`). | | `--dir ` | Grava o pacote completo (`plugin.json` e `skills/`) em `/doublex/`, para clientes que carregam plugins de uma pasta ou para versionar no projeto. | ```bash doublex plugin install --dir .claude/plugins ``` ## O que a skill ensina - Conferir o acesso com `doublex whoami --json` e, se faltar login, pedir que você rode `doublex login`. - Usar sempre `--json` ao ler a saída e consultar `--help` antes de usar um comando, sem inventar opções. - Descobrir agentes, modelos, conectores e ferramentas antes de agir, sem adivinhar nomes. - Pedir confirmação antes de ações que mudam dados de verdade: enviar e-mails, postar mensagens, apagar itens ou chamar ferramentas de escrita dos conectores. - Nunca mostrar, registrar ou versionar a chave de API. ## Exemplos de pedidos Depois de instalar, peça em linguagem natural: - "Pergunte ao agente de suporte quais são os erros mais comuns desta semana e crie issues para os três primeiros." - "Suba a pasta `docs/` para o Brain no escopo do time de Produto." - "Crie um gatilho que roda o agente de QA toda segunda às 9h." - "Consulte no banco de BI quantos pedidos ficaram atrasados ontem." ## Ler esta documentação Agentes de programação também podem ler esta documentação inteira em texto: ```bash curl -s https://doublex.ai/docs/llms-full.txt ``` --- # Agentes Liste, inspecione, crie, edite e apague agentes pelo terminal. ```bash doublex agents list | get | create | update | delete ``` ## Listar ```bash doublex agents list doublex agents list --mine --search vendas --limit 10 ``` | Opção | Para quê | | --- | --- | | `--search ` | Filtra pelo nome e pela descrição. | | `--mine` | Só os seus agentes e os compartilhados com você. Para administradores, sem essa opção a lista traz todos os agentes da organização. | | `--limit ` | Mostra só os `n` primeiros. | | `--json` | Devolve `{ "agents": [...] }` com todos os campos. | A tabela mostra o ID, o nome, o modelo (`provedor/modelo`), o escopo, o número de conversas e se você pode editar. ## Ver um agente ```bash doublex agents get agt_8f3a2b1c9d0e ``` Mostra o modelo, o esforço de raciocínio, o escopo, a descrição, quantas skills, conectores, documentos do Brain e subagentes ele usa, e as instruções completas. Com `--json`, devolve também as conversas recentes e os gatilhos do agente. ## Criar ```bash doublex agents create \ --name "Analista de CRM" \ --description "Responde perguntas sobre o funil de vendas" \ --instructions-file instrucoes.md \ --emoji 📊 \ --model anthropic/claude-sonnet-5-5 \ --effort high ``` A CLI mostra o ID do agente criado. O agente nasce no escopo **Pessoal**; para compartilhar com um time ou com a organização, use a tela do agente. | Opção | Para quê | | --- | --- | | `--name ` | Obrigatória. Até 60 caracteres. | | `--description ` | Até 300 caracteres. | | `--instructions ` | As instruções do agente (até 20.000 caracteres). Use `-` para ler do stdin. | | `--instructions-file ` | Lê as instruções de um arquivo. | | `--emoji ` | Emoji do agente. | | `--model ` | Modelo. Use um ID de `doublex models list`, ou `auto` para o **DoubleX Auto**, que escolhe o modelo a cada mensagem. Sem ela, o agente usa o modelo padrão da organização. | | `--effort low\|medium\|high` | Esforço de raciocínio. O padrão é `medium`. | | `--args-json ` / `--args-file ` | Outros campos do corpo de criação, em JSON (por exemplo, `color` e `avatar`). As opções acima têm prioridade. | Para criar a partir de um template pronto, mande a chave do template em `--args-json`: ```bash doublex agents create --args-json '{"templateKey": "briefing-diario"}' ``` ## Editar ```bash doublex agents update agt_8f3a2b1c9d0e --model auto --effort low doublex agents update agt_8f3a2b1c9d0e --instructions-file instrucoes.md ``` Aceita `--name`, `--description`, `--instructions`, `--instructions-file`, `--model`, `--effort` e `--args-json`/`--args-file`. Só o que você passa é alterado. Com `--args-json` você altera qualquer campo da [API de agentes](/docs/api/agentes#patch-api-agents-id), por exemplo as skills, os conectores e os documentos do Brain que o agente usa: ```bash doublex agents update agt_8f3a2b1c9d0e --args-json '{ "skillIds": ["skl_3e8f1a2b4c5d"], "connectorIds": ["con_7a9b1c3d5e2f"], "knowledgeIds": ["kno_2c4e6a8b0d1f"] }' ``` > [!WARNING] > As listas (`skillIds`, `connectorIds`, `knowledgeIds`, `subagentIds`) **substituem** o valor inteiro. Para acrescentar um item, leia a lista atual com `doublex agents get --json` e mande a lista completa. Você só edita agentes em que tem permissão de edição (coluna **EDITA** da lista). ## Apagar ```bash doublex agents delete agt_8f3a2b1c9d0e --yes ``` Sem `--yes`, a CLI só avisa o que seria apagado. Apagar um agente remove também as conversas, os gatilhos e os arquivos do computador dele. --- # Conversas Converse com agentes pelo terminal, continue conversas, acompanhe o que está rodando e cancele. Uma conversa (na CLI, `session`) é uma sequência de mensagens com um agente. Ela fica no histórico da tela **Tarefas** e pode ser continuada pelo app, pela CLI ou pela API. ```bash doublex sessions list | create | send | get | cancel | delete ``` ## Começar uma conversa ```bash doublex sessions create agt_8f3a2b1c9d0e --input "Liste os pedidos atrasados desta semana" ``` A resposta aparece enquanto o agente escreve. As ferramentas que ele usa aparecem no stderr com `›`, e avisos com `!`: ```text › Buscando na base de conhecimento › Criando arquivo Encontrei 4 pedidos atrasados nesta semana: … Conversa task_5d2c9a3e1f07. Continue com: doublex sessions send task_5d2c9a3e1f07 --input "..." ``` Para mensagens longas, leia do stdin: ```bash doublex sessions create agt_8f3a2b1c9d0e --input - < pedido.md git diff | doublex sessions create agt_2b7e4c6a1f3d --input - ``` ## Continuar ```bash doublex sessions send task_5d2c9a3e1f07 --input "Mande um e-mail para cada cliente avisando o novo prazo" ``` O agente lembra de tudo o que já foi dito na conversa. Mande só a mensagem nova. ## Saída em JSON (NDJSON) Com `--json`, `create` e `send` mostram cada evento da resposta numa linha, exatamente como a [API](/docs/api/conversas#eventos-do-streaming) envia: ```bash doublex sessions create agt_8f3a2b1c9d0e --input "Oi" --json ``` ```ndjson {"type":"task","taskId":"task_5d2c9a3e1f07"} {"type":"text","delta":"Olá! "} {"type":"text","delta":"Como posso ajudar?"} {"type":"done","status":"completed"} ``` Para juntar só o texto da resposta: ```bash doublex sessions create agt_8f3a2b1c9d0e --input "Oi" --json | jq -rj 'select(.type == "text") | .delta' ``` ## Listar ```bash doublex sessions list --agent agt_8f3a2b1c9d0e --status failed --limit 20 ``` | Opção | Para quê | | --- | --- | | `--agent ` | Só as conversas de um agente. | | `--status processing\|completed\|failed` | Filtra pela situação. | | `--limit ` | Quantas mostrar (padrão 50, das mais novas para as mais antigas). | A tabela mostra o ID, o agente, o título, a situação, a origem (`chat`, `trigger`, `webhook` ou `subagent`) e a última atualização. ## Ver ```bash doublex sessions get task_5d2c9a3e1f07 ``` Mostra o título, a situação e as últimas 10 mensagens. Com `--json`, traz a conversa inteira (inclusive as ferramentas usadas) e o campo `running`, que diz se o agente ainda está trabalhando. ## Interromper e cancelar - **Ctrl+C** durante a resposta interrompe a leitura e cancela a conversa no servidor. O código de saída é `130`. - Se você só parar de ler (por exemplo, fechando o terminal), o agente continua no servidor e salva o resultado. Cancele assim: ```bash doublex sessions cancel task_5d2c9a3e1f07 ``` Uma conversa cancelada fica como **Falhou**, com o aviso de que foi interrompida. O que já foi processado é cobrado. ## Apagar ```bash doublex sessions delete task_5d2c9a3e1f07 --yes ``` ## Quando a resposta falha O comando termina com código `1` quando a resposta tem um evento `error` ou termina com `done` em `failed`: créditos esgotados, modelo indisponível, conector que precisa ser reconectado. A mensagem aparece no stderr com `✗`. Uma conversa só responde uma mensagem por vez. Se você mandar outra enquanto o agente ainda trabalha, recebe o aviso de que a conversa está em andamento. --- # Chat Chame um modelo de IA direto do terminal, sem agente, com streaming ou resposta inteira. `doublex chat` manda uma mensagem direto para um modelo, sem instruções de agente, conectores nem histórico. Use para perguntas rápidas, transformar texto em scripts ou testar um modelo. ```bash doublex chat "Explique o que é EBITDA em duas frases" -m anthropic/claude-sonnet-5.5 ``` Sem `-m`, a CLI usa o modelo padrão: o **DoubleX Auto** nas organizações com créditos da plataforma, ou o modelo padrão das suas chaves de provedor. Veja os modelos disponíveis com `doublex models list`. ## Opções | Opção | Para quê | | --- | --- | | `-m`, `--model ` | Modelo a usar. `openrouter/auto` é o DoubleX Auto. | | `-s`, `--system ` | Instrução de sistema. Pode repetir; as instruções são juntadas na ordem. | | `--message-stdin -` | Lê a mensagem do stdin. Sem mensagem no comando e com o stdin redirecionado, a CLI também lê do stdin. | | `--max-tokens ` | Limite de tokens da resposta (até 128.000). | | `--temperature ` | Temperatura, de `0` a `2`. | | `--stream` / `--no-stream` | Força a resposta em partes ou inteira. Por padrão, há streaming quando a saída é o terminal. | | `--args-file ` / `--args-json ` | Corpo da requisição em JSON (por exemplo, um histórico em `messages`). A mensagem do comando é acrescentada no fim. | | `--json` | Devolve a resposta completa (sem streaming) ou os eventos NDJSON (com `--stream`). | ## Exemplos Resumir um arquivo: ```bash doublex chat -s "Resuma em tópicos curtos, em português" < ata-da-reuniao.txt ``` Usar num script, com a resposta inteira em JSON: ```bash doublex chat "Classifique o sentimento: 'Adorei o atendimento'" --no-stream --json | jq -r .text ``` ```json { "provider": "openrouter", "model": "openrouter/auto", "text": "Positivo", "usage": { "inputTokens": 21, "outputTokens": 3, "costUsd": 0.00002 }, "servedModel": "google/gemini-3.8-flash" } ``` `servedModel` mostra o modelo que de fato respondeu quando você usa o DoubleX Auto. Continuar uma conversa a partir de um histórico: ```bash cat > historico.json <<'EOF' { "messages": [ { "role": "user", "content": "Meu nome é Ana." }, { "role": "assistant", "content": "Prazer, Ana!" } ] } EOF doublex chat "Qual é o meu nome?" --args-file historico.json ``` ## Custos Cada chamada consome créditos pelo custo do modelo, com origem **Terminal (CLI)** no relatório de **Uso e créditos**. Sem créditos, o comando termina com o erro `402`. --- # Modelos e créditos Veja os modelos de IA disponíveis, o preço de cada um e o saldo de créditos da organização. ## Modelos ```bash doublex models list ``` Nas organizações que usam os modelos da plataforma, a lista mostra o catálogo com o preço em créditos por milhão de tokens de entrada e de saída. A primeira linha é o **DoubleX Auto** (`openrouter/auto`), que escolhe o modelo a cada mensagem dentro das famílias e da faixa de custo definidas pela organização em **Modelos**. ```text MODELO NOME CRÉDITOS / MILHÃO (ENTRADA / SAÍDA) openrouter/auto DoubleX Auto o do modelo escolhido anthropic/claude-sonnet-5.5 Claude Sonnet 5.5 300 / 1500 google/gemini-3.8-flash Gemini 3.8 Flash 30 / 250 ``` Nas instalações em que cada organização usa as próprias chaves de provedor, a lista mostra os modelos dos provedores com chave pronta e de quem é a chave (pessoal, do time ou da organização). Use o valor da coluna **MODELO** em `doublex chat -m`, `doublex agents update --model` e `doublex triggers create --model`. Com `--json`, o comando devolve o catálogo inteiro, com contexto máximo, preço em dólar e descrição de cada modelo. ## Créditos ```bash doublex credits doublex credits --month 2026-09 ``` ```text Saldo: 48210 créditos Consumo em 2026-10: 1790 créditos AGENTE CRÉDITOS Analista de CRM 920 Briefing Diário 540 ``` | Opção | Para quê | | --- | --- | | `--month AAAA-MM` | Consumo de outro mês. O padrão é o mês atual. | | `--json` | Todos os detalhes: consumo por agente, por origem, por modelo e por dia, e os lançamentos. | Membros veem o próprio consumo. Administradores veem o da organização inteira. Créditos só são adicionados pela tela **Configurações › Uso e créditos**. Se a instalação não usa créditos (cada provedor com a própria chave), o comando avisa e termina. --- # Conectores Liste seus conectores, descubra as ferramentas de cada um e execute-as direto do terminal. Os conectores ligam a plataforma aos seus apps: Gmail, Google Agenda, Drive, Planilhas, Slack, HubSpot, Notion, GitHub, bancos de dados e servidores MCP. O grupo `mcp` da CLI usa as mesmas conexões dos agentes, com as suas permissões. ```bash doublex mcp list | get | tools | call ``` > [!NOTE] > Para conectar um app novo, use a tela **Conectores** do app. A CLI usa as conexões que já existem. ## Listar ```bash doublex mcp list ``` ```text ID NOME CATÁLOGO STATUS ESCOPO FERRAMENTAS CONTA con_7a9b1c3d5e2f Gmail gmail connected personal 9 ana@empresa.com con_1f3e5d7c9b2a HubSpot hubspot connected team 24 Empresa SA con_4b6d8f0a2c3e Banco de BI postgres connected team 3 bi@db.interno ``` A coluna **STATUS** mostra `connected`, `needs_auth` (precisa reconectar na tela Conectores) ou `error`. ## Ver as ferramentas Em todo comando, `` aceita o ID, o ID do catálogo (por exemplo, `gmail`) ou o nome: ```bash doublex mcp tools gmail ``` ```text NOME LEITURA DESCRIÇÃO search_emails sim Busca e-mails com a sintaxe do Gmail read_email sim Lê um e-mail completo send_email não Envia um e-mail ``` A coluna **LEITURA** diz se a ferramenta só consulta (`sim`) ou se altera algo no app (`não`). A descrição de cada ferramenta explica os argumentos que ela aceita. `doublex mcp get ` mostra os detalhes da conexão: catálogo, conta, escopo, situação e último erro. ## Executar uma ferramenta ```bash doublex mcp call gmail search_emails --args-json '{"query": "is:unread newer_than:1d", "max_results": 5}' ``` | Opção | Para quê | | --- | --- | | `--args-json ` | Argumentos da ferramenta, em JSON. | | `--args-file ` | Lê os argumentos de um arquivo JSON. | | `--args -` | Lê os argumentos do stdin. | | `--json` | Devolve `{ "text": "...", "isError": false }`. | A CLI mostra o texto que a ferramenta devolveu (até 20.000 caracteres). Se a própria ferramenta acusar erro, o comando termina com código `1`. > [!WARNING] > Ferramentas de escrita (enviar e-mail, criar evento, apagar arquivo, atualizar o CRM) agem nas suas contas de verdade. Teste antes com ferramentas de leitura. ## Quem pode usar cada conexão | Escopo da conexão | Quem usa | | --- | --- | | Pessoal | Só a pessoa que conectou. | | Time | Os membros do time. | | Organização | Todas as pessoas da organização. | Uma conexão pessoal de outra pessoa nunca é usada no seu lugar, nem por administradores. Se a ferramenta precisar da sua conta, conecte o app na tela **Conectores**. ## Bancos de dados Os conectores PostgreSQL e MySQL têm quatro ferramentas: | Ferramenta | O que faz | | --- | --- | | `list_tables` | Lista as tabelas. | | `describe_table` | Mostra as colunas de uma tabela. | | `query` | Roda uma consulta de leitura (`SELECT`, `WITH`, `SHOW`, `EXPLAIN`), em transação somente leitura, por até 20 segundos. Argumentos: `sql` e `limit` (opcional). | | `execute` | Roda um comando que altera dados. Só existe quando a conexão foi criada com escrita liberada. | ```bash doublex mcp call "Banco de BI" query --args-json '{"sql": "select status, count(*) from pedidos group by status"}' ``` --- # Brain Crie e edite notas, organize pastas, suba arquivos e busque no Brain pela linha de comando. O Brain guarda o que os agentes consultam: manuais, políticas, tabelas de preço, atas, contratos. Ele funciona como um cofre do Obsidian: notas em Markdown, em pastas, ligadas por `[[Nome da nota]]`. Pela CLI você mantém o Brain atualizado a partir de pastas, repositórios e jobs. ```bash doublex brain list | folders | get | search | create | update | upload | delete ``` ## Criar e editar notas ```bash doublex brain create "Reunião com a Acme" --folder Clientes/Reuniões --content "Próximos passos com a [[Acme]]. #reuniao" cat ata.md | doublex brain create "Ata 29/10" --folder Atas --content - doublex brain update kno_2c4e6a8b0d1f --content-file politica.md ``` | Opção | Para quê | | --- | --- | | `--folder ` | Pasta da nota, como `Clientes/Reuniões`. O padrão é a raiz. | | `--content ` | Texto da nota. Use `-` para ler do stdin ou `--content-file `. | | `--scope`, `--team-id` | Quem pode ver a nota (só ao criar). O padrão é `personal`. | Se já existir uma nota com o mesmo nome na pasta, a nova ganha um número (`Ata 29/10 1`). ## Renomear e mover ```bash doublex brain update kno_2c4e6a8b0d1f --title "Política de reembolso e cancelamento" doublex brain update kno_2c4e6a8b0d1f --folder Comercial/Políticas ``` Os links das outras notas que você pode editar acompanham a mudança, como no Obsidian. A CLI mostra quantos links mudaram. Use `--no-update-links` para não mexer nelas. ## Subir arquivos ```bash doublex brain upload politica-de-reembolso.pdf --folder Comercial doublex brain upload docs/*.md --scope team --team-id team_9c8b7a6d5e4f doublex brain upload contrato.docx --title "Contrato padrão 2026" doublex brain upload manual.pdf --replace kno_7e9f1a3b5c2d ``` | Opção | Para quê | | --- | --- | | `--folder ` | Pasta de destino. | | `--scope personal\|team\|organization` | Quem pode ver. O padrão é `personal`. `organization` exige ser administrador. | | `--team-id ` | O time, quando o escopo é `team`. Veja os IDs com `doublex teams list`. | | `--title ` | Nome da nota (só quando você sobe um arquivo). O padrão é o nome do arquivo. | | `--replace ` | Troca o texto de uma nota existente pelo do arquivo. O ID, o nome e os agentes ligados continuam. | Formatos aceitos: **PDF**, **Word** (`.docx`), **Excel** (`.xlsx`), **CSV**, **JSON**, **Markdown** e **texto**. Cada arquivo pode ter até 20 MB. PDFs escaneados (só imagem) e arquivos protegidos por senha são recusados, porque não têm texto para extrair. ## Buscar ```bash doublex brain search "prazo de reembolso" --limit 5 doublex brain search "tag:#cliente plano" doublex brain search "path:Comercial \"30 dias\" -rascunho" ``` A busca não diferencia acentos e maiúsculas e mostra os trechos mais relevantes com a nota de origem. É a mesma busca que os agentes usam. Os operadores `tag:`, `path:`, `file:`, `"frase exata"` e `-palavra` filtram as notas, como no Obsidian. ## Listar, ler e apagar ```bash doublex brain list doublex brain list --folder Clientes doublex brain folders doublex brain get kno_2c4e6a8b0d1f > politica.md doublex brain delete kno_2c4e6a8b0d1f --yes ``` `list` mostra o caminho, o tamanho em caracteres, o escopo e quantos agentes usam cada nota. `get` imprime o texto. `delete` também tira a nota dos agentes que a usavam. ## Ligar uma nota a um agente Subir uma nota não basta: o agente só consulta as notas ligadas a ele. Ligue pela tela do agente ou pela CLI: ```bash doublex agents update agt_8f3a2b1c9d0e --args-json '{"knowledgeIds": ["kno_2c4e6a8b0d1f", "kno_7e9f1a3b5c2d"]}' ``` O agente busca trechos e também abre a nota inteira pelo nome, seguindo os `[[links]]` entre as notas ligadas a ele. ## Manter o Brain em dia Um exemplo de job que troca o texto de um manual toda vez que ele muda, sem mudar o ID (os agentes continuam ligados): ```bash #!/bin/sh set -e ID=$(doublex brain list --json | jq -r '.docs[] | select(.path == "Manuais/manual.pdf") | .id') if [ -n "$ID" ]; then doublex brain upload manual.pdf --replace "$ID" else doublex brain upload manual.pdf --folder Manuais --scope organization fi ``` --- # Skills Mantenha skills como arquivos SKILL.md, no Git, e sincronize com a plataforma. Uma skill é um conjunto de instruções reutilizável que você anexa a qualquer agente: o passo a passo de uma proposta comercial, o tom de voz da marca, o checklist de uma auditoria. Pela CLI, cada skill vira um arquivo `SKILL.md`, que você versiona no Git e edita no seu editor. ```bash doublex skills list | get | download | create | update | delete ``` ## O formato SKILL.md ```markdown --- name: Proposta comercial description: Monta propostas comerciais no padrão da empresa, com escopo, prazos e preço. --- # Proposta comercial 1. Comece pelo problema do cliente, com as palavras dele. 2. Liste o escopo em entregas verificáveis. ... ``` | Campo | Regra | | --- | --- | | `name` | De 2 a 80 caracteres. Sem ele, a CLI usa o primeiro título `#` ou o nome do arquivo. | | `description` | **Obrigatória**, de 2 a 1024 caracteres (o mesmo limite das skills do Claude). É o que o agente lê para saber quando usar a skill. | | Corpo | As instruções, de 2 a 30.000 caracteres. | ## Baixar ```bash doublex skills list --search proposta doublex skills get skl_3e8f1a2b4c5d # mostra como SKILL.md doublex skills download skl_3e8f1a2b4c5d -o skills/proposta/ ``` `-o` aceita um arquivo, uma pasta que já exista (grava `SKILL.md` dentro dela) ou `-` (stdout). Sem `-o`, grava `SKILL.md` na pasta atual. ## Criar ```bash doublex skills create skills/proposta/SKILL.md doublex skills create SKILL.md --scope team --team-id team_9c8b7a6d5e4f ``` | Opção | Para quê | | --- | --- | | `--name`, `--description` | Trocam os valores do arquivo. | | `--scope personal\|team\|organization` | Quem vê e usa a skill. O padrão é `personal`. | | `--team-id ` | O time, quando o escopo é `team`. | ## Atualizar ```bash doublex skills update skl_3e8f1a2b4c5d skills/proposta/SKILL.md ``` Troca o nome, a descrição e as instruções pelo conteúdo do arquivo. Os agentes que usam a skill passam a usar a versão nova na próxima mensagem. ## Apagar ```bash doublex skills delete skl_3e8f1a2b4c5d --yes ``` Apagar uma skill também a tira dos agentes que a usavam. ## Anexar a um agente ```bash doublex agents update agt_8f3a2b1c9d0e --args-json '{"skillIds": ["skl_3e8f1a2b4c5d"]}' ``` --- # Criações Liste e baixe os arquivos que os agentes criaram no computador deles. Cada agente tem um computador próprio, onde grava relatórios, planilhas em CSV, páginas HTML, dashboards e outros arquivos. Esses arquivos aparecem na tela **Criações**. ```bash doublex artifacts list | download ``` ## Listar ```bash doublex artifacts list doublex artifacts list --agent agt_8f3a2b1c9d0e ``` ```text AGENTE CAMINHO BYTES ALTERADO agt_8f3a2b1c9d0e relatorios/pedidos-outubro.md 4821 2026-10-27 09:12 agt_8f3a2b1c9d0e dashboards/funil.html 18304 2026-10-26 18:40 ``` Aparecem os arquivos dos agentes que você pode ver, dos mais recentes para os mais antigos. ## Baixar ```bash doublex artifacts download agt_8f3a2b1c9d0e relatorios/pedidos-outubro.md doublex artifacts download agt_8f3a2b1c9d0e dashboards/funil.html -o ~/Downloads/ doublex artifacts download agt_8f3a2b1c9d0e dados/pedidos.csv -o - | head ``` `-o` aceita um arquivo, uma pasta que já exista ou `-` (stdout). Sem `-o`, a CLI grava com o nome original na pasta atual. Cada arquivo pode ter até 2 MB. Os agentes criam arquivos de texto: Markdown, HTML, CSV, JSON, SVG e código. --- # Gatilhos Faça os agentes trabalharem sozinhos, num horário, uma única vez, por webhook ou quando algo acontece num app. Um gatilho roda um agente sem ninguém mandar mensagem. Cada execução vira uma conversa na tela **Tarefas**, com origem **Gatilho** ou **Webhook**. ```bash doublex triggers list | create | update | run | delete | apps ``` > [!NOTE] > Para criar, editar, rodar ou apagar gatilhos, você precisa poder editar o agente. O gatilho roda com a conta de **quem o criou**: usa os conectores e as permissões dessa pessoa. ## Tipos | Tipo | Opção | Quando roda | | --- | --- | --- | | Agendado | `--cron ""` ou `--describe ""` | Num horário recorrente. | | Único | `--once ` | Uma vez, no horário marcado. | | Webhook | `--webhook` | Quando outro sistema chama o endereço do gatilho. Veja [Webhooks](/docs/webhooks). | | De app | `--app --connector ` | Quando chega um e-mail, nasce um evento na agenda, aparece um arquivo no Drive ou uma linha nova na planilha. | ## Agendado ```bash doublex triggers create agt_8f3a2b1c9d0e --name "Briefing das 8h" \ --prompt "Gere o briefing diário de hoje e mande no meu e-mail" \ --cron "0 8 * * 1-5" --timezone America/Sao_Paulo ``` A expressão cron tem 5 campos (minuto, hora, dia do mês, mês, dia da semana). O intervalo mínimo é de 5 minutos. Prefere escrever em português? Use `--describe` e o servidor converte a frase em cron: ```bash doublex triggers create agt_8f3a2b1c9d0e --name "Relatório semanal" \ --prompt "Monte o relatório de vendas da semana" \ --describe "toda sexta às 17h30" ``` ```text cron: 30 17 * * 5 trg_6a2c4e8b1d3f ``` A conversão usa um modelo de IA e consome alguns créditos. Também funcionam os formatos simples `--every `, `--daily HH:MM` e `--weekly @HH:MM` (dia de `0`, domingo, a `6`, sábado). ## Único ```bash doublex triggers create agt_8f3a2b1c9d0e --name "Lembrete da renovação" \ --prompt "Confira se o contrato da Empresa SA foi renovado e me avise" \ --once "2026-11-03T14:00" ``` A data precisa estar no futuro. Sem fuso na data, a CLI usa o fuso do seu computador; para fixar outro, inclua o deslocamento, como em `2026-11-03T14:00-03:00`. ## Webhook ```bash doublex triggers create agt_8f3a2b1c9d0e --name "Novo lead" --webhook \ --prompt "Chegou um lead: {{nome}} ({{email}}). Qualifique e registre no CRM." ``` A CLI mostra o endereço e o segredo do webhook. Com `--raw`, o agente recebe só o JSON do corpo, sem prompt. ## De app Veja os eventos disponíveis e as suas contas conectadas: ```bash doublex triggers apps ``` | Evento | Dispara quando | Parâmetros | | --- | --- | --- | | `gmail.new_email` | Chega um e-mail | `query`: filtro do Gmail, por exemplo `from:cliente.com is:unread` | | `google-calendar.new_event` | Um evento novo aparece na agenda | `calendar_id` (padrão `primary`) | | `google-calendar.event_starting` | Um evento vai começar | `calendar_id`, `minutes_before` (padrão `15`) | | `google-drive.new_file` | Um arquivo novo aparece no Drive | `folder`: pasta a observar | | `google-sheets.new_row` | Uma linha nova aparece na planilha | `spreadsheet` (obrigatório), `sheet` | ```bash doublex triggers create agt_2b7e4c6a1f3d --name "Pedido por e-mail" \ --app gmail.new_email --connector con_7a9b1c3d5e2f --param "query=subject:pedido is:unread" \ --prompt "Chegou um pedido de {{from}}: {{subject}}. Registre na planilha de pedidos e responda confirmando." ``` O prompt pode citar os campos do evento entre chaves duplas: `{{from}}`, `{{subject}}`, `{{body}}` no Gmail; `{{title}}`, `{{start}}`, `{{attendees}}` na agenda; `{{name}}`, `{{link}}` no Drive; `{{row}}` nas planilhas. O conector precisa ser seu (ou compartilhado com você) e do mesmo serviço do evento. A plataforma consulta o app a cada dois minutos. A primeira consulta só marca o ponto de partida: o que já existia antes do gatilho não dispara. ## Opções comuns | Opção | Para quê | | --- | --- | | `--name ` | Obrigatória. Até 80 caracteres. | | `--prompt ` | O que o agente deve fazer (até 4.000 caracteres). Aceita `-` (stdin) e `--prompt-file `. | | `--model ` | Modelo só para este gatilho. `auto` é o DoubleX Auto. Sem ela, vale o modelo do agente. | | `--timezone ` | Fuso IANA dos gatilhos agendados e únicos. O padrão é `America/Sao_Paulo`. | | `--raw` | Webhook e app: manda só o JSON do evento, sem prompt. | ## Listar, editar e rodar ```bash doublex triggers list --agent agt_8f3a2b1c9d0e doublex triggers update trg_6a2c4e8b1d3f --cron "0 9 * * 1-5" --model none doublex triggers update trg_6a2c4e8b1d3f --disable doublex triggers run trg_6a2c4e8b1d3f doublex triggers delete trg_6a2c4e8b1d3f --yes ``` - `update` aceita `--name`, `--prompt`, `--cron` (e as formas simples), `--once`, `--model` (`none` volta ao modelo do agente), `--timezone`, `--raw`, `--enable` e `--disable`. O tipo do gatilho não muda: para trocar, apague e crie outro. - `run` roda o gatilho agora, em segundo plano. Num gatilho de app, faz a consulta na hora e mostra quantos itens novos achou. - A lista mostra quando cada gatilho roda, se está ativo e a próxima execução. --- # Times Veja os times da organização e os IDs que os outros comandos pedem. ```bash doublex teams list ``` ```text ID NOME MEMBROS SEU PAPEL team_9c8b7a6d5e4f 💼 Comercial 8 admin team_1d3f5b7a9c2e ⚙️ Operações 5 member team_4e6a8c0b2d1f 📣 Marketing 3 - ``` A lista traz todos os times da organização. A coluna **SEU PAPEL** mostra se você é `admin` ou `member` do time, ou `-` se não participa. Use o ID do time com `--team-id` nos comandos que criam itens compartilhados: ```bash doublex brain upload manual.pdf --scope team --team-id team_9c8b7a6d5e4f doublex skills create SKILL.md --scope team --team-id team_9c8b7a6d5e4f ``` Para criar algo no escopo de um time, você precisa ser membro dele. Criar e gerenciar times, membros e convites é feito em **Configurações › Times**, pelo app. Com `--json`, o comando devolve também os membros de cada time e quantos agentes, skills e documentos do Brain o time tem.