Descubra os 12 fatores para construir agentes de IA robustos e escaláveis: da conversão de linguagem natural e domínio dos prompts, à colaboração humana e design sem estado. Construa sistemas de IA prontos para produção que entregam valor real ao negócio.
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.
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.
{
"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.
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:
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.
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:
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.
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:
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:
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[];
};
}
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.
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:
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:
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:
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:
À medida que os LLMs evoluem, esses pequenos agentes podem ampliar seu escopo mantendo a qualidade, garantindo escalabilidade a longo prazo.
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:
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.
Essa abordagem conceitual vê agentes como funções puras que não mantêm estado interno, proporcionando:
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.
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
A metodologia do Agente de IA dos 12 Fatores é um conjunto de melhores práticas inspiradas no modelo de aplicativo dos 12 fatores, projetado para ajudar desenvolvedores a construir agentes de IA robustos, fáceis de manter e escaláveis, que atuam de forma confiável em ambientes de produção reais.
A gestão de contexto garante que agentes de IA mantenham o histórico relevante de conversas, prompts e estado, otimizando desempenho, reduzindo o uso de tokens e melhorando a precisão na tomada de decisões.
Os agentes de IA do FlowHunt estruturam chamadas de ferramentas para solicitar input humano quando necessário, permitindo colaboração fluida, aprovações e fluxos de trabalho duráveis para cenários complexos ou de alto risco.
Agentes de IA sem estado são previsíveis, mais fáceis de depurar e mais simples de escalar, pois transformam o contexto de entrada em ações de saída sem manter estado interno oculto.
Arshia é Engenheira de Fluxos de Trabalho de IA na FlowHunt. Com formação em ciência da computação e paixão por IA, ela se especializa em criar fluxos de trabalho eficientes que integram ferramentas de IA em tarefas do dia a dia, aumentando a produtividade e a criatividade.
Pronto para criar agentes de IA robustos e prontos para produção? Descubra as ferramentas do FlowHunt e veja como a metodologia dos 12 fatores pode transformar sua automação.
Aprenda a construir agentes de IA sofisticados com acesso ao sistema de arquivos, implemente estratégias de offloading de contexto e otimize o uso de tokens atr...
Aprenda como agentes de IA utilizam planejamento para superar limitações de janela de contexto e melhorar a execução de tarefas. Explore a implementação com Lan...
Um agente inteligente é uma entidade autônoma projetada para perceber seu ambiente por meio de sensores e agir sobre esse ambiente usando atuadores, equipada co...
Consentimento de Cookies
Usamos cookies para melhorar sua experiência de navegação e analisar nosso tráfego. See our privacy policy.
