Por Que Confiabilidade É um Problema de Arquitetura, Não de Modelo

Quando você constrói um agente de IA para um domínio onde uma resposta errada pode mandar um navio de patrulha para o lado oposto do oceano, o modelo é a parte menos interessante do sistema. O verdadeiro desafio de engenharia é construir algo em que você possa confiar: correto, dentro dos limites, e que se mantenha firme em tarefas completamente diferentes — contra dados ao vivo, não um snapshot estático.

Essa é a história de como o time por trás de uma plataforma aberta de consciência do domínio marítimo construiu seu agente. As lições valem para qualquer um colocando agentes em produção — seja em saúde, finanças ou atendimento ao cliente.

O insight central: agentes são não-determinísticos, mas as ferramentas que eles usam não precisam ser. Cada ganho de confiabilidade veio de restringir o que cada camada da stack pode errar.

Se você tem pensado em como agentes aprendem com conhecimento especializado sem retraining, esse padrão arquitetural conversa direto com a abordagem do segundo cérebro organizacional.

AI agent answering maritime domain awareness query about Ghana EEZ with source attribution and map deep link Programming Illustration

A Anatomia do Agente: Alma, Habilidades e Config

O time decompõe o agente em três partes:

  • Alma (Soul) — o system prompt que define a persona e os limites comportamentais. Diz explicitamente o que o agente não vai fazer (ex.: "nunca fazer determinações legais", "nunca especular além dos dados").
  • Habilidades (Skills) — arquivos markdown com frontmatter estruturado que codificam como lidar com tipos específicos de requisição. Mesma spec usada pelo Claude Code e Codex.
  • Config — escolha de harness, escolha de LLM, configurações de runtime. Trocar o modelo é mudança de config, não rebuild.

Alma + habilidades ficam empacotadas em uma imagem Docker — artefato versionado e deployável. Segredos são injetados em runtime.

Por Que Essa Separação Importa

Quando os limites vivem no system prompt (e não em fine-tuning), eles são auditáveis e fáceis de revisar. Quando as habilidades são markdown puro, cada uma é compreensível, versionável e diffável em um PR.

Ferramentas Determinísticas para um Agente Não-Determinístico

A maior vitória de confiabilidade: encapsule sua API em uma CLI feita sob medida, em vez de deixar o agente construir chamadas cruas.

# ANTES: agente constrói chamadas de API do zero
# Resultado: paginação malformada, erros de encoding de geometria,
# bugs silenciosos de tipo de filtro que retornam dados *errados*

# DEPOIS: agente emite um comando tipado, a CLI cuida do encanamento
# skylight events search --region "EEZ do Panamá" \
#   --type fishing --since 2024-01-01 --output resultados.json

Por que a abordagem via CLI funciona:

  1. Flags de filtro tipadas colapsam objetos de query aninhados complexos em uma interface previsível.
  2. Auto-documentada — texto extenso de --help e mensagens de erro estruturadas deixam o agente se recuperar sem adivinhar.
  3. Escreva em disco, não em stdout — passar JSON grande por pipe de shell estoura buffer e quebra ferramentas como jq. Escrever em arquivo local resolve os dois problemas e permite que o agente leia resultados ao longo de workflows multi-etapa.

Debaixo da CLI fica uma API tipada com um par comum de operações search/aggregate em todos os tipos de recurso. Cada camada restringe o que a próxima pode errar: API tipada → CLI determinística → habilidades do agente referenciando comandos da CLI.

Kubernetes pods provisioning isolated agent sandbox sessions for multi-user AI platform

Sandbox, Isolamento e Avaliação do Agente Inteiro

Sessões Isoladas por Usuário

Quando seu agente atende centenas de agências governamentais e ONGs em mais de 70 países, isolamento de dados não é negociável. O padrão:

  • Cada sessão de usuário ganha um deployment Kubernetes dedicado com seus próprios pods.
  • O JWT do usuário é injetado no provisionamento, escopando todas as chamadas de API aos dados dele.
  • Arquivos escritos durante a análise existem apenas naquela sessão.
  • Acesso de rede é restrito apenas aos serviços que o agente precisa.

Esse é o tipo de decisão de infraestrutura que parece chata num slide, mas é onde a maioria dos projetos de agente em produção falha silenciosamente.

⚠️ Os Limites Que Você Precisa Conhecer

Mesmo um agente bem arquitetado tem modos de falha. Dos próprios dados de avaliação do time:

  • Ultrapassar para recomendações — o agente escorregou de apoio à decisão para conselho tático. Guardrails precisam ser testados, não presumidos.
  • Bugs de simplificação de geometria — fronteiras simplificadas espacialmente fizeram o agente perder eventos reais perto das bordas.
  • Chamadas de ferramenta inventadas — o agente alucinou um comando de CLI que não existia. É exatamente por isso que sua CLI precisa retornar um erro claro de "comando desconhecido" com a lista dos válidos.

Avaliando o Agente, Não o Modelo

Benchmarks estáticos não dizem se seu agente funciona em produção. O time construiu seu próprio pipeline de avaliação:

  1. Especialistas de domínio escrevem cenários e rubricas, e ponderam cada critério por tarefa.
  2. Um prompt em linguagem natural roda pelo sandbox real, contra dados ao vivo.
  3. Um juiz LLM pontua cada critério de 0 a 1 com justificativa escrita.
  4. O agregado ponderado é comparado a um limiar fixo de aprovação.
  5. Resultados são timestampados e diffados contra a execução anterior.

Uma versão que regride nos critérios de avaliação nunca chega aos usuários finais. Essa é a disciplina que separa um demo de um produto.

Para outro ângulo sobre tornar o comportamento da infraestrutura transparente e debugável, veja este texto sobre tornar falhas de trust anchor do DNSSEC visíveis.

LLM judge evaluation pipeline scoring AI agent responses against weighted rubric criteria on live data Development Concept Image

O Que Roubar para o Seu Próprio Agente

Se você está construindo um agente em produção, aqui está o checklist que emergiu desse projeto:

  1. Separe alma, habilidades e config. Empacote alma+habilidades em uma imagem versionada. Faça a troca de modelo ser mudança de config.
  2. Nunca deixe o agente construir chamadas cruas de API. Encapsule tudo em uma CLI tipada e auto-documentada com erros estruturados.
  3. Escreva saídas grandes em disco, não em stdout. Pipes de shell vão te trair em escala.
  4. Faça sandbox de cada sessão. Isolamento por usuário não é opcional quando dados reais estão envolvidos.
  5. Avalie o agente inteiro, não o modelo. Rubricas, juízes LLM, scores ponderados, diffs de versão.
  6. Bloqueie release em regressão de avaliação. Sem verde, sem ship.

O Que Vem a Seguir Nesse Espaço

Três padrões que valem ficar de olho: controle de UI dirigido pelo agente (o agente não só devolve links, ele dirige o mapa), roteamento de modelo (modelos baratos para lookups, modelos frontier para investigações) e memória entre threads (fatos persistentes como a jurisdição de um usuário carregados automaticamente entre conversas).

Para Onde Ir Daqui

  • Comece instrumentando seu agente atual com um harness de avaliação antes de adicionar features.
  • Se você ainda não tem um wrapper de CLI para sua API, esse é o passo um.
  • Leia o writeup original de engenharia para o contexto completo: evidências e material-fonte.

Confiabilidade não é uma feature que você adiciona no final. É a arquitetura que você escolhe no início. 🚀

Este conteúdo foi elaborado com o auxílio de ferramentas de IA, com base em fontes confiáveis, e revisado pela nossa equipe editorial antes da publicação. Não substitui o aconselhamento de um profissional especializado.