Um agente pode entender uma solicitação, consultar documentos e decidir qual ação executar. Uma API legada, porém, não trabalha com essa flexibilidade. Ela espera campos obrigatórios, tipos específicos, códigos válidos e regras que muitas vezes só aparecem em documentação antiga ou no comportamento do próprio sistema.
A validação de saídas com estrutura tipada cria uma fronteira clara entre a interpretação feita pelo modelo e a execução feita pelo sistema. O modelo produz uma intenção estruturada. Um componente determinístico verifica essa intenção. Só depois a aplicação transforma os dados no formato exigido pela API enterprise.
Esse padrão não elimina alucinações nem torna o agente autônomo por completo. Ele reduz uma classe importante de falhas: dados incompletos, tipos incorretos, valores fora do domínio permitido e chamadas incompatíveis com o contrato do sistema legado. A pessoa responsável pelo processo continua necessária para casos ambíguos, operações sensíveis e mudanças de regra.
Mapeamento de sistemas existentes
Antes de escolher um esquema, mapeie o caminho completo da informação. Em geral, há quatro partes: a entrada recebida pelo agente, a saída estruturada proposta pelo modelo, o adaptador de integração e a API ou fila do sistema legado.
Para cada etapa, registre:
- Quais campos entram e saem.
- Quais campos são obrigatórios.
- Quais tipos são aceitos, como texto, número, data ou lista.
- Quais valores pertencem a um conjunto fechado.
- Quais combinações de campos são proibidas.
- Quais efeitos a operação produz no sistema legado.
- Como erros são retornados e identificados.
Esse inventário costuma revelar que o contrato real é mais restritivo do que a documentação indica. Uma API pode aceitar uma data em texto, mas exigir um formato específico. Um campo descrito como opcional pode ser necessário para determinado tipo de operação. Um código de status pode parecer livre, mas aceitar apenas valores cadastrados no ERP.
Separe o modelo interno do modelo externo. O esquema interno deve representar a intenção da aplicação com nomes claros e tipos úteis para o domínio. O esquema externo deve representar o contrato da API legada. O adaptador faz a conversão entre os dois.
Por exemplo, o agente pode produzir uma solicitação de alteração de cadastro com customer_id, reason, requested_by e changes. O sistema legado pode exigir outros nomes, uma data de atualização e uma estrutura específica para cada campo alterado. Não peça ao modelo que memorize todas as peculiaridades do sistema externo. Mantenha essa responsabilidade no adaptador, onde ela pode ser testada e versionada.
Um esquema tipado deve validar mais do que a presença de campos. Ele deve verificar tipos, limites, formatos e valores permitidos. Uma biblioteca de validação de esquemas para a linguagem usada pela aplicação pode fazer essa tarefa. Em ambientes que suportam saída estruturada, o modelo também pode receber o esquema como restrição de geração. Ainda assim, essa restrição não substitui a validação local. A aplicação deve tratar a resposta do modelo como entrada não confiável.
A sequência recomendada é:
- Receber a resposta do modelo.
- Decodificar o conteúdo estruturado.
- Validar o esquema e os tipos.
- Aplicar regras de negócio determinísticas.
- Converter para o contrato externo.
- Validar novamente o payload externo.
- Executar a chamada somente se todas as verificações passarem.
A segunda validação é útil porque a transformação pode introduzir problemas. Um identificador pode ser convertido para o campo errado. Uma data pode perder o fuso horário. Uma lista pode ser achatada em um texto incompatível com a API. O payload enviado precisa ser tratado como um artefato próprio, não como uma consequência automaticamente segura do primeiro esquema.
Quando a validação falhar, não tente corrigir silenciosamente qualquer valor. Classifique o erro. Um campo ausente pode permitir uma nova pergunta ao usuário. Um código desconhecido pode exigir consulta a uma tabela autorizada. Uma inconsistência grave deve interromper o fluxo e encaminhar o caso para revisão humana.
Protocolos de comunicação seguros
A estrutura correta não protege uma integração se o transporte e a autorização forem frágeis. A chamada ao sistema legado deve ocorrer em um componente controlado pela aplicação, não em uma ação livre para o modelo executar diretamente.
Use uma camada de serviço ou adaptador com responsabilidades explícitas. Ela deve receber apenas dados já validados, aplicar autenticação, registrar o identificador de correlação e chamar o endpoint permitido. O agente não deve receber credenciais, escolher URLs arbitrárias ou montar cabeçalhos de segurança.
Prefira conexões criptografadas e mecanismos de autenticação compatíveis com o ambiente. O segredo deve ficar em um gerenciador de credenciais ou em uma configuração protegida, nunca no prompt, no esquema ou nos registros de conversa. A conta usada pela integração deve ter o menor conjunto de permissões necessário. Se a operação exige apenas consulta, não use uma credencial que também possa alterar cadastros.
Valide também o destino. Em integrações com APIs REST antigas, mantenha uma lista explícita de hosts, caminhos e métodos permitidos. Isso reduz o risco de o sistema enviar dados para um endpoint inesperado. Para sistemas que usam filas, valide o nome da fila, o tipo de mensagem e a versão do contrato antes do envio.
Idempotência é outro requisito importante. Agentes podem repetir uma ação após um erro de rede, uma interrupção ou uma resposta não recebida. Se a operação criar um pedido, atualizar um cadastro ou emitir um documento, use uma chave de idempotência quando o sistema suportar esse recurso. Caso não suporte, implemente uma proteção no adaptador, como o registro de uma chave de operação e a consulta de seu resultado antes de repetir a chamada.
Não trate toda falha como motivo para repetir. Erros de autenticação, validação ou autorização normalmente exigem correção, não novas tentativas. Repetições devem ser limitadas e usar espera progressiva para falhas temporárias. Também defina um tempo limite. Uma chamada sem limite pode manter um agente ocupado, aumentar custos de inferência e acumular operações pendentes.
Inclua confirmação humana para ações de alto impacto. O agente pode preparar um payload válido para cancelar um contrato, alterar dados financeiros ou modificar permissões. Validade estrutural não significa autorização de negócio. Antes da chamada final, mostre ao responsável os campos relevantes, a origem dos dados e o efeito esperado. Registre a decisão e a identidade de quem aprovou.
Monitoramento da integração
Uma integração tipada precisa ser observável em três níveis: saída do modelo, validação e sistema externo. Sem essa separação, uma falha na API pode ser confundida com erro de interpretação, e uma resposta inválida do modelo pode parecer instabilidade do legado.
Gere um identificador de correlação para cada execução e propague-o entre o agente, o adaptador e a API. Registre eventos estruturados, como esquema usado, versão do adaptador, resultado da validação, tipo de operação, código de resposta e duração. Evite armazenar documentos completos, tokens de acesso e dados pessoais sem necessidade. Para depuração, prefira identificadores mascarados e amostras controladas.
Acompanhe pelo menos estas métricas:
- Percentual de saídas que falham na decodificação.
- Percentual de saídas rejeitadas pelo esquema.
- Percentual de falhas nas regras de negócio.
- Taxa de erro por endpoint e tipo de operação.
- Latência da inferência, validação e chamada externa.
- Quantidade de tentativas e operações duplicadas.
- Percentual de casos encaminhados para uma pessoa.
Observe também a distribuição dos valores. Um aumento repentino de um código de cliente desconhecido pode indicar mudança no cadastro, problema de recuperação de dados ou alteração no comportamento do modelo. Uma queda na taxa de validação pode ser causada por mudança no prompt, no esquema ou no provedor de inferência. Compare versões e mantenha registros suficientes para reproduzir a execução.
Teste o contrato em duas direções. Testes unitários devem verificar se o adaptador transforma corretamente cada tipo de intenção. Testes de contrato devem confirmar que o payload continua aceito pelo sistema externo. Inclua casos de campos ausentes, tipos inválidos, caracteres especiais, datas fora do intervalo e respostas inesperadas.
Quando o sistema legado oferecer um ambiente de teste, use-o para validar o fluxo completo. Caso não ofereça, crie um servidor simulado baseado no contrato conhecido e mantenha uma lista de diferenças em relação à produção. O objetivo não é confiar cegamente no simulador, mas detectar regressões antes de liberar uma alteração.
Faça a versão do esquema e do adaptador. Uma mudança aparentemente pequena, como tornar um campo obrigatório, pode alterar decisões do agente e invalidar operações antigas. Preserve a compatibilidade quando possível. Quando não for, encaminhe respostas produzidas pela versão anterior para o adaptador correspondente ou bloqueie a migração até que os casos pendentes sejam tratados.
Checks de segurança antes da chamada final
Antes de permitir que uma saída estruturada alcance um sistema legado, use uma lista de verificação curta e obrigatória:
- A resposta foi decodificada sem aceitar conteúdo extra como instrução?
- O esquema correto e sua versão foram aplicados?
- Todos os campos obrigatórios estão presentes e com tipos válidos?
- Os valores pertencem aos domínios autorizados?
- As regras de negócio foram verificadas fora do modelo?
- O adaptador gerou um payload compatível com o contrato externo?
- O destino está em uma lista permitida?
- A credencial tem apenas as permissões necessárias?
- A operação é idempotente ou possui proteção contra repetição?
- A ação exige aprovação humana?
- O identificador de correlação foi criado?
- O conteúdo dos registros não expõe segredos ou dados desnecessários?
Se uma resposta falhar, preserve o motivo da rejeição e o contexto mínimo para análise. Não envie um payload parcialmente corrigido sem deixar claro o que foi alterado. Em muitos fluxos, a melhor saída é pedir uma informação específica ao usuário ou colocar a operação em uma fila de revisão.
A validação tipada funciona porque distribui responsabilidades. O modelo interpreta e propõe. O esquema verifica a forma. As regras determinísticas verificam o significado permitido. O adaptador traduz para o sistema existente. A autenticação controla o acesso. O monitoramento mostra o que aconteceu. Essa arquitetura não remove a complexidade de integrar IA a sistemas legados, mas torna os limites explícitos, testáveis e operáveis.
