CrewAI + Ollama: orquestrar vários agentes de IA em local

#Por que orquestrar uma equipe CrewAI localmente

O padrão multiagentes parte de uma constatação simples: dividir uma tarefa complexa entre vários agentes especializados produz resultados melhores do que um único prompt gigante. Cada agente tem um papel claro, um objetivo preciso e vê apenas sua parte do trabalho. CrewAI é o framework Python que formaliza essa divisão — papéis, tarefas, colaboração sequencial ou hierárquica — sem a complexidade de montar sozinho um grafo de estados.

Executar essa crew no Ollama em vez de no GPT-4 ou no Claude muda três coisas. Primeiro, a privacidade: um pipeline multiagente multiplica as chamadas ao modelo e, portanto, as possíveis exposições de dados a terceiros; localmente, nada sai da máquina. Em seguida, o custo: uma crew que troca muitas mensagens pode consumir centenas de milhares de tokens por execução, o que fica caro rapidamente em uma API cobrada por token — localmente, o custo marginal é nulo. Por fim, o controle: você escolhe o modelo, a quantização e o contexto, e faz iterações sem cotas nem limites de frequência de requisições.

#Os 4 componentes do CrewAI

Antes de escrever uma linha, é preciso conhecer o vocabulário. O CrewAI se baseia em quatro objetos que se encaixam. Compreendê-los evita 90% dos erros de projeto de uma crew.

Agente

Um LLM com uma identidade: um papel («Analista de mercado»), um objetivo (goal) e uma história (backstory) que orientam seu comportamento. Cada agente pode usar seu próprio modelo Ollama.

Task

Uma unidade de trabalho confiada a um agente: uma descrição, um resultado esperado (expected_output) e, muitas vezes, ferramentas. É a tarefa, não o agente, que contém a instrução concreta.

Tool

Uma capacidade externa que um agente pode chamar: pesquisa na web, leitura de arquivo, consulta SQL, cálculo. Sem ferramentas, um agente apenas raciocina sobre o que já conhece.

Crew

A equipe: a lista de agentes, a lista de tarefas e o processo que decide a ordem de execução (sequential ou hierarchical). É o objeto que você inicia com kickoff().

O processo merece um esclarecimento. No modo sequential, as tarefas são executadas na ordem declarada e a saída de uma alimenta a próxima — perfeito para uma cadeia de pesquisa → redação → revisão. No modo hierarchical, um agente “gerente” (um LLM dedicado) delega tarefas e coordena os outros. O modo hierárquico é mais poderoso, mas exige muito mais de um modelo local, pois o gerente precisa raciocinar sobre quem faz o quê: comece sempre pelo modo sequencial.

#Pré-requisitos e escolha dos modelos

Ollama funcional

Daemon iniciado, endpoint em http://localhost:11434. Verifique com « ollama list » se pelo menos um modelo capaz de usar ferramentas está presente.

Python 3.10+ e um venv

O CrewAI pode ser instalado de forma adequada em um ambiente virtual isolado. Evite instalá-lo no Python do sistema.

VRAM e paciência

O sistema multiagente encadeia chamadas: cada tarefa = uma ou várias idas e voltas ao modelo. Considere um modelo de no mínimo 8B, idealmente na faixa de 12 a 24B, para que o raciocínio se sustente.

Um modelo capaz de usar ferramentas

Para equipar os agentes com ferramentas, é necessário um modelo que suporte chamadas de função: Qwen 3.5, Qwen 3.8, Mistral Small ou GLM 4.7 Flash. Um modelo sem suporte ao uso de ferramentas só pode raciocinar em texto.

#Instalar o CrewAI e conectá-lo ao Ollama

O CrewAI pode ser instalado via pip. O pacote crewai-tools também fornece uma biblioteca de ferramentas prontas para uso (pesquisa, arquivos, scraping).

# Créer et activer un environnement virtuel
python -m venv .venv
source .venv/bin/activate   # Windows : .venv\Scripts\activate

# Installer CrewAI et sa bibliothèque d'outils
pip install crewai crewai-tools

O ponto-chave da conexão local: o CrewAI usa o LiteLLM para se comunicar com os modelos. Para usar o Ollama, adicione o prefixo “ollama/” ao nome do modelo e configure a URL base para apontar para o daemon local. Certifique-se de ter baixado o modelo previamente.

# Un modèle solide et tool-capable pour les agents
ollama pull qwen3.5:9b

# Un modèle plus léger pour les tâches simples (optionnel)
ollama pull qwen3.5:4b

from crewai import LLM

# Un LLM CrewAI branché sur Ollama en local
local_llm = LLM(
    model="ollama/qwen3.5:9b",
    base_url="http://localhost:11434",
    temperature=0.3,   # bas = plus déterministe, utile pour une crew
)

#Primeira equipe: definir funções e tarefas

Vamos montar uma equipe clássica e imediatamente útil: um pesquisador que reúne as informações, seguido por um redator que as organiza. Essa é a estrutura que reutilizamos para o monitoramento de informações, a síntese documental ou a geração de conteúdo. Primeiro, definimos os agentes, com papéis claros.

from crewai import Agent

chercheur = Agent(
    role="Analyste de recherche",
    goal="Rassembler des faits précis et vérifiables sur {sujet}",
    backstory=(
        "Tu es un analyste rigoureux. Tu distingues les faits "
        "des opinions et tu ne retiens que l'information solide."
    ),
    llm=local_llm,
    verbose=True,
)

redacteur = Agent(
    role="Rédacteur technique francophone",
    goal="Produire une synthèse claire et structurée en français",
    backstory=(
        "Tu écris pour un public technique. Tu vas droit au but, "
        "sans jargon inutile ni remplissage marketing."
    ),
    llm=local_llm,
    verbose=True,
)

O papel, o objetivo e a história de fundo não são decorativos: eles constituem o prompt de sistema de cada agente. Um papel vago (« Assistente ») gera um agente vago. Seja específico e defina uma postura — é isso que impede um modelo pequeno de sair dos limites definidos. Observe o placeholder {sujet}: o CrewAI o injeta na inicialização a partir dos inputs.

Em seguida vem o cerne do trabalho: as tarefas. Cada tarefa indica um agente, descreve o que ele deve produzir e, sobretudo, especifica um expected_output. Esse campo é o recurso mais subestimado do CrewAI para melhorar a qualidade: quanto mais concreto ele for, mais bem definido será o resultado.

from crewai import Task

tache_recherche = Task(
    description=(
        "Recherche les points clés sur {sujet}. Identifie 5 à 7 "
        "faits marquants, chiffrés quand c'est possible."
    ),
    expected_output="Une liste à puces de 5 à 7 faits sourcés et concis.",
    agent=chercheur,
)

tache_redaction = Task(
    description=(
        "À partir des faits rassemblés, rédige une synthèse "
        "structurée de 300 mots sur {sujet}, en français."
    ),
    expected_output="Un texte de ~300 mots avec un titre et 3 sections.",
    agent=redacteur,
    context=[tache_recherche],   # nourrie par la sortie de la recherche
)

O parâmetro context vincula explicitamente as tarefas: a redação recebe a saída da pesquisa. No modo sequencial, o encadeamento já é implícito, mas declarar context torna a dependência clara e a transferência de informações mais confiável. Por fim, montamos a crew e a executamos.

from crewai import Crew, Process

crew = Crew(
    agents=[chercheur, redacteur],
    tasks=[tache_recherche, tache_redaction],
    process=Process.sequential,
    verbose=True,
)

resultat = crew.kickoff(inputs={"sujet": "les LLM open-weight en 2026"})
print(resultat)

1. 01
   O pesquisador é executado

   O LLM local recebe sua função e a descrição da tarefa de pesquisa e produz a lista de fatos esperada.
2. 02
   O resultado é repassado

   O CrewAI passa o resultado da pesquisa como contexto para a tarefa de redação, de acordo com o campo context.
3. 03
   O redator executa a tarefa.

   Seu agente recebe os fatos e redige a síntese de 300 palavras, delimitada pelo seu expected_output.
4. 04
   kickoff() retorna o resultado final

   A saída da última tarefa é retornada. verbose=True exibe todo o raciocínio intermediário no terminal.

#Dar ferramentas aos agentes

Um agente sem ferramentas apenas raciocina sobre o que o modelo já tem na memória — logo encontra limitações e fica sujeito a alucinações. As ferramentas dão a ele capacidades concretas: ler um arquivo, buscar na web, consultar uma base de dados. O crewai-tools oferece uma série de ferramentas prontas para uso, e você pode escrever as suas próprias.

from crewai_tools import FileReadTool
from crewai.tools import tool

# Outil intégré : lire un fichier local
lecteur = FileReadTool()

# Outil maison : décoré avec @tool
@tool("Compteur de mots")
def compter_mots(texte: str) -> int:
    """Compte le nombre de mots d'un texte donné."""
    return len(texte.split())

# On équipe l'agent des deux outils
chercheur = Agent(
    role="Analyste de recherche",
    goal="Analyser des documents locaux sur {sujet}",
    backstory="Tu analyses des sources internes avec rigueur.",
    tools=[lecteur, compter_mots],
    llm=local_llm,
    verbose=True,
)

É aqui que a escolha do modelo se torna decisiva. Para usar uma ferramenta, o agente precisa gerar uma chamada de função estruturada (function calling), que o CrewAI intercepta e executa. Um modelo que não domina o uso de ferramentas ignorará a ferramenta ou produzirá um JSON inválido. Qwen 3.5, Qwen 3.8, Mistral Small e GLM 4.7 Flash lidam bem com esse mecanismo; muitos modelos genéricos pequenos, não.

#Quais modelos locais dão conta de sistemas multiagentes

Essa é a verdadeira questão deste guia. O uso de múltiplos agentes é muito mais exigente que o chat: cada agente deve seguir um papel, respeitar um formato de saída e, muitas vezes, chamar ferramentas — tudo isso encadeando tarefas sem perder o fio. Um modelo pequeno demais perde o fio. Aqui estão os níveis realistas, em Q4_K_M, com a VRAM associada.

8B (≈5-7 GB) — piso

Granite 4.2 8B (5,3 GB), Qwen 3.5 9B (6,6 GB). Suportam uma equipe simples de 2 agentes que atuam sequencialmente, com ferramentas básicas. RTX 3060 12 GB, RTX 4070. Abaixo desse tamanho, o uso de múltiplos agentes torna-se arriscado.

16 GB (≈14 GB) — recomendado

gpt-oss 20B ou Mistral Small 24B (≈14 GB, este último muito bom em francês), ou Qwen 3.5 9B em Q8 (11 GB). Um bom equilíbrio: raciocínio sólido, uso confiável de ferramentas, segue os papéis sem se desviar. Da RTX 4070 de 12 GB (no limite) à RTX 4080 de 16 GB. É o ponto de equilíbrio para a maioria das equipes.

24 GB (≈18–19 GB) — conforto

Qwen 3.8 27B (18 GB, 262k ctx) ou o MoE Qwen3-Coder 30B-A3B (19 GB). Suporta crews mais longas, múltiplas ferramentas e um modo hierárquico leve. RTX 4090 de 24 GB ou Mac M4 Pro com memória unificada. Lembre-se de definir o nível de raciocínio do Qwen 3.8 como “low”; caso contrário, ele raciocina demais em uma crew.

MoE 35B+ (≈23-32 GB) — próximo da qualidade dos modelos em nuvem

Qwen 3.6 35B-A3B (23 GB) ou Qwen3-Coder 30B-A3B em Q8 (32 GB). A qualidade de coordenação se aproxima da oferecida pelas APIs de nuvem, agora alcançável a partir de 32 GB graças às arquiteturas MoE. Mac Studio com muita memória unificada ou configuração multi-GPU. Reservado para equipes ambiciosas.

Dica de arquitetura: nada obriga todos os agentes a compartilhar o mesmo modelo. Atribua as tarefas simples (reformulação, contagem, extração) a um modelo pequeno e rápido (Qwen 3.5 4B, Granite 4.2 8B) e reserve um Qwen 3.8 27B ou um MoE 35B para os agentes que raciocinam ou orquestram. Basta instanciar dois objetos LLM e atribuí-los por agente.

gros = LLM(model="ollama/qwen3.8:27b", base_url="http://localhost:11434")
petit = LLM(model="ollama/granite4.2:8b", base_url="http://localhost:11434")

stratege = Agent(role="Stratège", goal="...", llm=gros)
assistant = Agent(role="Assistant", goal="...", llm=petit)

#Custos e limitações em comparação com uma equipe de agentes que usa uma API de nuvem

O grande argumento a favor da execução local é o custo. Uma equipe de agentes é naturalmente falante: cada agente relê o contexto, raciocina, chama ferramentas, e a expansão do contexto ao longo das tarefas aumenta o número de tokens. Uma única execução um pouco ambiciosa pode consumir centenas de milhares de tokens. Com uma API cobrada por token, um pipeline executado em loop durante o desenvolvimento logo pesa no bolso; localmente, cada iteração é gratuita após a compra do hardware.

Custo — vantagem local

Custo zero por token. Você itera, executa novamente e depura sem um contador de custos rodando. O uso de múltiplos agentes, que consome muitos tokens, é aquele em que a execução local compensa mais rapidamente o investimento na GPU.

Confidencialidade — vantagem local

Nenhuma das chamadas — e elas são muitas — sai da máquina. Decisivo para código proprietário, dados de clientes ou qualquer coisa sujeita a NDA ou RGPD.

Qualidade de coordenação — vantagem da nuvem

GPT-4 e Claude gerenciam o modo hierárquico, as cadeias longas e o uso complexo de ferramentas com uma confiabilidade que um modelo local de 14B não alcança. A diferença se acentua quando a equipe se torna mais complexa.

Velocidade — depende do hardware

A nuvem costuma responder mais rápido que uma GPU voltada ao consumidor em modelos grandes. Uma equipe de 4 agentes usando um modelo 32B local pode levar vários minutos por execução.

Uma avaliação honesta: a execução local se destaca em equipes sequenciais bem estruturadas, nas quais cada agente tem um papel claro e uma tarefa delimitada. Ela mostra seus limites em orquestrações hierárquicas ambiciosas, nas quais um modelo de 14B tem dificuldade para atuar como gerente que delega. A melhor estratégia costuma ser híbrida — prototipar e executar localmente, reservar a nuvem para as etapas em que a coordenação ultrapassa o que seu modelo consegue suportar. Um proxy como o LiteLLM permite justamente rotear entre os dois.

#Solução de problemas

O agente ignora suas ferramentas

O modelo não oferece function calling. Mude para Qwen 3.5, Qwen 3.8, Mistral Small ou GLM 4.7 Flash, e verifique se o agente tem a lista tools=[...].

« Connection refused » / erro litellm

O daemon Ollama não está em execução ou a base_url está incorreta. Verifique « ollama ps » e se a URL é http://localhost:11434.

O agente entra em loop ou não para

Modelo pequeno demais para a tarefa ou excesso de ferramentas. Aumente o tamanho (Qwen 3.5 9B, no mínimo), reduza o número de ferramentas, diminua a temperatura e defina max_iter no agente.

Saídas fora do formato / expected_output ignorado

Papel muito vago ou expected_output pouco claro. Torne ambos bem concretos e prefira um modelo mais capaz (Qwen 3.8 27B, Mistral Small 24B) que siga melhor as instruções de formato.

Crew muito lenta

O modelo é parcialmente transferido para a RAM e executado na CPU por falta de VRAM (o comando 'ollama ps' mostra isso), ou vários modelos provocam o descarregamento uns dos outros. Escolha um modelo de tamanho imediatamente menor ou padronize o uso de um único modelo.

O modo hierárquico sai dos trilhos

O LLM que atua como gerente não dá conta da tarefa. Volte para Process.sequential ou reserve um Qwen 3.8 27B ou um MoE 35B para o papel de gerente.

#Para se aprofundar

Uma equipe CrewAI local se apoia em componentes já abordados no site. Estes guias complementam este guia:

Criar um agente de IA local em Python com LangChain e Ollama

Os fundamentos do agente único — ferramentas, loop de raciocínio — antes de passar para multiagentes.

Function calling e saídas JSON estruturadas com Ollama

Para entender o mecanismo de uso de ferramentas do qual dependem as ferramentas dos seus agentes.

LiteLLM: um proxy unificado local e em nuvem

Para rotear uma equipe entre o Ollama local e uma API na nuvem de acordo com a tarefa, em uma estratégia híbrida.