êntica para devs: guia prático com Python e LangGraph

Da IA generativa à agêntica: o salto que pouca gente está prestando atenção

A IA generativa já virou commodity. Hoje qualquer dev usa ChatGPT, Claude ou Gemini para responder perguntas e gerar código. O próximo salto — e é o que mais me empolga em 2026 — é a IA agêntica. Não estamos mais falando de um modelo que “responde”, mas de um sistema que age, decide e executa tarefas em múltiplos passos.

Segundo o Sapo.pt, a IA agêntica “define ou interpreta objetivos, planeia os passos necessários, utiliza ferramentas e executa ações com pouca intervenção humana”. Na prática, isso muda tudo para quem programa. Passei as últimas semanas testando agentes em produção e quero compartilhar o que funcionou, o que quebrou e onde ainda há mais hype do que entrega real.

O que muda, de fato, entre IA generativa e IA agêntica

A diferença não é só conceitual. Ela afeta arquitetura, custo, latência e confiança. Olha o comparativo que eu uso nos meus briefings:

O exemplo do Sapo.pt é didático: pergunte a uma IA generativa “quais voos para Londres na sexta?” e ela lista opções. Peça a um agente “organize minha viagem a Londres na sexta” e ele pesquisa voos, compara hotéis, reserva restaurante e monta roteiro — sem você ditar cada passo.

Como um agente funciona por baixo dos panos

Quando eu desmonto um sistema agêntico em produção, encontro quatro blocos recorrentes:

1. LLM como cérebro — o modelo raciocina e decide o próximo passo.
2. Memória — curto prazo (contexto da conversa) e longo prazo (vector store, banco relacional).
3. Ferramentas (tools) — funções que o agente pode chamar: APIs, bancos, navegadores, shell.
4. Loop de execução — o agente observa o resultado da ação, atualiza o estado e decide o próximo passo.

Esse loop é o que diferencia um agente de um chatbot com plugins. Ele tem autonomia para reagir a falhas. Se uma ferramenta retorna erro, o agente pode tentar outra ou reformular a query. É o pattern ReAct (Reasoning + Acting), publicado originalmente por Shunyu Yao em 2022 e que continua sendo a base de tudo.

Frameworks que eu uso e recomendo em 2026

Não reinvente a roda. Testei vários em projetos reais e estes ficaram no meu stack:

• LangChain / LangGraph — o mais maduro. LangGraph permite fluxos cíclicos, essenciais para agentes de verdade com checkpoints e human-in-the-loop.
• CrewAI — ótimo para sistemas multi-agente (um pesquisador, um escritor, um revisor trabalhando juntos com papéis definidos).
• AutoGen (Microsoft) — forte em conversação entre agentes, ideal para research workflows.
• OpenAI Assistants API — menos código, mais caixa-preta. Útil para protótipos rápidos e MVPs.
• Claude + MCP (Model Context Protocol) — o MCP virou padrão de fato para integração com ferramentas. Vale aprender.

Para a maioria dos meus projetos, vou de LangGraph com Claude ou GPT-4o. A curva é maior, mas o controle compensa em produção.

Na Prática: montando um agente funcional em Python

Vou mostrar um agente real que escrevi semana passada para organizar viagens. Simplifiquei para fins didáticos, mas a estrutura é a mesma que uso em produção.

import os
from langchain_openai import ChatOpenAI
from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain import hub
from langchain.tools import Tool

# 1. Ferramentas que o agente pode chamar autonomamente
def buscar_voos(origem_destino_data: str) -> str:
    # Em producao: chamada real a Skyscanner, Duffel, Amadeus
    return f"Voos {origem_destino_data}: TAP EUR120, Ryanair EUR89, BA EUR145"

def buscar_hoteis(cidade_checkin: str) -> str:
    return f"Hoteis em {cidade_checkin}: Hotel A EUR90/noite, Hotel B EUR140/noite"

def montar_roteiro(cidade_dias: str) -> str:
    return f"Roteiro: Dia 1 centro historico, Dia 2 museus, Dia 3 parques."

tools = [
    Tool(
        name="buscar_voos",
        func=buscar_voos,
        description="Busca voos entre cidades. Input: 'origem-destino-data'. Exemplo: 'GRU-LHR-2026-03-15'"
    ),
    Tool(
        name="buscar_hoteis",
        func=buscar_hoteis,
        description="Busca hoteis em uma cidade. Input: 'cidade-checkin'"
    ),
    Tool(
        name="montar_roteiro",
        func=montar_roteiro,
        description="Monta roteiro turistico. Input: 'cidade-dias'"
    ),
]

# 2. Cerebro do agente
llm = ChatOpenAI(model="gpt-4o", temperature=0)
prompt = hub.pull("hwchase17/openai-functions-agent")
agent = create_openai_functions_agent(llm, tools, prompt)

# 3. Executor com loop autonomo
executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,
    max_iterations=10,
    early_stopping_method="generate",
    handle_parsing_errors=True
)

# 4. Objetivo amplo - sem instrucoes passo a passo
resultado = executor.invoke({
    "input": "Organize minha viagem para Londres na proxima sexta, quero 3 dias partindo de SP"
})

print(resultado["output"])

Três decisões que importam nesse snippet:

• temperature=0 — reduz alucinações em ações determinísticas.
• max_iterations=10 — limite de segurança. Sem isso, um agente travado pode queimar centenas de dólares em tokens.
• handle_parsing_errors=True — evita que o loop morra por causa de uma saída mal formatada.

Dica de produção: verbose ligado em dev, desligado em prod — o log pode vazar dados sensíveis dos parâmetros das ferramentas.

Erros comuns que eu vejo devs cometendo

Em produção, esses são os tropeços mais frequentes. Anota aí:

1. Confiar cegamente na saída do agente. Agentes alucinam ferramentas que não existem, inventam parâmetros e mentem sobre resultados. Sempre valide a saída antes de executar ações irreversíveis — enviar email, cobrar cartão, deletar recurso, publicar em produção.

2. Esquecer o limite de iteração. Sem max_iterations, um agente em loop infinito já me queimou US$ 400 em uma única requisição de cliente. Coloque timeout e custo máximo por execução.

3. Não separar “raciocinar” de “executar”. Em ações sensíveis, use o padrão human-in-the-loop: o agente propõe, um humano aprova. LangGraph tem interrupt_before exatamente para isso. Em produção, isso não é opcional — é lei.

4. Tool descriptions ruins. O agente decide qual ferramenta usar baseado na descrição. Se ela for vaga, ele chama a ferramenta errada. Invista tempo escrevendo descrições claras, com exemplo de input e output. Eu uso docstrings detalhadas e às vezes um exemplo few-shot dentro da description.

5. Misturar memória de curto e longo prazo entre usuários. Você não quer que dados do usuário A vazem para o usuário B. Cada sessão precisa de isolamento. Eu uso Redis com TTL para sessão e um vector store por usuário para memória longa.

6. Subestimar a latência. Um agente que faz 5 chamadas LLM leva 10-30 segundos. Se você precisa de resposta em 2 segundos, agente não é a solução — é um workflow determinístico ou um cache agressivo.

Quando NÃO usar IA agêntica

Nem tudo precisa de agente. Eu evito quando:

• A tarefa tem fluxo fixo e conhecido — use código tradicional ou workflow engine tipo Temporal.
• A latência é crítica (resposta em <2s).
• A ação é irreversível e de alto risco sem revisão humana.
• O custo por execução supera o valor entregue.

Para 80% dos casos que vejo, um simples RAG com function calling resolve. Agente é para os 20% onde a flexibilidade justifica o custo e a complexidade.

FAQ — perguntas que devs sempre me fazem

1. Qual a diferença prática entre RAG, function calling e agente?
RAG busca informação estática para enriquecer o prompt. Function calling executa uma função específica quando o LLM decide. Agente orquestra múltiplas chamadas, ferramentas e raciocínio em loop, com autonomia para replanejar.

2. Preciso de um modelo grande para rodar agentes?
Não necessariamente. GPT-4o-mini, Claude Haiku e Gemini Flash já dão conta de agentes simples com 2-3 ferramentas. Para raciocínio complexo multi-step com muitas decisões, vai de modelo maior (GPT-4o, Claude Sonnet).

3. Quanto custa rodar um agente em produção?
Depende das iterações. Um agente simples custa centavos. Um agente que faz 15-20 chamadas LLM por execução pode custar US$ 0.50 a US$ 2.00. Sempre calcule o custo médio por task e monitore com tracing (LangSmith, Langfuse).

4. Agentes vão substituir programadores?
Não no curto prazo. Substituem tarefas específicas: buscar dados em múltiplas APIs, gerar código boilerplate, fazer revisão de PR, organizar informação. Mas a arquitetura, decisões de produto e validação continuam humanas. Quem souber orquestrar agentes vai ter mais valor de mercado, não menos.

5. Por onde começo a estudar?
Leia o paper ReAct (Yao et al., 2022) — é o seminal. Depois faça o tutorial oficial do LangGraph, que tem a melhor documentação. Em paralelo, estude o paper Reflexion para entender auto-correção. Por fim, monte um projeto real — aprender fazendo é insubstituível.

Considerações finais

IA agêntica não é hype vazio. É a próxima camada de abstração sobre LLMs e vai mudar a forma como construímos software nos próximos 2-3 anos. Mas exige maturidade: telemetria, limites de custo, fallback, revisão humana, observabilidade. Quem pular essas etapas vai queimar dinheiro e reputação.

Se você está começando, não tente construir um agente autônomo genérico no primeiro dia. Comece com escopo fechado — agendar reunião, organizar viagem, resumir emails, fazer scraping estruturado — e vá expandindo. Cada iteração vai te ensinar mais do que qualquer tutorial.

Referência: Sapo.pt — “IA agêntica: o que é e porque está a mudar a forma como usamos a Inteligência Artificial?”

Gostou? Me segue no GitHub e deixa um comentário se tiver dúvida ou quiser aprofundar algum ponto.