#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 é 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:

npx @vatio-ai/cli docs

O mesmo está em um único arquivo Markdown em 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.

#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, 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:

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.
• 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:

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:

#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:

vatio init bicicletaria-norte

Depois substitua o vatio.yml inicial. O exemplo é uma loja de bicicletas com oficina:

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:

vatio secrets set LOJA_API https://api.bicicletaria-norte.example
vatio secrets set LOJA_API_KEY sk_live_...

tools/consultar_estoque.yml:

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 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:

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

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:

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

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:

O agente está no preview: <o link de Try it>

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

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:

vatio tokens create --env live --label website --origin https://bicicletaria-norte.example

<script async src="https://cdn.vatio.ai/v1/widget.js"
        data-workspace="bicicletaria-norte"
        data-token="vatpub_REPLACE_ME"></script>

• 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

#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.

Atualizado: 11 de outubro de 2026