> Supervisores reportam respostas erradas, seu coding agent corrige a causa, o vatio eval repete cada relato contra o preview e a publicação é recusada se algo que funcionava quebrar. # 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: ```bash 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: | O que o digest mostra | Onde vai a correção | |---|---| | Uma tool respondeu com erro, ou sem o campo de que a resposta precisava | O backend que essa tool chama, e depois o `respond.data` da tool | | Nenhuma busca no conhecimento achou nada, ou a entrada está desatualizada | Uma entrada de conhecimento, com `vatio kb write` | | As instruções dizem pouco demais, ou demais | `vatio.yml` | | O visitante precisava de uma pessoa e o agente seguiu sozinho | `handoff.when` no `vatio.yml` | 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: ```bash 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` ```bash 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: ```bash 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 ```bash 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: ```yaml # 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](/pt/guias/boas-praticas-agentes-de-ia). Todos os comandos estão na [documentação](https://vatio.ai/docs/improve). ## Perguntas frequentes ### Como melhorar um agente de IA que já está em produção? Comece pelas respostas que deram errado. Na Vatio, um supervisor reporta uma resposta no inbox e escreve o que ela deveria ter dito. No Claude Code, /vatio:vatio-improve pega todos os relatos abertos: o vatio flags os entrega ao seu coding agent, ele corrige, o vatio push atualiza o preview, o vatio eval repete cada relato contra ele e o vatio publish leva a correção ao ar. Cada relato que a versão publicada passa fica resolvido com a versão que o corrigiu. ### O que é um caso de eval na Vatio? Todo relato com nota, feito no live ou no preview. Os turnos do visitante são a entrada e a nota do supervisor é o resultado esperado. O vatio eval repete esses turnos em um chat novo contra o preview, e um juiz de outra família de modelos, diferente da do seu agente, decide se a nova resposta atende à nota. ### Devo corrigir uma resposta errada mudando o prompt? Só se o prompt for a causa, e muitas vezes não é. Uma tool devolveu um erro ou não trouxe o campo de que a resposta precisava, falta uma entrada de conhecimento, ou uma regra de transferência não disparou. O digest mostra o que seu backend respondeu naquele turno, então a causa é corrigida onde ela está. ### Os evals chamam meu backend de verdade? Sim, cada caso é um turno real do agente. Defina um valor de testes para o secret da URL da tool, apontando para um backend de staging (vatio secrets set KEY URL --tests): todas as repetições o usam. Uma gravação cuja URL não tem valor de testes não é enviada: o agente recebe um sucesso e o juiz ainda confere a chamada. ### O que impede uma correção de quebrar o que já funcionava? O vatio publish. Ele é recusado enquanto a versão do preview não foi testada com vatio eval, enquanto os testes dela ainda rodam e quando um relato que o live passa falha no preview. Os relatos que continuam abertos não bloqueiam: uma correção parcial pode ir ao ar.