Como Construir um Agente de IA: Um Tutorial Passo a Passo para Programadores

Construir um agente de IA parece complexo — e pode ser, se tentares construir tudo do zero. Mas o padrão principal é simples: dá a um modelo de linguagem acesso a ferramentas, deixa-o decidir qual ferramenta usar e quando, e repete até o objetivo ser alcançado.

Este guia explica como construir um agente de IA passo a passo, desde a arquitetura até ao código funcional. No final, terás 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 a construir.

Um agente de IA é um sistema que recebe um objetivo, planeia uma sequência de ações, usa ferramentas para executar essas ações, observa os resultados e adapta-se. Ao contrário de um chatbot que responde a um único prompt, um agente trabalha de forma autónoma em direção a um objetivo — potencialmente ao longo de dezenas de chamadas de ferramentas.

Chatbot: "Resume este artigo." → Devolve um resumo. Agente de IA: "Pesquisa este tópico, encontra as melhores fontes, escreve um relatório e publica-o." → Planeia, pesquisa, lê, escreve, publica.

O poder do agente vem das suas ferramentas — as capacidades que pode invocar. Sem ferramentas, um agente é apenas um modelo de linguagem com um prompt longo. Com ferramentas, pode interagir com o mundo.

A Arquitetura de um Agente de IA

Todos os agentes seguem 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? Devolver resultados.          │
└─────────────────────────────────────────┘

Isto chama-se o padrão ReAct (Raciocínio + Ação). Todas as frameworks de agentes — LangChain, CrewAI, AutoGen, OpenAI Agents SDK — implementam alguma versão deste loop.

Os três componentes de que precisas:

1. Um modelo de linguagem — o motor de raciocínio (Claude, GPT-4o, Gemini)
2. Um conjunto de ferramentas — o que o agente pode fazer (pesquisar, crawlar, gerar, guardar, publicar)
3. Um orquestrador — o loop que decide qual ferramenta chamar a seguir

Passo 1: Escolhe as Tuas Ferramentas

As ferramentas definem o que o teu agente pode realizar. Começa por perguntar: "O que é que o meu agente precisa de fazer no mundo real?"

Ferramentas comuns de agentes:

O erro mais comum dos principiantes: dar a um agente poucas ferramentas e depois perguntar porque é que ele não consegue realizar nada. Um agente só de pesquisa apenas devolve links. Um agente com pesquisa + crawling + 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, crawling, geração de imagens, armazenamento e publicação atrás de uma única interface. Em vez de configurares cinco APIs separadas e gerires cinco conjuntos de credenciais, o teu agente chama uma CLI com um único fluxo de autenticação. Isto mantém o loop do agente simples e a sobrecarga de tokens baixa.

Passo 2: Define o Prompt de Sistema do Teu Agente

O prompt de sistema é o "manual de operação" do agente. Diz ao modelo o que ele é, que ferramentas tem e como usá-las.

Um bom prompt de sistema tem quatro partes:

1. Identidade: O que o agente é
2. Objetivo: O que deve alcançar
3. Ferramentas: O que pode usar e quando
4. Restrições: O que não deve fazer

Exemplo:

Tu és um agente de pesquisa. O teu objetivo é pesquisar um tópico
dado minuciosamente e produzir um relatório abrangente.

Tens acesso a estas ferramentas:
- search: Encontra informação na web. Usa para pesquisa ampla.
- crawl: Lê uma página web específica na íntegra. Usa depois de
  encontrares fontes promissoras.
- drive upload: Guarda relatórios e recursos de forma persistente.
- page deploy: Publica o relatório final como uma página web.

Fluxo de trabalho:
1. Começa com consultas de pesquisa amplas para entender o panorama.
2. Identifica as fontes mais autorizadas e faz crawling delas.
3. Sintetiza as descobertas num relatório estruturado.
4. Carrega o relatório para o Drive para guardar em segurança.
5. Publica o relatório como uma página ativa.

Restrições:
- Cita sempre as tuas fontes.
- Se uma fonte contradizer outra, investiga mais.
- Nunca inventes informação.

Passo 3: Implementa 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 devolve 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 "O agente atingiu o máximo de passos sem completar o objetivo."

Passo 4: Lida com Falhas

Os agentes falham. A questão é como lidam com isso. Constrói estas salvaguardas desde o início:

Proteção por Timeout

Não deixes um agente ficar em loop para sempre. Define um número máximo de passos e um limite de tempo. Se o agente exceder qualquer um deles, deve devolver o que tem até ao momento — não falhar silenciosamente.

Recuperação de Falhas de Ferramentas

Quando uma chamada de ferramenta falha — um URL está inacessível, uma API devolve um erro — o agente deve receber a mensagem de erro e decidir o que fazer a seguir. Não escondas os erros do agente. Ele precisa de saber quando algo não funcionou.

try:
    result = call_tool(tool_name, **tool_params)
except Exception as e:
    result = {"error": str(e), "suggestion": "Tenta uma abordagem alternativa"}

Consciência de Custos

Cada pesquisa, cada crawl, cada geração de imagem custa créditos. Dá ao agente um orçamento e torna-o consciente dos custos. Um agente que gasta 100 pesquisas para responder a uma pergunta simples está mal concebido.

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 devolve texto. Um agente útil devolve um relatório publicado, uma imagem gerada ou uma página web publicada.

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 — apenas chama as ferramentas de que precisa. A complexidade da integração de APIs, autenticação e tratamento de erros reside no runtime, não no teu 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. Define o sucesso explicitamente: o agente está concluído quando produz uma saída específica (um relatório, uma página publicada) ou quando confirma que o objetivo é inalcançável.

Erro 2: Poucas Ferramentas

Agentes "só de pesquisa" são motores de busca glorificados. Dá ao teu agente o pipeline completo: encontrar → ler → criar → armazenar → entregar.

Erro 3: Ignorar Resultados das Ferramentas

Por vezes, os agentes chamam uma ferramenta e ignoram o resultado, prosseguindo com base no que assumiram que o resultado seria. Força o agente a incorporar cada resultado de ferramenta na sua próxima decisão.

Erro 4: Excesso de Engenharia no Loop

Não precisas de uma framework de orquestração personalizada para a maioria dos casos de uso. Um simples loop ReAct 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 construíste aqui é um ponto de partida. Para o tornar pronto para produção:

• Adiciona logging: Regista cada chamada de ferramenta, o seu resultado e o raciocínio do agente para depuração.
• Adiciona human-in-the-loop: Para ações de alto risco (publicar, enviar emails), exige aprovação humana.
• Adiciona monitorização: Acompanha a taxa de sucesso, a média de passos por tarefa e a distribuição de chamadas de ferramentas para identificar gargalos.
• Itera no prompt de sistema: O prompt é o cérebro do agente. Ajusta-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. Começa simples: um modelo, 3-5 ferramentas, um loop básico. Adiciona complexidade apenas quando a versão simples falhar.