Testes de contrato para ferramentas de agentes de IA

A integração pode responder e ainda quebrar o trabalho

Um agente comercial chama uma ferramenta para criar a próxima ação no CRM. A requisição recebe status de sucesso. Depois da atualização do conector, o campo data passa a aceitar horário em outro fuso, o retorno deixa de trazer o identificador da tarefa e erros de duplicidade passam a usar um código genérico.

A chamada continua tecnicamente disponível. O agente já não consegue confirmar quando a tarefa foi criada, distinguir repetição de falha temporária nem apresentar o registro correto ao responsável.

Testes de contrato para ferramentas de agentes de IA verificam se a interface entre agente, dispatcher, ferramenta e sistema de destino continua obedecendo ao acordo esperado. Eles conferem formato, significado, estados de erro, autorização, efeito e compatibilidade antes que uma mudança alcance casos reais.

O objetivo consiste em detectar quebras na fronteira entre componentes. Testar apenas a resposta do modelo ou o status da API deixa o trecho mais perigoso do processo sem prova.

O que é um contrato de ferramenta

Um contrato descreve o que uma capacidade aceita, promete, rejeita e registra.

Ele pode incluir:

nome e versão da operação;
finalidade e unidade de trabalho;
identidade autorizada;
campos obrigatórios e opcionais;
tipos, formatos, limites e enumerações;
pré-condições do objeto;
política e aprovação exigidas;
efeito permitido;
retorno em sucesso;
códigos e classes de erro;
comportamento diante de repetição;
timeout e estado incerto;
confirmação no sistema de destino;
evidência produzida;
regra de compatibilidade e retirada.

Considere uma ferramenta chamada criar_proxima_acao. O contrato útil vai além de aceitar texto e data. Ele determina que a oportunidade precisa estar ativa, que o responsável vem do CRM, que só pode existir uma tarefa aberta para o mesmo compromisso e que o sucesso devolve o identificador confirmado pelo sistema.

O catálogo de ferramentas para agentes de IA organiza essas capacidades, seus donos e controles. O teste de contrato comprova que a implementação continua fiel à ficha publicada.

Por que agentes tornam esse teste mais importante

Integrações comuns já sofrem com mudanças de API. Agentes acrescentam três fontes de variação.

A entrada pode ser proposta por um modelo

O agente interpreta linguagem, recupera contexto e monta argumentos. Mesmo com saída estruturada, pode selecionar enumeração inadequada, omitir evidência ou usar um identificador que pertence a outro objeto.

O contrato precisa rejeitar o que estiver formalmente correto e operacionalmente inválido.

A escolha da ferramenta também varia

O agente pode chamar uma capacidade parecida, insistir depois de um erro ou mudar a sequência prevista. O teste precisa confirmar quando a ferramenta pode ser usada e quando deve permanecer inacessível.

O retorno influencia decisões futuras

Um código de erro mal classificado pode provocar retentativa. Um sucesso sem confirmação pode fazer o agente declarar conclusão. Um campo removido pode apagar a evidência usada na aprovação humana.

A interface não transporta somente dados. Ela governa a próxima decisão do processo.

Teste de contrato, teste unitário e teste ponta a ponta

Esses testes se complementam.

Teste unitário

Verifica uma função ou regra isolada. Pode conferir cálculo, normalização, validação de um campo ou mapeamento de código.

Teste de contrato

Verifica o acordo na fronteira entre produtor e consumidor. Confirma que ambos entendem a mesma operação, os mesmos campos, erros e efeitos.

Teste de integração

Usa componentes reais ou representativos para conferir comunicação, autenticação, rede, serialização e comportamento do sistema conectado.

Teste ponta a ponta

Acompanha a unidade desde a entrada até a consequência confirmada. Mostra se o agente escolheu a ferramenta, recebeu autorização, executou e encerrou o trabalho corretamente.

O ambiente de teste para agentes de IA fornece a fronteira para executar essas camadas com identidades, dados e destinos controlados.

Um teste ponta a ponta pode falhar e exigir investigação longa. O teste de contrato localiza mais cedo se a quebra está na interface. Ele reduz diagnóstico, mas não substitui a prova do fluxo completo.

Comece pela responsabilidade, não pelo schema

Copiar a especificação da API para um teste automatizado pode confirmar a tecnologia e ignorar a operação.

Antes de escrever casos, registre:

qual unidade de trabalho usa a ferramenta;
que decisão autoriza a chamada;
qual objeto será consultado ou alterado;
que invariantes precisam permanecer;
qual efeito conta como sucesso;
que erros podem ser corrigidos;
que erros exigem bloqueio ou revisão;
que evidência permite confirmar o resultado;
quem mantém a capacidade;
quais consumidores dependem dela.

Uma API pode permitir atualizar qualquer campo de uma oportunidade. O contrato do agente comercial pode permitir apenas criar uma próxima ação, sem alterar responsável, estágio, valor ou contato.

O contrato empresarial precisa ser mais estreito que a superfície técnica disponível.

Teste a entrada em quatro camadas

Estrutura

Confirme:

campos obrigatórios;
tipos;
enumerações;
formatos de data e identificador;
tamanho de texto e lista;
proibição de campos desconhecidos quando houver risco;
versão declarada.

A página sobre saídas estruturadas para agentes de IA explica como schemas reduzem ambiguidade entre etapas.

Semântica

Um identificador pode ter formato válido e apontar para cliente errado. Uma data pode respeitar ISO 8601 e estar no passado. Um desconto pode ser numérico e superar a alçada.

Teste:

existência do objeto;
vínculo com a identidade solicitante;
estado atual compatível;
coerência entre campos;
faixa de valor;
validade temporal;
fonte autorizada;
evidência suficiente.

Política

A ferramenta deve conferir se aquela identidade pode executar aquela ação sobre aquele objeto naquele contexto.

Inclua casos com:

permissão ausente;
aprovação vencida;
cliente fora do escopo;
ambiente incorreto;
horário bloqueado;
classificação de dado incompatível;
volume acima do teto;
ação proibida para aquela versão do agente.

Idempotência e concorrência

A mesma entrada pode chegar novamente depois de timeout, retomada ou evento duplicado. Duas execuções também podem disputar o mesmo objeto.

Verifique se:

uma chave estável identifica o efeito;
repetição retorna o resultado anterior quando apropriado;
a ferramenta impede duplicidade;
conflito de versão produz erro tratável;
estado incerto segue para reconciliação;
duas chamadas concorrentes preservam as invariantes.

O guia sobre idempotência em agentes de IA detalha o intervalo entre comando, efeito e confirmação perdida.

Teste o retorno como parte da operação

Um contrato de saída precisa ajudar o consumidor a decidir o próximo passo.

Em sucesso, confira:

identificador da operação;
objeto afetado;
versão da ferramenta;
estado anterior e novo, quando aplicável;
horário e fuso;
confirmação do destino;
avisos;
pendências ainda abertas;
referência para auditoria.

Em falha, confira:

classe do erro;
código estável;
mensagem segura;
possibilidade de nova tentativa;
prazo para tentar novamente;
campos que precisam de correção;
estado do efeito externo;
destino de escalonamento.

Uma mensagem erro ao processar obriga o agente a adivinhar. Ele pode insistir em uma credencial inválida, corrigir um campo que estava certo ou abandonar uma tarefa já executada.

Erros devem separar pelo menos:

entrada inválida;
objeto inexistente;
estado incompatível;
permissão negada;
aprovação necessária;
conflito concorrente;
limite de capacidade;
falha temporária;
falha permanente;
efeito incerto;
duplicidade já concluída.

Simule estados incertos

O caso mais traiçoeiro aparece quando a ferramenta envia a ação, o sistema executa e a confirmação se perde.

O consumidor observa timeout. Se tentar novamente sem verificar, pode duplicar mensagem, pedido, tarefa ou pagamento. Se desistir, pode deixar a operação concluída sem registro local.

Crie testes para:

falha antes do envio;
falha durante a transmissão;
efeito concluído sem resposta;
resposta recebida sem persistência local;
confirmação parcial;
consulta de reconciliação indisponível;
retomada depois de expiração da credencial.

O contrato precisa indicar como localizar o efeito por chave ou identificador. A reconciliação em agentes de IA organiza a comparação entre fila, logs, estado local e sistema oficial.

Verifique compatibilidade entre versões

Mudanças aparentemente pequenas podem quebrar consumidores.

Mudanças geralmente compatíveis

Podem incluir campo opcional novo, código de aviso adicional ou aumento de limite que preserva significado. Mesmo assim, consumidores rígidos podem rejeitar campos desconhecidos.

Mudanças potencialmente incompatíveis

Incluem:

renomear ou remover campo;
alterar tipo;
trocar significado de enumeração;
mudar fuso ou unidade;
tornar campo opcional obrigatório;
reduzir limite;
alterar semântica de sucesso;
agrupar erros antes distintos;
mudar comportamento de repetição;
produzir efeito adicional;
retirar versão sem localizar consumidores.

Para cada mudança, teste a combinação entre produtor e consumidores ativos. Uma ferramenta nova precisa aceitar chamadas da versão ainda autorizada do agente durante a transição. Um agente novo não deveria depender de um campo que a ferramenta antiga não fornece no ambiente atual.

O controle de mudanças em agentes de IA deve publicar contrato, implementação, política, consumidores e testes como partes da mesma composição.

Use testes orientados pelo consumidor

A equipe que mantém a ferramenta conhece o que a API oferece. Cada consumidor conhece o que precisa para concluir sua responsabilidade.

Um contrato orientado pelo consumidor registra expectativas como:

o agente de reuniões precisa consultar histórico sem enxergar dados financeiros;
o agente financeiro precisa receber código de duplicidade separado de indisponibilidade;
o workflow comercial depende do identificador da tarefa criada;
o revisor precisa ver campos alterados e fonte;
a rotina de contingência precisa reconhecer quando o efeito ficou incerto.

Essas expectativas podem virar casos automatizados executados antes da publicação da ferramenta.

Evite permitir que qualquer consumidor imponha detalhes internos desnecessários. O contrato deve proteger comportamento relevante, não congelar a implementação inteira.

Mantenha uma matriz de casos mínimos

Uma matriz prática pode conter:

| Classe | Caso | Resultado esperado | |---|---|---| | comum | entrada válida e objeto elegível | efeito confirmado | | estrutura | campo obrigatório ausente | rejeição sem chamada externa | | semântica | objeto de outro cliente | bloqueio por escopo | | política | aprovação vencida | pendência para nova aprovação | | repetição | mesma chave já concluída | retorno do efeito existente | | concorrência | estado mudou desde a leitura | conflito sem sobrescrita | | capacidade | dependência limitada | fila ou espera conforme política | | falha | timeout antes do efeito | tentativa segura permitida | | incerteza | efeito sem confirmação | reconciliação obrigatória | | compatibilidade | consumidor antigo com versão nova | comportamento preservado ou bloqueio de publicação |

A matriz cresce a partir de incidentes, exceções e mudanças reais. Ela não precisa começar enorme. Precisa cobrir as consequências que a empresa não aceita descobrir em produção.

Automatize o teste no caminho de publicação

O teste perde força quando depende de alguém lembrar de executá-lo.

Um fluxo pode seguir esta sequência:

alterar contrato ou implementação;
validar schema e especificação;
executar testes unitários;
executar contratos de produtores e consumidores;
iniciar integrações em sandbox ou mocks realistas;
testar falhas, permissão e repetição;
executar regressão do agente;
comparar versão atual e candidata;
bloquear publicação diante de quebra não autorizada;
liberar para ambiente controlado;
observar execuções reais limitadas;
ampliar ou reverter.

A automação deve guardar versão, resultado e evidência. Um check verde sem indicar quais contratos foram exercitados oferece pouca ajuda durante uma investigação.

Trate mocks com cautela

Mocks aceleram testes, mas podem representar um sistema que nunca falha.

Um mock útil reproduz:

schema real;
códigos e classes de erro;
latência variável;
timeout;
limite de taxa;
conflito de versão;
paginação;
autenticação expirada;
sucesso parcial;
comportamento idempotente;
campos extras ou ausentes previstos em transição.

Compare periodicamente o mock com a sandbox ou especificação vigente. Um contrato validado contra uma simulação desatualizada cria confiança sobre uma interface que já deixou de existir.

Defina dono para contrato e consumidor

Cada ferramenta precisa de:

Dono operacional

Confirma finalidade, invariantes, efeito aceitável e impacto da mudança.

Mantenedor técnico

Mantém implementação, versão, testes, observabilidade e correção.

Donos consumidores

Confirmam quais campos, erros e garantias sustentam cada processo.

Responsável pela publicação

Verifica evidências, compatibilidade, plano gradual e reversão.

Uma integração compartilhada sem mapa de consumidores tende a quebrar processos silenciosamente. A retirada de uma versão só termina quando chamadas restantes, filas, credenciais e dependências foram localizadas.

Métricas que mostram a saúde dos contratos

Acompanhe:

contratos por ferramenta e versão;
consumidores conhecidos;
execuções dos testes por mudança;
quebras detectadas antes da produção;
mudanças incompatíveis abertas;
consumidores em versão vencida;
erros de schema em produção;
erros sem classe tratável;
efeitos incertos;
duplicidades evitadas;
falhas causadas por mocks desatualizados;
tempo entre quebra e diagnóstico;
incidentes provocados por mudança de interface;
ferramentas sem dono ou sem suíte mínima.

O indicador central não é a quantidade de testes. É a capacidade de mudar uma integração sem surpreender os processos que dependem dela.

Erros comuns

Testar somente o caso de sucesso

A maioria das decisões operacionais aparece nos limites, conflitos e falhas. Um contrato que só confirma entrada válida ensina pouco sobre produção.

Copiar a documentação do fornecedor

A especificação externa descreve a plataforma. O contrato interno precisa limitar operação, identidade, objeto e efeito conforme o processo.

Validar forma e ignorar significado

JSON válido pode carregar destinatário errado, aprovação vencida ou valor fora da alçada.

Tratar todo erro como nova tentativa

Permissão negada, entrada inválida e conflito de política não melhoram com insistência. A classificação do erro deve orientar a rota.

Atualizar ferramenta sem localizar consumidores

A mudança passa nos testes do produtor e quebra agentes, workflows, dashboards ou revisores que dependiam de outra semântica.

Confiar em mocks permanentes

A simulação fica verde enquanto a API real evolui. Valide paridade e execute integrações controladas.

Checklist de testes de contrato

[ ] A responsabilidade operacional da ferramenta está definida?
[ ] O contrato é mais estreito que a API genérica?
[ ] Entradas possuem schema, limites e versão?
[ ] Validações semânticas consultam estado e fonte autorizada?
[ ] Identidade, permissão e aprovação fazem parte dos casos?
[ ] Sucesso exige confirmação do efeito?
[ ] Erros possuem classes e rotas tratáveis?
[ ] Timeout antes e depois do efeito foi testado?
[ ] Repetição e concorrência preservam invariantes?
[ ] Produtor e consumidores ativos são testados juntos?
[ ] Mudanças incompatíveis bloqueiam a publicação?
[ ] Mocks reproduzem falhas e permanecem alinhados?
[ ] Existe plano de convivência, migração e retirada?
[ ] Testes ficam ligados à versão publicada?
[ ] Incidentes viram casos de regressão?

Contrato testado transforma integração em capacidade confiável

Agentes aumentam o valor das integrações porque conseguem combinar contexto e agir em vários sistemas. A mesma flexibilidade torna cada fronteira mais sensível a mudanças de formato, significado, erro e autorização.

Testes de contrato tornam essas expectativas executáveis. Eles verificam o que entra, o que sai, qual efeito ocorreu, como a falha deve ser tratada e quais consumidores continuam compatíveis.

A empresa ganha liberdade para evoluir ferramentas sem usar a operação como ambiente de descoberta. O contrato deixa de ser documentação decorativa e passa a proteger a continuidade do trabalho.