O agente funcionou na demo. Respondia perguntas, chamava ferramentas, produzia output estruturado. Duas semanas em produção: acumulou contexto até as respostas degradarem, invocou ferramentas sem validar inputs, perdeu estado entre execuções e não tinha mecanismo para escalar quando encontrou algo fora do seu treinamento. O post-mortem identificou a causa raiz como “limitações do LLM.” A causa raiz real: a equipe construiu o agente dando a um modelo acesso a ferramentas e chamou isso de sistema.
Não era um sistema. Era um LLM com API keys.
O Erro de Categoria Causando Falhas de Agentes
Quando uma equipe corporativa constrói um agente conectando um modelo a ferramentas e mandando-o descobrir o resto, delegou o design do sistema ao modelo. O modelo decidirá qual contexto reter, quando chamar qual ferramenta, o que constitui sucesso e quando parar. Tomará essas decisões de forma inconsistente, porque essas decisões exigem regras determinísticas, não modelagem de linguagem.
O framework 12-Factor Agents, desenvolvido por Dex Horthy na HumanLayer, chama isso de erro de categoria: tratar o LLM como o sistema em vez de como um componente dentro de um sistema. O reframe: o modelo gera tokens (e nada mais). Código determinístico executa ferramentas, valida estado, gerencia contexto, persiste resultados e decide quando pausar ou escalar.
Esse reframe muda o que você constrói. Também muda como você o depura. Quando um agente falha, a pergunta não é mais “o que o modelo fez de errado?” A pergunta é “qual componente falhou, e qual teste de software teria detectado isso?”
O Princípio Central: Seja Dono do Loop
Todo agente é um loop: observar, pensar, agir. Observar significa ler contexto, incluindo estado atual, resultados anteriores de ferramentas, memória relevante e qualquer coisa mais que o modelo precisa para raciocinar. Pensar significa planejar a próxima ação dado o objetivo e o estado observado. Agir significa executar a ação, seja uma chamada de ferramenta, uma escrita de arquivo, uma solicitação de API ou um output.
Ser dono do loop significa tornar cada parte desse ciclo explícita e controlada por software, não implícita e delegada ao modelo.
Seja dono do que entra na janela de observação. O modelo raciocina sobre o que está na janela de contexto. Os conteúdos da janela de contexto devem ser montados por código determinístico que carrega exatamente o que esta etapa exige. Não “aqui está tudo, modelo, descubra o que importa.” Mágica de framework que injeta memória, histórico de conversa e resultados de ferramentas implicitamente produz janelas de contexto imprevisíveis em produção e impossíveis de depurar quando o modelo degrada.
Seja dono da estrutura da etapa de raciocínio. Chain-of-thought, raciocínio de scratchpad, schemas de output estruturado e validação de output são todos mecanismos para fazer a etapa de raciocínio produzir outputs inspecionáveis e testáveis. Um modelo que escreve texto desestruturado antes de agir é mais difícil de validar do que um modelo que produz um objeto de decisão estruturado.
Seja dono das restrições sobre ação. Toda chamada de ferramenta deve ser precedida de validação de schema. Toda ação com consequências deve ser precedida de uma classificação de reversibilidade. Algumas ações devem exigir aprovação humana antes da execução. Esses são componentes de software, não comportamentos do modelo.
Para empresas: ser dono do loop também significa ser dono da trilha de auditoria. Qual janela de contexto produziu qual decisão, em qual etapa, em qual execução. Isso é um requisito de compliance em indústrias reguladas, não uma conveniência de logging.
Os Fatores Mais Úteis para Produção
O framework completo de 12 fatores está disponível no material de origem. Os fatores que previnem mais diretamente os modos de falha observados em implantações corporativas:
Seja dono dos prompts token por token. Saiba exatamente o que está na janela de contexto em cada etapa. Sem injeção implícita. Se um framework está adicionando memória, histórico ou resultados de ferramentas ao contexto sem instrução explícita, isso é um risco de produção. “O framework gerencia o contexto” é uma frase que deve produzir preocupação, não tranquilidade.
Monte contexto explicitamente. Carregue apenas o que é necessário para esta etapa. Uma etapa de pesquisa precisa de resultados de busca na web e uma declaração de objetivo. Não precisa do histórico completo de conversas, o perfil do usuário e o conteúdo de três outros documentos. Inchaço de contexto degrada qualidade e aumenta custo. A janela de contexto é um recurso, não um scratchpad para tudo que pode ser relevante.
Trate ferramentas como schemas tipados mais código determinístico. Defina schemas de input e output para toda ferramenta. Valide inputs antes da execução. Teste ferramentas independentemente do loop do agente. Uma ferramenta que escreve em um banco de dados deve ser testável sem rodar o agente inteiro. Se a ferramenta não pode ser testada independentemente, não é uma ferramenta. É código indiferenciado com uma API.
Separe estado de execução de estado de negócio. O progresso do agente pelas etapas (em qual etapa está, quais ferramentas chamou, quais outputs produziu) é estado de execução. O objeto de negócio sendo modificado (um pedido de compra, um registro de cliente, uma constatação de compliance) é estado de negócio. Esses vivem em lugares diferentes. Conflacioná-los torna a recuperação de estado após falha complexa e propensa a erros.
Mantenha agentes pequenos. Três a dez etapas com condições de entrada e saída claras. Agentes com mais de 30 etapas e loops abertos são pesadelos de depuração. Quando a tarefa exige mais de dez etapas, quase sempre é decomponível em dois ou três agentes menores com um protocolo de handoff.
Sumarize erros antes de reinjetar. Quando uma chamada de ferramenta falha, o trace de exceção bruto consome tokens e frequentemente confunde modelos. Comprima o erro: “ferramenta X falhou porque Y; as últimas três tentativas produziram Z.” Dê ao modelo informação estruturada sobre a falha, não uma parede de stack trace.
Aprovação humana como componente de sistema. Para ações de alto stakes ou irreversíveis, aprovação humana não é um caminho de exceção adicionado quando algo dá errado. É uma etapa projetada no fluxo de trabalho, com uma interface de aprovação definida, uma política de timeout definida e um caminho de escalada definido. Construa antes de precisar.
MCP como Infraestrutura de Ferramentas Governada
Model Context Protocol (MCP) é o padrão para expor ferramentas a agentes como conectores governados, versionados e auditáveis. O MCP define como um agente descobre ferramentas, chama ferramentas e recebe resultados, com autenticação, validação de schema e logging de auditoria construídos na camada de protocolo.
Em dezembro de 2025, o MCP foi doado para a Agentic AI Foundation sob a Linux Foundation, agora co-governado por Anthropic, OpenAI, Google, Microsoft e AWS. Mais de 10.000 servidores MCP estão ativos, com 97 milhões de downloads mensais de SDK. O MCP tornou-se o padrão de fato para conectividade de ferramentas de agentes, não uma solução específica de fornecedor.
Para empresas: o MCP transforma toda ferramenta em uma interface governada com escopo definido, autenticação, rate limiting e um log de auditoria para cada invocação. Em vez de cada agente fazer chamadas de API diretas com seu próprio gerenciamento de autenticação e seu próprio tratamento de erros, o MCP fornece uma camada de infraestrutura compartilhada. As permissões são gerenciadas na camada MCP, não replicadas por agente.
O risco que vale nomear diretamente: MCP sem governance é uma superfície de ataque bem rotulada. Todo servidor MCP conectado a sistemas de produção precisa de whitelist explícita, autenticação e logging de auditoria. A descoberta de abril de 2026 de uma classe de vulnerabilidade RCE no design do protocolo MCP reforçou que servidores MCP, como qualquer componente de software, exigem revisão de segurança e patches. A existência de um padrão não substitui práticas de segurança.
LangGraph para Orquestração de Agentes Corporativos
Para agentes que exigem gestão de estado, ramificação, etapas human-in-the-loop e execução paralela, o LangGraph fornece um grafo de estado explícito onde toda transição de estado é visível, pausável e retomável.
A distinção arquitetural que importa para empresas: o LangGraph é stateful. O estado de execução do agente persiste entre etapas. Se um agente pausa para aprovação humana, o estado é preservado. Se um agente falha no meio da execução, o estado pode ser inspecionado e retomado. Esse não é o comportamento padrão da maioria dos frameworks de agentes.
A adoção em produção inclui implantações na Cisco, Uber, LinkedIn e JPMorgan em 2026. A plataforma não é experimental.
O LangSmith, a plataforma de observabilidade associada, rastreia cada etapa da execução do agente: o que estava na janela de contexto, quais ferramentas foram chamadas, o que retornaram e quanto tempo cada etapa levou. Para implantações corporativas onde explicar o comportamento do agente a uma equipe de compliance é um requisito, o LangSmith fornece o trace. O Langfuse é a alternativa auto-hospedada para ambientes com requisitos de residência de dados.
Quando Não Usar um Agente
A maioria das tarefas propostas como fluxos de trabalho de agentes é melhor servida por automação determinística ou uma única chamada de LLM.
Um agente é apropriado quando: a tarefa exige múltiplas chamadas de ferramentas heterogêneas onde a sequência não é fixada antecipadamente, resultados intermediários informam quais ferramentas chamar em seguida, e o espaço de possíveis caminhos pela tarefa não é enumerável antes da execução começar.
Um agente está errado quando: a tarefa segue um procedimento fixo, as ferramentas são sempre chamadas na mesma ordem e toda execução percorre o mesmo caminho. Isso é automação de fluxo de trabalho. Zapier, n8n ou Trigger.dev lidam com isso de forma mais barata e mais confiável do que um agente. O modelo adiciona custo e não-determinismo sem adicionar inteligência.
A pergunta diagnóstica do framework 12-Factor aplicada como gate pré-construção: esta tarefa exige compreensão de linguagem em pontos de decisão, especificamente para decidir qual ação tomar a seguir? Ou apenas exige automação de uma sequência fixada?
Se a resposta honesta é automação, construa automação. O enquadramento de agente a tornará mais complexa para depurar, mais cara para rodar e mais difícil de explicar quando algo der errado.
Arquiteturas multi-agente aplicam a mesma lógica um nível acima: mais agentes não é mais inteligência. A decisão é se a estrutura da tarefa realmente o exige.
Para equipes corporativas avaliando onde agentes criam valor genuíno versus onde adicionam complexidade sem retorno, o AI Opportunity Sprint mapeia a decisão.