# 12-Factor Agents: um guia rápido, e quanto a minha fábrica segue cada fator · Eduardo Galbiati URL: https://www.edugalbs.com/blog/12-factor-agents > Os 12 princípios para colocar agentes de IA em produção, um parágrafo cada, com um medidor de quanto a minha fábrica de software agêntica segue cada um. Tecnologia27 de outubro de 20268 min de leitura ## 12-Factor Agents: um guia rápido, e quanto a minha fábrica segue cada fator Os 12 princípios para colocar agentes de IA em produção, um parágrafo cada, com um medidor de quanto a minha fábrica de software agêntica segue cada um. por Eduardo Galbiati 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](https://github.com/humanlayer/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](https://www.edugalbs.com/fabrica-24x7) 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**100%** 2 · Own your prompts**90%** 3 · Own your context window**130%** 4 · Tools are just structured outputs**110%** 5 · Unify execution state and business state**70%** 6 · Launch, pause, resume with simple APIs**90%** 7 · Contact humans with tool calls**70%** 8 · Own your control flow**150%** 9 · Compact errors into the context window**120%** 10 · Small, focused agents**120%** 11 · Trigger from anywhere, meet users where they are**60%** 12 · Make your agent a stateless reducer**30%** 13 · Pre-fetch all the context you might need (bonus)**120%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-01-natural-language-to-tool-calls.md)) **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. Factory adherence**100%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-02-own-your-prompts.md)) **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. Factory adherence**90%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-03-own-your-context-window.md)) **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. Factory adherence**130%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-04-tools-are-structured-outputs.md)) **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. Factory adherence**110%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-05-unify-execution-state.md)) **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. Factory adherence**70%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-06-launch-pause-resume.md)) **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. Factory adherence**90%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-07-contact-humans-with-tools.md)) **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. Factory adherence**70%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-08-own-your-control-flow.md)) **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. Factory adherence**150%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-09-compact-errors.md)) **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. Factory adherence**120%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-10-small-focused-agents.md)) **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. Factory adherence**120%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-11-trigger-from-anywhere.md)) **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. Factory adherence**60%** ### 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](https://github.com/humanlayer/12-factor-agents/blob/main/content/factor-12-stateless-reducer.md)) **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. Factory adherence**30%** ### 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](https://github.com/humanlayer/12-factor-agents#factor-13-pre-fetch-all-the-context-you-might-need)) **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. Factory adherence**120%** ### 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](https://www.edugalbs.com/fabrica-24x7) conta, capítulo a capítulo, como essa fábrica foi construída.