Agentes de 12 Fatores: O Que Aprendi Construindo Sistemas Agentivos em Produção

Existe um momento que todo construtor de agentes inevitavelmente enfrenta. A demo funciona. O caminho feliz roda limpo. Você mostra para alguém e eles acenam entusiasticamente. Depois você implanta em um fluxo de trabalho real e ele começa a fazer algo sutilmente errado — de forma consistente, silenciosa, e de um jeito extremamente difícil de depurar porque você não controla a pilha de chamadas.

Eu bati nessa parede construindo meu framework de orquestração Python. E de novo com o harness de SDLC que hoje alimenta o pipeline de conteúdo deste site. E de novo com o sistema de automação de suporte que construí para um contrato anterior. A cada vez, reconstruí com mais cuidado. A cada vez, os mesmos instintos de engenharia que me ajudaram em software não-AI acabaram se aplicando aqui também.

Ao longo de três sistemas em produção, 12 fatores continuaram surgindo como a diferença entre agentes que se mantinham sob carga real e agentes que pareciam ótimos até que não pareciam mais. Este post é minha destilação desses fatores — enraizada em sistemas que eu realmente opero, não em teoria.

A Armadilha em Que a Maioria Cai

Frameworks são otimizados para chegar a 70%. Isso não é uma crítica — é a otimização certa para demos, protótipos e provar viabilidade. O problema é que equipes confundem o teto de 70% com uma arquitetura. Quando os últimos 30% se tornam uma sessão de depuração sete camadas dentro de abstrações que você não controla, a única saída é uma reescrita que deveria ter sido a primeira escrita.

O antídoto não é um framework melhor. É tratar agentes como software — software de primeira classe com estado explícito, fluxo de controle explícito e propriedade explícita dos prompts. É isso que esses 12 fatores representam.

Fator 1: Extração de JSON É o Primitivo Central

A coisa mais confiável que um LLM faz é converter linguagem natural em dados estruturados. Todo o resto — chamadas de ferramentas, raciocínio em múltiplas etapas, decisões de roteamento — é derivado dessa única capacidade.

No meu framework de orquestração Python, toda interação com agentes termina aqui. O trabalho do LLM é produzir uma decisão em JSON. O trabalho do orquestrador é rotear essa decisão para o código.

Fator 2: Tenha Controle de Cada Token dos Seus Prompts

Abstrações de prompt que constroem automaticamente sua mensagem de sistema te levarão 80% do caminho rapidamente. Quando você precisar dos 20% restantes — quando o modelo está fazendo algo sutilmente errado em um caso específico — você precisa controlar cada token.

No meu harness de SDLC, mantenho um diretório prompts/. Cada estágio do fluxo de trabalho tem seu próprio arquivo de prompt, versionado junto com o código. Quando um agente de revisão começou a produzir veredictos excessivamente permissivos, eu pude comparar os prompts, apertar a linguagem e rastrear a mudança de comportamento. Você não consegue fazer isso quando seu framework monta o prompt a partir de uma dúzia de abstrações internas.

Fator 3: Janelas de Contexto Exigem Gerenciamento Ativo

O acúmulo de contexto é o assassino silencioso de agentes de longa duração. No meu sistema de automação de suporte, as primeiras versões acrescentavam cada resultado de ferramenta e etapa de raciocínio intermediário ao contexto em execução. No passo 15 de um fluxo de triagem complexo, o modelo estava lendo ruído irrelevante do passo 3.

A correção é o gerenciamento explícito de contexto: resumir eventos antigos, manter resultados recentes de ferramentas, podar o raciocínio intermediário. Trate a janela de contexto como memória de trabalho — selecione o que fica, o que é resumido e o que é descartado.

Fator 4: "Uso de Ferramentas" É Roteamento de JSON, Nada Mais

O enquadramento de "uso de ferramentas" encoraja pensamento mágico. Um agente não usa uma ferramenta — ele produz JSON, e seu código roteia esse JSON para uma função. Desmistificar isso torna a depuração direta.

No meu framework de orquestração Python, toda saída do agente passa por uma única função de despacho. Não há reflexão, descoberta automática nem mágica de framework:

Quando algo quebra, há exatamente um lugar para olhar.

Fator 5: Agentes Focados Superam Monólitos

Meu harness de SDLC executa cerca de 50 agentes de tarefa discretos em uma especificação. Cada agente de tarefa lida com uma fatia estreita: implementar uma tarefa, executar validação, escrever um relatório de revisão. Nenhum agente único orquestra toda a especificação. O orquestrador de bloco coordena-os, mas seu trabalho é sequenciamento e mesclagem — não executar o trabalho de conteúdo em si.

Isso mantém a janela de contexto de cada agente focada. O agente de implementação não carrega lógica de revisão. O agente de revisão não carrega histórico de implementação. Contexto focado significa menos confabulações e rastros de erro muito mais limpos quando algo dá errado.

Fator 6: Controle Seu Fluxo de Controle

Frameworks que ocultam o loop agentivo — o ciclo "enquanto não concluído: chamar LLM, executar resultado" — tornam impossível adicionar checkpoints, timeouts ou portais humanos sem brigar com a abstração. Nos meus sistemas, o loop é sempre explícito:

Cada condição de saída é visível. Cada checkpoint é explícito. O loop é seu.

Fator 7: Agentes Devem Ser Sem Estado — Sua Aplicação Não

Uma função de agente deve receber estado como entrada e retornar novo estado como saída. Ela não deve possuir uma conexão de banco de dados, uma sessão em execução ou memória interna mutável. A camada de aplicação — o orquestrador — é dona da persistência.

É assim que meu harness de SDLC pode interromper um agente no meio da execução, salvar o estado em disco e retomá-lo em um novo processo. O próprio agente não sabe nada sobre persistência:

Imutável, serializável, retomável e testável de forma isolada.

Fator 8: Escalação Humana É uma Ação de Primeira Classe

No meu sistema de automação de suporte, a ação mais importante que o agente de triagem podia tomar era pedir ajuda a um humano. Não como um modo de falha — como um resultado válido e esperado para tickets ambíguos.

Tornar a escalação humana uma ação de primeira classe na tabela de despacho significa que você pode testá-la, registrá-la e medi-la como qualquer outra ação. Também significa que o agente a usará naturalmente em vez de confabular uma resposta confiante quando a confiança não é justificada.

Fator 9: Encontre os Usuários nos Seus Fluxos de Trabalho Existentes

O sistema de automação de suporte se integrou à interface existente do sistema de tickets — sem novo painel, sem novo login. Agentes que exigem que os usuários adotem uma nova ferramenta enfrentam um problema de adoção de UX além do problema de engenharia. Roteie as saídas dos agentes de volta para onde o usuário já trabalha.

Fator 10: Trate Erros Explicitamente — Não Acrescente e Torça

No início do meu framework de orquestração, minha estratégia de tratamento de erros era "acrescentar o erro ao contexto e deixar o modelo resolver". Isso funciona para casos simples e falha gravemente para qualquer coisa envolvendo limites de taxa, timeouts de rede ou falhas repetidas de ferramentas. O modelo começa a raciocinar sobre erros em vez de tomar ações produtivas.

O tratamento explícito de erros significa categorizar erros na camada de despacho, decidir programaticamente se deve tentar novamente, recuar ou escalar para um humano, e manter os detalhes de erro fora do contexto de raciocínio a menos que sejam diretamente acionáveis.

Fator 11: Separe Estado de Execução do Estado de Negócio

Executar um agente envolve duas preocupações de estado distintas que não devem ser misturadas:

• Estado de execução — contador de passos, contagem de tentativas, janela de contexto, temporização
• Estado de negócio — o que foi realmente realizado, saídas produzidas, interações humanas tomadas

No meu harness de SDLC, o orquestrador rastreia o estado de execução. O registro de tarefa no diretório de planejamento rastreia o estado de negócio. Eles nunca compartilham uma estrutura de dados. Isso torna os replays e a depuração diretos — você pode re-executar um agente com o mesmo estado de negócio e um estado de execução novo sem efeitos colaterais indesejados.

Fator 12: Empurre o Modelo aos Seus Limites, Depois Engenharia a Confiabilidade

O trabalho que cria valor real está exatamente na fronteira do que o modelo consegue fazer de forma confiável. A triagem de automação de suporte lidava com tickets ambíguos e multi-intenção onde um classificador ingênuo produziria lixo. O agente de revisão do SDLC captura incompatibilidades sutis de critérios de aceitação que exigem compreensão semântica genuína.

Essa fronteira muda conforme os modelos melhoram. A tarefa de engenharia é encontrá-la e construir andaimes de confiabilidade ao redor — prompts estruturados, loops de validação, caminhos de escalação humana — para que a capacidade se torne confiável em vez de impressionante às vezes.

Juntando Tudo

Esses 12 fatores não vieram de um whitepaper. Vieram do mesmo lugar de onde todos os instintos de engenharia vêm: depurar falhas em produção, ver algo que funcionava em demo colapsar sob carga real e iterar.

A boa notícia é que nada disso exige conhecimento especial em IA. Se você já entregou software em produção, você já entende gerenciamento de estado, fluxo de controle, interfaces explícitas e o custo de abstrações ocultas. Agentes são software. Os mesmos instintos se aplicam.

Comece com o Fator 1 e o Fator 2 — tenha controle da sua extração de JSON e dos seus prompts. Os outros fatores se seguem naturalmente assim que você para de tratar o LLM como uma caixa preta e começa a tratar seu agente como um sistema pelo qual você é responsável.

O framework de 12 fatores serve como espinha dorsal do caminho de aprendizado de desenvolvimento de agentes de 12 fatores neste site, onde cada fator recebe um tratamento mais profundo com exemplos práticos dos meus sistemas reais. Se você quiser construir algo que se mantenha em produção, esse é um bom lugar para continuar.