#Como melhorar seu agente de IA com flags

Para melhorar um agente de IA que atende clientes reais, comece pelas respostas que deram errado. Com a Vatio, um supervisor reporta uma resposta errada no inbox e escreve o que ela deveria ter dito, e cada relato com nota vira um teste. Seu coding agent corrige a causa no seu repositório, o vatio eval repete cada relato contra o preview, e o vatio publish recusa uma versão que quebra o que funcionava. O Claude corrige, a Vatio confere. O agente é um vatio.yml que responde no WhatsApp, no Instagram e na web, então um único ciclo cobre todos os canais.

#Por que corrigir a partir dos relatos

Quem lê as conversas do seu agente sabe quando uma resposta está errada. Você conhece o código. Normalmente os dois se encontram em uma mensagem do tipo “ontem o bot falou uma coisa estranha para um cliente”, sem a conversa e sem como saber se a causa foram as instruções, o conhecimento ou o backend.

Um relato fecha essa lacuna. Ele traz a conversa, cada chamada de tool que o agente fez naquele turno com o que seu backend respondeu, e o que alguém que conhece o negócio diz que a resposta deveria ter sido. Isso basta para um coding agent achar a causa, e basta para transformar o erro em um teste, então ele não volta escondido na próxima mudança.

#Como o ciclo funciona

1. Relato. Um supervisor reporta uma resposta errada no inbox e escreve o que ela deveria ter dito. A partir daí, é um teste.
2. Correção. No Claude Code, /vatio:vatio-improve pega todos os relatos abertos de uma vez: lê o vatio flags, agrupa por causa e corrige cada uma onde ela está.
3. Preview. vatio push atualiza o preview. Não roda nenhum teste.
4. Eval. vatio eval repete cada relato contra o preview. Os que passam aparecem no inbox como corrigidos no preview.
5. Publicação. vatio publish leva a versão ao ar se ela não quebra nada que o live passa, e cada relato que ela passa fica resolvido, com a versão que o corrigiu.

Ninguém precisa avisar que um relato está resolvido. O agente passar no teste dele é a evidência.

#Passo 1: os supervisores reportam no inbox

Convide os supervisores em Equipe no inbox. Eles entram com um código enviado para o email, veem cada conversa e as chamadas de tools do agente, podem responder para assumir uma conversa (até 8 horas depois da última mensagem da pessoa) e podem editar as entradas de conhecimento. Eles não conseguem fazer deploy de nada.

Em qualquer resposta do agente, Reportar esta resposta pede o que deveria ter acontecido. Peça aos supervisores que escrevam a correção, não um veredito: a resposta certa, uma ação ou uma tool que o agente deveria ter usado.

• Fraca: “errado”.
• Útil: “Deveria ter buscado o pedido e mandado o link de rastreio: ele sai na quinta.”

Todo relato com nota é um teste, tenha sido feito no live ou no preview. Um relato sem nota não entra no digest e não tem teste: “isso estava errado” sem dizer o que deveria ter acontecido não serve para corrigir um agente. Um dado desatualizado, como um preço antigo, o supervisor também pode corrigir na hora, na entrada de conhecimento; cada edição fica guardada como versão.

O estado de cada relato aparece na própria resposta reportada, na conversa: aberto enquanto o agente com que os visitantes falam ainda falha, corrigido · falta publicar quando o vatio eval o passou na versão atual do preview, e resolvido quando o live o passa, com os 7 caracteres da versão que o corrigiu. Se o supervisor não concordar com uma resolução, reescreve a nota e o relato volta a ficar aberto. Melhoria contínua, no inbox, lista todos os relatos com o estado e o último teste, diz o que vem a seguir (correções a fazer, correções esperando publicação ou uma que quebrou algo) com o prompt para colar no Claude Code, /vatio:vatio-improve, e é onde se remove um relato.

#Passo 2: o digest diário chega a quem desenvolve

Toda manhã às 8:00 (America/Santiago), cada workspace com relatos novos manda ao dono e aos developers um email com quantos chegaram, quantos estão abertos e o prompt para colar no Claude Code, /vatio:vatio-improve. O email não cita o que ninguém escreveu: as conversas, as respostas das tools e as notas só se leem com um token da Vatio.

Para o Claude Code, instale a skill vatio-improve:

/plugin marketplace add vatio-ai/skills
/plugin install vatio@vatio

Depois disso, /vatio:vatio-improve dentro do seu repositório leva o ciclo inteiro em uma sessão. Para qualquer outro coding agent, npx @vatio-ai/skills na raiz do seu projeto copia a mesma skill para .agents/skills/, onde Codex, Cursor e a maioria dos outros procuram skills, e o vatio init escreve uma seção curta da Vatio no AGENTS.md do workspace apontando para o vatio flags. O Claude Code não atualiza sozinho plugins de marketplaces de terceiros: ative uma vez em /plugin → Marketplaces → vatio → Enable auto-update. O vatio flags avisa quando suas skills estão desatualizadas.

O que a skill lê é o digest:

vatio flags --save        # grava vatio-flags.md

Para cada relato, o digest traz o canal e a versão publicada, as 10 mensagens anteriores à resposta reportada, cada chamada de tool naquele turno com os argumentos e a resposta que seu backend devolveu, as buscas no conhecimento e a nota do supervisor. As primeiras linhas explicam a um coding agent como trabalhar com ele.

O vatio-flags.md contém conversas de visitantes reais. Coloque-o no .gitignore e, em commits e pull requests, cite os relatos pelo número.

#Passo 3: corrija a causa onde ela está

Vários relatos costumam ter a mesma causa, e muitas vezes a causa não é o prompt:

Os relatos só pegam o que um supervisor notou. Uma tool com falha quase nunca é reportada, porque o agente pede desculpas e segue, então peça ao seu coding agent que também rode vatio tools --env live: a página Ferramentas do inbox em Markdown, com a taxa de erro, os timeouts e a latência p50/p95 de cada tool, e as chamadas que falharam com o que seu backend respondeu. Depois de publicar uma correção, vatio tools --env live --period 1h mostra se os erros pararam.

Seu coding agent tem seu repositório e seu backend na frente dele, e a Vatio não; por isso a correção é trabalho dele. Quando termina, ele atualiza o preview:

vatio push                # atualiza o preview; não roda testes

Existem só dois ambientes: o preview, a próxima versão, e o live, o que os visitantes usam. Se o preview tem um push ainda não publicado, feito de outra branch do git, o vatio push é recusado: publique esse antes, ou use --force para substituí-lo.

#Passo 4: prove com vatio eval

vatio eval                # todos os relatos, contra o preview
vatio eval --show RUN_ID  # o motivo do juiz para cada caso

Cada caso roda em um chat novo: os turnos do visitante (até os últimos 8) são enviados um por um, e um juiz lê a conversa, incluindo cada tool que o agente chamou, e a nota, e responde se passou ou falhou, em uma frase. Uma nota que pede uma tool passa quando o agente a chama. O juiz é um modelo de outra família, diferente da do seu agente, para nunca avaliar respostas do seu próprio tipo. Os casos rodam de 5 em 5 nos servidores da Vatio e levam alguns minutos; no Claude Code, rode o vatio eval em segundo plano. O comando sai com 1 quando algum caso falha.

Leia primeiro as regressões. Um relato que passa no live e falha no preview aparece no topo: a correção quebrou algo que funcionava ontem. Cada caso é um turno real do agente, então pode passar uma vez e falhar na seguinte sem nada mudar; por isso um caso que falha se repete sozinho, até 3 vezes.

Sem terminal, Rodar testes na página Testar do inbox repete os mesmos relatos no preview, e o cartão do preview diz quantos passaram.

Os evals chamam suas tools. Aponte-as para um backend de staging com um valor de testes, que todas as repetições e o preview usam. Uma gravação (agendamentos, pedidos, chamados) cuja URL não tem valor de testes é simulada em vez de enviada:

vatio secrets set LOJA_API https://staging.api.torrefacao-serra.example --tests

Os chats dos evals não aparecem no inbox e não contam como conversas.

#Passo 5: publique e deixe o live resolver o relato

vatio publish

Depois da primeira publicação, o vatio publish só leva ao ar uma versão testada. Ele é recusado quando:

• a versão atual do preview não tem nenhuma rodada de eval: rode vatio eval e publique;
• os testes dela ainda estão rodando: o vatio eval espera por eles;
• um relato que passa no live falha no preview. O erro lista quais; --force publica mesmo assim, e os resultados que falharam vão para o live junto.

Os relatos que continuam abertos não bloqueiam: uma correção parcial pode ir ao ar. Ao publicar, os resultados do preview passam para o live sem rodar de novo, e cada relato que a versão passa fica resolvido com o sha dela. O botão Publicar no live da página Testar do inbox passa pela mesma verificação, e não aparece enquanto o preview é a mesma versão do live: não há nada para publicar.

Antes da primeira publicação, o workspace é um rascunho e o preview é o agente: um relato fica resolvido quando o vatio eval o passa no preview, e a primeira publicação não tem verificação.

#Um exemplo completo

A Torrefação Serra vende café em grãos pela internet e atende no WhatsApp. O email de segunda-feira traz três relatos:

• Relatos 31 e 35. Diante de “quando chega meu pedido?”, o agente respondeu “está a caminho”. As duas notas: “Deveria ter dado a data de entrega e o link de rastreio.” O digest mostra que status_pedido devolveu o status e mais nada.
• Relato 34. Diante de “vocês moem para cafeteira italiana?”, o agente disse que só vendem em grãos. A nota: “Moemos na hora para qualquer método. Perguntar qual.” Nenhuma busca no conhecimento achou nada.

O desenvolvedor cola /vatio:vatio-improve no Claude Code, que encontra duas causas. Nos relatos 31 e 35, o prompt nunca foi o problema: o endpoint não devolvia nenhuma data. Ele adiciona entrega_prevista e url_rastreio à resposta do backend, sobe isso para staging e mapeia os dois campos na tool:

# tools/status_pedido.yml
description: Consulta o status de um pedido.
when_to_use: O visitante pergunta onde está o pedido ou quando ele chega.
parameters:
  type: object
  properties:
    numero_pedido: { type: string }
    email: { type: string, description: "o email usado na compra" }
  required: [numero_pedido, email]
access: public
request:
  method: GET
  base_url: "$env.LOJA_API"
  path: /pedidos/consulta
  requires: [params.numero_pedido, params.email]
  headers:
    Authorization: "Bearer $env.LOJA_API_KEY"
  query:
    numero: "$params.numero_pedido"
    email: "$params.email"
respond:
  data:
    status: "$.pedido.status"
    entrega_prevista: "$.pedido.entrega_prevista"
    url_rastreio: "$.pedido.url_rastreio"
  message: Pedido encontrado.

Um link devolvido por uma tool pode ser enviado pelo agente pelo resto da conversa, então a URL de rastreio não precisa ser declarada. Para o relato 34, ele escreve uma entrada moagem com vatio kb write loja moagem moagem.md. Depois roda vatio push e, em segundo plano, vatio eval.

A primeira rodada mostra uma regressão: um relato antigo, “nunca prometer data para pré-venda”, passa no live e falha no preview, porque agora as pré-vendas também voltam com data. Essa correção também fica no backend, que deixa entrega_prevista vazio nas pré-vendas. Depois de outro push, a segunda rodada passa em todos os casos, o vatio publish leva a versão ao ar, e os relatos 31, 34 e 35 aparecem no inbox como resolvidos, com a versão que os corrigiu.

#Erros comuns

• Corrigir todo relato no prompt. Regras novas escondem a causa e incham o prompt. Leia primeiro as respostas das tools no digest.
• Notas que julgam em vez de responder. “Tom ruim” não vira teste; “deveria ter pedido desculpas e dado a nova data” vira.
• Uma nota que pede algo que o agente não deve fazer, como um desconto que ele não pode dar. Diga isso ao supervisor em vez de pular o relato em silêncio; ele pode editar ou remover a nota.
• Publicar sem rodar vatio eval. A publicação é recusada; o passo que falta é o vatio eval, não o --force.
• Evals gravando em produção. Defina um valor de testes com --tests.
• Conversas no repositório. Deixe o vatio-flags.md fora dos seus commits.

#Próximos passos

Para os hábitos que mantêm os relatos raros, leia Boas práticas. Todos os comandos estão na documentação.

Atualizado: 11 de outubro de 2026