O Que é um Agente de IA? (além do chatbot)
Um chatbot responde perguntas. Um agente resolve problemas.
A diferença fundamental: um agente pode tomar ações no mundo real — executar código, buscar informações na web, chamar APIs, criar arquivos, enviar emails, consultar bancos de dados. E mais importante: ele decide quando e como usar essas ferramentas para atingir um objetivo, em vez de apenas gerar texto.
Um agente de IA é um sistema que:
1. Recebe um objetivo em linguagem natural
2. Raciocina sobre quais passos são necessários
3. Escolhe e executa ferramentas disponíveis
4. Observa o resultado de cada ação
5. Ajusta o plano com base nos resultados
6. Repete até o objetivo ser atingido
Exemplo concreto: você pede "Pesquise as últimas notícias sobre IA, analise as tendências e me mande um resumo por email". Um chatbot diria que não pode fazer isso. Um agente vai buscar as notícias, processar o conteúdo, identificar padrões e enviar o email — tudo de forma autônoma.
Agentes são o paradigma que está transformando LLMs de ferramentas de geração de texto em sistemas capazes de executar fluxos de trabalho complexos.
---
Agentes vs Chatbots vs Workflows: As Diferenças
| Característica | Chatbot | Workflow Fixo | Agente |
|----------------|---------|---------------|--------|
| Toma decisões? | Não | Não (fluxo fixo) | Sim |
| Usa ferramentas? | Raramente | Sim (roteiro fixo) | Sim (escolha dinâmica) |
| Adapta ao resultado? | Não | Não | Sim |
| Planeja passos? | Não | Não | Sim |
| Imprevisível? | Baixo | Não | Sim |
| Confiável em produção? | Alta | Alta | Média |
| Bom para tarefas abertas? | Não | Não | Sim |
Quando usar cada um:
- Chatbot: FAQ, suporte nível 1, interface conversacional simples. Sem autonomia necessária.
- Workflow fixo: processos bem definidos onde cada passo é conhecido. Muito mais confiável e auditável.
- Agente: tarefas abertas onde os passos variam dependendo da situação, ou quando o processo de descoberta faz parte da solução.
A regra prática: use o sistema mais simples que resolve o problema. Agentes adicionam complexidade e imprevisibilidade. Use-os quando workflow fixo não for suficiente.
---
Arquitetura de um Agente: ReAct, Tool Use, Planning
ReAct (Reason + Act)
O padrão mais comum. O agente alterna entre dois passos:
1. Thought (raciocínio): "Para responder isso, preciso buscar a cotação atual do dólar"
2. Action (ação): chama a ferramenta buscar_cotacao
3. Observation (resultado): "Cotação: R$ 5,43"
4. Repete até ter a resposta final
Objetivo: Qual foi a variação do dólar nos últimos 7 dias?
Thought: Preciso buscar cotações do dólar para os últimos 7 dias.
Action: buscar_cotacao(moeda='USD', periodo='7d')
Observation: {seg: 5.41, ter: 5.43, ..., dom: 5.38}
Thought: Tenho os dados. Preciso calcular a variação.
Action: calcular_variacao(inicio=5.41, fim=5.38)
Observation: -0.55%
Thought: Tenho a resposta completa.
Final Answer: O dólar variou -0,55% nos últimos 7 dias.Tool Use (Function Calling)
Modelos modernos (GPT-4, Claude, Gemini) têm suporte nativo a tool use. Em vez de o modelo gerar texto de ação, ele retorna um JSON estruturado indicando qual função chamar e com quais argumentos. Isso é mais confiável e fácil de parsear que texto livre.
Planning (Multi-step)
Para tarefas complexas, o agente primeiro gera um plano completo antes de executar. Isso melhora a coerência em fluxos longos mas é menos flexível para adaptar ao resultado de cada passo.
---
Construindo seu Primeiro Agente com LangChain
pip install langchain langchain-openai langchain-community duckduckgo-searchfrom langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent, AgentExecutor
from langchain.tools import Tool
from langchain_community.tools import DuckDuckGoSearchRun
from langchain import hub
import subprocess
import json
# 1. Definir as ferramentas disponíveis para o agente
search = DuckDuckGoSearchRun()
def calcular(expressao: str) -> str:
"""Executa uma expressão matemática. Exemplo: '2 + 2 * 10'"""
try:
resultado = eval(expressao, {'__builtins__': {}}, {})
return str(resultado)
except Exception as e:
return f'Erro: {e}'
def obter_clima(cidade: str) -> str:
"""Retorna informações de clima para uma cidade."""
# Em produção, integraria com uma API real
return f'Temperatura em {cidade}: 25°C, ensolarado'
ferramentas = [
Tool(
name='Busca na Web',
func=search.run,
description='Útil para buscar informações atuais na internet. Use quando precisar de fatos recentes, notícias ou dados que não estão no seu conhecimento de treinamento.'
),
Tool(
name='Calculadora',
func=calcular,
description='Executa cálculos matemáticos. Passe a expressão matemática como string. Exemplo: "150 * 0.07"'
),
Tool(
name='Clima',
func=obter_clima,
description='Retorna o clima atual de uma cidade. Passe apenas o nome da cidade.'
)
]
# 2. Configurar o LLM
llm = ChatOpenAI(model='gpt-4o-mini', temperature=0)
# 3. Carregar o prompt ReAct padrão do LangChain Hub
prompt = hub.pull('hwchase17/react')
# 4. Criar o agente
agente = create_react_agent(llm=llm, tools=ferramentas, prompt=prompt)
# 5. Criar o executor (que gerencia o loop de ação)
executor = AgentExecutor(
agent=agente,
tools=ferramentas,
verbose=True, # mostra o raciocínio passo a passo
max_iterations=10,
handle_parsing_errors=True
)
# 6. Executar
resultado = executor.invoke({
'input': 'Qual é a temperatura em São Paulo hoje? Calcule também quanto seria em Fahrenheit.'
})
print('\n=== RESPOSTA FINAL ===')
print(resultado['output'])---
Ferramentas Essenciais: Busca Web, Python REPL, APIs
from langchain_experimental.tools import PythonREPLTool
from langchain.tools import StructuredTool
from pydantic import BaseModel
import requests
# Python REPL: o agente pode escrever e executar código Python
python_repl = PythonREPLTool()
# Exemplo de uso: análise de dados, geração de gráficos, qualquer operação Python
resultado = python_repl.run("""
import pandas as pd
import json
data = [10, 25, 15, 30, 45, 20]
df = pd.Series(data)
print(f'Média: {df.mean():.1f}')
print(f'Máximo: {df.max()}')
print(f'Desvio padrão: {df.std():.2f}')
""")
print(resultado)
# Ferramenta customizada com schema tipado (StructuredTool)
class BuscaCEPInput(BaseModel):
cep: str
def buscar_cep(cep: str) -> str:
"""Busca endereço a partir de um CEP brasileiro."""
cep_limpo = cep.replace('-', '').replace('.', '').strip()
try:
response = requests.get(f'https://viacep.com.br/ws/{cep_limpo}/json/', timeout=5)
data = response.json()
if 'erro' in data:
return f'CEP {cep} não encontrado.'
return f"{data['logradouro']}, {data['bairro']}, {data['localidade']}/{data['uf']}"
except Exception as e:
return f'Erro ao buscar CEP: {e}'
busca_cep_tool = StructuredTool.from_function(
func=buscar_cep,
name='buscar_cep',
description='Busca o endereço completo de um CEP brasileiro. Passe o CEP com ou sem traço.',
args_schema=BuscaCEPInput
)
# Testar a ferramenta
print(busca_cep_tool.run({'cep': '01310-100'})) # Av. Paulista
# Ferramenta de leitura de arquivo
def ler_arquivo(caminho: str) -> str:
"""Lê o conteúdo de um arquivo de texto."""
try:
with open(caminho, 'r', encoding='utf-8') as f:
conteudo = f.read()
return conteudo[:5000] # limitar para não explodir o contexto
except FileNotFoundError:
return f'Arquivo não encontrado: {caminho}'
except Exception as e:
return f'Erro ao ler arquivo: {e}'---
Agentes com Memória de Longo Prazo
Por padrão, cada execução do agente começa do zero. Para criar um assistente que lembra conversas anteriores, você precisa adicionar memória.
from langchain.memory import ConversationBufferWindowMemory, ConversationSummaryBufferMemory
from langchain_openai import ChatOpenAI
from langchain.agents import create_react_agent, AgentExecutor
from langchain import hub
from langchain.tools import Tool
from langchain_community.tools import DuckDuckGoSearchRun
llm = ChatOpenAI(model='gpt-4o-mini', temperature=0)
# Memória dos últimos K turnos (mais leve)
memoria_janela = ConversationBufferWindowMemory(
k=10, # mantém os últimos 10 turnos
memory_key='chat_history',
return_messages=True
)
# Memória com resumo automático (para conversas longas)
memoria_resumo = ConversationSummaryBufferMemory(
llm=llm,
max_token_limit=2000, # quando exceder, resume o histórico
memory_key='chat_history',
return_messages=True
)
ferramentas = [
Tool(name='Busca', func=DuckDuckGoSearchRun().run,
description='Busca informações na web.')
]
# Usar prompt que suporta memória
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
prompt_com_memoria = ChatPromptTemplate.from_messages([
('system', 'Você é um assistente útil. Você tem acesso às seguintes ferramentas: {tools}\n\nFormato de resposta:\nThought: seu raciocínio\nAction: nome_da_ferramenta\nAction Input: input da ferramenta\nObservation: resultado\n... (repita N vezes)\nThought: tenho a resposta\nFinal Answer: resposta final\n\nFerrametas disponíveis: {tool_names}'),
MessagesPlaceholder(variable_name='chat_history'),
('user', '{input}'),
MessagesPlaceholder(variable_name='agent_scratchpad')
])
agente = create_react_agent(llm=llm, tools=ferramentas, prompt=prompt_com_memoria)
executor_com_memoria = AgentExecutor(
agent=agente,
tools=ferramentas,
memory=memoria_janela,
verbose=True
)
# Conversa com memória
executor_com_memoria.invoke({'input': 'Meu nome é Carlos e gosto de Python.'})
executor_com_memoria.invoke({'input': 'Qual é o meu nome?'}) # o agente lembrará---
LangGraph: Agentes com Estado e Fluxo Controlado
LangGraph permite construir agentes como grafos de estados — mais previsíveis e controláveis que loops ReAct livres. Ideal para produção.
pip install langgraphfrom typing import TypedDict, Annotated
from langgraph.graph import StateGraph, START, END
from langgraph.prebuilt import ToolNode
from langchain_openai import ChatOpenAI
from langchain.tools import Tool
from langchain_community.tools import DuckDuckGoSearchRun
import operator
# 1. Definir o estado do agente
class EstadoAgente(TypedDict):
mensagens: Annotated[list, operator.add] # acumula mensagens
proxima_acao: str
# 2. Configurar ferramentas e LLM
ferramentas = [DuckDuckGoSearchRun()]
llm = ChatOpenAI(model='gpt-4o-mini').bind_tools(ferramentas)
# 3. Definir os nós do grafo
def no_agente(estado: EstadoAgente) -> dict:
"""Nó principal: o LLM decide a próxima ação."""
mensagens = estado['mensagens']
resposta = llm.invoke(mensagens)
return {'mensagens': [resposta]}
def roteador(estado: EstadoAgente) -> str:
"""Decide se continua com ferramentas ou termina."""
ultima_mensagem = estado['mensagens'][-1]
if hasattr(ultima_mensagem, 'tool_calls') and ultima_mensagem.tool_calls:
return 'ferramentas' # vai executar ferramentas
return 'fim' # chegou à resposta final
# 4. Construir o grafo
no_ferramentas = ToolNode(ferramentas)
builder = StateGraph(EstadoAgente)
builder.add_node('agente', no_agente)
builder.add_node('ferramentas', no_ferramentas)
builder.add_edge(START, 'agente')
builder.add_conditional_edges(
'agente',
roteador,
{'ferramentas': 'ferramentas', 'fim': END}
)
builder.add_edge('ferramentas', 'agente') # após executar ferramenta, volta ao agente
grafo = builder.compile()
# 5. Executar
from langchain_core.messages import HumanMessage
resultado = grafo.invoke({
'mensagens': [HumanMessage(content='Qual é a notícia de IA mais recente de hoje?')]
})
print(resultado['mensagens'][-1].content)A vantagem do LangGraph sobre AgentExecutor simples: você tem controle total sobre o fluxo, pode adicionar checkpoints (pausar e retomar execução), implementar intervenção humana em pontos específicos (human-in-the-loop) e depurar o estado em cada nó.
---
Monitorando Agentes com LangSmith
Agentes são difíceis de debugar sem observabilidade. O LangSmith é a ferramenta oficial da LangChain para rastrear execuções, medir latência e identificar onde o agente está errando.
pip install langsmithConfiguração (adicionar às variáveis de ambiente):
export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY=sua-api-key-langsmith
export LANGCHAIN_PROJECT=meu-agente-producaoCom essas variáveis definidas, toda execução LangChain é rastreada automaticamente — sem mudar nenhuma linha de código.
import os
os.environ['LANGCHAIN_TRACING_V2'] = 'true'
os.environ['LANGCHAIN_API_KEY'] = 'sua-key'
os.environ['LANGCHAIN_PROJECT'] = 'meu-projeto'
# A partir daqui, qualquer execução de LangChain é rastreada
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model='gpt-4o-mini')
resposta = llm.invoke('Explique o que é LangSmith') # esta chamada aparece no dashboard
# Adicionar metadados customizados a um trace
from langsmith import traceable
@traceable(name='meu-pipeline-rag', metadata={'versao': '1.2', 'usuario': 'carlos'})
def pipeline_rag(pergunta: str) -> str:
# Toda a lógica aqui aparece como um trace único no LangSmith
return 'resposta processada'No dashboard do LangSmith você visualiza: cada etapa do agente com duração, tokens consumidos, o raciocínio exato em cada passo, onde ocorreram erros e qual foi o custo em dólares de cada execução.
---
Casos de Uso Reais de Agentes de IA
Agente de pesquisa: recebe um tema, busca múltiplas fontes, sintetiza as informações e produz um relatório estruturado. Substitui horas de pesquisa manual.
Agente de suporte técnico nível 2: acessa bases de conhecimento, histórico de tickets, documentação técnica e sistemas internos. Resolve problemas mais complexos que um chatbot de FAQ.
Agente de análise de dados: recebe um CSV ou conexão a banco de dados, escreve e executa queries/código Python, produz visualizações e insights sem o usuário precisar saber SQL ou pandas.
Agente de automação de tarefas: monitora emails, categoriza, responde os simples, escalona os complexos, atualiza CRM. Substitui tarefas administrativas repetitivas.
Agente de code review: lê pull requests, verifica boas práticas, identifica bugs, sugere melhorias, cria relatórios de qualidade.
Agente de monitoramento: monitora métricas de um sistema, detecta anomalias, cria tickets automaticamente e notifica os responsáveis com contexto relevante.
Agente de onboarding de clientes: guia novos usuários pelo produto, responde dúvidas específicas ao contexto deles, executa configurações iniciais via API.
---
Erros Comuns e Como Evitar
1. Loop infinito sem critério de parada
Sempre defina max_iterations no AgentExecutor. Um agente pode entrar em loop tentando corrigir um erro indefinidamente.
executor = AgentExecutor(agent=agente, tools=ferramentas, max_iterations=10)2. Descrições de ferramentas vagas
A qualidade da descrição da ferramenta determina quando o agente vai usá-la. Seja específico: "Use quando o usuário perguntar sobre preço atual de ações ou câmbio" é muito melhor que "Busca dados financeiros".
3. Contexto de janela estourando
Em conversas longas ou agentes com muitas iterações, o contexto enche rapidamente. Use ConversationSummaryBufferMemory em vez de manter todo o histórico, e limite o retorno das ferramentas.
4. Ferramentas que falham silenciosamente
Sempre adicione tratamento de erro nas ferramentas e retorne mensagens descritivas de erro. O agente precisa saber o que deu errado para tentar de outra forma.
5. Não testar o agente com inputs adversariais
Usuários vão pedir coisas inesperadas. Teste com perguntas ambíguas, inputs malformados, pedidos que exigem ferramentas indisponíveis. Defina comportamentos de fallback.
6. Temperatura alta em agentes
Use temperature=0 em agentes de produção que precisam ser determinísticos. Temperatura alta aumenta criatividade, mas também aumenta alucinações de tool calls.
7. Sem logging das ações do agente
Em produção, registre cada ação que o agente toma. Sem isso, é impossível auditar comportamentos inesperados. Use verbose=True em desenvolvimento, LangSmith em produção.
---
Perguntas Frequentes
1. Qual LLM usar como base para meu agente?
Para produção: GPT-4o ou Claude 3.5 Sonnet têm o melhor suporte a tool use. Para desenvolvimento/teste com custo menor: GPT-4o-mini ou Claude 3 Haiku. Para rodar localmente sem custo: Llama 3.1 8B via Ollama (qualidade inferior, mas funciona para ferramentas simples).
2. Quando usar LangGraph vs AgentExecutor simples?
AgentExecutor é mais simples de começar. LangGraph é a escolha para produção quando você precisa de: fluxos com ramificações, human-in-the-loop, checkpointing (salvar e retomar estado), múltiplos agentes colaborando ou depuração detalhada.
3. Como evitar que o agente faça ações destrutivas?
Implemente o padrão human-in-the-loop para ações irreversíveis. No LangGraph, adicione um nó de "aprovação humana" antes de executar ferramentas destrutivas (deletar dados, enviar emails, fazer pagamentos). No código, implemente uma lista de permissões de ações e valide antes de executar.
4. Qual é o custo de rodar um agente em produção?
Depende do número de iterações e do modelo. Um agente que faz 5 iterações com GPT-4o-mini e usa ferramentas pode consumir 3.000–10.000 tokens por execução. Com 1.000 execuções/dia, isso é ~$1–3/dia. Modelos maiores multiplicam esse custo por 10–30x. Monitore com LangSmith e otimize o número de iterações.
5. Agentes são confiáveis o suficiente para produção?
Depende da tarefa. Para tarefas abertas com alta variabilidade: confiabilidade é ~70–85% nos melhores casos. Para tarefas bem definidas com ferramentas claras: pode chegar a 95%+. Em produção, implemente: rate limiting, aprovação humana para ações de alto risco, monitoramento de anomalias e fallback para humano quando o agente falhar por N tentativas.
6. Posso rodar agentes LangChain com modelos locais (Ollama)?
Sim. Use langchain-ollama como provider. A limitação é que modelos menores têm suporte a tool use menos confiável — podem não seguir o formato correto de chamada de ferramenta consistentemente. Para agentes com múltiplas ferramentas, modelos 13B+ têm resultados significativamente melhores que 7B.