Agentes de 12 fatores: princípios de design para criar aplicativos LLM confiáveis de nível de produção

Introdução geral

“Agentes de 12 fatores" Não se trata de uma biblioteca ou estrutura de software específica, mas de um conjunto de princípios de design para a criação de aplicativos LLM (Large Language Model) confiáveis, dimensionáveis e fáceis de manter. Esse projeto foi iniciado pelo desenvolvedor Dex, que descobriu que muitas equipes conseguiam atingir facilmente os níveis de qualidade 70-80% ao desenvolver funcionalidades voltadas para o cliente usando as estruturas existentes de AI Intelligent Body, mas era excepcionalmente difícil superar esse gargalo em ambientes de produção. A causa principal é que muitas estruturas avançadas ocultam muito dos controles subjacentes, o que faz com que os desenvolvedores tenham que fazer engenharia reversa ou começar do zero quando é necessária uma profunda personalização e otimização. Portanto, este projeto toma emprestada a ideia da metodologia clássica de desenvolvimento de software "12-Factor App" e propõe 12 princípios fundamentais. Seu objetivo é fornecer aos engenheiros de software um guia de ideias para integrar a funcionalidade modular de IA aos produtos existentes de forma gradual e confiável, em vez de reescrevê-los de forma disruptiva. A ideia central é que ótimos aplicativos de IA ainda são, essencialmente, ótimos softwares, cuja parte principal deve consistir em código determinístico, com a mágica do LLM aplicada exatamente onde é mais necessária.

Lista de cursos

• Prefácio:Como chegamos até aqui: uma breve história do software
• Princípio I:Linguagem natural para chamadas de ferramentasMapeamento estável da entrada de linguagem natural do usuário para uma ou mais chamadas específicas de ferramentas (funções).
• Princípio II:Assuma o controle de suas palavras-chaveControle de versão e gerencie prompts como se eles fizessem parte do código principal do aplicativo, em vez de serem gerados dinamicamente.
• Princípio III:Assuma o controle de sua janela de contextoControle preciso do conteúdo contextual das entradas para o LLM como a chave para obter confiabilidade.
• Princípio IV:Ferramentas como resultados estruturadosFerramentas: pense nas ferramentas como uma forma de forçar o LLM a produzir um resultado estruturado, não apenas uma coleção de funções.
• Princípio V:Harmonizar o status da implementação com o status do negócioCombine o estado operacional das inteligências com o modelo de estado comercial principal do aplicativo para obter consistência de estado.
• Princípio VI:Iniciar/pausar/retomar por meio de APIs simplesControle de Inteligência: Garanta que as tarefas de longa duração das inteligências possam ser controladas por sistemas externos por meio de interfaces simples.
• Princípio VII:Interagir com humanos por meio de chamadas de ferramentasQuando um sistema inteligente requer entrada ou revisão humana, ele deve ser acionado por uma chamada de ferramenta padrão, não por um tratamento especial.
• Princípio VIII:Assuma o controle do seu fluxo de controleLógica de negócios: a lógica de negócios principal e as transformações de processo do aplicativo devem ser conduzidas por um código determinístico e não deixadas inteiramente a critério do LLM.
• Princípio IX:Compactação de mensagens de erro na janela de contextoQuando uma ferramenta não é executada, sua mensagem de erro é resumida e enviada ao LLM para correção.
• Princípio X:Criação de uma inteligência pequena e focadaA tendência é combinar várias inteligências pequenas e compactas em vez de criar uma inteligência enorme que possa fazer tudo.
• Princípio XI:Acione em qualquer lugar, interaja em qualquer lugarO Intelligentsia deve ser capaz de ser acionado a partir de várias fontes de eventos (por exemplo, solicitações de API, alterações no banco de dados, tarefas cronometradas) e interagir na plataforma em que o usuário está localizado (por exemplo, Slack, e-mail).
• Princípio XII:Projetando uma inteligência como um redutor sem estadoO corpo inteligente foi projetado como uma função pura que recebe o estado e os eventos atuais e retorna o novo estado.

Usando a Ajuda

O "12-Factor Agents" é um conjunto de ideias e princípios arquitetônicos que não têm processo de instalação. Ele é "usado" no sentido de que os desenvolvedores adotam e praticam esses princípios em seus próprios projetos. A seguir, há uma descrição detalhada de como aplicar esses 12 princípios em sua prática de engenharia de software.

Filosofia principal: os aplicativos de IA são, antes de tudo, software

Antes de começarmos, é importante entender a filosofia central de que a grande maioria do código de um chamado "aplicativo de IA" ou "inteligência de IA" deve ser um código de engenharia de software tradicional e determinístico, e que as chamadas de LLM são apenas uma peça do quebra-cabeça, usada precisamente no ponto em que a compreensão da linguagem natural ou a tomada de decisões é necessária. compreensão, geração ou tomada de decisões em linguagem natural. Em vez de entregar o controle de todo o aplicativo a uma caixa preta do tipo "request-tool-loop", os desenvolvedores devem pensar no LLM como uma função que pode ser chamada com recursos especiais.

Processo detalhado para operar cada princípio

Princípio 1: linguagem natural para chamadas de ferramentas
Esse é o ponto de entrada para a inteligência interagir com o mundo externo. Quando você recebe uma entrada do usuário (por exemplo, "ajude-me a verificar o tempo em Pequim ontem"), você precisa de um mecanismo confiável para transformá-la em uma chamada de função, como search_weather(date="2025-07-21", city="北京").

• método operacionalUse a funcionalidade "chamada de função" ou "uso de ferramenta" do LLM. Na solicitação enviada ao modelo, você fornece não apenas a entrada do usuário, mas também uma definição detalhada do esquema JSON da lista de ferramentas (funções) que podem ser chamadas e seus parâmetros. O modelo retorna um objeto JSON indicando qual função deve ser chamada e quais parâmetros devem ser passados. Seu código é responsável por analisar esse JSON e executar a função apropriada.

Princípio 2: Seja dono de seus prompts.
Não gere dinamicamente palavras de dicas complexas em seu código. Isso dificultará muito a depuração e a iteração.

• método operacionalTratamento dos prompts (Prompts) como arquivos de configuração estáticos (por exemplo .txt talvez .md ) para gerenciar. Carregue esses modelos de palavras-chave em seu código e os preencha com variáveis. Incorporar esses arquivos de palavras-chave em um sistema de controle de versão como o Git é como gerenciar o main.py talvez index.js O mesmo. Dessa forma, você pode acompanhar cada modificação na palavra-chave e testar e reverter facilmente.

Princípio 3: Seja dono de sua janela de contexto
A janela de contexto é a única "memória" do LLM. A qualidade da entrada determina diretamente a qualidade da saída. Não coloque indiscriminadamente todas as mensagens históricas nela.

• método operacionalImplementar uma estratégia precisa de criação de contexto. Antes de cada chamada ao LLM, seu código deve selecionar e combinar cuidadosamente as mensagens com base nas necessidades da tarefa em questão. Isso pode incluir: um prompt do sistema, as poucas mensagens históricas mais importantes, trechos de documentação relevantes (resultados do RAG) e o problema mais recente do usuário. O objetivo é fornecer ao LLM as informações mínimas e mais críticas necessárias para resolver o problema em questão.

Princípio 4: As ferramentas são apenas resultados estruturados
Embora esses recursos sejam chamados de "ferramentas", de outra perspectiva, eles são a única maneira confiável de forçar o LLM a produzir o JSON bem formado que você deseja.

• método operacionalDefinindo o LLM como uma "ferramenta" quando você precisar que ele extraia informações para você, categorize-as ou realize qualquer tarefa que exija um formato de saída determinístico. Por exemplo, se você precisar extrair nomes e empresas de um texto, poderá definir um extract_entities(person: str, company: str) Para "chamar" essa ferramenta, o LLM deve gerar saída nesse formato.

Princípio nº 8: Seja dono do seu fluxo de controle.
Isso é contrário a muitas estruturas de inteligência automatizada, mas é fundamental. O "que fazer em seguida" do aplicativo não deve ser determinado inteiramente pelo LLM em um loop.

• método operacionalCódigo determinístico: Use código determinístico (por exemplo, if/else, instruções switch ou máquinas de estado) para escrever os principais processos de negócios. Por exemplo, um processo de processamento de pedidos pode ser:接收订单 -> [LLM分类意图] -> if (查询) then call_query_api() else if (退货) then call_refund_api()Nesse caso, o LLM é responsável apenas pela etapa "classificar tu". Aqui, o LLM é responsável apenas pela etapa "classificar tu", e todo o processo é controlado pelo seu código. Isso torna o comportamento do sistema previsível e passível de depuração.

Princípio 10: Agentes pequenos e focados
Não tente criar uma "superinteligência" que possa lidar com tudo.

• método operacional: Decompor tarefas complexas. Por exemplo, um sistema de suporte ao cliente pode ser decomposto em: uma inteligência para reconhecimento de intenções, uma inteligência para consulta à base de conhecimento e uma inteligência para processamento de pedidos. Seu código de fluxo de controle principal (princípio oito) é responsável pelo roteamento e programação entre elas. Cada uma das inteligências menores tem sua própria palavra-chave focada (princípio dois) e conjunto de ferramentas (princípio quatro).

Princípio XII: Faça do seu agente um redutor sem estado
Isso se baseia nas ideias de gerenciamento de estado de estruturas de front-end, como o Redux, e pode melhorar muito a capacidade de teste e a previsibilidade de um sistema.

• método operacionalImplementar sua inteligência, ou uma de suas etapas, como uma função pura com uma assinatura como (currentState, event) => newState.
  • currentState são todos os estados do aplicativo atual.
  • event é um evento que acabou de ocorrer (como uma nova mensagem do usuário ou um resultado retornado da API).
  • O valor de retorno de uma função newState é o estado atualizado.
    A função em si não tem estado (não depende de nenhuma variável externa) e tudo o que faz é computar a saída com base na entrada. Isso facilita muito a criação de testes unitários: você só precisa fornecer diferentes currentState responder cantando event e, em seguida, afirma newState Se ele atende às expectativas.

Seguindo esses princípios, você pode criar aplicativos LLM mais estáveis em seu comportamento, mais fáceis de depurar e que funcionam em harmonia com os sistemas de software existentes.

cenário do aplicativo

1. Adição de recursos de IA aos produtos SaaS existentes
   Para um produto SaaS maduro que já tenha uma lógica de negócios estável (por exemplo, CRM, ferramentas de gerenciamento de projetos), os desenvolvedores desejam introduzir a funcionalidade de IA de forma incremental sem reescrever o código principal. Por exemplo, usando os Princípios Um e Oito, traduza as instruções de linguagem natural de um usuário ("Crie uma tarefa que deve ser entregue na próxima semana e atribua-a a Zhang San") em uma chamada para uma API existente, mantendo a estabilidade da lógica central de criação de tarefas.
2. Desenvolvimento de assistentes de IA de alta qualidade para usuários finais
   Ao desenvolver um assistente de IA que interage diretamente com clientes pagantes, a confiabilidade e a experiência do usuário são essenciais. O uso direto de estruturas genéricas pode resultar em um comportamento imprevisível ao lidar com casos complexos ou de borda. Ao aplicar esses princípios, especificamente o Princípio Três (Dominar o Contexto), o Princípio Oito (Dominar o Fluxo de Controle) e o Princípio Nove (Comprimir Mensagens de Erro), é possível garantir que o assistente lide com os problemas de forma graciosa ou busque ajuda quando necessário por meio do Princípio Sete (Interagir com Humanos), em vez de dar respostas incorretas ou travar.
3. Produção de protótipos de IA
   Muitas equipes usam estruturas avançadas para criar rapidamente um protótipo impressionante (demonstração), mas quando estão prontas para lançá-lo como um produto completo, descobrem que o protótipo é instável em cenários complexos do mundo real (a qualidade não quebra 80%). Nesse ponto, o 12-Factor Agents fornece um conjunto de diretrizes de "refatoração". As equipes podem revisitar e reformular o código do protótipo com práticas de engenharia de software mais robustas que seguem esses princípios, como a refatoração de fluxos de controle ambíguos (loop-until-done) em máquinas de estado explícitas (Princípio Oito) e a unificação de prompts fragmentados e gerenciamento de estado (Princípios Dois e Cinco).

QA

1. O "12-Factor Agents" é uma estrutura de software instalável?
   Não é. Não é um lugar como o LangChain ou o Griptape, onde você pode diretamentepip installO pacote de software. É um conjunto de filosofias de design e princípios arquitetônicos criados para orientar os desenvolvedores sobre como organizar melhor seu código e sua maneira de pensar para criar aplicativos LLM confiáveis. É um documento, uma metodologia.
2. Por que assumir você mesmo o controle do fluxo de controle e não deixar que o LLM decida? Não é essa a beleza das inteligências?
   Essa é uma das ideias centrais da metodologia. O apelo de deixar o LLM determinar completamente o fluxo de controle (ou seja, "o que fazer em seguida") está na sua flexibilidade e no potencial de descobrir novos caminhos. Entretanto, em um ambiente de produção, essa incerteza traz riscos significativos e dificuldades de depuração. Quando algo dá errado em um aplicativo, é difícil identificar se o problema está na tomada de decisão do LLM ou na execução da ferramenta." 12-Factor Agents" defende que os principais processos de negócios de alto risco sejam definidos em código determinístico (por exemplo, máquinas de estado) e que, em determinados pontos do processo, os LLMs possam ser invocados para tomar decisões locais (por exemplo, classificação, extração de informações etc.). Isso aproveita os recursos dos LLMs e, ao mesmo tempo, garante a previsibilidade e a estabilidade gerais do sistema.
3. Esse conjunto de princípios significa que não posso usar as estruturas de IA existentes?
   Não é bem assim. Você pode usar as estruturas existentes seguindo esses princípios. A chave é como você as utiliza. Você pode pensar em uma estrutura como uma "biblioteca" que fornece ferramentas úteis, em vez de uma "estrutura" que controla o fluxo de todo o seu aplicativo. Por exemplo, você pode usar a funcionalidade de análise de chamadas de ferramentas fornecida por uma estrutura, mas escrever você mesmo o fluxo de controle principal, ou usar o módulo RAG (Retrieval Augmentation Generation) fornecido por ela para preencher o contexto, mas as especificidades desse contexto estão sob seu controle preciso, de acordo com o Princípio Três. O objetivo é manter o controle sobre as partes principais do aplicativo, em vez de terceirizar tudo para a estrutura.
4. Esse conjunto de princípios é fácil de ser seguido por engenheiros de software tradicionais sem formação em IA?
   É tão fácil que podemos até dizer que esse conjunto de princípios é feito sob medida para bons engenheiros de software. Grande parte dele (por exemplo, controle de versão, gerenciamento de estado, modularidade, fluxo de controle determinístico) é uma prática recomendada da engenharia de software. Ele incentiva os engenheiros a navegar no LLM com o pensamento de engenharia com o qual já estão familiarizados e são confiáveis, em vez de exigir que eles aprendam um paradigma de programação baseado em probabilidade totalmente novo. Ele "rebaixa" o LLM a um "componente" poderoso, mas cuidadosamente gerenciado, que permite que os engenheiros trabalhem em seus próprios domínios familiares.