12 Factor Agents - 12 Princípios para Construir Aplicações LLM Confiáveis

Visão Geral

12 Factor Agents é uma metodologia de princípios para construir software impulsionado por LLM (Large Language Model) que pode ser usado em ambientes de produção, desenvolvida por Dex Horthy e a equipe HumanLayer.

Contexto e Motivação

Por que precisamos deste conjunto de princípios?

Após conversar com mais de 100 construtores de SaaS (principalmente fundadores técnicos), os autores descobriram que a maioria dos desenvolvimentos de AI Agent encontra um "gargalo de qualidade de 70-80%":

1. Progresso rápido inicial: Atingir rapidamente 70-80% da funcionalidade usando frameworks existentes.
2. Gargalo de qualidade: Descobrir que 80% não é bom o suficiente para funcionalidades voltadas para o cliente.
3. Limitações do framework: Para ultrapassar os 80%, é necessário fazer engenharia reversa do framework, prompts, fluxos, etc.
4. Começar do zero: Eventualmente, ter que abandonar o framework e recomeçar.

Insight Central

• A maioria dos "AI Agents" de nível de produção bem-sucedidos não são tão "agentes" assim.
• São principalmente sistemas de software cuidadosamente projetados que usam LLMs de forma inteligente em pontos-chave.
• A maneira mais rápida de colocar software de IA de alta qualidade nas mãos dos clientes é adotar conceitos pequenos e modulares e integrá-los aos produtos existentes.

12 Princípios Essenciais

Factor 1: Natural Language to Tool Calls

Linguagem Natural para Chamadas de Ferramentas

A superpotência central do LLM é converter linguagem natural em dados estruturados (JSON). Todas as operações do Agent devem começar com esta conversão fundamental.

// Padrão central
const response = await llm.generateToolCall(userMessage, availableTools);
// response é JSON estruturado, não texto livre

Factor 2: Own your prompts

Possua seus prompts

Trate os prompts como ativos de código críticos e versionados, não como entradas descartáveis.

• Gerencie prompts na base de código da aplicação.
• Suporte testes sistemáticos, implantação e reversão.
• Garanta consistência, reprodutibilidade e evolução controlada.

Factor 3: Own your context window

Possua sua janela de contexto

Gerencie a janela de contexto do LLM de forma proativa e intencional.

• Garanta que a janela de contexto contenha apenas informações diretamente relevantes para a tarefa atual.
• Pode dados desnecessários para evitar "deriva de contexto".
• Melhore o desempenho do LLM e reduza o uso de tokens.

Factor 4: Tools are just structured outputs

Ferramentas são apenas saídas estruturadas

Trate "ferramentas" como JSON estruturado da saída do LLM e valide-as.

// Chamadas de ferramentas são apenas validação de esquema JSON
const toolCall = validateToolCall(llmOutput, toolSchema);
const result = await executeValidatedTool(toolCall);

Factor 5: Unify execution state and business state

Unifique o estado de execução e o estado de negócio

Garanta que o "estado de execução" interno do LLM esteja alinhado com o "estado de negócio" real da aplicação.

• Evite que o LLM opere com base em informações desatualizadas ou incorretas.
• Evite alucinações ou operações inválidas.
• Persista o estado de execução ao lado do estado de negócio.

Factor 6: Launch/Pause/Resume with simple APIs

Lançar/Pausar/Retomar com APIs simples

Projete agentes LLM com interfaces de programação claras que suportam o gerenciamento do ciclo de vida.

interface AgentControl {
  launch(config: AgentConfig): Promise<AgentInstance>;
  pause(instanceId: string): Promise<void>;
  resume(instanceId: string): Promise<void>;
}

Factor 7: Contact humans with tool calls

Contate humanos com chamadas de ferramentas

Trate a interação humana como uma chamada de ferramenta de primeira classe.

• Encaminhe etapas de alto risco para revisão humana.
• O feedback humano é retornado ao sistema como entrada estruturada.
• Fluxos de trabalho de colaboração humano-máquina sem interrupções.

Factor 8: Own your control flow

Possua seu fluxo de controle

Mantenha o fluxo de controle em código comum ou em seu próprio motor de fluxo de trabalho.

• Execute um ciclo OODA explícito (Observar-Orientar-Decidir-Agir).
• Use heurísticas de convergência em vez de prompts aninhados.
• Evite que o LLM gerencie fluxos de controle complexos.

Factor 9: Compact Errors into Context Window

Compactar Erros na Janela de Contexto

Compacte as informações de erro no próximo prompt para fechar o ciclo de feedback.

• Permita que o LLM aprenda e se recupere de erros.
• Forneça informações de erro estruturadas.
• Suporte a capacidade de autocorreção.

Factor 10: Small, Focused Agents

Agentes Pequenos e Focados

Construa agentes pequenos e de propósito único, em vez de chatbots monolíticos e volumosos.

// Boa prática: Agentes pequenos e focados
class EmailSummaryAgent {
  async summarize(email: Email): Promise<Summary> { /* ... */ }
}

class PriorityClassificationAgent {
  async classify(email: Email): Promise<Priority> { /* ... */ }
}

Factor 11: Trigger from anywhere, meet users where they are

Acionar de qualquer lugar, encontrar usuários onde eles estão

Acione agentes de onde os usuários já estão trabalhando: CLI, webhook, cron, etc.

• Integração em fluxos de trabalho existentes.
• Múltiplos mecanismos de acionamento.
• Pontos de acesso amigáveis ao usuário.

Factor 12: Make your agent a stateless reducer

Torne seu agente um redutor sem estado

A aplicação gerencia o estado, o Agent permanece sem estado.

// Padrão de Agente sem estado
class StatelessAgent {
  step(state: State): Promise<State> {
 
  }
}

Padrões de Arquitetura Técnica

Simplificação do Ciclo Central

Cada Agent essencialmente se resume a:

const prompt = "Instruções para a seleção da próxima etapa";
const switchFunction = (json) => routeToFunction(json);
const context = manageWhatLLMSees();
const loop = whileNotDone();

Diferença em relação aos DAGs tradicionais

• DAG Tradicional: Engenheiros de software codificam cada etapa e caso de borda.
• Método do Agente: Dê ao Agente um objetivo e um conjunto de transformações, permitindo que o LLM decida o caminho em tempo real.
• Situação Real: As implementações mais bem-sucedidas usam o padrão de Agente de forma inteligente dentro de um DAG determinístico maior.

Cenários Aplicáveis

Cenários mais adequados

• Tarefas estruturadas que exigem compreensão da linguagem natural.
• Fluxos de trabalho que exigem colaboração humano-máquina.
• Processos de negócio complexos com múltiplas etapas.
• Ambientes de produção que exigem alta confiabilidade.

Cenários não adequados

• Tarefas determinísticas simples (é melhor escrever código diretamente).
• Tarefas de missão crítica que exigem 100% de precisão.
• Ambientes com recursos extremamente limitados.

Recomendações de Implementação

Adoção Progressiva

1. Comece pequeno: Escolha um princípio relevante para um desafio atual.
2. Implemente e observe: Veja os efeitos da melhoria.
3. Adicione gradualmente: Em seguida, adicione outro princípio.
4. Otimize continuamente: Refine e ajuste constantemente.

Recomendações de Pilha Tecnológica

• Linguagem: TypeScript (recomendado pelo autor, mas também suporta Python e outras linguagens).
• Bibliotecas chave: BAML (para análise de alinhamento de esquema).
• Implantação: Suporta cloud-native e Kubernetes.

Recursos Relacionados

Recursos Oficiais

• Repositório GitHub
• Site Oficial HumanLayer
• Blog The Outer Loop

Leitura Adicional

• Building Effective Agents (Anthropic)
• Metodologia Original 12 Factor Apps
• Function Calling vs Structured Outputs vs JSON Mode

Resumo

12 Factor Agents oferece uma abordagem sistemática para construir aplicações LLM verdadeiramente prontas para produção. Ele enfatiza não a construção de frameworks mais mágicos, mas a aplicação de melhores práticas de engenharia de software às capacidades do LLM. Lembre-se da ideia central: Agentes são software, trate-os como software, e eles o recompensarão com confiabilidade, manutenibilidade e capacidades que seus concorrentes não conseguirão igualar.