Testar chamadas de ferramentas de agente de IA sem sistemas reais

Para testar chamadas de ferramentas de agente de IA sem tocar em sistemas reais, grave as respostas que suas ferramentas devolvem, guarde cada uma como um registro versionado e reproduza esses registros sempre que o agente for testado. O agente faz as mesmas chamadas que faria em produção, mas cada leitura e cada escrita vai para uma cópia guardada, e não para o seu CRM, sistema financeiro, caixa de entrada ou agenda. Este artigo explica o que gravar, como organizar o conjunto de fixtures (registros gravados de chamadas) e como conferir as chamadas que o agente faz.

Principais pontos

• Um fixture de chamada de ferramenta é um par de pedido e resposta salvo para uma ferramenta, capturado uma vez a partir de uma interação real e reproduzido em todos os testes.
• Teste as decisões e os argumentos do agente, e não só o texto final, porque uma resposta educada pode esconder uma escrita errada.
• Grave os fixtures a partir de respostas reais, depois remova dados pessoais e mantenha os arquivos legíveis para quem revisa.
• Versione os fixtures junto com os prompts e as descrições das ferramentas, para que uma mudança em um deles fique visível ao lado dos outros.
• Mantenha as ferramentas de escrita em modo somente reprodução durante os testes, e só avance para ações reais depois que os resultados da reprodução e um período supervisionado estiverem de acordo.

O que um fixture de chamada de ferramenta realmente contém

Um agente trabalha por meio de ferramentas: uma consulta no sistema de pedidos, um rascunho no cliente de e-mail, uma atualização de chamado, uma reserva na agenda. Cada chamada tem dois lados que importam para o teste. O primeiro é o pedido que o agente envia, com o nome da ferramenta, os argumentos e os identificadores. O segundo é a resposta que a ferramenta devolve, e que o agente lê e usa para raciocinar. Um fixture guarda os dois lados de uma interação, identificados por uma descrição estável do pedido. Assim, o teste roda o agente, intercepta cada chamada e responde a partir do arquivo, sem acionar o sistema real.

Isso importa por três motivos. Os testes ficam repetíveis, porque a mesma entrada sempre gera a mesma resposta da ferramenta. Os testes ficam seguros, porque nenhuma execução consegue emitir um crédito, enviar uma mensagem ou alterar um registro. E os testes ficam baratos de rodar com frequência, porque ninguém precisa coordenar uma conta de homologação nem esperar pelos limites de uso de um fornecedor.

Um fixture também não é um mock escrito de memória. Um mock reflete o que o desenvolvedor acredita que a ferramenta devolve. Um fixture reflete o que a ferramenta de fato devolveu em um dia específico. Por isso, gravar a partir de respostas reais é o hábito central.

Quais ferramentas gravar e quais apenas reproduzir?

Nem toda ferramenta precisa do mesmo tratamento. Antes de gravar qualquer coisa, separe as ferramentas do agente em três grupos:

• Ferramentas de leitura, que devolvem registros, como consultas de clientes, situação de pedidos ou níveis de estoque. São as mais fáceis de gravar e as mais valiosas, porque o raciocínio do agente depende do formato exato dessas respostas.
• Ferramentas de escrita, que alteram estado, como emitir um crédito, mudar uma situação ou enviar uma mensagem. Nos testes, elas nunca podem chegar ao sistema real. Grave o que o agente tentou enviar e faça a reprodução devolver um sucesso ou um erro escolhido de propósito.
• Ferramentas com efeitos fora do seu controle, como um provedor de pagamento ou uma API de mensagens de terceiros. Grave as respostas e preste atenção especial aos códigos de limite de uso e de erro, porque o agente também precisa tratá-los em produção.

Decida também quais campos são estáveis e quais mudam a cada chamada, como carimbos de data e hora, identificadores gerados e tokens de sessão. Fixe ou normalize esses campos instáveis dentro do fixture. Caso contrário, os testes falham por motivos alheios ao agente, e a equipe aprende a ignorar os resultados vermelhos.

Um plano passo a passo para montar o primeiro conjunto de fixtures

Uma equipe pequena consegue montar um conjunto útil sem ferramentas especializadas, seguindo esta sequência:

• Passo 1: liste todas as ferramentas que o agente pode chamar e escreva uma frase descrevendo o que cada uma tem permissão para fazer.
• Passo 2: rode o agente em uma sessão controlada, com acesso somente de leitura, e registre cada chamada com seus argumentos e sua resposta.
• Passo 3: escolha tarefas realistas que cubram o caminho comum, os casos de borda e as falhas que você já conhece, e salve as chamadas registradas de cada tarefa como um conjunto de fixtures.
• Passo 4: remova dados pessoais e confidenciais, substituindo-os por marcadores consistentes, para que as referências continuem batendo entre as chamadas.
• Passo 5: escreva o comportamento esperado de cada tarefa: quais ferramentas devem ser chamadas, em que ordem, com quais argumentos obrigatórios e o que a resposta final precisa conter.
• Passo 6: guarde os fixtures e as expectativas no controle de versão, ao lado do prompt e das definições de ferramentas de que dependem.
• Passo 7: rode a suíte de reprodução sempre que qualquer um desses arquivos mudar, e revise cada diferença dos fixtures com o mesmo cuidado de uma mudança de código.

Comece pequeno. Poucos fixtures bem escolhidos ensinam mais do que um conjunto grande copiado de uma tarde movimentada.

Cenário ilustrativo: um agente de atendimento consulta um pedido, verifica se o prazo de devolução está aberto e rascunha uma resposta para o cliente. A equipe tem fixtures para uma consulta de item já enviado, outra para item entregue fora do prazo, outra para pedido sem endereço e um tempo esgotado na API de transporte. Cada um vem de uma resposta real, com nome e contato do cliente substituídos por marcadores. A ferramenta de crédito é reproduzida com uma resposta fixa de sucesso, e o teste confere se o agente só a chama no caso em que o prazo estava aberto.

O que o teste deve verificar de fato?

Conferir apenas a resposta final é o erro mais comum. Um agente pode escrever uma resposta com cara de correta depois de chamar a ferramenta de escrita errada, ou depois de ler um registro desatualizado. Para cada tarefa, confira quatro coisas:

• A sequência de chamadas de ferramentas, incluindo se o agente parou quando deveria.
• Os argumentos de cada chamada de escrita, principalmente identificadores, valores e destinatários.
• O tratamento de respostas de erro e de tempo esgotado, incluindo se o agente tentou de novo dentro da política definida ou se escalou para uma pessoa.
• A resposta final em relação aos fatos dos fixtures, para que cada afirmação do texto possa ser rastreada até uma resposta gravada.

Para chamadas de escrita, acrescente uma verificação de que uma chave de idempotência, ou identificador equivalente, está presente sempre que a ferramenta oferecer esse recurso. O raciocínio está explicado em Ações idempotentes em agentes de IA: como evitar reembolsos duplicados, e os campos que vale manter no registro de cada chamada estão listados em Trilha de auditoria de agente de IA: campos que cada ação precisa ter.

Inclua também testes de permissão. Um fixture em que a identidade do agente não tem direito a uma escrita deve produzir uma recusa ou um escalonamento, e não um atalho por outra ferramenta.

Como manter os fixtures atualizados sem que deixem de representar a realidade?

Fixtures envelhecem. Um fornecedor renomeia um campo, um código de status muda de significado, ou uma política altera o prazo de devolução. Uma suíte que continua passando com fixtures antigos dá uma confiança falsa. Três hábitos protegem contra isso:

• Regrave os fixtures em uma agenda e sempre que uma ferramenta mudar, e marque cada arquivo com a data em que foi capturado.
• Mantenha um pequeno conjunto de verificações ao vivo, somente de leitura, que compare as respostas atuais com o formato guardado, para que a divergência apareça antes de a suíte de reprodução falhar.
• Trate uma falha na reprodução como um possível sinal de mudança real no mundo externo, e não apenas como um bug do agente.

Os fixtures também merecem o mesmo cuidado dos dados de produção. Se as respostas originais eram sensíveis, restrinja quem pode ler o conjunto. Nunca deixe um fixture conter uma credencial ativa. Respostas gravadas às vezes trazem tokens, anotações internas ou dados de outras pessoas, por isso a etapa de limpeza é uma etapa de revisão, e não um detalhe posterior. Para o lado contínuo desse trabalho, veja Checklist semanal de manutenção de agentes de IA.

Como a Be Human trata o conjunto de fixtures na operação gerenciada

No modelo gerenciado da Be Human, o conjunto de fixtures faz parte do registro operacional do agente desde o primeiro trabalho. O primeiro trabalho define um papel útil, as ferramentas que esse papel precisa, os limites de aprovação e um critério de sucesso observável, e os fixtures iniciais são montados exatamente a partir dessas ferramentas e tarefas. Durante a operação, os fixtures são regravados quando as ferramentas mudam, as revisões de permissão confirmam quais ferramentas de escrita o agente consegue alcançar em qualquer ambiente de teste, e as falhas de reprodução entram no mesmo processo de incidentes usado para problemas de produção. A identidade, a memória e as permissões do agente continuam sob controle do cliente o tempo todo, para que o acesso de teste nunca vire um caminho até os sistemas reais.

Se você não tem certeza de qual dos seus fluxos de trabalho é o candidato certo para esse tipo de teste, o diagnóstico gratuito de IA da Be Human pode ajudar a encontrar a primeira tarefa que vale entregar a um agente.

Perguntas frequentes

Posso testar um agente com uma conta de homologação em vez de fixtures? Uma conta de homologação é útil, mas leva mais tempo para ser preparada e ainda depende do comportamento do fornecedor, que pode ser diferente do de produção. Os fixtures são rápidos, repetíveis e totalmente sob o seu controle. Muitas equipes usam fixtures nas execuções de rotina e mantêm uma homologação para verificações ponta a ponta ocasionais.

Quantos fixtures preciso antes de começar os testes? Os suficientes para cobrir o caminho comum, os principais casos de borda e as falhas conhecidas da tarefa que você está testando. Comece com um conjunto pequeno para um papel e depois amplie a partir de escalonamentos e incidentes reais, para que cada novo fixture represente uma situação que de fato aconteceu.

Fixtures gravados substituem avaliações com tarefas reais de negócio? Não. Os fixtures testam como o agente se comporta diante de respostas de ferramentas conhecidas, enquanto as avaliações com tarefas reais testam se o trabalho está bom o bastante para ser usado. Mantenha os dois e trate as falhas de fixtures e as falhas de avaliação como sinais separados, com responsáveis separados.

E se uma ferramenta de escrita não tiver modo de teste? Reproduza-a e nunca a chame de verdade. O ambiente de teste deve interceptar toda escrita e registrar a chamada tentada. Se uma ferramenta não puder ser interceptada, não dê essa ferramenta ao agente em nenhum ambiente de teste até que isso seja possível.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.