Criar um agente de IA local: arquitetura e ferramentas recomendadas

#Por que construir um agente de IA local

Um agente de IA local atende a três necessidades que a nuvem lida mal em atender. Primeiro, a confidencialidade: quando um agente lê seus e-mails, consulta sua base de dados ou percorre seus arquivos, cada chamada enviada a uma API externa representa um risco de vazamento. Localmente, o contexto nunca sai da máquina. Em seguida, o custo: um agente encadeia dezenas de chamadas ao modelo para uma única tarefa, e a conta de uma API cobrada por uso aumenta rapidamente. Por fim, a autonomia: sem limites de taxa de requisições, sem interrupções de rede, sem mudanças na política de preços de um dia para o outro.

O preço a pagar é real: um modelo local de 14B ou 32B não raciocina com tanta sutileza quanto os melhores modelos proprietários. O projeto do agente — ferramentas com funções bem delimitadas, prompts rigorosos, mecanismos de proteção — importa, portanto, mais do que na nuvem. É precisamente isso que este guia sobre o agente de IA local aborda.

#Anatomia de um agente

Independentemente do framework, um agente de IA local sempre se baseia nos mesmos componentes. Compreendê-los permite escolher suas ferramentas de forma consciente, em vez de seguir um tutorial às cegas.

O modelo (raciocínio)

O LLM que decide a ação seguinte. Ele deve gerenciar a chamada de ferramentas de forma confiável: Qwen 3.x, Granite 4.x ou Mistral Small são boas opções locais.

As ferramentas (ações)

Funções Python que o agente pode chamar: ler um arquivo, chamar uma API, realizar uma pesquisa, escrever em uma base. Cada ferramenta é descrita por um esquema JSON que o modelo lê.

Memória (estado)

Curto prazo (histórico da conversa em andamento) e longo prazo (um vector store que persiste entre as sessões). Esse é o papel do RAG, detalhado abaixo.

O orquestrador (loop)

O código que encadeia raciocínio, chamada de ferramenta e observação até que a condição de parada seja atendida. É isso que um framework como CrewAI ou AutoGen fornece.

O planejador (estratégia)

A lógica que divide um objetivo complexo em tarefas menores e ordenadas. Pode ser explícita (um agente planejador dedicado) ou implícita (o modelo raciocina passo a passo).

Um agente mínimo precisa apenas de um modelo, de duas ou três ferramentas e de um loop. Um sistema avançado adiciona memória persistente, planejamento em múltiplas etapas e vários agentes especializados que colaboram. Comece simples: a maioria das tarefas não exige uma equipe de dez agentes.

#Pré-requisitos e stack recomendada

A pilha de referência para um agente de IA local consiste em três camadas: Ollama para servir o modelo, um framework de orquestração em Python e um modelo capaz de chamada de ferramentas. Ollama escuta por padrão em http://localhost:11434 e expõe um endpoint compatível com a OpenAI, o que simplifica a integração com a maioria dos frameworks.

GPU / VRAM

Um agente raciocina melhor com um modelo de 14B+ do que com 7B. Estime cerca de 9 GB de VRAM para um modelo de 14B em Q4_K_M, cerca de 19 GB para um de 32B. Uma RTX 4070 de 12 GB executa confortavelmente um modelo de 14B; uma RTX 4090 de 24 GB ou um Mac M4 Pro visam o modelo de 32B.

Modelo

Escolha um modelo com reputação de confiabilidade na chamada de ferramentas. A qualidade do function calling importa mais do que o tamanho bruto: um 14B rigoroso vence um 32B que inventa argumentos.

Python 3.10+

CrewAI e AutoGen são bibliotecas Python. Trabalhe em um ambiente virtual dedicado para evitar conflitos de dependências.

Quantization

Q4_K_M oferece um bom equilíbrio como opção padrão. Passe para Q5_K_M ou Q8_0 se o modelo cometer erros de raciocínio e a VRAM permitir.

# 1. Vérifier qu'Ollama tourne
curl http://localhost:11434/api/tags

# 2. Récupérer un modèle capable de tool calling
ollama pull qwen3:14b

# 3. Environnement Python isolé
python -m venv .venv && source .venv/bin/activate
pip install crewai crewai-tools

#CrewAI ou AutoGen: qual escolher?

Os dois frameworks gerenciam agentes, mas com filosofias diferentes. A escolha certa depende da sua tarefa, não de um ranking absoluto.

CrewAI

Orientado a 'equipe': definimos agentes com um papel, um objetivo e ferramentas, depois atribuímos tarefas ordenadas. Abordagem declarativa, legível, ideal para pipelines de negócios (buscar → redigir → revisar). Memória RAG integrada

AutoGen

Orientado à « conversa »: os agentes dialogam entre si até convergirem. Mais flexível para problemas abertos e raciocínio colaborativo, mas exige mais ajustes para se manter dentro dos limites em execução local. A v0.4 se conecta ao Ollama por meio de seu cliente compatível com OpenAI.

Quando manter a simplicidade

Para um único agente com algumas ferramentas, um framework leve (ou LangChain) é suficiente. CrewAI e AutoGen tornam-se muito úteis quando há vários papéis ou uma orquestração não trivial.

from crewai import Agent, Task, Crew, LLM

# CrewAI passe par LiteLLM : préfixe 'ollama/' + base_url local
llm = LLM(
    model="ollama/qwen3:14b",
    base_url="http://localhost:11434",
)

chercheur = Agent(
    role="Analyste documentaire",
    goal="Extraire les faits clés des documents fournis",
    backstory="Expert méthodique, ne répond que sur la base des sources.",
    llm=llm,
    verbose=True,
)

tache = Task(
    description="Résume les 3 points essentiels du rapport fourni.",
    expected_output="Une liste à puces de 3 points, sourcés.",
    agent=chercheur,
)

equipe = Crew(agents=[chercheur], tasks=[tache])
print(equipe.kickoff())

from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.agents import AssistantAgent

# Endpoint OpenAI-compatible d'Ollama : /v1
client = OpenAIChatCompletionClient(
    model="qwen3:14b",
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # ignore par Ollama, mais requis par le client
    model_info={
        "function_calling": True,
        "json_output": True,
        "vision": False,
        "family": "unknown",
    },
)

agent = AssistantAgent(name="assistant", model_client=client)

#Construir o agente passo a passo

Aqui está o passo a passo para transformar um modelo bruto em um agente de IA local que realize uma tarefa real. A ordem importa: cada etapa valida a anterior.

1. 01
   Definir o objetivo e a condição de parada

   Escreva em uma frase o que o agente deve produzir e como saber que ele terminou. Um objetivo vago (« ajude-me ») gera um agente que fica andando em círculos; um objetivo delimitado (« classifique essas 20 faturas por fornecedor em um CSV ») gera um agente controlável.
2. 02
   Dividir em ferramentas atômicas

   Cada ação externa se torna uma função Python com nome explícito, argumentos tipados e docstring clara — é essa descrição que o modelo lê. Prefira várias ferramentas pequenas e precisas a uma ferramenta grande que tente fazer de tudo.
3. 03
   Escrever o prompt de sistema

   Defina o papel, as ferramentas disponíveis e as regras (nunca inventar, sempre citar a fonte, parar em caso de dúvida). Na execução local, um prompt rigoroso compensa a menor sofisticação de raciocínio do modelo.
4. 04
   Conectar o ciclo de orquestração

   Deixe o framework gerenciar o ciclo raciocinar → agir → observar, mas defina um limite de iterações (por exemplo, 10) para evitar que um agente travado consuma recursos indefinidamente. É uma proteção essencial na operação autônoma.
5. 05
   Adicionar memória

   Conecte um vector store para a memória de longo prazo se o agente precisar lembrar entre as sessões (ver seção seguinte). Sem essa necessidade, o histórico da conversa é suficiente.
6. 06
   Testar em casos reais e iterar

   Execute o agente com entradas variadas, leia os registros de execução (verbose), corrija os prompts e as descrições das ferramentas. 80% do trabalho de um agente local acontece aqui, não no código inicial.

#Memória de longo prazo com o RAG

Um agente sem memória começa do zero em cada sessão. A memória de longo prazo segue o mesmo princípio do RAG (Retrieval-Augmented Generation): armazenamos as informações em forma de vetores em uma base e recuperamos as mais pertinentes no momento desejado para reinjetá-las no contexto.

Embeddings locais

Gere os vetores com um modelo de embedding servido pelo Ollama (por exemplo, nomic-embed-text ou mxbai-embed-large): os dados a serem armazenados não saem da máquina, o que está alinhado com o objetivo de privacidade.

Armazenamento vetorial

ChromaDB é a escolha padrão para uso local: leve, com persistência em disco e integrado nativamente ao CrewAI. Para volumes maiores, o Qdrant auto-hospedado assume esse papel.

Memória integrada do CrewAI

O CrewAI oferece uma memória pronta para uso (memória de curto prazo, de longo prazo e de entidades) que pode ser configurada para usar um embedder Ollama, sem precisar montar manualmente o pipeline RAG.

from crewai import Crew

equipe = Crew(
    agents=[chercheur],
    tasks=[tache],
    memory=True,  # active la memoire long terme (ChromaDB sous le capot)
    embedder={
        "provider": "ollama",
        "config": {"model": "nomic-embed-text"},
    },
)

#Planejamento de tarefas

O planejamento é a capacidade do agente de dividir um objetivo complexo em etapas ordenadas antes de agir. Sem ele, um modelo local tende a partir direto para a primeira ação que surge e a se perder. Duas abordagens coexistem.

Planejamento implícito (ReAct)

O modelo raciocina em voz alta, passo a passo, escolhe uma ação, observa e depois replaneja. Fácil de implementar, mas frágil em modelos pequenos que perdem o fio após alguns turnos.

Planejamento explícito

Um agente (ou uma primeira tarefa) dedicado ao planejamento produz uma lista de etapas, que os agentes de execução processam em seguida. Mais robusto em execução local: separamos “pensar” e “fazer”, o que reduz a carga de cada chamada.

Decomposição hierárquica

Para tarefas longas, o CrewAI permite um processo hierárquico em que um agente 'gerente' delega e supervisiona. Poderoso, mas deve ser usado apenas em casos que justifiquem seu uso — a coordenação custa tokens.

Regra prática para uso local: quanto menor o modelo, mais explícito deve ser o planejamento e mais restrito deve ser o escopo de cada etapa. Um 14B que executa uma microtarefa bem delimitada é mais confiável que um 32B solto diante de um objetivo vago.

#Segurança dos dados

A execução inteiramente local elimina o vazamento de dados para APIs de terceiros, mas um agente autônomo introduz seus próprios riscos: ele executa ações, às vezes destrutivas, com base em texto gerado. A confidencialidade não dispensa medidas de proteção.

Princípio do menor privilégio

Dê ao agente apenas as ferramentas estritamente necessárias. Um agente que não precisa escrever no disco não deve ter ferramenta de escrita — é a primeira barreira contra danos.

Validação humana de ações sensíveis

Para tudo o que seja irreversível (excluir, enviar, pagar, modificar uma base), insira uma confirmação manual. A autonomia total só se justifica em ações seguras e reversíveis.

Isolamento da execução de código

Se o agente executar código, faça isso em um contêiner ou em um ambiente de sandbox, nunca diretamente na máquina hospedeira. Um prompt malicioso inserido em um documento pode desviar o comportamento de um agente (injeção de prompt).

Registro das ações

Rastreie cada chamada de ferramenta e cada decisão. Em caso de comportamento inesperado, o rastreamento é seu único meio de entender o que o agente realmente fez.

#Dicas e solução de problemas

O agente entra em loop sem nunca parar

Verifique a condição de parada e o limite de iterações. Muitas vezes o objetivo é muito vago ou o agente não reconhece que já terminou: deixe o resultado esperado explícito no prompt.

Chamadas de ferramentas mal formatadas

O modelo inventa argumentos ou esquece campos. Simplifique os esquemas de ferramentas, passe para um nível superior de quantização (Q4 → Q5) ou mude para um modelo mais confiável em chamada de ferramentas.

Respostas lentas com vários agentes

Cada agente é uma chamada completa ao modelo. Ao executar localmente, reduza o número de agentes, encurte os prompts de sistema e verifique se o modelo cabe inteiramente na VRAM (caso contrário, o offload para a CPU derruba a taxa de processamento).

A memória não recupera nada relevante

Modelo de embedding incorreto ou blocos muito grandes/pequenos. Verifique se o embedder Ollama está rodando e ajuste o tamanho dos blocos armazenados.

Conexão recusada em :11434

Ollama não está sendo executado ou está ouvindo em outra interface. Confirme com « curl http://localhost:11434/api/tags » e verifique a base_url passada ao framework.

#Para se aprofundar

Este guia define a arquitetura; esses tutoriais entram na implementação concreta de cada componente:

Múltiplos agentes com CrewAI

« CrewAI + Ollama: orquestrar vários agentes de IA localmente » detalha a montagem de uma equipe de agentes especializados, com papéis e tarefas definidos.

Um agente em Python de A a Z

« Criar um agente IA local em Python com LangChain e Ollama » constrói passo a passo um agente capaz de chamar ferramentas e ler arquivos.

Bloco de memória (RAG)

« RAG local com ChromaDB e Ollama : tutorial em Python » abrange o pipeline completo embeddings → pesquisa → resposta, o núcleo da memória de longo prazo.