Engenharia
Esta página é para quem vai auditar a arquitetura antes de assinar. Nove práticas que não são opcionais em nenhuma entrega — e a razão de cada uma existir.
O princípio
Modelo de linguagem é excelente para interpretar pedido ambíguo e redigir resposta clara. É péssimo como registro de decisão: não é reprodutível, não é testável linha a linha e não tem histórico de mudança.
Por isso a fronteira é rígida. Toda decisão que precisa ser justificada vive em código determinístico. O agente consome o resultado e comunica.
No exemplo ao lado, o modelo nunca aprova nem nega crédito. Ele recebe uma Decisao já tomada, com motivo e número da política aplicada, e escreve a mensagem ao cliente.
# Função pura. Mesma entrada, mesma decisão. Sempre.
# Coberta por teste unitário. Rastreável no histórico do Git.
def avaliar_elegibilidade(proposta: Proposta) -> Decisao:
if proposta.idade < IDADE_MINIMA:
return Decisao.negar(
motivo="IDADE_MINIMA",
politica="POL-CRED-014",
)
if proposta.score < faixa_minima(proposta.produto):
return Decisao.negar(
motivo="SCORE_ABAIXO_DA_FAIXA",
politica="POL-CRED-021",
)
return Decisao.aprovar(
limite=calcular_limite(proposta),
politica="POL-CRED-030",
)
# O agente recebe a Decisao pronta e escreve a mensagem.
# Ele não sabe aprovar. Ele não sabe negar.Práticas
Autorizar, calcular, classificar segundo norma e definir elegibilidade são funções puras em Python, com teste unitário. O agente recebe a decisão pronta e escreve a mensagem. Ele não sabe aprovar nem negar.
Por quê: Auditor não aceita "o modelo entendeu assim". Aceita função versionada e testada.
Todo agente roda dentro de um wrapper: guarda de fluxo (o usuário pode estar aqui?), guarda de entrada (escopo, tamanho, tentativa de injeção, dado sensível) e guarda de saída (vazamento técnico, PII de terceiro, formato). Nenhum nó escapa.
Por quê: Controle aplicado por convenção falha. Aplicado por construção, não.
Prompts vivem em YAML versionado, com número de versão explícito. Trocar comportamento é criar a versão seguinte, rodar a avaliação e promover. Voltar atrás é apontar para a versão anterior — sem deploy de código.
Por quê: Rollback de comportamento em minutos, com rastro de quem mudou o quê e quando.
Cada agente tem conjunto de avaliação construído com casos reais do seu domínio. Mudou prompt, modelo ou regra, a suíte roda. Queda além do limiar acordado bloqueia a promoção.
Por quê: É o equivalente a teste de regressão para comportamento não determinístico.
Log estruturado em JSON sempre ativo; buffer em memória alimentando o painel operacional; tracing externo opcional. As camadas superiores degradam em silêncio — se o tracing cai, o sistema não cai junto.
Por quê: Diagnosticar incidente em produção sem depender de fornecedor externo estar de pé.
Cada turno de conversa é persistido com o estado completo. A sessão sobrevive a reinício e a falha de processo, e pode ser reconstruída passo a passo meses depois.
Por quê: É isso que transforma "acho que foi assim" em trilha de auditoria de verdade.
O provedor de LLM fica atrás de uma fábrica com cache e configuração por variável de ambiente. Trocar de fornecedor, ou migrar para modelo aberto na sua infraestrutura, não toca na lógica de negócio.
Por quê: Preço e qualidade de modelo mudam a cada trimestre. Sua arquitetura não deveria.
Toda escolha estrutural relevante vira um ADR curto no repositório: contexto, alternativas consideradas, decisão e consequência. Entregamos o histórico junto com o código.
Por quê: Seis meses depois, o time novo entende por que está assim — sem arqueologia.
Provedor de modelo, banco de estado, tracing: cada dependência externa tem caminho degradado previsto e testado. O sistema perde recurso, não disponibilidade.
Por quê: Em ambiente regulado, indisponibilidade também é incidente reportável.
Stack
A arquitetura é desenhada para trocar peça sem reescrever o sistema. O que segue é o que usamos por padrão — e adaptamos ao que o seu time já opera e sabe manter.
Marcamos uma conversa técnica com o seu time de arquitetura e segurança. Sem apresentação comercial — abrimos a estrutura, os guardrails e a estratégia de avaliação.