12-Factor Agents: um guia rápido, e quanto a minha fábrica segue cada fator

Quem constrói agentes de IA chega cedo ou tarde no mesmo ponto: o protótipo funciona na demo e se perde em produção. O 12-Factor Agents, do Dex Horthy (HumanLayer), é uma lista de princípios para atravessar esse ponto. A tese cabe numa frase: um agente que funciona em produção é quase todo software comum, com a IA chamada só onde precisa de julgamento.

Foi assim que a minha fábrica de software agêntica nasceu. Nela, quem anda pelo fluxo de trabalho é o motor ⚙️, um programa sem IA, e o agente 🤖 entra para fazer um passo de cada vez. Então eu peguei os 12 fatores, mais o bônus, e medi quanto a fábrica segue cada um.

Este post é um guia. Ele dá uma visão rápida de cada fator, sem aprofundar. Nos próximos posts, vou trabalhar item a item: o que cada fator é, o que ele não é, e exemplos de como ele aparece (ou não) na fábrica.

Como ler o medidor

Cada fator tem um medidor de aderência. 100% é fazer o que o fator pede. As cores mostram a faixa: vermelho abaixo de 50%, amarelo de 50% a 89% e verde a partir de 90%. Acima de 100%, até 150%, a fábrica vai além do que o fator descreve. Os nomes dos fatores ficam em inglês, como no original.

1. Natural language to tool calls

De linguagem natural para chamadas de ferramenta

O que o modelo faz de mais útil é transformar uma frase num objeto estruturado que um código comum executa. O modelo decide o quê; o código faz. (fator 1)

Na fábrica: quando um passo falha, o supervisor de IA responde com uma decisão num formato fixo (corrigir, tentar de novo, ir para outro passo ou chamar um humano), e o motor executa. A IA nunca executa nada sozinha.

2. Own your prompts

Seja dono dos seus prompts

Prompt é código: versionado, revisado, testado e escrito por inteiro por quem é dono do agente, não escondido atrás de um framework. (fator 2)

Na fábrica: todos os prompts estão no arquivo do fluxo de trabalho e nas skills, e os testes rodam todos os fluxos de ponta a ponta. O que falta: o prompt de sistema das CLIs que rodam os agentes (Claude Code, Codex) é delas, não meu.

3. Own your context window

Seja dono da sua janela de contexto

Tudo o que o modelo vê é decisão sua: o que entra, em que formato e quanto. Uma janela pequena e bem organizada rende mais que uma conversa longa. (fator 3)

Na fábrica: cada run tem um orçamento de contexto, não só de dinheiro. Num fluxo de desenvolvimento, por exemplo, quando os agentes já leram 40 milhões de tokens somados, o motor pausa o run antes do próximo turno e me pergunta se continua ou para.

E quando um agente precisa voltar para ajustar algo, como o desenvolvedor depois de uma revisão, ele não carrega a conversa que já ficou grande. Se o contexto passou do limite (150 mil tokens), o próximo turno começa do zero, a partir de uma nota de passagem de até 250 palavras que o próprio agente escreveu no fim do turno anterior.

4. Tools are just structured outputs

Ferramentas são só saídas estruturadas

Uma "chamada de ferramenta" é só o modelo devolvendo JSON num formato que você declarou. Valide a resposta e deixe as decisões no código. (fator 4)

Na fábrica: cada passo declara o formato da resposta. O motor valida, devolve os erros uma vez se vier errado, e escolhe o próximo passo pelos campos da resposta, nunca pelo texto.

5. Unify execution state and business state

Unifique o estado da execução e o do negócio

O progresso do agente (em que passo está, o que espera) e os dados do negócio devem viver num lugar só, ou sair de um lugar só. Dois lugares se desencontram. (fator 5)

Na fábrica: cada run é uma pasta de arquivos com todos os seus eventos, e as issues e o código ficam no GitHub. O que falta: enquanto o run está rodando, o estado dele vive na memória do processo.

6. Launch, pause, resume with simple APIs

Iniciar, pausar e retomar com APIs simples

Um agente deve começar por um programa, pausar quando precisa de algo lento ou de uma pessoa, e voltar de onde parou. Na pausa, nenhum processo fica esperando. (fator 6)

Na fábrica: a pausa espera o turno terminar, salva tudo e o run retoma do mesmo ponto, ou de qualquer passo. O que falta: depois de uma queda, quem retoma sou eu, não a fábrica.

7. Contact humans with tool calls

Fale com humanos por chamadas de ferramenta

Pedir ajuda a uma pessoa é uma saída como outra qualquer: o agente diz o que precisa, o fluxo pausa e a resposta volta como evento, pelo canal que a pessoa usa. (fator 7)

Na fábrica: as aprovações são passos do fluxo e chegam no app ou no celular, horas depois se for preciso. O que falta: o agente ainda não consegue pedir ajuda no meio do turno.

8. Own your control flow

Seja dono do seu fluxo de controle

Não entregue o loop para o modelo. Escreva você qual passo vem depois, quando chamar a IA, quando esperar e quando parar. (fator 8)

Na fábrica: é o desenho original. O motor anda por um grafo declarado, espera o CI sem gastar modelo, limita voltas e custos, e a fábrica inteira roda nos testes sem nenhuma IA.

9. Compact errors into the context window

Compacte os erros na janela de contexto

Quando algo falha, mande para o modelo um resumo curto do que deu errado, não o stack trace. E conte as falhas: depois de algumas seguidas, chame alguém. (fator 9)

Na fábrica: uma tentativa que falhou vira um bloco curto no próximo prompt. Além disso, o motor percebe quando um agente repete a mesma decisão ou fica lento demais, e chama o supervisor.

10. Small, focused agents

Agentes pequenos e focados

Um agente que faz tudo se perde depois de algumas dezenas de passos. Faça agentes que fazem uma coisa só e junte-os com código comum. (fator 10)

Na fábrica: desenvolvedor, revisor, quem escreve testes, quem faz o deploy: cada um com o seu modelo, as suas ferramentas e as suas skills. O revisor só lê, e quem só faz push roda num modelo mais barato.

11. Trigger from anywhere, meet users where they are

Dispare de qualquer lugar, encontre as pessoas onde elas estão

O agente deve começar de onde as pessoas e os sistemas já estão: uma mensagem, um e-mail, um webhook, um agendamento. E responder pelo mesmo canal. (fator 11)

Na fábrica: um run começa do app, da linha de comando, do navegador, do roadmap ou do fim de outro run. O que falta: uma label numa issue ou um comentário num PR ainda não disparam nada.

12. Make your agent a stateless reducer

Faça do seu agente um reducer sem estado

O agente é uma função: estado + evento = novo estado. O estado fica fora do processo, e qualquer processo continua de onde o outro parou. (fator 12)

Na fábrica: o log de eventos de cada run já existe e já é lido assim para mostrar os runs. Fazer o motor rodar a partir dele é o próximo passo, e já é uma tarefa da própria fábrica.

13. Pre-fetch all the context you might need (bonus)

Busque antes o contexto que vai precisar

Se você já sabe que o modelo vai pedir algo (a issue, o diff, os testes), coloque isso no prompt antes do turno. O código busca; o modelo lê. (fator 13)

Na fábrica: o prompt já chega com os commits, os testes que falharam e o texto da issue. E o motor acompanha o PR e o CI sozinho, chamando o agente só quando há novidade.

O que vem depois

Esse é o mapa. Nos próximos posts, vou pegar um fator de cada vez e mostrar, com exemplos da fábrica, o que ele é, o que ele não é e onde é fácil errar.

Enquanto isso, o Diário da fábrica conta, capítulo a capítulo, como essa fábrica foi construída.