Construir um agente de IA parece complexo — e pode ser, se você tentar construir tudo do zero. Mas o padrão central é simples: dê a um modelo de linguagem acesso a ferramentas, deixe-o decidir qual ferramenta usar e quando, e repita até o objetivo ser alcançado.
Este guia explica como construir um agente de IA passo a passo, da arquitetura ao código funcional. Ao final, você terá um agente funcional capaz de pesquisar na web, gerar imagens e entregar resultados — tudo através de uma única CLI.
O Que É um Agente de IA?
Antes de escrever código, vamos definir o que estamos construindo.
Um agente de IA é um sistema que recebe um objetivo, planeja uma sequência de ações, usa ferramentas para executar essas ações, observa os resultados e se adapta. Diferente de um chatbot que responde a um único prompt, um agente trabalha de forma autônoma em direção a um objetivo — potencialmente através de dezenas de chamadas de ferramentas.
Chatbot: "Resuma este artigo." → Retorna um resumo. Agente de IA: "Pesquise este tópico, encontre as melhores fontes, escreva um relatório e publique-o." → Planeja, pesquisa, lê, escreve, publica.
O poder do agente vem de suas ferramentas — as capacidades que ele pode invocar. Sem ferramentas, um agente é apenas um modelo de linguagem com um prompt longo. Com ferramentas, ele pode interagir com o mundo.
A Arquitetura de um Agente de IA
Todo agente segue o mesmo loop fundamental:
┌─────────────────────────────────────────┐
│ LOOP DO AGENTE │
│ │
│ 1. Receber objetivo │
│ 2. Pensar: O que devo fazer a seguir? │
│ 3. Agir: Escolher e chamar uma ferramenta│
│ 4. Observar: Qual foi o resultado? │
│ 5. Decidir: O objetivo foi alcançado? │
│ → Não? Voltar ao passo 2. │
│ → Sim? Retornar resultados. │
└─────────────────────────────────────────┘
Isso é chamado de padrão ReAct (Raciocínio + Ação). Todo framework de agente — LangChain, CrewAI, AutoGen, OpenAI Agents SDK — implementa alguma versão deste loop.
Os três componentes que você precisa:
- Um modelo de linguagem — o motor de raciocínio (Claude, GPT-4o, Gemini)
- Um conjunto de ferramentas — o que o agente pode fazer (pesquisar, rastrear, gerar, salvar, publicar)
- Um orquestrador — o loop que decide qual ferramenta chamar em seguida
Passo 1: Escolha Suas Ferramentas
As ferramentas definem o que seu agente pode realizar. Comece perguntando: "O que meu agente precisa fazer no mundo real?"
Ferramentas comuns de agentes:
| Capacidade | Por Que Importa |
|---|---|
| Pesquisa web | Investigação, verificação de fatos, análise competitiva |
| Rastreamento web | Leitura aprofundada de páginas específicas, extração de dados |
| Geração de imagens | Criação de visuais, diagramas, assets |
| Armazenamento de arquivos | Saída persistente, compartilhamento, gestão de assets |
| Publicação web | Entrega de trabalho finalizado como páginas ativas |
| Execução de código | Execução de scripts, processamento de dados, automação |
O erro mais comum dos iniciantes: dar a um agente poucas ferramentas e depois se perguntar por que ele não consegue realizar nada. Um agente só de pesquisa retorna apenas links. Um agente com pesquisa + rastreamento + armazenamento + publicação pode produzir trabalho finalizado e entregue.
A forma mais simples de provisionar ferramentas: usar uma camada de capacidades unificada que agrupa pesquisa, rastreamento, geração de imagens, armazenamento e publicação por trás de uma única interface. Em vez de configurar cinco APIs separadas e gerenciar cinco conjuntos de credenciais, seu agente chama uma CLI com um único fluxo de autenticação. Isso mantém o loop do agente simples e a sobrecarga de tokens baixa.
Passo 2: Defina o Prompt de Sistema do Seu Agente
O prompt de sistema é o "manual de operação" do agente. Ele diz ao modelo o que ele é, quais ferramentas tem e como usá-las.
Um bom prompt de sistema tem quatro partes:
- Identidade: O que o agente é
- Objetivo: O que ele deve alcançar
- Ferramentas: O que ele pode usar e quando
- Restrições: O que ele não deve fazer
Exemplo:
Você é um agente de pesquisa. Seu objetivo é pesquisar um tópico
dado minuciosamente e produzir um relatório abrangente.
Você tem acesso a estas ferramentas:
- search: Encontre informações na web. Use para pesquisa ampla.
- crawl: Leia uma página web específica por completo. Use após
encontrar fontes promissoras.
- drive upload: Salve relatórios e assets de forma persistente.
- page deploy: Publique o relatório final como uma página web.
Fluxo de trabalho:
1. Comece com consultas de pesquisa amplas para entender o cenário.
2. Identifique as fontes mais autoritativas e rastreie-as.
3. Sintetize as descobertas em um relatório estruturado.
4. Faça upload do relatório para o Drive para armazenamento seguro.
5. Implante o relatório como uma página publicada.
Restrições:
- Sempre cite suas fontes.
- Se uma fonte contradisser outra, investigue mais.
- Nunca invente informações.
Passo 3: Implemente o Loop do Agente
Aqui está um loop de agente mínimo em Python. O padrão está pronto para produção — pensar, agir, observar, repetir:
import subprocess
import json
def call_tool(tool_name, **params):
"""Executa uma ferramenta e retorna o resultado."""
if tool_name == "search":
result = subprocess.run(
["anycap", "search", "--prompt", params["query"]],
capture_output=True, text=True
)
return json.loads(result.stdout)
elif tool_name == "crawl":
result = subprocess.run(
["anycap", "crawl", params["url"]],
capture_output=True, text=True
)
return result.stdout
elif tool_name == "drive_upload":
subprocess.run(
["anycap", "drive", "upload", params["file"]],
capture_output=True
)
return {"status": "uploaded", "file": params["file"]}
elif tool_name == "page_deploy":
result = subprocess.run(
["anycap", "page", "deploy", params["file"]],
capture_output=True, text=True
)
return json.loads(result.stdout)
# O loop do agente
def agent_loop(goal, tools, max_steps=20):
memory = [{"role": "system", "content": SYSTEM_PROMPT}]
memory.append({"role": "user", "content": goal})
for step in range(max_steps):
response = llm_call(memory, tools)
if response.get("done"):
return response["result"]
tool_name = response["tool"]
tool_params = response["params"]
result = call_tool(tool_name, **tool_params)
memory.append({"role": "assistant", "content": str(response)})
memory.append({"role": "tool", "content": str(result)})
return "Agente atingiu o máximo de passos sem completar o objetivo."
Passo 4: Lide com Falhas
Agentes falham. A questão é como eles lidam com isso. Construa estas salvaguardas desde o início:
Proteção por Timeout
Não deixe um agente ficar em loop para sempre. Defina um número máximo de passos e um limite de tempo. Se o agente exceder qualquer um deles, ele deve retornar o que tem até o momento — não travar silenciosamente.
Recuperação de Falhas de Ferramentas
Quando uma chamada de ferramenta falha — uma URL está inacessível, uma API retorna um erro — o agente deve receber a mensagem de erro e decidir o que fazer a seguir. Não esconda os erros do agente. Ele precisa saber quando algo não funcionou.
try:
result = call_tool(tool_name, **tool_params)
except Exception as e:
result = {"error": str(e), "suggestion": "Tente uma abordagem alternativa"}
Consciência de Custos
Cada pesquisa, cada rastreamento, cada geração de imagem custa créditos. Dê ao agente um orçamento e o torne consciente dos custos. Um agente que gasta 100 pesquisas para responder a uma pergunta simples está mal projetado.
Passo 5: A Diferença Entre Demo e Produção
A diferença entre um agente de demonstração e um agente útil é o acesso real a ferramentas. Um agente de demonstração retorna texto. Um agente útil retorna um relatório publicado, uma imagem gerada ou uma página web implantada.
Agentes de produção precisam de cinco capacidades: pesquisar na web, ler páginas específicas, gerar visuais, armazenar saída de forma persistente e publicar trabalho finalizado. O código do agente permanece simples — ele apenas chama as ferramentas de que precisa. A complexidade de integração de APIs, autenticação e tratamento de erros reside no runtime, não no seu loop de agente.
Erros Comuns ao Construir Agentes
Erro 1: Sem Condição de Saída
Um agente sem um sinal claro de "concluído" fará loop para sempre. Defina o sucesso explicitamente: o agente está concluído quando produz uma saída específica (um relatório, uma página implantada) ou quando confirma que o objetivo é inalcançável.
Erro 2: Poucas Ferramentas
Agentes "só de pesquisa" são mecanismos de busca glorificados. Dê ao seu agente o pipeline completo: encontrar → ler → criar → armazenar → entregar.
Erro 3: Ignorar Resultados das Ferramentas
Às vezes, os agentes chamam uma ferramenta e ignoram o resultado, prosseguindo com base no que assumiram que o resultado seria. Force o agente a incorporar cada resultado de ferramenta em sua próxima decisão.
Erro 4: Excesso de Engenharia no Loop
Você não precisa de um framework de orquestração personalizado para a maioria dos casos de uso. Um loop ReAct simples com um bom prompt de sistema e ferramentas capazes supera uma configuração multi-agente complexa em 80% das tarefas.
Do Tutorial à Produção
O agente que você construiu aqui é um ponto de partida. Para torná-lo pronto para produção:
- Adicione logging: Registre cada chamada de ferramenta, seu resultado e o raciocínio do agente para depuração.
- Adicione human-in-the-loop: Para ações de alto risco (publicar, enviar e-mails), exija aprovação humana.
- Adicione monitoramento: Acompanhe a taxa de sucesso, a média de passos por tarefa e a distribuição de chamadas de ferramentas para identificar gargalos.
- Itere no prompt de sistema: O prompt é o cérebro do agente. Ajuste-o com base em padrões de uso reais.
Construir um agente de IA não é sobre arquitetura complexa. É sobre dar a um motor de raciocínio as ferramentas certas e um objetivo claro. Comece simples: um modelo, 3 a 5 ferramentas, um loop básico. Adicione complexidade apenas quando a versão simples falhar.