Agentes de IA: O que São e Como Construir

Agentes de IA são LLMs que podem agir no mundo real — não apenas gerar texto, mas executar tarefas, usar ferramentas e tomar decisões autonomamente.

Chatbot vs Agente

CHATBOT:
Usuário: "Como está o tempo em SP?"
Bot: "Não tenho acesso a dados em tempo real..."
→ Apenas gera texto baseado no treinamento

AGENTE:
Usuário: "Como está o tempo em SP?"
Agente: 
  1. [Pensa] Preciso buscar dados de clima
  2. [Age] Chama API de clima
  3. [Observa] Resultado: 25°C, ensolarado
  4. [Responde] "Está 25°C e ensolarado em São Paulo!"
→ Toma ações para resolver a tarefa

Anatomia de um Agente

┌──────────────────────────────────────────────┐
│                   AGENTE                      │
├──────────────────────────────────────────────┤
│                                              │
│  ┌──────────┐    ┌───────────────────────┐  │
│  │   LLM    │────│   Raciocínio/Plano    │  │
│  │ (Cérebro)│    │   (Decide o que fazer)│  │
│  └──────────┘    └───────────────────────┘  │
│        │                    │               │
│        ▼                    ▼               │
│  ┌──────────────────────────────────────┐   │
│  │           FERRAMENTAS                 │   │
│  │  [Busca] [Cálculo] [Email] [API...]  │   │
│  └──────────────────────────────────────┘   │
│        │                                    │
│        ▼                                    │
│  ┌──────────────────────────────────────┐   │
│  │            MEMÓRIA                    │   │
│  │  [Curta: conversa] [Longa: facts]    │   │
│  └──────────────────────────────────────┘   │
│                                              │
└──────────────────────────────────────────────┘

Implementação: Agente com Function Calling

1. Definir Ferramentas

import json
from openai import OpenAI

client = OpenAI()

# Definir ferramentas que o agente pode usar
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Busca a previsão do tempo para uma cidade",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "Nome da cidade"
                    }
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_web",
            "description": "Busca informações na internet",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Termo de busca"
                    }
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "send_email",
            "description": "Envia um email",
            "parameters": {
                "type": "object",
                "properties": {
                    "to": {"type": "string"},
                    "subject": {"type": "string"},
                    "body": {"type": "string"}
                },
                "required": ["to", "subject", "body"]
            }
        }
    }
]

2. Implementar Ferramentas

# Implementações reais das ferramentas
import requests

def get_weather(city: str) -> str:
    # Integração com API de clima (exemplo)
    api_key = "sua_api_key"
    url = f"https://api.weather.com/v1?city={city}&key={api_key}"
    response = requests.get(url)
    data = response.json()
    return f"Temperatura: {data['temp']}°C, {data['condition']}"

def search_web(query: str) -> str:
    # Integração com API de busca
    # Poderia usar Serper, Tavily, etc.
    return f"Resultados para '{query}': ..."

def send_email(to: str, subject: str, body: str) -> str:
    # Integração com serviço de email
    # Exemplo com SendGrid, AWS SES, etc.
    print(f"Enviando email para {to}")
    return "Email enviado com sucesso!"

# Mapeamento de funções
TOOL_FUNCTIONS = {
    "get_weather": get_weather,
    "search_web": search_web,
    "send_email": send_email
}

3. Loop do Agente

def run_agent(user_message: str, max_iterations: int = 10):
    """Executa o agente até completar a tarefa."""
    
    messages = [
        {
            "role": "system",
            "content": """Você é um assistente útil que pode usar ferramentas.
            Pense passo a passo antes de agir.
            Use as ferramentas disponíveis para ajudar o usuário."""
        },
        {"role": "user", "content": user_message}
    ]
    
    for i in range(max_iterations):
        # 1. Chamar o modelo
        response = client.chat.completions.create(
            model="gpt-4",
            messages=messages,
            tools=tools,
            tool_choice="auto"
        )
        
        message = response.choices[0].message
        messages.append(message)
        
        # 2. Verificar se terminou
        if response.choices[0].finish_reason == "stop":
            return message.content
        
        # 3. Se pediu para usar ferramenta, executar
        if message.tool_calls:
            for tool_call in message.tool_calls:
                func_name = tool_call.function.name
                func_args = json.loads(tool_call.function.arguments)
                
                print(f"🔧 Executando: {func_name}({func_args})")
                
                # Executar função
                result = TOOL_FUNCTIONS[func_name](**func_args)
                
                # Adicionar resultado às mensagens
                messages.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": str(result)
                })
    
    return "Limite de iterações atingido"

# Usar o agente
response = run_agent("Qual o tempo em São Paulo? Me envie um email com a previsão.")
print(response)

Padrões de Agentes

ReAct (Reasoning + Acting)

Formato ReAct:

Pensamento: Preciso descobrir o clima em SP
Ação: get_weather("São Paulo")
Observação: 25°C, ensolarado
Pensamento: Agora preciso enviar o email
Ação: send_email(to="user@email.com", ...)
Observação: Email enviado
Pensamento: Tarefa concluída
Resposta Final: Enviei um email com a previsão...

Plan-and-Execute

# Primeiro cria plano, depois executa

def plan_and_execute(task: str):
    # 1. Criar plano
    plan_response = client.chat.completions.create(
        model="gpt-4",
        messages=[{
            "role": "user",
            "content": f"""Crie um plano para: {task}
            
            Formato:
            1. [Passo 1]
            2. [Passo 2]
            ...
            """
        }]
    )
    
    plan = parse_plan(plan_response.choices[0].message.content)
    
    # 2. Executar cada passo
    results = []
    for step in plan:
        result = execute_step(step)
        results.append(result)
    
    return results

Multi-Agent

# Múltiplos agentes especializados

class ResearcherAgent:
    """Especialista em buscar informações."""
    tools = [search_web, read_document]

class WriterAgent:
    """Especialista em escrever conteúdo."""
    tools = [write_text, edit_text]

class ReviewerAgent:
    """Especialista em revisar qualidade."""
    tools = [check_facts, review_grammar]

# Orquestrador coordena os agentes
def orchestrate(task: str):
    research = ResearcherAgent().run(task)
    draft = WriterAgent().run(research)
    final = ReviewerAgent().run(draft)
    return final

Memória para Agentes

# Agentes precisam lembrar de conversas anteriores

class AgentMemory:
    def __init__(self):
        self.short_term = []  # Conversa atual
        self.long_term = {}   # Fatos persistentes
    
    def add_message(self, role: str, content: str):
        self.short_term.append({"role": role, "content": content})
    
    def add_fact(self, key: str, value: str):
        self.long_term[key] = value
    
    def get_context(self, max_messages: int = 10) -> list:
        # Combinar memória curta + fatos relevantes
        facts = "\n".join(f"- {k}: {v}" for k, v in self.long_term.items())
        
        context = [{
            "role": "system",
            "content": f"Fatos conhecidos:\n{facts}"
        }]
        
        context.extend(self.short_term[-max_messages:])
        return context

Ferramentas Úteis

Ferramentas comuns para agentes:

INFORMAÇÃO:
- search_web: Buscar na internet
- read_url: Ler conteúdo de URL
- query_database: Consultar banco de dados

COMUNICAÇÃO:
- send_email: Enviar emails
- send_slack: Postar no Slack
- create_ticket: Criar ticket no Jira

CÓDIGO:
- run_python: Executar código Python
- run_sql: Executar queries SQL
- call_api: Chamar APIs externas

ARQUIVOS:
- read_file: Ler arquivos
- write_file: Escrever arquivos
- list_files: Listar diretório

CÁLCULO:
- calculator: Operações matemáticas
- convert_units: Converter unidades

Segurança de Agentes

⚠️ Agentes podem ser perigosos!

RISCOS:
- Executar código malicioso
- Vazar dados sensíveis
- Spam/abuso de APIs
- Ações destrutivas

MITIGAÇÕES:

1. Sandboxing
   - Executar código em containers isolados
   - Limitar acesso a rede/disco

2. Rate Limiting
   - Máximo de ações por minuto
   - Máximo de tokens gastos

3. Aprovação Humana
   - Ações críticas precisam de OK
   - Revisar antes de executar

4. Logging
   - Registrar todas as ações
   - Auditoria completa

5. Permissões
   - Princípio do menor privilégio
   - Cada agente só acessa o necessário

Frameworks para Agentes

1. LangChain/LangGraph
   - Mais popular
   - Muitas integrações
   - Documentação extensa

2. CrewAI
   - Multi-agent fácil
   - Papéis e tarefas
   - Bom para workflows

3. AutoGen (Microsoft)
   - Conversas entre agentes
   - Bom para pesquisa

4. Semantic Kernel
   - Microsoft/.NET focus
   - Plugins modulares

5. DIY (Function Calling)
   - Mais controle
   - Sem dependências extras

Exemplo Prático: Agente de Pesquisa

# Agente que pesquisa e resume informações

def research_agent(topic: str) -> str:
    """Agente que pesquisa um tópico e cria resumo."""
    
    messages = [{
        "role": "system",
        "content": """Você é um pesquisador expert.
        
        Para pesquisar um tópico:
        1. Busque informações relevantes
        2. Leia as fontes principais
        3. Sintetize em um resumo claro
        
        Sempre cite suas fontes."""
    }, {
        "role": "user",
        "content": f"Pesquise sobre: {topic}"
    }]
    
    tools = [
        search_web_tool,
        read_url_tool,
        take_notes_tool
    ]
    
    # Loop até ter informação suficiente
    while True:
        response = client.chat.completions.create(
            model="gpt-4",
            messages=messages,
            tools=tools
        )
        
        # Se terminou, retornar resumo
        if response.choices[0].finish_reason == "stop":
            return response.choices[0].message.content
        
        # Executar ferramentas...
        
# Uso
summary = research_agent("Últimas tendências em IA generativa")
print(summary)