Série Agent Gateway (Parte 6 de 7) | Observabilidade para Sistemas Não Determinísticos

Na engenharia de software tradicional, se um sistema falha, você olha para o stack trace. Ele aponta para a linha 42: NullPointerException. O erro NPE é determinístico, reproduzível e lógico.

Na Engenharia Agêntica, a falha é silenciosa e alucinatória. Um agente não lança uma exceção; ele mente com confiança. Ele pode dizer, "Atualizei o banco de dados com sucesso," quando na verdade não fez nada. Ou pode ficar preso em um loop de raciocínio, obcecado por um pequeno detalhe enquanto o usuário espera.

Você não pode depurar isso com logs padrão (console.log). Você precisa de um Gravador de Dados de Voo.

O Agent Gateway da TrueFoundry inclui um Módulo de Observabilidade abrangente projetado especificamente para sistemas probabilísticos. Ele registra a Cadeia de Pensamento (CoT) ou Árvore de Pensamentos (ToT), criando um histórico imutável e reproduzível de cada decisão que sua força de trabalho digital toma.

O Problema: O "Porquê" Está Faltando

Quando um LLM toma uma decisão, o "raciocínio" muitas vezes está oculto no estado transitório entre as chamadas de API.

• "Reserve-me um voo para NY."
• Saída: "Não consigo fazer isso."

Porquê? A API falhou? O prompt proibiu? O modelo alucinou uma restrição de política? Sem capturar o intermediário bloco de rascunhos — o monólogo interno do agente — você está agindo às cegas.

Um Exemplo Concreto: A Alucinação na Aprovação de Hipotecas

Para entender a necessidade deste sistema, vejamos um cenário de alto risco: Processamento Automatizado de Empréstimos.

O Incidente: Um cliente fiel com uma pontuação de crédito alta solicita uma hipoteca. O "Agente de Empréstimos" rejeita instantaneamente a solicitação com a seguinte razão: "O solicitante não cumpre os requisitos de residência." O cliente está furioso. Os engenheiros do banco estão perplexos — o cliente mora na mesma casa há 10 anos.

Depuração Sem um Gravador: Os engenheiros verificam os logs. Eles veem a entrada (PDF da solicitação) e a saída (Rejeição). Eles verificam o código — a função "Verificação de Residência" parece estar bem. Eles tentam reproduzir com um caso de teste, mas o modelo estocástico aceita o caso de teste. Eles não conseguem consertar o que não podem ver.

Depuração Com o Gravador TrueFoundry: A equipe consulta o ID de Rastreamento para aquela interação específica. Eles não veem apenas a E/S; eles veem o Rastro Cognitivo:

1. Etapa 1 (Planejamento): "Preciso verificar a renda e o endereço."
2. Etapa 2 (Chamada de Ferramenta): extract_address_from_pdf() -> Retorna "123 Maple St, Springfield, IL".
3. Etapa 3 (Raciocínio - O Bug): "Endereço extraído. Agora verificando o estado. O fundo do PDF é ligeiramente azul, o que me lembra o estilo de um passaporte não americano. Suspeito que seja uma solicitação estrangeira."
4. Etapa 4 (Alucinação): "A política exige residência nos EUA. Marcando como candidato estrangeiro."
5. Etapa 5 (Saída Final): "Rejeitado: Requisitos de residência."

A Solução: O bug não estava no código; estava na Cadeia de Raciocínio. O modelo alucinou uma correlação entre "fundo azul" e "passaporte não americano". Com essa percepção, os engenheiros atualizam o Prompt do Sistema: "Ignore artefatos visuais ou cores no documento ao determinar a residência. Confie APENAS no conteúdo do texto."

O bug foi corrigido.

‍

Fig 1: O Bug que vem da Cadeia de Raciocínio

Análise Técnica Aprofundada: O Rastro do Pensamento (OpenTelemetry)

Tratamos a cognição como um rastro distribuído. O Gateway integra-se com o OpenTelemetry (OTel) para visualizar o fluxo de trabalho do agente como uma cascata de spans.

Introduzimos convenções semânticas para spans de GenAI:

• genai.system_prompt: As instruções dadas ao modelo.
• genai.thought: O bloco de rascunho interno (oculto para o usuário).
• genai.tool_execution: As entradas e saídas das chamadas de função.
• genai.completion: O texto final enviado ao usuário.

Isso permite visualizar gargalos de latência. O agente está lento porque o GPT-4 está com atraso (Latência de Inferência)? Ou porque a consulta SQL demorou 10 segundos (Latência da Ferramenta)?

Conformidade: O Registro de Auditoria Imutável

Para indústrias regulamentadas (Finanças, Saúde), "A IA fez isso" não é uma defesa legal válida. De acordo com a Lei da IA da UE e SOC2 requisitos, você deve explicar Porquê uma decisão de IA foi tomada.

O Gateway implementa um Assíncrono Pipeline de Auditoria ..

1. Captura: Cada mensagem, pensamento e resultado de ferramenta é serializado.
2. Hashing: O payload é hashed (SHA-256) para garantir a integridade.
3. Armazenamento: O registo é enviado para S3 Object Lock (conformidade WORM - Write Once, Read Many). Isso garante que mesmo um administrador mal-intencionado não consiga alterar o histórico das decisões de um agente.

Se um auditor perguntar: "Mostre-me por que esta reivindicação médica foi negada em 15 de dezembro," pode obter a transcrição exata e à prova de adulteração.

‍

Fig. 2: Ilustração do Pipeline de Auditoria

Depuração Contrafactual e Avaliação

A observabilidade é inútil se você não puder agir sobre ela. O Gravador possibilita um fluxo de trabalho poderoso chamado Depuração Contrafactual.

Como capturamos todo o estado (Prompt do Sistema + Contexto + Entrada do Usuário) no momento da falha, o Gateway permite que você Bifurcar a Sessão. Você pode reproduzir a mesma solicitação exata, mas ajustar uma variável:

• E se usássemos GPT-4o em vez de GPT-3.5?
• E se aumentássemos a temperatura para 0.5?
• E se adicionássemos aquela nova instrução de segurança?

Você pode executar essas variações em paralelo (Modo Sombra) contra a gravação para verificar a correção antes de implantá-la em produção.

Conclusão

No mundo determinístico, monitoramos disponibilidade. No mundo agêntico, devemos monitorar alinhamento. O Gravador de Caixa Preta transforma a natureza caótica e probabilística da IA em um processo estruturado, observável e responsável. Ele fornece a visibilidade que os engenheiros precisam para depurar alucinações e a garantia que as equipes de conformidade precisam para aprovar a implantação.

‍