O Agente de IA dos 12 Fatores: Construindo Sistemas de IA Eficazes e Escaláveis

O que Torna um Agente de IA Eficaz?

Antes de mergulhar nos fatores, vamos esclarecer o que queremos dizer com “agentes de IA”. Em sua essência, são sistemas capazes de interpretar solicitações em linguagem natural, tomar decisões com base no contexto e executar ações específicas por meio de ferramentas ou APIs — tudo isso mantendo interações coerentes e contínuas.

Os agentes mais poderosos combinam as capacidades de raciocínio de modelos de linguagem com a confiabilidade do código determinístico. Mas alcançar esse equilíbrio exige escolhas de design cuidadosas, que é justamente o foco desses fatores.

Os 12 Fatores para Construir Agentes de IA Robustos

1. Domine a Conversão de Linguagem Natural para Chamada de Ferramenta

A capacidade de transformar solicitações em linguagem natural em chamadas de ferramentas estruturadas está no coração da funcionalidade do agente. É isso que permite ao agente pegar um comando como “crie um link de pagamento de R$750 para Terri para o meetup dos IA Tinkerers de fevereiro” e convertê-lo em uma chamada de API devidamente formatada.

URL da Imagem

{
  "function": {
    "name": "create_payment_link",
    "parameters": {
      "amount": 750,
      "customer": "cust_128934ddasf9",
      "product": "prod_8675309",
      "price": "prc_09874329fds",
      "quantity": 1,
      "memo": "Hey Jeff - see below for the payment link for the February AI Tinkerers meetup"
    }
  }
}

A chave para que isso funcione de forma confiável é usar código determinístico para manipular a saída estruturada do seu modelo de linguagem. Sempre valide os payloads das APIs antes da execução para evitar erros e garanta que seu LLM retorne formatos JSON consistentes que possam ser analisados de forma confiável.

2. Tenha Total Domínio dos Seus Prompts

Seus prompts são a interface entre sua aplicação e o modelo de linguagem — trate-os como código de primeira classe. Embora frameworks que abstraem prompts possam parecer convenientes, muitas vezes eles ocultam como as instruções são passadas para o LLM, dificultando ou impossibilitando ajustes finos.

Em vez disso, mantenha controle direto sobre seus prompts escrevendo-os explicitamente:

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
  prompt #"
    {{ _.role("system") }}
    Você é um assistente prestativo que gerencia deploys para sistemas frontend e backend.
    ...
    {{ _.role("user") }}
    {{ thread }}
    Qual deve ser o próximo passo?
  "#
}

Essa abordagem traz várias vantagens:

• Controle total para escrever instruções precisas sob medida para seu caso de uso
• Capacidade de criar avaliações e testes para prompts como qualquer outro código
• Transparência para entender exatamente o que o LLM recebe
• Liberdade para iterar com base em métricas de desempenho

3. Projete sua Janela de Contexto de Forma Estratégica

A janela de contexto serve como entrada para o LLM, abrangendo prompts, histórico de conversas e dados externos. Otimizá-la aumenta o desempenho e a eficiência do uso dos tokens.

URL da Imagem

Vá além dos formatos padrão baseados em mensagens para estruturas personalizadas que maximizam a densidade de informações:

<slack_message>
    From: @alex
    Channel: #deployments
    Text: Can you deploy the backend?
</slack_message>
<list_git_tags>
    intent: "list_git_tags"
</list_git_tags>
<list_git_tags_result>
    tags:
      - name: "v1.2.3"
        commit: "abc123"
        date: "2024-03-15T10:00:00Z"
</list_git_tags_result>

Esta abordagem oferece diversos benefícios:

• Redução do uso de tokens com formatos compactos
• Melhor filtragem de dados sensíveis antes de passar para o LLM
• Flexibilidade para experimentar formatos que aprimorem o entendimento do LLM

4. Implemente Ferramentas como Saídas Estruturadas

No essencial, ferramentas são apenas saídas JSON do LLM que disparam ações determinísticas no seu código. Isso cria uma separação clara entre a tomada de decisão da IA e a lógica de execução.

Defina claramente os esquemas das ferramentas:

class CreateIssue {
  intent: "create_issue";
  issue: {
    title: string;
    description: string;
    team_id: string;
    assignee_id: string;
  };
}

class SearchIssues {
  intent: "search_issues";
  query: string;
  what_youre_looking_for: string;
}

Depois, construa o parsing confiável para as saídas JSON do LLM, use código determinístico para executar as ações e devolva os resultados ao contexto para fluxos de trabalho iterativos.

5. Unifique Execução e Estado de Negócio

Muitos frameworks de agentes separam o estado de execução (ex: etapa atual de um processo) do estado de negócio (ex: histórico de chamadas de ferramentas e seus resultados). Essa separação adiciona complexidade desnecessária.

Em vez disso, armazene todo o estado diretamente na janela de contexto, inferindo o estado de execução a partir da sequência de eventos:

<deploy_backend>
    intent: "deploy_backend"
    tag: "v1.2.3"
    environment: "production"
</deploy_backend>
<error>
    error running deploy_backend: Failed to connect to deployment service
</error>

Esta abordagem unificada proporciona:

• Simplicidade com uma única fonte de verdade para o estado
• Melhor depuração com o histórico completo em um só lugar
• Recuperação fácil ao retomar de qualquer ponto carregando o thread

Levando Agentes de IA para Produção

6. Projete APIs para Iniciar, Pausar e Retomar

Agentes de nível de produção precisam se integrar perfeitamente a sistemas externos, pausando para tarefas longas e retomando quando acionados por webhooks ou outros eventos.

Implemente APIs que permitam iniciar, pausar e retomar agentes, com armazenamento de estado robusto entre operações. Isso possibilita:

• Suporte flexível para fluxos de trabalho assíncronos
• Integração limpa com webhooks e outros sistemas
• Retomada confiável após interrupções sem reiniciar

7. Habilite Colaboração Humana com Chamadas de Ferramenta

Agentes de IA frequentemente necessitam de input humano para decisões críticas ou situações ambíguas. Usar chamadas de ferramentas estruturadas torna essa interação fluida:

class RequestHumanInput {  
  intent: "request_human_input";  
  question: string;  
  context: string;  
  options: {  
    urgency: "low" | "medium" | "high";  
    format: "free_text" | "yes_no" | "multiple_choice";  
    choices: string[];  
  };  
}

URL da Imagem

Essa abordagem fornece especificação clara do tipo de interação e urgência, suporta input de múltiplos usuários e combina bem com APIs para fluxos de trabalho duráveis.

8. Controle o Fluxo do Seu Agente

Fluxo de controle personalizado permite pausar para aprovação humana, armazenar resultados em cache ou implementar limitações de taxa — adaptando o comportamento do agente às suas necessidades específicas:

URL da Imagem

async function handleNextStep(thread: Thread) {
  while (true) {
    const nextStep = await determineNextStep(threadToPrompt(thread));
    if (nextStep.intent === 'request_clarification') {
      await sendMessageToHuman(nextStep);
      await db.saveThread(thread);
      break;
    } else if (nextStep.intent === 'fetch_open_issues') {
      const issues = await linearClient.issues();
      thread.events.push({ type: 'fetch_open_issues_result', data: issues });
      continue;
    }
  }
}

Com essa abordagem, você ganha:

• Possibilidade de interrupção para revisão humana antes de ações críticas
• Opções de personalização para logging, cache ou sumarização
• Manipulação confiável de tarefas de longa duração

9. Insira Erros no Contexto para Autocorreção

Incluir erros diretamente na janela de contexto permite que agentes de IA aprendam com falhas e ajustem sua abordagem:

try {
  const result = await handleNextStep(thread, nextStep);
  thread.events.push({ type: `${nextStep.intent}_result`, data: result });
} catch (e) {
  thread.events.push({ type: 'error', data: formatError(e) });
}

Para que isso funcione de modo eficaz:

• Limite as tentativas para evitar loops infinitos
• Escale para humanos após falhas repetidas
• Formate erros de maneira clara para que o LLM entenda o que deu errado

Melhores Práticas Arquiteturais

10. Construa Agentes Pequenos e Focados

Agentes pequenos que lidam com 3 a 20 etapas mantêm janelas de contexto administráveis, melhorando o desempenho e a confiabilidade do LLM. Essa abordagem proporciona:

• Clareza com escopo bem definido para cada agente
• Menor risco do agente perder o foco
• Testes e validação mais fáceis de funções específicas

URL da Imagem

À medida que os LLMs evoluem, esses pequenos agentes podem ampliar seu escopo mantendo a qualidade, garantindo escalabilidade a longo prazo.

11. Habilite Gatilhos de Múltiplas Fontes

Deixe seus agentes acessíveis permitindo acionamento por Slack, e-mail ou sistemas de eventos — encontrando os usuários onde eles já trabalham.

Implemente APIs que iniciam agentes a partir de diversos canais e respondem pelo mesmo meio. Isso permite:

• Melhor acessibilidade ao integrar com plataformas preferidas dos usuários
• Suporte a fluxos de trabalho de automação orientados a eventos
• Workflows de aprovação humana para operações críticas

12. Projete Agentes como Redutores Sem Estado

Trate agentes como funções sem estado que transformam o contexto de entrada em ações de saída, simplificando a gestão de estado e tornando-os previsíveis e mais fáceis de depurar.

URL da Imagem

Essa abordagem conceitual vê agentes como funções puras que não mantêm estado interno, proporcionando:

• Comportamento previsível para entradas dadas
• Rastreabilidade facilitada de problemas pelo histórico de contexto
• Testes e validação mais simples

Construindo para o Futuro

O campo dos agentes de IA evolui rapidamente, mas esses princípios centrais continuarão relevantes mesmo com a melhoria dos modelos subjacentes. Começando com agentes pequenos e focados que sigam essas práticas, você pode criar sistemas que entregam valor hoje e se adaptam aos avanços do futuro.

Lembre-se de que os agentes de IA mais eficazes combinam as capacidades de raciocínio dos modelos de linguagem com a confiabilidade do código determinístico — e esses 12 fatores ajudam você a alcançar esse equilíbrio.

Como o FlowHunt Aplicou a Metodologia dos 12 Fatores

No FlowHunt, colocamos esses princípios em prática desenvolvendo nosso próprio agente de IA que cria automações de workflow automaticamente para nossos clientes. Veja como aplicamos a metodologia dos 12 fatores para construir um sistema confiável e pronto para produção