12 Factor Agents: padrões para agentes que chegam à produção

Agentes como software com decisões explícitas

O framework 12 Factor Agents da HumanLayer parte de uma ideia pragmática: um agente de produção costuma combinar lógica determinística com passos de modelo onde a linguagem, a classificação ou a seleção de uma ferramenta agregam valor. Não propõe eliminar o software tradicional nem adotar uma arquitetura única; oferece princípios para tornar o comportamento controlável.

Em um ciclo delimitado, o modelo propõe uma saída estruturada, o programa valida a proposta e executa apenas capacidades permitidas, e o resultado se transforma em nova evidência. O sistema decide como lidar com erros, limites, estado e condições de parada.

Os 12 fatores, agrupados por responsabilidade

O guia original enumera estes fatores. Agrupá-los ajuda a transformá-los em decisões de projeto:

1. Interface e entradas: 1) traduzir linguagem natural em chamadas estruturadas; 2) ter e versionar os prompts; 3) administrar a janela de contexto.
2. Ferramentas e fluxo: 4) tratar as chamadas como saídas estruturadas; 5) unificar estado de execução e de negócio; 6) expor APIs simples para iniciar, pausar e retomar; 7) contatar pessoas por meio de ferramentas; 8) manter o controle do fluxo no código.
3. Erros e escala: 9) resumir erros para que o modelo possa se recuperar; 10) preferir agentes pequenos e focados; 11) permitir a ativação a partir de diferentes eventos; 12) modelar o agente como um redutor sem estado, com estado explícito fora do modelo.

Inner loop e outer loop

O inner loop processa passos delimitados: contexto autorizado, decisão estruturada, validação determinística, execução e resultado. O outer loop coordena o processo de negócio: inicia tarefas, persiste estado, aplica timeouts, gerencia novas tentativas e decide quando uma pessoa deve revisar ou retomar.

Pausar não deveria ser uma exceção improvisada. O sistema pode parar antes de uma ação sensível, apresentar a uma pessoa o contexto e o efeito esperado, e retomar com a decisão recebida. A aprovação deve corresponder a uma ação e versão concretas, não a uma permissão aberta para todo o agente.

Controles para que o padrão seja operável

Valide cada saída contra um esquema, aplique permissões no serviço que realiza a operação, limite o número de passos e preserve identificadores de execução. Para ações repetíveis, projete idempotência; para ações de impacto, peça autorização explícita e registre quem decidiu o quê.

Os fatores são princípios de projeto, não uma garantia de segurança nem uma receita completa. O sistema deve ser avaliado com cenários representativos, falhas de ferramenta, respostas adversariais, perda de sessão e requisitos reais de privacidade e operação.