Como testar agente de IA com mocks e sandbox sem risco

Como testar agente de IA com mocks e sandbox sem risco

Para testar agente de IA com mocks, coloque uma camada entre o agente e cada ferramenta e troque as APIs reais por simulações com respostas combinadas de antemão. Assim você roda o mesmo cenário quantas vezes quiser e vê qual ferramenta o agente escolheu e com quais argumentos. Nada sai do ambiente de teste: nenhuma mensagem enviada, nenhum pedido alterado, nenhuma cobrança criada. Depois, confira as simulações contra o ambiente de teste do provedor para que elas não se afastem da realidade.

Principais pontos

• Teste a decisão, não só o texto: verifique qual ferramenta foi chamada, com quais argumentos, em que ordem e se o agente parou ou passou para um humano quando devia.
• Mock, fake e sandbox servem a propósitos diferentes. Use mock para cenários pontuais, fake quando o estado importa e sandbox do provedor para conferir o contrato.
• Ferramentas de escrita (enviar mensagem, reembolsar, remarcar) nunca executam no teste: elas apenas registram a chamada.
• Os cenários de falha valem mais que o caminho feliz: erro, timeout, dado ambíguo, pedido fora do limite e texto hostil vindo da ferramenta.
• Simulação envelhece. Reserve uma verificação periódica contra o sistema real e transforme cada incidente em um novo cenário de teste.

O que significa simular ferramentas em um agente de IA?

Um agente de IA decide, e a decisão vira ação por meio de ferramentas: consultar um cliente no CRM, listar horários de uma agenda, criar um pedido, enviar uma mensagem, solicitar um reembolso. Testar essas decisões diretamente nos sistemas reais traz problemas práticos. O primeiro é o risco, porque uma falha de teste pode virar uma mensagem real para um cliente real. O segundo é a repetibilidade: os dados mudam, a API fica fora do ar, e o cenário que falhou ontem não existe mais hoje. O terceiro são os limites de uso e a dependência de terceiros para cada rodada de teste.

Simular uma ferramenta é entregar ao agente um substituto que respeita o mesmo contrato (mesmo nome, mesmos parâmetros, mesmo formato de resposta), mas que você controla. Para o modelo, a diferença é invisível. Para você, ela muda tudo: o cenário passa a ser uma entrada fixa, e o resultado pode ser comparado com o que se espera.

Isso é diferente de testar o modelo isoladamente. O que se avalia aqui é o conjunto: instruções, modelo, ferramentas e regras de parada. Se o agente chama a ferramenta errada ou inventa um argumento, o problema pode estar em qualquer uma dessas partes, e o teste com simulação mostra onde olhar.

Mock, stub, fake e sandbox: qual usar em cada caso?

Os termos se misturam no dia a dia, então vale separar pelo que cada um faz. Use este guia de decisão:

• Stub: devolve uma resposta padrão simples, sem lógica. Serve para ferramentas que existem no fluxo, mas não importam para o que está sendo testado.
• Mock: devolve uma resposta específica para uma chamada específica e permite verificar se ela aconteceu. Serve para cenários pontuais, como cliente não encontrado ou erro de timeout.
• Fake: uma implementação simplificada com estado, como uma agenda em memória. Serve quando a sequência importa: o agente consulta horários, reserva um, e a consulta seguinte precisa refletir essa reserva.
• Gravar e reproduzir: você grava respostas reais uma vez e as reproduz nos testes. Ajuda quando o formato real é complexo, mas exige revisar e anonimizar dados pessoais antes de guardar qualquer coisa (LGPD).
• Sandbox do provedor: o ambiente de teste que o fornecedor da API oferece, quando oferece. Serve para conferir se o contrato continua válido, não para a suíte diária, porque pode ter limites e comportamentos próprios. Confira a documentação do fornecedor.

Na prática, uma suíte útil começa com mocks e um ou dois fakes para as ferramentas com estado. O sandbox do provedor entra num segundo momento, como verificação de que as simulações ainda dizem a verdade.

Como montar uma camada de ferramentas que pode ser trocada?

O segredo técnico é simples: o agente nunca deve saber se está falando com o sistema real ou com a simulação. Para isso, siga este plano:

• Passo um: liste todas as ferramentas do agente e classifique cada uma como leitura ou escrita. Escrita é onde mora o risco.
• Passo dois: escreva o contrato de cada ferramenta: nome, parâmetros, formato de retorno e erros possíveis. Descrições claras ajudam o agente a usá-las bem, como discute o artigo da Anthropic sobre como escrever ferramentas para agentes.
• Passo três: crie uma interface entre o agente e a implementação. A escolha entre real e simulada deve vir de configuração do ambiente, nunca de uma instrução escrita no prompt.
• Passo quatro: para ferramentas de escrita, o substituto não executa nada. Ele registra a chamada (qual ferramenta, quais argumentos, em que ordem) e devolve uma resposta de sucesso ou de erro conforme o cenário.
• Passo cinco: no ambiente de teste, não coloque credenciais reais. Sem chave de produção, um erro de configuração falha de forma segura.
• Passo seis: monte as fixtures com dados sintéticos, nomes e telefones inventados. Não copie base de clientes para dentro do repositório de testes.
• Passo sete: rode o cenário e compare o registro de chamadas e o estado final do fake com o resultado esperado.

Se o agente é construído em uma plataforma de fluxos, a lógica é a mesma: troque o nó que chama a API real por um nó que registra e responde com dados do cenário. No caso de um fluxo com a API oficial do WhatsApp, por exemplo, o fluxo de atendimento com n8n e WhatsApp Cloud API pode ter, no ambiente de teste, um registrador no lugar do envio de mensagens.

Quais cenários o mock precisa cobrir?

O caminho feliz é o menos interessante. O valor da simulação está em reproduzir, de forma controlada, situações que na produção são raras ou perigosas. Uma lista mínima:

• Caminho feliz: confirma que o fluxo básico funciona e serve de referência.
• Resultado vazio: o cliente não foi encontrado, o pedido não existe. O agente deve dizer isso, não inventar um registro.
• Erro e timeout: a ferramenta falha. O agente deve tentar de novo com limite, avisar ou transferir, e nunca afirmar que concluiu a ação. Veja também como limitar passos, tempo e gasto em agente de IA em loop infinito.
• Dados ambíguos: dois clientes com o mesmo nome, duas datas possíveis. O agente deve perguntar, não escolher sozinho.
• Pedido fora do limite: o cliente pede algo que o agente não tem autorização para aprovar. O comportamento correto é transferir para uma pessoa, com o contexto resumido.
• Texto hostil na resposta da ferramenta: um campo de observação do cliente contém uma instrução como ignorar as regras anteriores. O agente deve tratar aquilo como dado, não como ordem. O tema é detalhado em prompt injection em agentes de IA, e o OWASP mantém um guia de prevenção.
• Chamada repetida: o agente envia o mesmo pedido duas vezes por causa de uma falha de rede. Alguns provedores documentam chaves de idempotência justamente para que repetir uma chamada não duplique o efeito, como a Stripe descreve. Se a API real tem esse comportamento, o fake deve imitá-lo, e o teste deve verificar que o estado final não tem duplicidade.

Cenário ilustrativo: remarcação no WhatsApp

Cenário ilustrativo: uma clínica fictícia usa um agente para atender pedidos de remarcação pelo WhatsApp. As ferramentas são buscar_agendamento, listar_horarios, remarcar e enviar_mensagem. No teste, a agenda é um fake em memória com dados inventados, e enviar_mensagem apenas grava o texto que seria enviado.

O cenário de entrada: a cliente fictícia escreve que quer remarcar para sexta à tarde. O fake de agenda está configurado para não ter nenhum horário livre nesse período. O que se espera, de forma verificável:

• O agente chamou buscar_agendamento antes de qualquer outra coisa.
• O agente chamou listar_horarios com a data de sexta e não chamou remarcar com um horário que não apareceu na lista.
• A mensagem registrada oferece alternativas reais, vindas do fake, e não promete sexta à tarde.
• O estado final da agenda é igual ao inicial, porque nada foi confirmado.

Variação um: listar_horarios devolve timeout. O esperado é que o agente avise que não conseguiu consultar a agenda e ofereça retorno ou transferência, sem afirmar nenhuma disponibilidade. Variação dois: a cliente insiste numa exceção que a regra da clínica não permite. O esperado é uma transferência para atendimento humano, com o pedido resumido. Cada variação leva poucos minutos para escrever e passa a rodar sempre que alguém mudar as instruções ou o modelo. Para entender o fluxo completo, veja agendamento automático no WhatsApp com IA.

Como avaliar o resultado se o modelo varia a cada execução?

O texto que o agente escreve muda de uma rodada para outra, então comparar frases exatas é um caminho frágil. Em vez disso, verifique o que importa para o negócio:

• Chamadas obrigatórias: a ferramenta de consulta foi usada antes de responder.
• Chamadas proibidas: a ferramenta de reembolso não foi acionada neste cenário.
• Argumentos válidos: datas, identificadores e valores vieram da ferramenta ou do cliente, não foram inventados.
• Estado final: a agenda, o pedido ou o registro simulado terminou como deveria.
• Condição de parada: o agente encerrou, perguntou ou transferiu dentro do limite de passos.

Rode cada cenário mais de uma vez. Um único resultado bom não prova que o comportamento é estável, e a taxa de falha observada ao longo de várias execuções diz mais do que um teste isolado. A Anthropic discute esse tipo de avaliação para agentes no artigo sobre evals, e a OpenAI mantém um guia próprio sobre o tema. Para a qualidade do texto em si (tom, clareza, cortesia), use um critério escrito e revisão humana por amostragem, porque isso não se resolve com uma verificação automática simples.

Um hábito que compensa: todo erro visto em produção ou em piloto vira um novo cenário na suíte. Com o tempo, a suíte passa a ser a memória dos problemas que já aconteceram.

Como evitar que a simulação minta?

O risco de uma suíte baseada em mocks é ficar verde enquanto o mundo real mudou. Alguns cuidados ajudam:

• Compare periodicamente o formato dos mocks com as respostas do sandbox do provedor ou da documentação oficial, para detectar campos novos, removidos ou renomeados.
• Inclua nos mocks os erros reais da API, com o mesmo formato e a mesma mensagem, e não apenas um erro genérico inventado.
• Evite simulações simpáticas demais. Se a API real às vezes devolve dados incompletos, o mock também deve devolver.
• Diferencie o que vem de documentação oficial, o que vem de experiência de implementação e o que é hipótese. Um comportamento suposto da API deve estar marcado como suposição no teste, até ser confirmado.

No método que Juan Carlo usa com empresas, esse trabalho se encaixa nas quatro etapas. Em mapear, entram as ferramentas do processo e o que cada uma pode fazer. Em limitar, definem-se as permissões, separando leitura de escrita. Em pilotar, um fluxo real roda primeiro contra as simulações e depois, com registros e uma métrica combinada, em operação controlada. Em transferir, a suíte de cenários é entregue junto com o agente, para que a equipe decida se expande, ajusta ou interrompe com evidência na mão.

Perguntas frequentes

Preciso de sandbox do provedor se já tenho mocks? Nem sempre no dia a dia, mas vale usar de tempos em tempos. Os mocks dão velocidade e repetibilidade, e o sandbox confirma que o contrato real continua igual ao que você simulou. Se o provedor não oferece ambiente de teste, uma verificação manual e cuidadosa na documentação oficial já cumpre parte desse papel.

Posso usar dados reais de clientes nos testes? O mais seguro é não usar. Dados sintéticos cobrem quase todos os cenários e evitam que informações pessoais circulem por repositórios, logs e ferramentas de terceiros, o que se alinha ao princípio de necessidade da LGPD. Se for preciso gravar respostas reais para reproduzir um formato complexo, anonimize antes de guardar e limite quem tem acesso.

Isso funciona com agentes que usam MCP ou plataformas de fluxo sem código? Sim, porque a ideia é independente da tecnologia: o agente precisa receber ferramentas com o mesmo contrato, e a implementação por trás pode ser real ou simulada. Num servidor MCP, isso significa ter uma versão de teste que expõe as mesmas ferramentas. Em plataformas de fluxo, significa trocar os nós de integração por registradores no ambiente de teste.

Testar com mocks dispensa o piloto em produção? Não. Os mocks reduzem o risco e mostram falhas de decisão antes de qualquer cliente ser afetado, mas não reproduzem toda a variedade de mensagens e situações reais. O caminho mais prudente é rodar a suíte simulada, seguir para um piloto com um fluxo real, limites claros e transferência humana ativa, e só então decidir sobre ampliar o escopo.

Fontes

• Anthropic: Demystifying evals for AI agents
• Anthropic: Writing effective tools for agents
• Stripe: idempotent requests
• OWASP: LLM Prompt Injection Prevention Cheat Sheet