Projetando sistemas agentivos que não colapsam em produção

De demos impressionantes a agentes frágies em produção

Sistemas agentivos são aplicações nas quais um LLM não se limita a responder a um prompt, mas decide o que fazer a seguir: quais ferramentas chamar, quais dados buscar, quais passos executar e quando está “feito”. Eles combinam um modelo, um conjunto de ferramentas (APIs, bancos de dados, serviços), um loop de planejamento/execução e a infraestrutura que junta tudo isso.

Em uma demo, isso parece mágico: um agente elabora um plano, chama algumas ferramentas e retorna um resultado perfeito. O caminho feliz é curto, a latência é baixa e nada falha ao mesmo tempo.

Por que as demos funcionam e a produção quebra

Sob cargas reais, o mesmo agente é pressionado de maneiras que a demo nunca viu:

• APIs expiram, retornam dados parciais ou mudam contratos.
• Várias requisições competem por recursos compartilhados e corrompem estado.
• Conversas de longa duração incham a memória e excedem limites de contexto.
• Erros sutis do modelo se acumulam através de muitas chamadas de ferramenta.

O resultado: comportamento instável difícil de reproduzir, corrupção silenciosa de dados e fluxos de usuário que ocasionalmente travam ou giram para sempre.

O impacto real no negócio

Agentes instáveis não apenas prejudicam a “experiência”:

• Disparam incidentes e páginas de on‑call.
• Produzem respostas erradas que vazam para sistemas downstream.
• Erodem a confiança do usuário: pessoas param de confiar na funcionalidade.
• Inflam a fatura de nuvem via retries e loops descontrolados.

No que este guia foca

Este artigo trata de padrões de engenharia, não de “prompts melhores”. Vamos ver máquinas de estado, contratos explícitos de ferramentas, estratégias de retry e tratamento de falhas, controle de memória e concorrência, e padrões de observabilidade que tornam sistemas agentivos predizíveis sob carga — não apenas impressionantes no palco.

Por que a maioria das arquiteturas de agentes quebra em escala

A maioria dos sistemas de agentes parece funcionar bem em uma demo com caminho feliz único. Eles falham quando tráfego, ferramentas e casos de borda aparecem juntos.

Comportamentos frágeis: loops, bloqueios, trabalho parcial, erros silenciosos

Orquestrações ingênuas presumem que o modelo “fará a coisa certa” em uma ou duas chamadas. No uso real, você vê padrões recorrentes:

• Loops: o agente continua replanejando ou re‑chamando a mesma ferramenta porque nunca reconhece conclusão ou falha.
• Bloqueios: o agente espera por uma ferramenta ou subtarefa sem timeout, deixando sessões de usuário penduradas.
• Trabalho parcial: o agente completa metade do fluxo (por exemplo, rascunha um e‑mail mas não o envia, gera um plano mas não executa os passos).
• Erros silenciosos: ferramentas falham ou schema diverge, mas o agente retorna com confiança uma resposta plausível com dados faltantes ou errados.

Sem estados explícitos e condições finais, esses comportamentos são inevitáveis.

Não‑determinismo oculto e a não confiabilidade das ferramentas

A amostragem do LLM, variabilidade de latência e tempos das ferramentas criam não‑determinismo oculto. A mesma entrada pode percorrer ramos diferentes, invocar ferramentas distintas ou interpretar resultados de maneira diversa.

Em escala, problemas das ferramentas dominam:

• Timeouts e instabilidade de APIs e bancos upstream
• Drift de schema entre contratos de ferramenta e o que os serviços realmente retornam
• Formatos de erro inconsistentes que o agente nunca aprendeu a tratar

Cada um desses vira loops espúrios, retries ou respostas finais incorretas.

Concorrência amplifica casos de borda e desalinhamento de produto

O que raramente quebra a 10 RPS quebrará constantemente a 1.000 RPS. A concorrência revela:

• Condições de corrida em estado compartilhado ou caches
• Limites de taxa esgotados que causam falhas em cascata de ferramentas
• Revoadas de retries desencadeadas por um único pico em uma dependência

Times de produto frequentemente esperam fluxos determinísticos, SLAs claros e auditabilidade. Agentes, deixados sem restrições, oferecem comportamento probabilístico, best‑effort com garantias fracas.

Quando arquiteturas ignoram esse desalinhamento — tratando agentes como serviços tradicionais em vez de planejadores estocásticos — os sistemas se comportam de forma imprevisível justamente quando a confiabilidade importa mais.

Princípios de design para sistemas agentivos prontos para produção

Agentes prontos para produção têm menos a ver com “prompts inteligentes” e mais com design disciplinado de sistemas. Uma forma útil de pensá‑los é como pequenas máquinas previsíveis que ocasionalmente chamam um LLM, não como blobs misteriosos de LLM que ocasionalmente tocam seus sistemas.

O que torna um agente pronto para produção?

Quatro propriedades importam mais:

• Segurança: o agente deve respeitar restrições sobre acesso a dados, efeitos colaterais e promessas ao usuário. Isso implica permissões explícitas, guardrails nas ferramentas e tratamento cuidadoso de saídas não confiáveis.
• Previsibilidade: dadas as mesmas entradas e estado, o agente deve se comportar dentro de uma banda estreita e esperada. Você deve ser capaz de explicar o que ele pode e o que não pode fazer.
• Depurabilidade: quando algo dá errado, você consegue traçar o caminho: qual estado, qual decisão, qual chamada de ferramenta, qual chamada de modelo. Sem loops ocultos, sem “pensamentos” opacos sem estrutura.
• Tolerância a mudanças: você pode atualizar modelos, ferramentas ou estratégias sem reescrever todo o sistema.

Você não obtém essas propriedades apenas com prompts. Você as obtém com estrutura.

Prefira fluxos explícitos a loops livres

O padrão inicial de muitas equipes é: “enquanto não estiver pronto, chame o modelo, deixe‑o pensar, talvez chame uma ferramenta, repita”. Isso é fácil de prototipar e difícil de operar.

Um padrão mais seguro é representar o agente como um fluxo explícito:

• Defina um conjunto finito de estados (ex.: COLLECTING_INPUT, PLANNING, EXECUTING_STEP, WAITING_ON_HUMAN, DONE).
• Defina quais transições são permitidas entre estados.
• Use o LLM principalmente para decisões locais: escolher o próximo estado, selecionar uma ferramenta ou preencher parâmetros.

Isso transforma o agente em uma máquina de estado onde cada passo é inspecionável, testável e replayable. Loops livres parecem flexíveis, mas fluxos explícitos é o que torna incidentes depuráveis e comportamentos auditáveis.

Separe o “agente deus” em skills modulares

Agentes monolíticos que “fazem tudo” são atraentes, mas criam acoplamento entre responsabilidades não relacionadas: planejamento, recuperação, lógica de negócio, orquestração de UI e mais.

Em vez disso, componha agentes pequenos e bem escopados ou skills:

• Um planner que decompõe tarefas.
• Um executor que roda passos concretos.
• Um especialista por domínio (faturamento, suporte, analytics, etc.).

Cada skill pode ter sua própria máquina de estados, ferramentas e regras de segurança. A lógica de composição vira então um fluxo de nível superior, não um prompt em crescimento contínuo dentro de um único agente.

Essa modularidade mantém cada agente simples o suficiente para raciocinar e permite evoluir uma capacidade sem desestabilizar as demais.

Separe política, estado e ferramentas

Um modelo mental útil é dividir um agente em três camadas:

1. Política de decisão (prompts + modelo)
   Encapsula como o agente escolhe próximas ações, interpretado sob restrições estritas. Você deve poder trocar o modelo, ajustar temperatura ou refinar prompts sem tocar o encanamento do sistema.

2. Máquina de estado / motor de workflow
   Assume onde você está no processo, quais transições são possíveis e como persistir progresso. A política sugere um movimento; a máquina de estado valida e aplica.

3. Camada de ferramentas
   Implementa o que pode realmente acontecer no mundo: APIs, bancos, filas, serviços externos. Ferramentas expõem contratos estreitos e bem tipados e aplicam autorização, limites de taxa e validação de entrada.

Ao impor essa separação, você evita o erro de esconder lógica de negócio em prompts ou descrições de ferramentas. O LLM vira um componente de decisão dentro de uma concha determinística clara, não a concha em si.

Projete para pequenez e clareza

Os sistemas agentivos mais confiáveis não são as demos mais impressionantes — são aqueles cujo comportamento você consegue explicar em um quadro branco.

Concretamente:

• Mantenha cada agente focado em um trabalho e uma métrica de sucesso principal.
• Codifique o fluxo e as transições de estado explicitamente em vez de em prosa.
• Deixe os LLMs escolherem entre opções bem definidas, não inventarem procedimentos inteiros do zero.

Esse viés para agentes pequenos, componíveis e bem estruturados permite que sistemas cresçam em escopo sem desabar sob sua própria complexidade.

Modelando fluxos de agente como máquinas de estado explícitas

A maioria das implementações de agente começa como um loop de “pensar, agir, observar” em volta de uma chamada de LLM. Isso funciona para demos, mas rapidamente vira opaco e frágil. Uma abordagem melhor é tratar o agente como uma máquina de estados explícita: um conjunto finito de estados, com transições bem definidas acionadas por eventos.

Representando fluxos de agente como estados e transições

Em vez de deixar o modelo decidir implicitamente o que fazer a seguir, defina um pequeno diagrama de estados:

• PLAN – interpretar o pedido do usuário, decompor em passos, escolher ferramentas.
• CALL_TOOL – executar uma única chamada de ferramenta (ou lote) com entradas validadas.
• VERIFY – checar saídas de ferramenta contra invariantes simples ou verificações adicionais do modelo.
• RECOVER – tratar erros: retry, fallback ou escalonamento.
• DONE – retornar uma resposta final e encerrar o workflow.
• FAILED – erro terminal com motivo e contexto claros.

Transições entre esses estados são acionadas por eventos tipados como UserRequestReceived, ToolCallSucceeded, ToolValidationFailed, TimeoutExceeded ou HumanOverride. Cada evento, junto com o estado atual, determina o próximo estado e ações.

Isso torna retries e timeouts diretos: você anexa políticas a estados individuais (por exemplo, CALL_TOOL pode re-tentar 3 vezes com backoff exponencial; PLAN pode não re-tentar) em vez de espalhar lógica de retry pelo código.

Externalizando estado para resiliência e escala

Persista o estado atual e o contexto mínimo em uma store externa (banco de dados, fila ou motor de workflow). O agente então vira uma função pura:

next_state, actions = transition(current_state, event, context)

Isso permite:

• Resiliência – se um worker morrer no meio da execução, outro pode retomar do último estado persistido.
• Escala horizontal – workers stateless consomem eventos, atualizam estado e emitem próximos eventos.
• Replays e compensações – você pode reconstruir uma execução, re‑dirigi‑la de qualquer estado ou executar ações compensatórias quando um fluxo precisa ser revertido.

Benefícios para raciocínio e auditoria

Com uma máquina de estados, cada passo do comportamento do agente é explícito: em qual estado estava, que evento ocorreu, qual transição disparou e quais efeitos colaterais foram produzidos. Essa clareza acelera a depuração, simplifica investigações de incidentes e cria uma trilha de auditoria natural para compliance. Você pode provar, a partir de logs e histórico de estado, que certas ações de risco só são tomadas a partir de estados específicos e sob condições definidas.

Desenhando contratos de ferramenta confiáveis para agentes

Agentes se comportam de forma muito mais previsível quando ferramentas parecem menos com “APIs escondidas em prosa” e mais com interfaces bem desenhadas com garantias explícitas.

Defina o contrato, não apenas o prompt

Cada ferramenta deve ter um contrato que cubra:

• Esquema de entrada: campos obrigatórios, tipos, enums, restrições, defaults.
• Esquema de saída: payload de sucesso, campos anuláveis e o que significa “sem resultado”.
• Modelo de erro: erros tipados (ex.: InvalidInput, NotFound, RateLimited, TransientFailure) com semânticas claras.
• SLAs: expectativas de latência, metas de disponibilidade e limites de taxa.

Exponha esse contrato ao modelo como documentação estruturada, não como um muro de texto. O planner do agente deve saber quais erros são re‑tentáveis, quais requerem intervenção humana e quais devem parar o workflow.

JSON estrito, validação rigorosa

Trate I/O de ferramenta como qualquer outra API de produção:

• Use schemas JSON estritos (ex.: OpenAPI, JSON Schema) para entradas e saídas.
• Valide antes da chamada (para pegar erros do modelo) e depois (para detectar regressões da ferramenta).
• Auto‑corrija problemas menores (ex.: coerção de tipos) mas registre‑os para ajuste posterior.

Isso permite simplificar prompts: em vez de instruções verbosas, confie em orientação guiada por schema. Restrições claras reduzem argumentos alucinados e sequências de ferramenta sem sentido.

Versionamento e compatibilidade

Ferramentas evoluem; agentes não devem quebrar sempre que isso ocorre.

• Versione contratos de ferramenta (v1, v1.1, v2) e fixe agentes a uma versão.
• Deprecate campos gradualmente; mantenha campos antigos legíveis por um tempo.
• Adicione campos de forma retrocompatível; evite mudar semântica silenciosamente.

A lógica de planejamento pode então misturar agentes e ferramentas em diferentes estágios de maturidade com segurança.

Tratando falhas e modos degradados

Projete contratos com falha parcial em mente:

• Permita resultados parciais com detalhes de erro por item.
• Defina uma resposta degradada (ex.: dados em cache, aproximados ou stale) em vez de falha dura.
• Marque quais campos são “best effort” versus “must have”.

O agente pode então adaptar: continuar o fluxo com funcionalidade reduzida, pedir confirmação ao usuário ou trocar para uma ferramenta alternativa.

Segurança e limites de autorização

Contratos de ferramenta são um local natural para codificar limites de segurança:

• Escopo do que a ferramenta pode ler ou modificar.
• Requerer parâmetros explícitos para ações sensíveis (ex.: confirm: true).
• Distinguir operações com escopo do usuário das com escopo do sistema.

Combine isso com checagens server‑side; nunca confie apenas no modelo para “se comportar”.

Por que bons contratos simplificam agentes

Quando ferramentas têm contratos claros, validados e versionados, prompts podem ser mais curtos, a orquestração fica mais simples e a depuração muito mais fácil. Você move complexidade de instruções em linguagem natural para schemas e políticas determinísticas, reduzindo chamadas de ferramenta alucinadas e efeitos colaterais inesperados.

Padrões de retries, idempotência e tratamento de falhas

Sistemas agentivos confiáveis assumem que tudo falhará eventualmente: modelos, ferramentas, redes, até sua própria camada de coordenação. O objetivo não é evitar falhas, mas torná‑las baratas e seguras.

Idempotência: a base para retries seguros

Idempotência significa: repetir a mesma requisição produz o mesmo efeito externamente visível que executá‑la uma vez. Isso é crítico para agentes LLM, que frequentemente reemitem chamadas de ferramenta após falhas parciais ou respostas ambíguas.

Torne ferramentas idempotentes por design:

• Request IDs: cada chamada inclui um request_id estável. A ferramenta armazena isso e retorna o mesmo resultado se vir o ID novamente.
• Upserts em vez de inserts: use semântica “create‑or‑update” baseada em uma chave de negócio natural ou sintética, não em um ID auto‑incremental.
• Checksums e versionamento: anexe hashes de conteúdo ou números de versão para que a ferramenta detecte duplicatas, escritas stale ou conflitos.

Estratégias de retry que não explodem custos

Use retries estruturados para falhas transitórias (timeouts, limites de taxa, 5xx): backoff exponencial, jitter para evitar revoadas e máximo de tentativas rígido. Registre cada tentativa com IDs de correlação para traçar o comportamento do agente.

Para falhas permanentes (4xx, erros de validação, violação de regras de negócio), não re‑tente. Exponha um erro estruturado ao policy do agente para que ele replaneje, pergunte ao usuário ou escolha outra ferramenta.

Circuit breakers e fallbacks

Implemente circuit breakers tanto na camada do agente quanto na das ferramentas: após falhas repetidas, bloqueie temporariamente chamadas àquela ferramenta e falhe rápido. Pareie isso com fallbacks bem definidos: modos degradados, dados em cache ou ferramentas alternativas.

Evite retries cegos a partir do loop do agente. Sem ferramentas idempotentes e classes de falha claras, você só multiplica efeitos colaterais, latência e custo.

Gerenciando memória, estado e consistência de dados para agentes

Agentes confiáveis começam com pensamento claro sobre o que é estado e onde ele vive.

Estado de curto prazo vs memória de longo prazo

Trate um agente como você trataria um serviço que atende uma requisição:

• Estado de curto prazo: tudo o que é necessário para completar a tarefa atual ou subtarefa. Inclui objetivo ativo, passo atual, saídas de ferramentas, decisões parciais e variáveis de controle (retries restantes, ramo escolhido, etc.). Deve ser escopado e descartável quando o workflow terminar.
• Memória de longo prazo: informações que devem sobreviver entre execuções e sessões: perfis de usuário, preferências, decisões anteriores, histórico de projeto e atalhos aprendidos.

Misturar esses tipos leva a confusão e bugs. Por exemplo, colocar resultados efêmeros de ferramentas na “memória” faz agentes reutilizarem contexto stale em conversas futuras.

Onde armazenar estado

Você tem três opções principais:

1. In‑context (apenas prompt) – Simples, baixa latência, mas limitado e não durável. Melhor para estado de curto prazo dentro de uma única execução.
2. Store externa – Banco de dados, cache ou store vetorial. Use para memória de longo prazo e qualquer estado que deva sobreviver a reinícios ou coordenar entre workers.
3. Híbrido – mantenha o estado autoritativo externamente; carregue apenas o necessário no contexto para o próximo passo.

Uma boa regra: o LLM é uma função stateless sobre um objeto de estado explícito. Persista esse objeto fora do modelo e regenere prompts a partir dele.

Evite o anti‑padrão “logs como memória”

Um padrão comum de falha é usar logs de conversa, traces ou prompts brutos como memória de fato.

Problemas:

• Recuperação vira ad hoc e frágil.
• Fatos importantes ficam enterrados em texto longo.
• Múltiplas execuções podem contradizer uma à outra sem um claro “last write wins”.

Em vez disso, defina schemas de memória estruturada: user_profile, project, task_history, etc. Derive logs a partir do estado, não o contrário.

Consistência com dados e ferramentas compartilhadas

Quando múltiplas ferramentas ou agentes atualizam as mesmas entidades (ex.: um registro de CRM ou status de tarefa), você precisa de controles básicos de consistência:

• Use fontes únicas da verdade para entidades-chave (ex.: pedido, ticket, documento).
• Prefira contratos idempotentes: ferramentas devem tratar retries com segurança usando IDs estáveis e semântica de upsert.
• Aplique concorrência otimista (números de versão, timestamps) quando agentes podem disputar a atualização do mesmo registro.

Para operações de alto valor, registre um log de decisões separado do log conversacional: o que mudou, por quê e com base em quais entradas.

Snapshots e execuções retomáveis

Para sobreviver a crashes, deploys e limites de taxa, workflows devem ser retomáveis:

• Após cada passo significativo, persista um snapshot de estado: passo atual, entradas, resultados de ferramentas e ações pendentes.
• Faça cada transição da sua máquina de estados reexecutável a partir do snapshot.
• Em falha ou reinício, recarregue o último snapshot e continue em vez de reiniciar do zero.

Isso também possibilita debugging com viagem no tempo: inspecionar e reproduzir o estado exato que levou a uma decisão ruim.

Privacidade, retenção e memória mínima

Memória é tanto ativo quanto passivo. Para agentes em produção:

• Modele explicitamente o que nunca deve ser armazenado (ex.: segredos, documentos brutos, PII sensível). Use redacção ou hashing onde apropriado.
• Defina políticas de retenção por tipo de memória (sessão, 30 dias, retenção legal, etc.).
• Dê aos usuários controles para visualizar e apagar sua memória de longo prazo.
• Evite armazenar prompts completos ou entradas de ferramenta quando um resumo estruturado menor é suficiente.

Trate memória como um produto: projetada, versionada e governada — não um despejo de texto em crescimento preso ao seu agente.

Concorrência, limites de taxa e backpressure em sistemas de agentes

Agentes parecem sequenciais em um quadro, mas se comportam como sistemas distribuídos sob carga real. Assim que você tem muitos usuários concorrentes, ferramentas e jobs em background, você está lidando com condições de corrida, trabalho duplicado e problemas de ordenação.

Riscos de concorrência em fluxos de agente

Modos comuns de falha:

• Condições de corrida: duas execuções de agente atualizam o mesmo ticket, carrinho ou documento concorrentemente, sobrescrevendo uma à outra.
• Trabalho duplicado: retries ou workers mal configurados processam a mesma tarefa duas vezes (ex.: cobrança dupla).
• Efeitos fora de ordem: chamadas a ferramentas terminam em ordem inesperada, fazendo um resultado antigo sobrescrever um mais novo.

Você mitiga isso com contratos idempotentes de ferramentas, estado de workflow explícito e locking otimista/pessimista na camada de dados.

Filas vs fluxos síncronos

Fluxos síncronos request–response são simples mas frágeis: cada dependência deve estar ativa, dentro dos limites de taxa e rápida. Quando agentes se ramificam para muitas ferramentas ou subtarefas em paralelo, mova etapas longas ou com efeitos colaterais para trás de uma fila.

Orquestração baseada em fila permite:

• Controlar concorrência com pools de workers
• Centralizar retries e deduplicação
• Isolar ferramentas lentas ou instáveis da latência voltada ao usuário

Limites de taxa e backpressure

Agentes normalmente atingem três classes de limites:

• Modelos: tokens por minuto, requisições por minuto, tamanho de contexto
• Ferramentas: serviços internos com QPS ou limites de CPU
• APIs upstream: cotas de terceiros e limites rígidos

Você precisa de uma camada de rate‑limit explícita com throttles por usuário, por tenant e globais. Use baldes de tokens ou leaky buckets para aplicar políticas, e exponha erros claros (ex.: RATE_LIMIT_SOFT, RATE_LIMIT_HARD) para que agentes possam retroceder com elegância.

Backpressure é como o sistema se protege sob estresse. Estratégias incluem:

• Descartar primeiro tráfego não crítico
• Degradar recursos (contextos menores, menos chamadas de ferramenta)
• Pausar filas de baixa prioridade enquanto mantém fluxos críticos em movimento

Monitore sinais de saturação: profundidade de filas, utilização de workers, taxas de erro de modelo/ferramenta e percentis de latência. Filas crescendo combinadas com latência e erros 429/503 são seu aviso precoce de que agentes estão derrubando o ambiente.

Observabilidade: tracing, métricas e logs para comportamento de agentes

Você não consegue tornar um agente confiável se não consegue responder duas perguntas rapidamente: o que ele fez? e por que ele fez isso? Observabilidade para sistemas agentivos é sobre tornar essas respostas baratas e precisas.

O que você precisa ver

Projete observabilidade para que uma única tarefa tenha um trace que atravesse:

• Cada passo do agente e transição de estado
• Cada chamada de ferramenta e resposta
• Cada invocação de modelo e variante de prompt

Dentro desse trace, anexe logs estruturados para decisões-chave (escolha de roteamento, revisão de plano, acionamentos de guardrail) e métricas para volume e saúde.

Um trace útil normalmente inclui:

• Metadados da tarefa: tenant, usuário, canal, prioridade
• Estado do agente: nome do estado atual, próximo estado, contador de retries
• I/O de ferramentas: inputs, outputs, latência, erros, status de circuit breaker
• Chamadas de modelo: ID do template de prompt, nome do modelo, contagem de tokens, latência

Logging e redação

Log prompts, entradas e saídas de ferramentas em forma estruturada, mas passe‑os por uma camada de redacção antes:

• Mascarar PII e segredos
• Truncar payloads muito grandes com hashes para correlação
• Marcar campos com níveis de sensibilidade para controlar retenção e acesso

Mantenha conteúdo bruto atrás de feature flags em ambientes não‑prod; a produção deve padronizar visualizações redigidas.

Métricas que realmente importam

No mínimo, monitore:

• Taxa de sucesso/falha de tarefas por agente e caso de uso
• Contagem média e P95 de passos por tarefa
• Latência: ponta a ponta e por ferramenta/modelo
• Custo por tarefa (tokens, gasto com ferramentas) e por resultado bem‑sucedido

Quando incidentes acontecem, bons traces e métricas permitem transformar “o agente parece instável” em uma afirmação precisa como: “P95 de tarefas falhando em ToolSelection após 2 retries devido a novo schema em billing_service”, cortando o diagnóstico de horas para minutos e dando alavancas concretas para ajuste.

Estratégias de teste e avaliação para sistemas agentivos

Testar agentes significa testar tanto as ferramentas que eles chamam quanto os fluxos que unem tudo. Trate isso como teste de sistemas distribuídos, não apenas ajuste de prompts.

Testes unitários: contratos de ferramenta, não prompts

Comece com testes unitários na fronteira da ferramenta:

• Valide schemas: campos obrigatórios, enums, ranges e invariantes.
• Cheque idempotência e semântica de erro (quais erros, quais códigos, re‑tentabilidade).
• Asserte que ferramentas lidam com entradas malformadas de forma graciosa e retornam falhas estruturadas.

Esses testes não dependem do LLM. Chame a ferramenta diretamente com entradas sintéticas e afirme a saída ou contrato de erro exato.

Testes de integração: fluxos e comportamento multi‑passos

Testes de integração exercitam o workflow do agente end‑to‑end: LLM + ferramentas + orquestração.

Modele‑os como testes baseados em cenários:

• Caminhos felizes para jornadas principais do usuário (reserva, reembolso, escalonamento, etc.).
• Casos de borda: dados faltantes, falhas parciais de ferramenta, timeouts, limites de taxa.
• Interações entre ferramentas: quando a saída da ferramenta A alimenta a B.

Esses testes afirmam transições de estado e chamadas de ferramenta, não cada token do LLM. Verifique: quais ferramentas foram chamadas, com quais argumentos, em que ordem e qual estado/resultado final o agente alcançou.

Fixtures determinísticas para LLM e ferramentas

Para manter testes repetíveis, fixe respostas do LLM e saídas de ferramentas.

• Grave respostas do LLM uma vez (por prompt + modelo + configuração) e armazene‑as como fixtures JSON.
• Mocke sistemas externos por trás das ferramentas para que testes não atinjam serviços ao vivo.
• Use seeds explícitos e configurações de temperatura fixa nos testes.

Um padrão típico:

with mocked_llm(fixtures_dir="fixtures/llm"), mocked_tools():
    result = run_agent_scenario(input_case)
    assert result.state == "COMPLETED"

Suites de regressão para prompts e schemas

Qualquer mudança de prompt ou schema deve acionar uma execução de regressão inegociável:

• Mantenha um corpus curado de entradas mais estados esperados, traces de ferramenta ou classificações.
• Trave esses como arquivos golden; diffs destacam mudanças de comportamento.
• Aprove explicitamente ou reverta qualquer drift em fluxos críticos.

Evolução de schema (adicionar campos, apertar tipos) recebe seus próprios casos de regressão para detectar agentes ou ferramentas que ainda assumem o contrato antigo.

Avaliação offline antes do rollout

Nunca envie um novo modelo, política ou estratégia de roteamento direto para produção.

Em vez disso:

• Reexecute seu corpus de regressão offline contra a nova configuração.
• Rode testes de replay em interações históricas amostradas.
• Calcule métricas automáticas (sucesso de tarefa, taxa de erro de ferramenta, latência, custo) e, quando necessário, avaliações humanas em amostras.

Só após passar por portões offline é que uma nova variante deve chegar à produção, idealmente atrás de feature flags e rollout gradual.

Gestão de dados de teste e anonimização

Logs de agentes frequentemente contêm dados sensíveis. Testes devem respeitar isso.

• Construa conjuntos de teste a partir de entradas anonimizadas ou sintéticas.
• Remova ou hasheie identificadores, PII em texto livre e segredos antes de armazenar logs ou fixtures.
• Segmente acesso: engenheiros veem traces de comportamento, mas não segredos brutos de usuário.

Codifique essas regras no pipeline de CI para que nenhum artefato de teste seja gerado ou armazenado sem checagens de anonimização.

Operando, monitorando e evoluindo agentes em produção

Operar agentes em produção é mais parecido com rodar um sistema distribuído do que entregar um modelo estático. Você precisa de controles para rollout, metas de confiabilidade claras e gestão disciplinada de mudanças.

Estratégias de rollout seguras

Introduza novos agentes ou comportamentos gradualmente:

• Shadow mode: rode o agente ao lado do sistema existente, registre decisões, mas não afete usuários. Compare saídas offline.
• Canários: exponha uma pequena porção do tráfego (ex.: 1–5%) à nova versão. Observe taxas de erro, latência e qualidade antes de escalar.
• Testes A/B: para fluxos visíveis ao usuário, compare novo vs. antigo nas métricas de negócio, não apenas métricas de modelo.

Sustente tudo isso com feature flags e políticas dirigidas por configuração: regras de roteamento, ferramentas habilitadas, temperatura, ajustes de segurança. Mudanças devem ser configuráveis, não codificadas, e instantaneamente reversíveis.

SLOs e fluxos de incidentes

Defina SLOs que reflitam saúde do sistema e valor ao usuário:

• Confiabilidade: taxa de sucesso de tarefas, chamadas de ferramenta e workflows ponta a ponta.
• Latência: p50/p95 para caminhos críticos.
• Qualidade: scores de auto‑avaliação, distribuição de avaliações humanas ou métricas específicas de sucesso de tarefa.

Ligue isso a alertas e trate incidentes como em qualquer serviço de produção: propriedade clara, runbooks de triagem e passos padrão de mitigação (rollback de flag, drenagem de tráfego, modo seguro).

Melhoria contínua e controle de mudanças

Use logs, traces e transcrições para refinar prompts, ferramentas e políticas. Trate cada mudança como um artefato versionado com revisão, aprovação e capacidade de rollback.

Evite mudanças silenciosas de prompt ou ferramenta. Sem controle de mudanças, você não consegue correlacionar regressões a edições específicas, e resposta a incidentes vira tentativa e erro em vez de engenharia investigativa.

Uma arquitetura de referência para sistemas agentivos confiáveis

Um sistema agentivo pronto para produção se beneficia de separação clara de responsabilidades. O objetivo é manter o agente inteligente nas decisões, mas pouco inteligente na infraestrutura.

Componentes centrais

1. Gateway / borda de API
Ponto de entrada único para clientes (apps, serviços, UIs). Ele lida com:

• Autenticação e autorização (usuário, serviço, tenant)
• Limites de taxa e cotas
• Modelagem de requisição (schemas, limites de tamanho, validação básica)

2. Orquestrador
O orquestrador é o “tronco”, não o cérebro. Ele coordena:

• Planner: traduz intenção do usuário em workflow ou máquina de estados
• Orquestrador de estado: executa o workflow, rastreia estado, trata retries e timeouts
• Motor de políticas: aplica segurança, compliance, ferramentas permitidas, regras de PII e orçamentos de custo

Os LLMs ficam atrás do orquestrador, usados pelo planner e por ferramentas específicas que precisam de entendimento de linguagem.

3. Camada de ferramentas e armazenamento
Lógica de negócio permanece em microservices existentes, filas e sistemas de dados. Ferramentas são wrappers finos em torno de:

• Serviços internos HTTP/gRPC
• Bancos de dados, stores vetoriais, caches
• APIs externas

O orquestrador invoca ferramentas via contratos estritos, enquanto sistemas de armazenamento continuam sendo a fonte de verdade.

Integração, controles e telemetria

Aplique auth e cotas no gateway; aplique segurança, acesso a dados e políticas no orquestrador. Todas as chamadas (LLM e ferramentas) emitem telemetria estruturada para um pipeline que alimenta:

• Traces para comportamento passo a passo
• Métricas para SLOs e limites de taxa
• Logs de auditoria para segurança e compliance
• Contabilidade de custos por usuário, projeto e ferramenta

Uma arquitetura simples (gateway → orquestrador único → ferramentas) é mais fácil de operar; adicionar planners separados, motores de política e gateways de modelo aumenta flexibilidade, ao custo de mais coordenação, latência e complexidade operacional.

Juntando tudo e próximos passos para seu time

Você agora tem os ingredientes centrais para agentes que se comportam de forma previsível sob carga real: máquinas de estado explícitas, contratos de ferramenta claros, retries disciplinados e observabilidade profunda. O passo final é transformar essas ideias em prática repetível para seu time.

Os padrões centrais, em uma frase

Pense em cada agente como um workflow com estado:

• Uma máquina de estados define passos legais (plan → gather → act → summarize, etc.) e transições entre eles.
• Contratos de ferramenta definem o que cada ação pode fazer, com schemas rígidos, timeouts e superfícies de erro.
• Retries e idempotência protegem cada interação externa para que replays sejam seguros e efeitos colaterais não se dupliquem.
• Observabilidade (traces, métricas, logs) torna cada decisão e chamada de ferramenta explicável e depurável.

Quando essas peças se alinham, você obtém sistemas que degradam com graça em vez de colapsar diante de casos de borda.

Checklist leve para levar um agente à produção

Antes de enviar um agente protótipo a usuários reais, confirme:

• Workflow: estados e transições explícitos; sem loops ocultos, sem cadeias ilimitadas de ferramentas.
• Contratos: cada ferramenta tem entradas/saídas tipadas, modos claros de falha e timeouts.
• Segurança: guardrails em entradas, saídas e ações (limites de taxa, allowlists, cotas).
• Retries: políticas definidas por ferramenta; chaves de idempotência para todas chamadas com efeitos colaterais.
• Estado: memória e estado persistente são escopados, versionados e recuperáveis.
• Observabilidade: você consegue responder “o que aconteceu?” de qualquer sessão de usuário em um único trace.
• Testes: você tem testes baseados em cenários e suítes de regressão para prompts, ferramentas e políticas.

Se algum item estiver faltando, você ainda está em modo protótipo.

Como times podem dividir propriedade

Uma configuração sustentável normalmente separa:

• Times de produto: proprietários do comportamento do agente, prompts, ferramentas de domínio e conjuntos de avaliação.
• Times de plataforma/infra: responsáveis pelo framework de máquinas de estado, SDKs de ferramenta comuns, logging e tracing, enforcement de políticas e infraestrutura de avaliação compartilhada.

Isso permite que times de produto avancem rapidamente enquanto times de plataforma impõem confiabilidade, segurança e controles de custo.

Extensões futuras e iteração segura

Com fundações estáveis, você pode explorar:

• Políticas baseadas em aprendizado: usar traces logados para melhorar roteamento, seleção de ferramenta e estratégias de fallback.
• Aprendizado por reforço: otimizar resultados de longo horizonte como conclusão de tarefa ou receita, não apenas respostas únicas.
• Workflows autoajustáveis: ajustar automaticamente temperaturas, ferramentas ou sub‑fluxos com base no desempenho observado.

Progresso aqui deve ser incremental: introduza novos componentes de aprendizado atrás de feature flags, com avaliação offline e guardrails fortes.

O tema em tudo isso é o mesmo: projete para falha, favoreça clareza sobre esperteza e itere onde você pode observar e reverter com segurança. Com essas restrições, sistemas agentivos deixam de ser protótipos assustadores e viram infraestrutura em que sua organização pode confiar.