> Para Claude Code, Codex, Cursor ou qualquer coding agent a quem pedem um agente na Vatio: o que olhar, o que perguntar, o que escrever, como testar e o que entregar. # Criar um agente na Vatio: o manual para coding agents Esta página é escrita para o coding agent, Claude Code, Codex, Cursor ou qualquer outro, a quem um developer pediu para criar na Vatio um agente de IA que atenda clientes. É a ordem que funciona: o que olhar, o que perguntar ao dono, o que escrever, como testar e o que entregar, com um exemplo completo. Pessoas também podem ler; a [versão para developers](/pt/guias/construir-um-agente-de-ia) é mais curta. O contrato, cada campo do `vatio.yml` e cada comando, está na documentação, e a documentação vale onde não bater com esta página. Leia antes de escrever qualquer coisa: ```bash npx @vatio-ai/cli docs ``` O mesmo está em um único arquivo Markdown em [vatio.ai/docs/docs.md](https://vatio.ai/docs/docs.md), e cada página da documentação também está no próprio endereço mais `.md`. Esta página está em [vatio.ai/pt/guias/manual-para-coding-agents.md](https://vatio.ai/pt/guias/manual-para-coding-agents.md). ## O que você está construindo - **Um workspace, um agente.** Um workspace tem um slug e roda exatamente um agente, descrito em um `vatio.yml` cujas únicas chaves raiz são `workspace`, `agent` e `auth`. - **Instruções, tools e conhecimento.** As instruções dizem o que o agente faz e as regras que ele nunca quebra. Uma tool é uma requisição HTTP para a API do negócio, descrita em YAML em `tools/`. O conhecimento são entradas em Markdown que o agente busca, guardadas na Vatio e versionadas. - **Ambientes.** Existem dois: `vatio push` faz o deploy em `preview`, e `vatio publish` leva para o `live`. Nada chega aos clientes antes de ser publicado. - **Nenhum modelo para escolher.** A Vatio roda o modelo e as conversas. Não há chave de modelo nem configuração de modelo. - **Canais.** O mesmo agente responde em um widget no site, no WhatsApp, nas mensagens diretas do Instagram e nos SDKs de navegador, iOS e Android. Os supervisores leem cada conversa no inbox, assumem uma respondendo e marcam as respostas que saíram erradas. O que ele não faz, para você nunca prometer ao dono: - Ele responde em texto. Lê imagens, áudios e PDFs, mas não envia arquivos. - Ele não lê sites. O que ele precisa saber, você escreve como conhecimento. - Ele escreve primeiro só quando o backend do negócio chama a [Messages API](https://vatio.ai/docs/api/messages), no WhatsApp. Nunca decide sozinho escrever para alguém. - A Vatio ainda não avisa ninguém de uma transferência: a conversa aparece como pendente no inbox. ## A ordem que funciona 1. Instale as skills. 2. Olhe antes de criar. 3. Conte o que encontrou e recomende. 4. Pergunte ao dono só o que o código não responde. 5. Escreva o agente: `vatio.yml`, tools e conhecimento. 6. Confira, faça o push e teste. 7. Entregue o link. 8. Publique só quando pedirem. 9. Antes de terminar, conte o que atrapalhou. ## 1. Instale as skills A menos que `.agents/skills/vatio-init` já esteja no projeto, rode isto na raiz dele: ```bash npx @vatio-ai/skills ``` Isso copia as skills da Vatio para `.agents/skills/` e `.claude/skills/`, então este procedimento e o de melhorar o agente ficam no repositório para a próxima sessão, seja qual for o coding agent que a rodar. Abaixo, `vatio` é `npx @vatio-ai/cli` quando a CLI não está instalada globalmente. Ela precisa do Node.js 20 ou mais recente. ## 2. Olhe antes de criar O projeto pode já ter um agente. - **Procure um `vatio.yml`** no diretório atual ou acima dele, e em qualquer lugar do repositório: `git ls-files '*vatio.yml'`. A linha `workspace:` dele dá o nome do workspace. Se houver um, o agente existe: nunca rode `vatio init` ali, porque ele escreve um agente inicial e o push dele substitui o verdadeiro. Siga [Joining an existing workspace](https://vatio.ai/docs/#joining-an-existing-workspace). - **Um slug de workspace mas nenhum `vatio.yml`:** peça o repositório onde ele vive. A Vatio guarda o que foi publicado no deploy, não os arquivos de onde veio. - **Leia o app.** O que ele faz e para quem; a API que um agente poderia chamar (rotas, controllers, um arquivo OpenAPI); como os usuários fazem login; e a documentação, as perguntas frequentes e as políticas que um agente poderia ler. - **Confira a máquina.** `vatio doctor` diz se a CLI está logada e a qual workspace este diretório corresponde. ## 3. Conte o que encontrou e recomende Antes de mudar qualquer coisa, diga à pessoa para quem você trabalha, em poucas linhas, o que existe e o que você recomenda, e peça que ela confirme. Faça uma proposta concreta, a partir do código dela: ```text Este é o backend de uma loja de bicicletas com uma API de produtos (GET /produtos) e uma política de trocas em docs/trocas.md. Ainda não existe um agente da Vatio. Recomendo um agente para WhatsApp e para o site que: - responda estoque e preços chamando GET /produtos (tool consultar_estoque) - responda manutenção, horários e trocas com conhecimento escrito a partir de docs/ - passe reclamações e pedidos de reembolso para uma pessoa Antes de escrever, preciso que você me responda quatro coisas. ``` ## 4. Pergunte ao dono só o que o código não responde Quatro perguntas, curtas, todas de uma vez: 1. O que o negócio faz, e quem escreve? 2. O que o agente nunca pode dizer nem prometer? 3. Quando uma pessoa precisa assumir a conversa? 4. De quais dos seus sistemas ele deve ler: uma API, uma agenda, um catálogo? Não invente dados do negócio que não te deram: preços, horários, políticas, prazos de entrega. Se o dono ainda não sabe, escreva a instrução para o agente dizer que não sabe e oferecer uma pessoa. Cada resposta tem o seu lugar: | O que te dizem | Onde vai | |---|---| | O que o negócio faz, quem escreve | `agent.instructions` | | O que ele nunca pode dizer nem prometer | Uma lista de regras dentro de `agent.instructions` | | Quando uma pessoa assume a conversa | `agent.handoff.when` e `agent.handoff.after_turns` | | Os sistemas de onde ele lê | Um arquivo por ação em `tools/` | | Políticas longas, perguntas frequentes, procedimentos | Entradas de conhecimento | | O nome, a descrição e o horário do negócio | Não vão no `vatio.yml`: a página **Negócio** do inbox, ou `vatio business hours` | ## 5. Escreva o agente ### vatio.yml Crie o workspace no repositório ao qual o agente pertence, normalmente o do backend que ele vai chamar. O `init` escreve o `vatio.yml` no diretório atual e uma seção da Vatio no `AGENTS.md`, e não precisa de conta: ```bash vatio init bicicletaria-norte ``` Depois substitua o `vatio.yml` inicial. O exemplo é uma loja de bicicletas com oficina: ```yaml workspace: bicicletaria-norte agent: name: Bicicletaria Norte personality: Simpático, direto e breve. instructions: | Você ajuda os clientes da Bicicletaria Norte, uma loja de bicicletas com oficina. Você responde sobre bicicletas e peças em estoque, preços de manutenção, horários e trocas. Estoque e preços: chame consultar_estoque. Só diga que algo tem em estoque, ou informe o preço, quando consultar_estoque tiver devolvido. Manutenção, horários e trocas: busque primeiro em knowledge_lookup. Se não encontrar a resposta, diga isso e ofereça passar a pergunta para a equipe. Regras que você nunca quebra: - Nunca invente um produto, um preço ou uma data de entrega. - Nunca prometa um desconto ou um prazo de manutenção. tools: [consultar_estoque, knowledge_lookup] knowledge: [loja] handoff: after_turns: 10 when: - uma reclamação sobre uma compra ou uma manutenção - o cliente pede o dinheiro de volta ``` Como escrever: - **`agent.instructions` é o único campo obrigatório.** Escreva o que o agente faz, depois qual tool ou qual conhecimento responde cada tipo de pergunta, e depois as regras. A Vatio adiciona o contexto do negócio, o contato, as descrições das tools e as próprias instruções da plataforma, então não repita isso. - **Regras escritas como regras.** "Nunca prometa um desconto" em um item próprio se sustenta muito melhor do que uma frase sobre o tom. - **`handoff`** é o que dá ao agente a tool para passar a conversa para uma pessoa, nas condições de `when`, com as palavras do dono. `after_turns` é o piso: passadas essas mensagens do cliente, ele transfere mesmo assim. Um cliente que pede para falar com uma pessoa sempre consegue. - **Idioma.** O agente responde no idioma do visitante. Diga isso em `instructions` só se o negócio precisar de um idioma fixo. - **Uma chave raiz desconhecida faz o push falhar.** Um bloco `business:` ou `hours:` é ignorado com um aviso. ### Tools Uma tool é uma requisição HTTP para a API do negócio. O nome do arquivo é a chave da tool, e a tool só existe para o agente quando a chave dela está em `agent.tools`. Endereços e chaves vão em secrets, nunca no repositório: ```bash vatio secrets set LOJA_API https://api.bicicletaria-norte.example vatio secrets set LOJA_API_KEY sk_live_... ``` `tools/consultar_estoque.yml`: ```yaml description: Consulta o estoque e o preço de uma bicicleta, peça ou acessório. when_to_use: O cliente pergunta se algo está disponível ou quanto custa. parameters: type: object properties: produto: { type: string, description: "Nome, modelo ou tamanho, por exemplo capacete trail M" } required: [produto] access: public request: method: GET base_url: "$env.LOJA_API" path: /produtos requires: [params.produto] headers: Authorization: "Bearer $env.LOJA_API_KEY" query: q: "$params.produto" respond: data: produtos: "$.produtos" message: when_empty: Nenhum produto com esse nome. default: "Encontrei {{count}} produtos." ``` O que mais quebra as tools: - **Um endpoint por tarefa.** Tudo o que precisa de ramificações, uma segunda chamada ou uma resposta derivada é código, e fica no backend. Se o endpoint de que o agente precisa não existe, proponha adicioná-lo lá e diga isso antes de escrever. - **Status reais.** Uma resposta que não é 2xx vira um erro que o agente consegue explicar; um erro dentro de um 200 parece sucesso. A mensagem de um erro deve dizer o que mudar, para o agente se corrigir na chamada seguinte. - **Nada de `localhost`.** As tools rodam nos servidores da Vatio. A API precisa estar acessível pela internet; um deploy de staging serve. - **Os testes chegam ao backend.** Uma conversa no preview chama a API real. Para escritas, dê ao secret um valor de staging com `--tests`, que todos os ambientes menos o live usam. - **Limites.** Uma chamada expira em 8 segundos, e uma resposta faz no máximo 12 chamadas de tools. - **Clientes logados.** Uma tool que lê os dados do próprio cliente é `access: private`, com um bloco `auth:`: o backend assina um token dizendo quem é o cliente, e a Vatio só verifica. Se o app faz login com Supabase, rode `vatio auth --supabase` primeiro. [Conectar seu backend](/pt/guias/conectar-seu-backend) explica. ### Conhecimento O conhecimento é Markdown que você escreve, uma entrada por assunto, com títulos que consigam responder uma pergunta sozinhos. Uma base de conhecimento listada em `agent.knowledge` precisa existir antes do push: ```bash vatio kb create loja vatio kb write loja manutencao manutencao.md vatio kb write loja horarios-e-trocas horarios-e-trocas.md vatio kb show loja ``` Escreva as entradas a partir da documentação e das políticas do repositório, e do que o dono te disse. Nada de um site chega ao agente se você não colocar em uma entrada. ## 6. Confira, faça o push e teste ```bash vatio diff vatio push ``` O `diff` valida os arquivos e mostra o que o push mudaria. O primeiro `push` faz o login do developer: abre o navegador dele, ou imprime um link para mostrar a ele se não conseguir. O developer faz login com e-mail, Google ou GitHub e confere se o código da página é o mesmo do terminal. Se o comando desistir de esperar, rode de novo depois que ele tiver feito login; ele retoma a mesma página. Depois teste as conversas que dizem se funciona: ```bash vatio chat "Vocês têm capacete trail tamanho M?" vatio chat "O capacete que comprei semana passada quebrou. Quero meu dinheiro de volta" vatio chat --new "Faz um desconto se eu pagar no Pix?" vatio chat show ``` | Teste | Ele deve | |---|---| | A pergunta que a maioria dos clientes faz | Chamar a tool certa e responder com o que ela devolveu | | Algo que nem as tools nem o conhecimento cobrem | Dizer que não sabe e oferecer uma pessoa | | Algo que ele nunca pode prometer | Recusar, seguindo a regra | | Um caso da lista de transferência | Transferir | | `--new` e uma primeira mensagem | Atender um visitante que nunca viu | `vatio chat show` imprime cada chamada de tool com o que a API respondeu. Quando uma resposta sair errada, procure a causa, que muitas vezes está na resposta da tool e não nas instruções, corrija, faça o push de novo e repita a mesma conversa. ## 7. Entregue o link `vatio push` imprime um link depois de `Try it:`. Ele abre a página **Testar** do inbox, onde o developer e o dono testam o agente: - **Chat web**, na página. - **WhatsApp**: um QR code conecta o celular ao número compartilhado de preview da Vatio, sem conta na Meta. Até cinco telefones de teste. - **Instagram**: uma conta compartilhada de preview, até cinco contas de teste. Entregue o link com o que você testou e como ele respondeu, e o que só o dono pode decidir: ```text O agente está no preview: Testei cinco conversas: - estoque de um capacete trail: chamou consultar_estoque e respondeu que há 2 por R$ 250 - capacete quebrado, quer o dinheiro de volta: passou para uma pessoa - desconto para pagar no Pix: recusou, como dizem as regras - uma pergunta sobre marcas de pneus: não está no conhecimento, ofereceu uma pessoa - um visitante novo dizendo oi: se apresentou e perguntou do que ele precisava Pendente para você: os preços de manutenção em manutencao.md vêm da pasta docs; confira se estão atualizados. ``` ## 8. Publique só quando pedirem ```bash vatio publish ``` Rode quando o developer ou o dono pedir, e não antes. A primeira publicação não tem verificação; as seguintes são recusadas se a versão do preview não foi testada com `vatio eval` ou se quebra uma flag que o live passa. Depois, os canais: - **Site.** Um token para o domínio, e um script tag: ```bash vatio tokens create --env live --label website --origin https://bicicletaria-norte.example ``` ```html ``` - **WhatsApp e Instagram.** O dono conecta no inbox, em **Canais**, no live: o número da empresa pelo cadastro da Meta e depois a chave **Em produção**; uma conta profissional do Instagram. `vatio whatsapp` imprime o link. `vatio rollback` restaura o deploy anterior do live, configuração e conhecimento juntos. ## 9. Antes de terminar 1. Se um erro ou a documentação te deixou adivinhando, diga: `vatio feedback "o que você estava fazendo e o que faltou"`. Quem escreve os dois lê. 2. No Claude Code, rode `vatio share-session --should-ask` por último. Se imprimir `yes`, mostre à pessoa para quem você trabalha o que seria enviado (`vatio share-session --save ARQUIVO`) e pergunte uma vez se você envia para a equipe da Vatio: enviar, agora não, ou não perguntar de novo (`vatio share-session --never`). Se uma verificação de permissões não deixar você enviar, passe `vatio share-session --id ID --yes` para a pessoa rodar no terminal dela e depois confira com `vatio share-session --list`, que marca as sessões enviadas. Se imprimir `no`, não diga nada. ## Erros que custam uma sessão | Erro | O que acontece | Em vez disso | |---|---|---| | `vatio init` onde existe um `vatio.yml` | O agente inicial substitui o verdadeiro no push | Trabalhe a partir do `vatio.yml` existente | | Um arquivo de tool que não está em `agent.tools` | O agente nunca vê a tool | Liste cada chave em `agent.tools` | | `base_url` em `localhost` | Todas as chamadas falham | Uma API acessível pela internet | | Uma chave de API no YAML de uma tool | A chave fica no repositório | `vatio secrets set`, lida como `$env.KEY` | | Um erro devolvido como 200 | O agente lê o erro como resposta | Devolva o status real | | Horário ou nome do negócio no `vatio.yml` | É ignorado, com um aviso | A página **Negócio** do inbox | | Uma base de conhecimento que ainda não existe | O push falha | `vatio kb create` primeiro | | Preços ou políticas inventados para fechar a demo | O agente fala isso para os clientes | Pergunte ao dono, ou faça o agente dizer que não sabe | | Publicar para mostrar progresso | Os clientes recebem um agente não testado | Entregue o link do preview e espere | ## Quando o agente já existe Se o projeto já tem um `vatio.yml`, o trabalho é outro: faça login com o endereço com que o developer foi convidado, compare a pasta com o live (`vatio diff --env live`), explique o agente a partir do `vatio.yml` e recomende a partir do que encontrar. `vatio flags` lista o que os supervisores reportaram, que a skill `vatio-improve` trabalha, e `vatio tools` lista as chamadas de tools que estão falhando, que se corrigem no backend que elas chamam. Uma mudança vai para o preview com `vatio push`, é provada com `vatio eval` e vai ao ar com `vatio publish`. Veja [Melhorar seu agente](/pt/guias/melhorar-seu-agente-de-ia). ## Perguntas frequentes ### Onde está o contrato completo da Vatio para um coding agent? Na documentação, que vale sempre que um guia não bater com ela. npx @vatio-ai/cli docs imprime tudo no terminal, vatio.ai/docs/docs.md é o mesmo em um único arquivo Markdown, e cada página da documentação também está no próprio endereço mais .md. ### E se o negócio não tiver uma API? Comece com um agente que responde a partir do conhecimento e passa para uma pessoa tudo o que precisa dos sistemas do negócio, e diga isso ao dono. Quando uma ação precisa de dados, o endpoint fica no backend dele, um endpoint por tarefa; proponha e construa só se pedirem. ### Dá para testar o agente no WhatsApp antes de o negócio conectar o número dele? Sim. A página Testar do inbox conecta até cinco telefones ao número compartilhado de preview da Vatio com um QR code, sem conta na Meta. O Instagram tem uma conta compartilhada de preview do mesmo tipo. O negócio conecta o próprio número depois de publicar. ### O que um coding agent nunca deve fazer com um agente da Vatio? Rodar vatio init onde já existe um vatio.yml, porque o push do agente inicial que ele escreve substitui o verdadeiro; publicar sem que peçam; escrever chaves de API no repositório em vez de usar vatio secrets; ou inventar preços, horários ou políticas que o dono não informou.