Atualizando o CrewAI

Visão Geral

Os lançamentos do CrewAI trazem novos recursos regularmente. Este guia mostra os passos práticos para manter sua instalação atualizada — tanto a CLI quanto o ambiente virtual do seu projeto.

Se você está começando do zero, veja Instalação. Se está vindo de outro framework, veja Migrando do LangGraph.

As Duas Coisas Que Você Pode Querer Atualizar

O CrewAI vive em dois lugares na sua máquina, e cada um se atualiza de forma independente:

O quê	Como é instalado	Como atualizar
A CLI global `crewai`	`uv tool install crewai`	`uv tool install crewai --upgrade`
O venv do projeto (onde seu código roda)	`crewai install` / `uv sync`	`uv add "crewai[...]>=X.Y.Z"` e depois `crewai install`

Esses dois podem — e frequentemente ficam — fora de sincronia. Rodar crewai --version mostra a versão da CLI. Rodar uv pip show crewai dentro do seu projeto mostra a versão do venv. Se forem diferentes, isso é normal; o que importa para o código em execução é a versão do venv.

Por Que `crewai install` Sozinho Não Atualiza

crewai install é um wrapper fino em torno de uv sync. Ele instala exatamente o que o arquivo uv.lock atual diz — ele não muda nenhuma restrição de versão.

Se seu pyproject.toml diz crewai>=1.11.1 e o lock file resolveu para 1.11.1, executar crewai install vai te manter em 1.11.1 para sempre, mesmo que 1.14.4 esteja disponível.

Para realmente atualizar, você precisa:

Atualizar a restrição de versão em pyproject.toml
Re-resolver o lock file
Sincronizar o venv

uv add faz os três de uma vez só.

Como Atualizar Seu Projeto

# Aumenta a restrição e re-resolve o lock em um único comando
uv add "crewai[tools]>=1.14.4"

# Sincroniza o venv (crewai install chama uv sync por baixo dos panos)
crewai install

# Verifica
uv pip show crewai
# → Version: 1.14.4

Substitua [tools] por quaisquer extras que seu projeto utilize (ex.: [tools,anthropic]). Verifique a lista de dependencies do seu pyproject.toml se estiver em dúvida.

Atualizando a CLI Global

A CLI global é separada do seu projeto. Atualize com:

uv tool install crewai --upgrade

Se seu shell avisar sobre o PATH após a atualização, recarregue-o:

uv tool update-shell

Isso não mexe no venv do seu projeto — você ainda precisa de uv add + crewai install dentro do projeto.

Verifique Se Ambos Estão em Sincronia

# Versão da CLI global
crewai --version

# Versão do venv do projeto
uv pip show crewai | grep Version

Eles não precisam coincidir — mas a versão do venv do projeto é o que importa para o comportamento em runtime.

Breaking Changes e Notas de Migração

A maioria das atualizações requer apenas pequenos ajustes. As áreas abaixo são as que quebram silenciosamente ou com tracebacks confusos.

Caminhos de import: tools e `BaseTool`

O caminho canônico para tools é crewai.tools. Caminhos antigos ainda aparecem em tutoriais, mas devem ser atualizados.

# Antes
from crewai_tools import BaseTool
from crewai.agents.tools import tool

# Depois
from crewai.tools import BaseTool, tool

O decorador @tool e a subclasse BaseTool ambos vivem em crewai.tools. AgentFinish e outros símbolos internos do agente não fazem mais parte da superfície pública — se você os estava importando, mude para event listeners ou callbacks de Task.

Mudanças de parâmetros em `Agent`

from crewai import Agent

agent = Agent(
    role="Researcher",
    goal="Find authoritative sources on {topic}",
    backstory="You are a careful, source-driven researcher.",
    llm="gpt-4o-mini",   # nome do modelo como string OU um objeto LLM
    verbose=True,        # bool, não um nível inteiro
    max_iter=15,         # default mudou entre versões — defina explicitamente
    allow_delegation=False,
)

llm aceita tanto um nome de modelo como string (resolvido pelo provedor configurado) quanto um objeto LLM para controle granular.
verbose é um bool puro. Passar um inteiro não alterna mais níveis de log.
Os defaults de max_iter mudaram entre releases. Se seu agente para silenciosamente de iterar após a primeira chamada de tool, defina max_iter explicitamente.

Parâmetros de `Crew`

from crewai import Crew, Process

crew = Crew(
    agents=[...],
    tasks=[...],
    process=Process.sequential,   # ou Process.hierarchical
    memory=True,
    cache=True,
    embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}},
)

process=Process.hierarchical requer ou manager_llm= ou manager_agent=. Sem um deles, o kickoff lança erro na validação.
memory=True com um provedor de embedding não-default precisa de um dicionário embedder — veja Configuração de memória e embedder abaixo.

Saída estruturada de `Task`

Use output_pydantic, output_json ou output_file para forçar o resultado de uma task em um formato tipado:

from pydantic import BaseModel
from crewai import Task

class Article(BaseModel):
    title: str
    body: str

write = Task(
    description="Write an article about {topic}",
    expected_output="A short article with a title and body",
    agent=writer,
    output_pydantic=Article,        # a classe, NÃO uma instância
    output_file="output/article.md",
)

output_pydantic recebe a classe em si. Passar Article(title="", body="") é um erro comum e falha com um erro de validação confuso.

Configuração de memória e embedder

Se memory=True e você não está usando os embeddings padrão da OpenAI, é preciso passar um embedder:

crew = Crew(
    agents=[...],
    tasks=[...],
    memory=True,
    embedder={
        "provider": "ollama",
        "config": {"model": "nomic-embed-text"},
    },
)

Defina as credenciais do provedor relevante (OPENAI_API_KEY, OLLAMA_HOST, etc.) no seu arquivo .env. Os caminhos de armazenamento de memória são locais ao projeto por default — apague o diretório de memória do projeto se trocar de embedder, já que dimensões diferentes não se misturam.