O CrewAI passou de mais um projeto de nicho para um dos frameworks mais usados para orquestrar equipas de agentes de IA. Com a versão 1.15.18 (lançada a 27 de agosto de 2026), o projeto acumula cerca de 57.217 estrelas no GitHub, ultrapassando o LangGraph nesse indicador e aproximando-se do AutoGen, segundo uma comparação publicada em agosto de 2026. Neste tutorial, vamos instalar o CrewAI, construir uma equipa de agentes funcional do zero e publicar um projeto completo pronto a correr, com código real testado passo a passo.
Ao contrário de frameworks baseados em grafos de estados, o CrewAI assenta numa metáfora simples: uma equipa (crew) de agentes, cada um com um papel definido, executa tarefas (tasks) segundo um processo (sequencial ou hierárquico). Essa abstração de alto nível é o que tem atraído programadores que acham o LangGraph demasiado verboso para tarefas do dia a dia. Vamos ver exatamente como isso funciona na prática, com prós, contras e armadilhas comuns.
O que é o CrewAI e porque está a ganhar tração em 2026
O CrewAI é uma framework Python de código aberto para construir sistemas multiagente. Em vez de escrever um único prompt gigante que tenta fazer tudo, divide-se o problema em papéis especializados: um agente pesquisa, outro escreve, um terceiro revê. Cada agente tem uma personalidade definida por três campos: role (papel), goal (objetivo) e backstory (história de fundo), que moldam o comportamento do modelo de linguagem subjacente.
A documentação oficial resume bem a proposta: “Build collaborative AI agents, crews, and flows – production ready from day one”. Também descreve as capacidades centrais como: “Design agents, orchestrate crews, and automate flows with guardrails, memory, knowledge, and observability baked in”. Esta ênfase em observabilidade e guardrails de origem é relevante: muitos projetos de agentes falham em produção não por o modelo ser mau, mas por faltar visibilidade sobre o que cada agente decidiu fazer.
Comparado com o LangGraph, que exige desenhar explicitamente um grafo de estados com nós e arestas, o CrewAI oferece um ponto de entrada mais direto. Isto não significa que seja sempre a escolha certa (voltamos a essa comparação mais à frente), mas explica por que motivo tantos tutoriais recentes recorrem a ele para protótipos rápidos de automação com múltiplos agentes.
Pré-requisitos e versões necessárias
Antes de instalar, confirme que o seu ambiente cumpre estes requisitos. A documentação oficial é explícita: “CrewAI requires Python >=3.10 and <3.14", ou seja, precisa de Python 3.10, 3.11, 3.12 ou 3.13 (o 3.14 ainda não é suportado).
- Python 3.10 a 3.13 instalado (verifique com
python3 --version) - pip atualizado para a versão mais recente
- Uma chave de API de pelo menos um fornecedor de LLM: OpenAI, Anthropic (Claude), Google Gemini, Groq ou um modelo local via Ollama
- Terminal Linux, macOS ou Windows com WSL2
- Pelo menos 2 GB de RAM livre para o ambiente virtual e dependências
- Ligação à internet estável (as chamadas a modelos remotos são feitas via HTTPS)
- Editor de código com suporte a Python (VS Code, PyCharm ou equivalente)
Não é preciso experiência prévia com frameworks de agentes, mas ajuda perceber os fundamentos de uma API de LLM. Se nunca usou a API da Anthropic ou da OpenAI diretamente, vale a pena rever primeiro o nosso guia prático da Claude API, já que vamos reutilizar esses conceitos de autenticação por chave.
Passo 1: Criar o ambiente virtual e instalar o CrewAI
Comece por isolar o projeto num ambiente virtual, para não conflituar com outras bibliotecas Python que já tenha instaladas. Abra o terminal e execute:
python3 -m venv crewai-tutorial
source crewai-tutorial/bin/activate # Linux/macOS
# crewai-tutorial\Scripts\activate # Windows
pip3 install --upgrade pip
pip3 install crewai crewai-toolsO pacote crewai-tools traz ferramentas prontas a usar (pesquisa web, leitura de ficheiros, scraping) que os agentes podem invocar. A instalação demora normalmente entre um e três minutos, dependendo da ligação, porque arrasta dependências como o LiteLLM, o Pydantic e bibliotecas de tokenização.
Para confirmar que tudo ficou instalado corretamente:
python3 -c "import crewai; print(crewai.__version__)"Resultado esperado (a versão pode variar consoante a data de instalação):
1.15.18Se preferir gerir dependências com uv em vez de pip, o CrewAI também suporta extras específicos por fornecedor, por exemplo uv add "crewai[openai]" para trazer apenas as dependências da OpenAI.
Passo 2: Configurar as chaves de API
O CrewAI liga-se a praticamente qualquer fornecedor de LLM através do LiteLLM e de SDKs nativos, incluindo OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, Groq, Cohere, Mistral AI e modelos locais via Ollama. Para este tutorial vamos usar duas opções em paralelo: um modelo cloud (para qualidade) e o Ollama (para correr sem custos, caso já tenha seguido o nosso guia de instalação do Ollama).
Crie um ficheiro .env na raiz do projeto:
# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
SERPER_API_KEY=...Nunca faça commit deste ficheiro para um repositório público. Adicione .env ao .gitignore antes do primeiro commit. Para carregar as variáveis de ambiente, instale a biblioteca auxiliar:
pip3 install python-dotenvNos exemplos de código de configuração da própria documentação, os modelos referenciados incluem gpt-4o e gpt-4o-mini para OpenAI, claude-3-5-sonnet-20240620 para Anthropic, e gemini-2.0-flash ou gemini-1.5-pro para Google. Para modelos locais, o prefixo é ollama/, como em ollama/llama3.1.
Passo 3: Perceber os quatro conceitos-chave: Agent, Task, Crew e Process
Antes de escrever código, vale a pena fixar o vocabulário do CrewAI, porque é diferente do LangGraph e do AutoGen:
- Agent – uma entidade autónoma com papel, objetivo e história de fundo, normalmente associada a um LLM e a um conjunto de ferramentas.
- Task – uma unidade de trabalho concreta, com descrição, resultado esperado e o agente responsável por a executar.
- Crew – a equipa completa: o conjunto de agentes que colaboram para resolver um problema maior que nenhum deles resolveria sozinho.
- Process – a forma como as tarefas são executadas: sequencial (uma a seguir à outra, passando contexto), hierárquico (um agente gestor distribui subtarefas) ou, em cenários mais avançados, por consenso.
A documentação da AWS resume bem esta filosofia: “CrewAI provides a role-based implementation of teams of AI agents approach for business stakeholders”. E acrescenta que a framework permite “define specialized autonomous agents with specific roles, goals, and expertise areas”. Na prática, isto significa pensar no problema como pensaria ao montar uma equipa humana: quem pesquisa, quem escreve, quem revê.
Passo 4: Criar a estrutura do projeto
Vamos construir um projeto completo: uma equipa de três agentes que pesquisa um tema, escreve um rascunho e depois revê o texto antes de o entregar. Crie a seguinte estrutura de pastas:
crewai-tutorial/
├── .env
├── main.py
├── agents.py
├── tasks.py
└── requirements.txtNo ficheiro requirements.txt, registe as dependências para que o projeto seja reprodutível noutra máquina:
crewai>=1.15.18
crewai-tools>=0.1.0
python-dotenv>=1.0.0Passo 5: Definir os agentes
Crie o ficheiro agents.py. Vamos definir três agentes: um investigador, um redator e um revisor. Cada um recebe um papel, um objetivo claro e uma história de fundo que ajuda o modelo a manter-se coerente com o tom pretendido.
from crewai import Agent
from crewai_tools import SerperDevTool
search_tool = SerperDevTool()
investigador = Agent(
role="Investigador Sénior de Tecnologia",
goal="Reunir factos atuais e verificáveis sobre o tema pedido",
backstory=(
"Trabalhaste 10 anos como jornalista de tecnologia. "
"Só aceitas factos com fonte identificável e datas concretas."
),
tools=[search_tool],
verbose=True,
allow_delegation=False,
)
redator = Agent(
role="Redator Técnico",
goal="Transformar os factos recolhidos num texto claro e bem estruturado",
backstory=(
"Escreves para leitores técnicos que querem respostas diretas, "
"sem palha nem adjetivos vazios."
),
verbose=True,
allow_delegation=False,
)
revisor = Agent(
role="Editor de Qualidade",
goal="Verificar factos, cortar redundâncias e garantir consistência",
backstory=(
"Já rejeitaste centenas de rascunhos por falta de rigor. "
"Não deixas passar afirmações sem suporte."
),
verbose=True,
allow_delegation=False,
)Note o parâmetro allow_delegation=False. Por omissão, alguns agentes podem delegar tarefas uns aos outros, o que é útil em processos hierárquicos mas pode gerar ciclos difíceis de depurar em protótipos simples. Desative a delegação até perceber bem o comportamento do seu processo sequencial.
Passo 6: Definir as tarefas
Crie o ficheiro tasks.py. Cada tarefa liga-se a um agente e descreve claramente o que se espera como resultado (expected_output). Este campo é mais importante do que parece: é a principal forma de controlar a qualidade da saída sem escrever código adicional.
from crewai import Task
from agents import investigador, redator, revisor
def criar_tarefas(tema: str):
pesquisar = Task(
description=f"Pesquisa factos atuais e verificáveis sobre: {tema}",
expected_output="Lista de 8 a 10 factos, cada um com fonte e data",
agent=investigador,
)
escrever = Task(
description=f"Escreve um artigo de 400 palavras sobre {tema} usando os factos pesquisados",
expected_output="Artigo em Markdown com título e 3 secções",
agent=redator,
context=[pesquisar],
)
rever = Task(
description="Revê o artigo, corrige erros e remove afirmações sem fonte",
expected_output="Versão final do artigo, pronta a publicar",
agent=revisor,
context=[escrever],
)
return [pesquisar, escrever, rever]O parâmetro context é o que substitui, num processo sequencial, a gestão manual de estado que o LangGraph exige através de um grafo explícito. Ao passar context=[pesquisar], a tarefa de escrita recebe automaticamente o resultado da tarefa de pesquisa.
Passo 7: Montar a Crew e executar
Agora junte tudo no ficheiro main.py:
from dotenv import load_dotenv
from crewai import Crew, Process
from agents import investigador, redator, revisor
from tasks import criar_tarefas
load_dotenv()
tema = "impacto dos modelos de raciocínio na cibersegurança em 2026"
tarefas = criar_tarefas(tema)
equipa = Crew(
agents=[investigador, redator, revisor],
tasks=tarefas,
process=Process.sequential,
verbose=True,
)
resultado = equipa.kickoff()
print("\n--- RESULTADO FINAL ---\n")
print(resultado)Execute com:
python3 main.pyVai ver no terminal, em tempo real (graças a verbose=True), cada agente a “pensar” em voz alta: que ferramenta está a invocar, que resultado obteve e como o está a passar ao agente seguinte. Isto é essencial para depurar por que motivo um agente falhou ou produziu algo fora do esperado.
Passo 8: Trocar de processo sequencial para hierárquico
O processo sequencial funciona bem para fluxos lineares, mas em tarefas mais complexas (por exemplo, quando não sabe de antemão quantas subtarefas serão necessárias) o processo hierárquico é mais flexível. Um agente gestor decompõe o pedido original em subtarefas e distribui-as pelos restantes agentes.
from crewai import Crew, Process
equipa_hierarquica = Crew(
agents=[investigador, redator, revisor],
tasks=tarefas,
process=Process.hierarchical,
manager_llm="gpt-4o",
verbose=True,
)
resultado = equipa_hierarquica.kickoff()Repare no parâmetro manager_llm: no modo hierárquico é obrigatório indicar qual o modelo que vai atuar como gestor, já que este tem de tomar decisões de distribuição de trabalho que não fazem parte de nenhuma das tarefas definidas explicitamente.
Passo 9: Adicionar ferramentas personalizadas aos agentes
Além das ferramentas prontas do pacote crewai-tools, pode criar as suas próprias, por exemplo para consultar uma base de dados interna ou chamar uma API específica da sua empresa:
from crewai.tools import BaseTool
class VerificadorDePrecoTool(BaseTool):
name: str = "Verificador de Preço"
description: str = "Consulta o preço atual de um produto pelo SKU"
def _run(self, sku: str) -> str:
# Substitua por uma chamada real à sua API ou base de dados
precos = {"SKU123": "29,99€", "SKU456": "49,99€"}
return precos.get(sku, "SKU não encontrado")
investigador.tools.append(VerificadorDePrecoTool())Esta é a forma mais comum de ligar o CrewAI a sistemas internos: em vez de o LLM “inventar” dados, a ferramenta força uma chamada determinística a uma fonte real, reduzindo alucinações em respostas que dependem de dados factuais e atualizados.
Passo 10: Usar Flows para controlo de fluxo orientado a eventos
As Flows foram introduzidas para dar ao CrewAI um controlo de fluxo mais próximo do que o LangGraph oferece com o seu grafo de estados, mas mantendo a sintaxe declarativa por decoradores. Uma comparação de ecossistema publicada em agosto de 2026 descreve as Flows como a resposta do CrewAI ao controlo por grafo ao estilo LangGraph, usando decoradores como @start, @listen e @router para definir um controlo explícito e determinístico.
from crewai.flow.flow import Flow, start, listen, router
class FluxoDePublicacao(Flow):
@start()
def gerar_rascunho(self):
resultado = equipa.kickoff()
self.state["rascunho"] = str(resultado)
return resultado
@listen(gerar_rascunho)
def validar_tamanho(self, rascunho):
if len(rascunho) < 300:
return "curto"
return "ok"
@router(validar_tamanho)
def decidir_proximo_passo(self, estado):
if estado == "curto":
return "reescrever"
return "publicar"
fluxo = FluxoDePublicacao()
fluxo.kickoff()Use Flows quando precisar de decisões condicionais entre execuções de crews (por exemplo, "se o rascunho for demasiado curto, volta a pedir à equipa"), e mantenha o processo sequencial simples nos restantes casos. Misturar as duas abordagens sem necessidade só torna o código mais difícil de seguir.
Passo 11: Testar com um modelo local via Ollama para reduzir custos
Durante o desenvolvimento, cada execução de teste consome créditos de API. Uma forma de baixar custos é apontar os agentes para um modelo local via Ollama enquanto valida a lógica, reservando os modelos cloud para a versão final:
from crewai import Agent, LLM
modelo_local = LLM(
model="ollama/llama3.1",
base_url="http://localhost:11434",
)
investigador_local = Agent(
role="Investigador Sénior de Tecnologia",
goal="Reunir factos atuais sobre o tema pedido",
backstory="Testas a lógica da equipa sem gastar créditos de API.",
llm=modelo_local,
verbose=True,
)Isto exige, obviamente, ter o Ollama já instalado e o modelo llama3.1 descarregado com ollama pull llama3.1. Os resultados com modelos locais tendem a ser menos consistentes do que com modelos cloud maiores, por isso use esta abordagem só para depurar a estrutura da equipa, não para validar a qualidade final do texto.
Passo 12: Exportar e reutilizar a configuração em YAML
Para projetos maiores, escrever cada agente e tarefa diretamente em Python torna-se difícil de manter. O CrewAI suporta configuração declarativa via YAML, separando a definição da lógica de execução:
# config/agents.yaml
investigador:
role: "Investigador Sénior de Tecnologia"
goal: "Reunir factos atuais e verificáveis sobre o tema pedido"
backstory: "Trabalhaste 10 anos como jornalista de tecnologia."
redator:
role: "Redator Técnico"
goal: "Transformar os factos recolhidos num texto claro"
backstory: "Escreves para leitores técnicos que querem respostas diretas."Esta separação facilita a colaboração entre quem define o comportamento dos agentes (frequentemente alguém sem perfil de engenharia) e quem escreve a lógica de orquestração em Python.
Passo 13: Adicionar memória entre execuções
Por omissão, cada chamada a kickoff() começa do zero, sem memória do que aconteceu em execuções anteriores. Isto é adequado para tarefas isoladas, mas torna-se um problema em assistentes que devem lembrar-se de interações passadas com o mesmo utilizador ou projeto. O CrewAI resolve isto com três tipos de memória que pode ativar de forma independente.
- Memória de curto prazo – guarda o contexto da execução atual, partilhado entre agentes durante um único
kickoff(). - Memória de longo prazo – persiste entre execuções diferentes, permitindo que a equipa se lembre de decisões tomadas em sessões anteriores.
- Memória de entidades – regista factos específicos sobre pessoas, produtos ou conceitos mencionados ao longo das conversas, útil quando o mesmo nome ou termo aparece em várias tarefas.
Para ativar a memória, basta um parâmetro na definição da Crew:
equipa_com_memoria = Crew(
agents=[investigador, redator, revisor],
tasks=tarefas,
process=Process.sequential,
memory=True,
verbose=True,
)Internamente, a memória de longo prazo é guardada em disco (por omissão numa base de dados SQLite local), pelo que em ambientes de produção com múltiplas instâncias a correr em paralelo deve considerar apontar o armazenamento para uma base de dados partilhada, evitando que cada instância tenha a sua própria "versão da verdade" sobre o histórico do projeto.
Passo 14: Empacotar o projeto com Docker
Para distribuir o projeto de forma reprodutível, ou para o correr num servidor sem instalar Python diretamente na máquina, vale a pena empacotá-lo num contentor Docker. Crie um ficheiro Dockerfile na raiz do projeto:
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip3 install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python3", "main.py"]Construa e execute a imagem, passando as chaves de API como variáveis de ambiente em vez de as copiar para dentro da imagem:
docker build -t crewai-tutorial .
docker run --env-file .env crewai-tutorialUsar python:3.12-slim como imagem base garante compatibilidade com o intervalo de versões exigido pelo CrewAI (3.10 a 3.13), mantendo o tamanho da imagem final reduzido. Evite copiar o ficheiro .env para dentro da imagem com COPY; use sempre --env-file ou variáveis de ambiente injetadas pela plataforma de orquestração (Kubernetes, ECS, etc.) para não deixar chaves de API gravadas na camada da imagem.
CrewAI vs LangGraph vs AutoGen: qual escolher
Esta é provavelmente a pergunta mais comum de quem chega a este tutorial. Não há uma resposta universal, mas os três frameworks têm filosofias claramente distintas, resumidas na tabela abaixo com base numa comparação de ecossistema de agosto de 2026:
| Framework | Estrelas GitHub (ago. 2026) | Modelo central | Gestão de estado |
|---|---|---|---|
| CrewAI | ~57.217 | Crews baseadas em papéis + Flows orientadas a eventos | Pipeline sequencial/hierárquico ou estado gerido por Flow |
| LangGraph | ~39.876 | Grafo dirigido de nós e arestas | Estado tipado explícito, com checkpoints |
| AutoGen | ~60.475 | Agentes conversacionais em grupo | Histórico de conversa em memória |
Na prática: escolha o CrewAI se quer chegar a um protótipo funcional rapidamente e o problema se encaixa bem no modelo "equipa com papéis". Escolha o LangGraph se precisa de controlo fino sobre transições de estado, checkpoints e retomar execuções interrompidas, algo comum em fluxos de produção de longa duração. Escolha o AutoGen se o seu caso de uso é essencialmente uma conversa multiagente livre, sem uma estrutura de tarefas rígida.
Como o CrewAI se liga a diferentes fornecedores de LLM
Uma das razões para a adoção do CrewAI é a flexibilidade na escolha do modelo. Através do LiteLLM e de SDKs nativos, a framework liga-se a mais de uma dezena de fornecedores sem alterar a estrutura do código, bastando trocar o parâmetro llm de cada agente.
| Fornecedor | Variável de ambiente | Exemplo de modelo |
|---|---|---|
| OpenAI | OPENAI_API_KEY | gpt-4o, gpt-4o-mini, o1-mini |
| Anthropic | ANTHROPIC_API_KEY | claude-3-5-sonnet-20240620 |
| Google Gemini | GEMINI_API_KEY | gemini-2.0-flash, gemini-1.5-pro |
| Groq | GROQ_API_KEY | llama-3.1-70b-versatile |
| Ollama (local) | não aplicável | ollama/llama3.1 |
Esta tabela reflete a configuração documentada oficialmente. Para outros fornecedores, como AWS Bedrock, Azure OpenAI ou Snowflake Cortex, existe suporte nativo via extras específicos instalados com uv add "crewai[nome-do-extra]". Se já testou a nossa API da Mistral AI ou o Promptfoo para testar LLMs locais, o processo de configuração de chaves é essencialmente o mesmo.
5 erros comuns ao começar com CrewAI
Depois de configurar várias equipas de agentes, estes são os erros que mais se repetem entre quem está a começar:
- Descrições de tarefa vagas. Escrever "resume isto" em vez de especificar formato, tamanho e critérios de aceitação leva a saídas inconsistentes entre execuções.
- Ativar delegação sem necessidade. Com
allow_delegation=Trueem todos os agentes, é fácil criar ciclos onde um agente delega para outro que delega de volta, consumindo créditos de API sem produzir resultado. - Ignorar o campo
expected_output. É o principal mecanismo de controlo de qualidade e muitos tutoriais saltam-no ou preenchem-no de forma genérica. - Misturar processo sequencial com dependências circulares. Se a tarefa 3 depende do contexto da tarefa 1, mas a tarefa 1 é definida depois da 3 na lista, o CrewAI não vai resolver isso automaticamente.
- Não limitar o número de iterações do agente gestor no modo hierárquico. Sem um limite, um agente gestor mal configurado pode entrar em ciclos de replaneamento que disparam o consumo de tokens.
Resolução de problemas: 8 situações frequentes
Estas são as situações mais reportadas por quem está a configurar o CrewAI pela primeira vez, com a respetiva causa provável e correção:
- Erro "ModuleNotFoundError: No module named 'crewai'" – o ambiente virtual não está ativo. Confirme com
which python3que aponta para dentro da pastacrewai-tutorial. - Erro de autenticação 401 na primeira execução – a variável de ambiente não foi carregada. Confirme que chama
load_dotenv()antes de criar qualquer agente. - Agente fica preso a repetir a mesma ferramenta – normalmente indica que a ferramenta está a devolver um erro em formato de texto que o LLM interpreta como "tenta outra vez". Adicione tratamento de exceções na ferramenta personalizada.
- Resultado final vazio ou truncado – verifique o limite de tokens de saída do modelo escolhido; modelos mais pequenos como o
gpt-4o-minitêm limites mais apertados do que variantes maiores. - Processo hierárquico não distribui tarefas corretamente – confirme que definiu
manager_llm; sem esse parâmetro o processo hierárquico falha silenciosamente ou lança erro na inicialização. - Custos de API acima do esperado – ative
verbose=Truepara inspecionar quantas chamadas cada agente está a fazer; delegação excessiva é a causa mais comum. - Ferramenta personalizada não é chamada pelo agente – confirme que o campo
descriptionda ferramenta explica claramente quando deve ser usada; o LLM decide invocar a ferramenta com base nesse texto. - Erro de versão de Python incompatível – se estiver a correr Python 3.14 ou mais recente, o CrewAI ainda não suporta essa versão; instale uma versão entre 3.10 e 3.13 com
pyenvou similar.
Segurança: cuidados ao dar ferramentas e dados sensíveis aos agentes
Um sistema multiagente com acesso a ferramentas reais (bases de dados, APIs de pagamento, sistemas de ficheiros) introduz uma superfície de ataque diferente da de um chatbot simples. Como o agente decide autonomamente quando invocar cada ferramenta, um prompt malicioso injetado nos dados que o agente processa pode, em teoria, levá-lo a chamar uma ferramenta de forma não pretendida. Isto é conhecido como injeção de prompt indireta, e já abordámos o tema em detalhe no nosso artigo sobre injeção de prompt em sistemas de IA em produção.
Antes de ligar o CrewAI a sistemas com dados reais, aplique estas precauções:
- Nunca dê a um agente uma ferramenta com permissões mais amplas do que as estritamente necessárias. Se o agente só precisa de ler preços, não lhe dê uma ferramenta capaz de escrever na mesma base de dados.
- Trate o conteúdo devolvido por ferramentas de pesquisa web como não confiável. Uma página maliciosa pode conter instruções escondidas dirigidas ao LLM, não ao utilizador humano.
- Valide sempre a saída antes de a usar em ações irreversíveis. Se um agente pode acionar um envio de email ou um pagamento, intercale uma etapa de confirmação humana ou de outro agente crítico antes da execução final.
- Não guarde chaves de API em ficheiros de configuração YAML versionados. Mantenha-as sempre em variáveis de ambiente ou num gestor de segredos dedicado.
- Registe todas as chamadas a ferramentas para auditoria. Em caso de comportamento inesperado, o registo de logs é a única forma prática de perceber que decisão o agente tomou e porquê.
Estas práticas não são exclusivas do CrewAI, aplicam-se a qualquer framework de agentes autónomos, mas tornam-se mais visíveis aqui precisamente porque o CrewAI facilita tanto a criação de agentes com acesso a ferramentas externas.
Dicas avançadas para produção
Depois de validar a lógica localmente, há um conjunto de práticas que separam um protótipo de um sistema fiável em produção:
- Defina limites de custo por execução. Registe o número de tokens consumidos por cada crew e corte a execução se ultrapassar um limite definido, evitando faturas inesperadas.
- Guarde os logs de cada agente. Com
verbose=Trueem desenvolvimento, mas grave a saída em ficheiro estruturado (JSON) em produção para auditoria posterior. - Use memória persistente para conversas longas. O CrewAI suporta memória entre execuções, útil quando a mesma equipa é invocada várias vezes sobre o mesmo contexto de projeto.
- Teste cada agente isoladamente antes de o integrar na crew. Um agente com um prompt mal desenhado é mais fácil de depurar sozinho do que dentro de uma cadeia de três ou quatro agentes.
- Considere um "agente crítico" dedicado. Um agente cuja única função é validar a saída de outro antes de a aceitar reduz significativamente erros que passariam despercebidos num pipeline sequencial simples.
Preços: o CrewAI é gratuito?
A framework Python em si (o pacote crewai instalado via pip) é totalmente gratuita e de código aberto, licenciada para uso irrestrito no seu próprio código. Não há limite de agentes, tarefas ou execuções impostos pela biblioteca.
A empresa por trás do projeto oferece também uma plataforma paga com um construtor visual do tipo "canvas", pensada para equipas que não querem escrever código diretamente. Não existem, à data desta publicação, preços públicos detalhados dessa oferta empresarial, pelo que não deve assumir qualquer valor de assinatura sem confirmar diretamente com a equipa comercial do CrewAI. Os custos reais de qualquer projeto vêm quase sempre do consumo da API do LLM escolhido, não da framework em si.
Projeto completo: assistente de pesquisa e redação em código único
Juntando tudo o que vimos, aqui está a versão final e funcional do projeto, num único ficheiro para facilitar a cópia direta:
import os
from dotenv import load_dotenv
from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool
load_dotenv()
search_tool = SerperDevTool()
investigador = Agent(
role="Investigador Sénior de Tecnologia",
goal="Reunir factos atuais e verificáveis sobre o tema pedido",
backstory="Trabalhaste 10 anos como jornalista de tecnologia.",
tools=[search_tool],
verbose=True,
)
redator = Agent(
role="Redator Técnico",
goal="Transformar os factos recolhidos num texto claro",
backstory="Escreves para leitores técnicos, sem palha.",
verbose=True,
)
revisor = Agent(
role="Editor de Qualidade",
goal="Verificar factos e cortar redundâncias",
backstory="Não deixas passar afirmações sem suporte.",
verbose=True,
)
def montar_crew(tema: str) -> Crew:
pesquisar = Task(
description=f"Pesquisa factos atuais sobre: {tema}",
expected_output="Lista de 8 a 10 factos com fonte e data",
agent=investigador,
)
escrever = Task(
description=f"Escreve um artigo de 400 palavras sobre {tema}",
expected_output="Artigo em Markdown com título e 3 secções",
agent=redator,
context=[pesquisar],
)
rever = Task(
description="Revê o artigo e remove afirmações sem fonte",
expected_output="Versão final pronta a publicar",
agent=revisor,
context=[escrever],
)
return Crew(
agents=[investigador, redator, revisor],
tasks=[pesquisar, escrever, rever],
process=Process.sequential,
verbose=True,
)
if __name__ == "__main__":
tema = "impacto dos modelos de raciocínio na cibersegurança em 2026"
equipa = montar_crew(tema)
resultado = equipa.kickoff()
print("\n--- RESULTADO FINAL ---\n")
print(resultado)Ao correr este ficheiro com python3 main.py, deve ver no terminal três blocos de atividade (um por agente), seguidos do artigo final impresso após a etiqueta "RESULTADO FINAL". Um tempo de execução típico, com modelos cloud rápidos, ronda os 30 a 90 segundos, dependendo da latência da ferramenta de pesquisa e do tamanho do texto pedido.
Onde o CrewAI já está a ser usado
Não há, até ao momento, uma lista pública e verificável de casos de uso empresariais específicos com nomes de empresas associados ao CrewAI em produção. O que existe, de forma consistente entre várias análises de ecossistema de 2026, é uma adoção sustentada na comunidade open source, refletida no crescimento constante de estrelas no GitHub, que passou de cerca de 53 mil em junho para aproximadamente 57 mil em agosto de 2026, um ritmo de crescimento superior ao do LangGraph no mesmo período.
Esse crescimento reflete-se também na oferta educativa: existe um curso dedicado, "Multi AI Agent Systems with CrewAI", disponível na plataforma DeepLearning.AI, o que sugere procura suficiente por parte de programadores para justificar formação estruturada sobre o tema.
Quanto custa realmente correr uma equipa de agentes
A pergunta que mais surge depois de perceber que a framework é gratuita é: quanto vou pagar à OpenAI, Anthropic ou Google por cada execução? A resposta depende de três fatores: o número de agentes, o número de "voltas" que cada agente dá antes de decidir que terminou, e o tamanho do contexto que cada tarefa acumula à medida que avança na cadeia.
Num projeto simples de três agentes como o deste tutorial, uma execução completa (pesquisa, redação e revisão) tipicamente gera entre 6 e 12 chamadas ao LLM, dependendo de quantas vezes o agente investigador precisa de invocar a ferramenta de pesquisa antes de considerar ter recolhido factos suficientes. Cada chamada carrega consigo o histórico acumulado da conversa daquele agente, o que significa que o custo por chamada tende a aumentar ligeiramente ao longo da execução, não a manter-se constante.
Na prática, isto tem duas implicações diretas para quem está a planear um orçamento: primeiro, processos hierárquicos custam sistematicamente mais do que processos sequenciais, porque o agente gestor introduz chamadas adicionais de planeamento que não existem numa cadeia linear. Segundo, cada ferramenta que devolve muito texto (por exemplo, o resultado bruto de uma pesquisa web) infla o contexto de todas as chamadas seguintes desse agente, pelo que vale a pena resumir ou filtrar a saída das ferramentas antes de a devolver ao LLM, em vez de passar o conteúdo integral sem tratamento.
Perguntas frequentes
O CrewAI é gratuito para uso comercial?
Sim, a framework Python é open source e pode ser usada em projetos comerciais sem custo de licenciamento. Os únicos custos são os da API do LLM que escolher usar.
Preciso de saber Python avançado para usar o CrewAI?
Não. Conhecimentos básicos de Python (funções, classes simples, variáveis de ambiente) são suficientes para seguir este tutorial e construir os primeiros projetos.
O CrewAI funciona com modelos totalmente locais, sem internet?
Sim, desde que use o Ollama ou outro servidor de inferência local compatível. Nesse caso, a única ligação de rede necessária é, no máximo, a de ferramentas externas que os agentes invoquem, como pesquisa web.
Qual a diferença prática entre processo sequencial e hierárquico?
No sequencial, a ordem das tarefas é fixa e definida por si. No hierárquico, um agente gestor decide como distribuir o trabalho, o que é mais flexível mas também menos previsível e mais caro em tokens.
Posso combinar CrewAI com LangGraph no mesmo projeto?
Tecnicamente sim, já que ambos são bibliotecas Python independentes, mas raramente compensa a complexidade adicional. É mais comum escolher um dos dois como motor principal de orquestração.
Como controlo os custos de API quando uso vários agentes?
Monitorize o número de chamadas por execução com verbose=True, desative delegação desnecessária e prefira modelos mais pequenos e baratos para tarefas simples, reservando modelos maiores só para as etapas que exigem mais raciocínio.
O que são as Flows e quando devo usá-las?
As Flows são uma camada de controlo orientada a eventos, introduzida para dar mais controlo determinístico sobre a execução de crews. Use-as quando precisar de lógica condicional entre execuções, por exemplo repetir uma tarefa se o resultado não cumprir um critério.
O CrewAI substitui completamente a necessidade de escrever prompts?
Não. Continua a escrever prompts, só que distribuídos por vários campos estruturados (role, goal, backstory, description, expected_output) em vez de um único bloco de texto. A qualidade da engenharia de prompt continua a determinar a qualidade do resultado final.
