Key Takeaways
- Agentes de IA seguem um loop: observar → raciocinar → agir → repetir.
- LangGraph é o framework recomendado para construir agentes locais com Ollama.
- Modelos locais de 70B ou maiores são necessários para raciocínio de múltiplas etapas confiável.
- Ferramentas comuns: busca na web, execução de código, leitura de arquivo, consultas a banco de dados.
- Sempre faça sandbox de agentes em containers Docker para produção.
- A LGPD brasileira é satisfeita com inferência local — nenhum dado de prompt sai da sua infraestrutura.
Um agente de IA combina um LLM, um conjunto de ferramentas e um loop -- o modelo decide qual ferramenta chamar, a executa, observa o resultado e decide a próxima ação -- e o LangGraph é o framework para construir isso inteiramente em hardware local via Ollama.
Um agente é diferente de um chatbot comum porque não apenas responde -- ele pode realizar ações, verificar o resultado e decidir sozinho o que fazer a seguir. O LangGraph dá a esse loop uma estrutura clara (nós e arestas) para que ele não rode para sempre ou se confunda, e executá-lo localmente via Ollama significa zero custo de API e nenhum dado saindo da sua máquina.
Como Funciona um Agente de IA?
Um agente segue este loop: (1) observar o estado/contexto, (2) o LLM raciocina sobre a melhor ação, (3) executar a ação (chamada de ferramenta), (4) observar o resultado, (5) repetir até concluir.
Exemplo: agente de pesquisa recebe a tarefa "Compare Llama 3.2 vs Qwen 3 em tarefas de codificação".
- Observação: tarefa recebida.
- Raciocínio: preciso encontrar benchmarks, buscar pontuações de HumanEval.
- Ação: usar a ferramenta web_search para encontrar "benchmark HumanEval do Llama 3.2".
- Observação: texto com pontuações recuperado.
- Ação: buscar "HumanEval do Qwen 3".
- Raciocínio: os dois modelos foram encontrados. Qwen é mais rápido, Llama é mais genérico.
- Ação final: sintetizar a resposta e retornar.
Um agente de IA é um programa que usa um LLM para decidir qual ferramenta chamar em seguida, observa o resultado e decide novamente — repetindo até a tarefa ser concluída.
💡Tip: A principal diferença em relação a uma cadeia é que os agentes usam a saída do LLM para *decidir* o que acontece a seguir, em vez de seguir um caminho predeterminado.
Qual a Diferença Entre Agentes e Cadeias?
Agentes tomam decisões dinâmicas em tempo real; cadeias seguem uma sequência predeterminada. Use agentes quando a tarefa exigir raciocínio ou recuperação de erros — use cadeias para fluxos de trabalho fixos e previsíveis.
| Aspect | Chains | Agents |
|---|---|---|
| Tomada de decisão | Sequência predeterminada | Dinâmica, o LLM decide |
| Loops | Sem loops | Loop de raciocínio (repete até concluir) |
| Recuperação de erros | Tratamento manual de erros | O LLM pode se recuperar de falhas |
| Caso de uso | Fluxos fixos (resumir → enviar e-mail) | Raciocínio complexo (pesquisa, automação) |
| Complexidade | Simples, previsível | Complexo, comportamento imprevisível |
📌Note: Agentes são mais lentos e imprevisíveis que cadeias porque o LLM precisa tomar uma decisão a cada etapa. Se a velocidade é crítica e seu fluxo de trabalho já é conhecido, use uma cadeia.
Como Funciona a Arquitetura do LangGraph?
O LangGraph define agentes como grafos acíclicos direcionados (DAGs) com nós (estados) e arestas (transições).
- Estado: informação que o agente mantém (contexto, observações, decisões).
- Nós: funções que processam o estado (raciocínio do LLM, execução de ferramentas).
- Arestas: transições entre nós (condicionais, baseadas na saída do LLM).
- Ferramentas: funções que o LLM pode chamar (busca na web, execução de código, consultas a banco de dados).
O LangGraph é como um fluxograma em que o LLM decide qual seta seguir em cada caixa de decisão — e pode voltar atrás quando algo dá errado.
Quais Ferramentas os Agentes Podem Usar?
A capacidade de um agente é definida inteiramente pelas suas ferramentas — as funções que ele pode chamar para interagir com o mundo. Limite a 5–10 ferramentas por agente para evitar paralisia de decisão.
- Busca na web: pesquisa informações na internet (DuckDuckGo, Google, Bing).
- Execução de código: executa código Python e retorna resultados.
- Operações de arquivo: lê/grava arquivos, lista diretórios.
- Consultas a banco de dados: consulta bancos de dados locais ou remotos.
- Recuperação de documentos: busca documentos em um banco de dados vetorial RAG.
- Calculadora: realiza aritmética e matemática simbólica.
- E-mail: envia mensagens (com cautela, verifique permissões).
- Chamadas de API: interage com serviços externos.
⚠️Warning: Ferramentas demais confundem o LLM — a latência por etapa aumenta e o agente escolhe a ferramenta errada com mais frequência. Comece com 3–5 ferramentas essenciais.
🛠️Practice: Escreva cada descrição de ferramenta em menos de 50 palavras e diga exatamente quando usá-la. Uma descrição clara ajuda o LLM a escolher a ferramenta certa.
Como os Agentes Raciocinam e Planejam?
O raciocínio do agente depende do tamanho do modelo LLM e da qualidade do prompt.
- Modelos pequenos (3-7B): raciocínio limitado. Funcionam melhor com tarefas determinísticas (busca de ferramentas, classificação).
- Modelos médios (13-30B): raciocínio razoável. Conseguem lidar com cadeias de raciocínio de 2-3 etapas.
- Modelos grandes (70B+): raciocínio forte. Conseguem resolver problemas complexos com planejamento em múltiplas etapas.
Técnica de prompting: Chain-of-Thought (CoT) ajuda os agentes a pensar nas etapas antes de decidir. Certifique-se de que o Ollama esteja instalado e em execução antes de testar o desempenho de raciocínio.
❌ Prompt ruim
“Você é um assistente de IA prestativo. Um usuário vai pedir para você fazer uma pesquisa. Faça o seu melhor.”
✅ Prompt bom
“Você é um agente de pesquisa. Para cada tarefa: (1) divida em 2–3 subperguntas, (2) busque cada uma usando a ferramenta web_search, (3) sintetize os achados, (4) cite as fontes. Sempre explique seu raciocínio antes de chamar uma ferramenta. Limite rígido: 10 etapas de raciocínio no máximo.”
# Exemplo: prompt de raciocínio CoT para agente
system_prompt = """
Você é um agente de pesquisa. Divida tarefas complexas em etapas:
1. Identifique quais informações você precisa
2. Chame as ferramentas apropriadas para reunir informações
3. Analise os resultados e determine os próximos passos
4. Retorne a resposta final com fontes
Sempre raciocine passo a passo antes de chamar ferramentas.
"""🔍Insight: Prompts Chain-of-Thought funcionam bem para agentes — o raciocínio explícito passo a passo ajuda o LLM a fazer melhores escolhas de ferramentas.
⚠️Warning: Prompts genéricos de "assistente prestativo" falham para agentes autônomos. Você precisa de limites explícitos de etapas, regras de formato de saída e instruções de raciocínio sobre ferramentas.
Quais Padrões de Agentes Locais Funcionam Melhor?
Cinco padrões cobrem a maioria dos casos de uso de agentes locais. Escolha com base na necessidade principal: raciocínio, execução de código, planejamento, conversação ou automação.
- Agente de pesquisa: busca em documentos e na web, sintetiza os achados.
- Agente de código: escreve e executa código para resolver problemas.
- Agente de planejamento: divide tarefas complexas em subtarefas, delega a outros agentes.
- Agente conversacional: mantém memória, responde perguntas, aprende com o feedback.
- Automação de fluxo de trabalho: lê e-mails, executa tarefas, envia confirmações.
Quais São os Erros Mais Comuns na Implementação de Agentes?
A maioria das falhas de agentes locais tem cinco causas raiz: excesso de ferramentas, descrições de ferramentas vagas, loops infinitos, ausência de tratamento de erros e descompasso no tamanho do modelo.
- Ferramentas demais: o agente fica confuso com muitas opções. Limite a 5-10 ferramentas relevantes.
- Descrições de ferramentas ruins: o LLM não usará as ferramentas corretamente se as descrições forem vagas. Escreva descrições claras e específicas.
- Loops infinitos: o agente pode ficar preso em loops de raciocínio. Adicione um limite máximo de iterações (por exemplo, 10 etapas).
- Sem tratamento de erros: chamadas de ferramentas podem falhar. Faça o agente lidar com falhas de forma elegante.
- Uso de modelos pequenos: modelos de 3B não raciocinam bem o suficiente para agentes complexos. Use 13B+ para agentes autônomos.
⚠️Warning: O maior erro é implantar um agente sem um limite rígido de iterações. Agentes podem entrar em loop para sempre se o LLM travar. Sempre defina max_iterations entre 10 e 20.
Perguntas Frequentes Sobre Agentes de IA Locais
🛠️Practice: Teste os agentes primeiro com um número máximo de iterações (por exemplo, 5 etapas) para detectar bugs antes de implantar em produção, onde eles poderiam desperdiçar recursos.
Quanto mais rápidos são os agentes na nuvem em comparação aos agentes locais?
Agentes na nuvem: ~1 segundo por etapa de raciocínio. Agentes locais: ~3-5 segundos por etapa, dependendo do tamanho do modelo e do hardware. A inferência local adiciona latência, mas elimina custos de API e mantém todos os dados no seu próprio hardware.
Agentes locais podem acessar a internet?
Sim, se você fornecer uma ferramenta web_search. O agente chama essa ferramenta da mesma forma que chama qualquer outra função. Opções populares incluem a API de busca do DuckDuckGo e o SerpAPI para resultados estruturados.
Como garantir que um agente não danifique nada (por exemplo, exclua arquivos)?
Execute as ferramentas dentro de um container Docker com permissões estritas de sistema de arquivos e rede. Registre cada chamada de ferramenta com suas entradas e saídas para trilhas de auditoria. Adicione uma etapa de confirmação antes de qualquer ação destrutiva.
Posso executar múltiplos agentes em paralelo?
Sim. Use frameworks assíncronos como FastAPI para lidar com solicitações concorrentes de agentes. Cada solicitação recebe seu próprio estado de conversa. Cada agente paralelo requer sua própria thread de inferência do LLM, então a VRAM limita quantos você pode executar simultaneamente.
Qual é o hardware mínimo necessário para executar um agente de IA local?
Um modelo com 13B+ parâmetros é recomendado para raciocínio autônomo confiável. Isso requer pelo menos 16GB de RAM e, de preferência, uma GPU com 8GB+ de VRAM para um modelo 13B quantizado. Em hardware somente CPU, espere de 5 a 15 segundos por etapa de raciocínio.
Quando devo usar o LangGraph em vez do LangChain puro?
Use o LangGraph quando seu fluxo de trabalho exigir loops, ramificações condicionais ou recuperação de falhas de ferramentas. O LangChain puro funciona bem para pipelines lineares sem pontos de decisão. Se seu agente precisar tentar novamente ou raciocinar de novo após uma etapa falha, a estrutura de grafo do LangGraph resolve isso de forma limpa.
O LangGraph é o mesmo que o LangChain?
Não. O LangChain é um kit de ferramentas de LLM de uso geral para construir cadeias e pipelines. O LangGraph é um framework separado, construído sobre o LangChain especificamente para agentes e fluxos de trabalho com estado — ele adiciona a estrutura de grafo necessária para loops de raciocínio confiáveis.
Quantas ferramentas um agente local deve ter?
Limite os agentes a 5-10 ferramentas. Com opções demais, o LLM tem dificuldade para selecionar a ferramenta certa e a latência por etapa aumenta. Comece com 3-5 ferramentas essenciais e expanda apenas ao encontrar uma lacuna de capacidade específica.
Fatos Rápidos
- Latência do agente local: ~3-5 seg por etapa de raciocínio (vs. ~1 seg para agentes na nuvem)
- Mínimo de modelo: 13B+ parâmetros para agentes autônomos confiáveis de múltiplas etapas
- Limite de ferramentas: 5-10 ferramentas por agente — acima de 10, a qualidade das decisões cai
- Iterações máximas: defina um limite rígido de 10-20 etapas para evitar loops infinitos
- Hardware: 8GB+ de VRAM para um modelo 7B quantizado; 16GB+ para agentes de 13B
- Latência de raciocínio em CPU: 5-15 seg por etapa em 13B (padrão do Ollama)
Contexto regional e conformidade
Brasil (LGPD / ANPD) — Agentes de IA locais mantêm todos os dados de prompt na sua infraestrutura, atendendo à LGPD (Lei nº 13.709/2018). Nenhuma chamada a API de nuvem é feita durante a inferência, satisfazendo os requisitos de residência de dados da ANPD.
UE/GDPR — A inferência local satisfaz o Artigo 28 do GDPR. Agentes locais são a escolha preferida para setores financeiros, de saúde e jurídicos da UE.
China (PIPL/CAC) — A inferência local com LangGraph + Ollama satisfaz os requisitos de localização de dados da lei CAC de IA Generativa de 2023.
Fontes
- Documentação do LangGraph — Repositório oficial e documentação do framework de agentes LangGraph.
- Documentação de Agentes do LangChain — Guia do módulo de agentes do LangChain com padrões de integração de ferramentas.
- ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., 2022) — Artigo fundamental que introduz o loop observar-raciocinar-agir usado nos agentes LangGraph.