Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
docs: add OSS upgrade & crew-to-flow migration guide (#5744)
iris-clawde4a91cdc0c01
diff --git a/docs/ar/guides/migration/upgrading-crewai.mdx b/docs/ar/guides/migration/upgrading-crewai.mdxnew file mode 100644index 000000000..372689335--- /dev/null+++ b/docs/ar/guides/migration/upgrading-crewai.mdx@@ -0,0 +1,190 @@+---+title: "ترقية CrewAI"+description: "كيفية ترقية CrewAI في مشروعك والتكيّف مع التغييرات الجذرية بين الإصدارات."+icon: "arrow-up-circle"+---++## نظرة عامة++تجلب إصدارات CrewAI قدرات جديدة بانتظام. يرشدك هذا الدليل خلال الخطوات العملية للحفاظ على تثبيتك محدّثًا — سواء أداة سطر الأوامر أو البيئة الافتراضية لمشروعك.++إذا كنت تبدأ من الصفر، راجع [التثبيت](/ar/installation). إذا كنت قادمًا من إطار عمل آخر، راجع [الترحيل من LangGraph](/ar/guides/migration/migrating-from-langgraph).++---++## الشيئان اللذان قد ترغب في ترقيتهما++يوجد CrewAI في مكانين على جهازك، ويتم ترقيتهما بشكل مستقل:++| ماذا | كيف يُثبَّت | كيف تتم الترقية |+|---|---|---|+| **أداة سطر الأوامر العامة `crewai`** | `uv tool install crewai` | `uv tool install crewai --upgrade` |+| **بيئة venv للمشروع** (حيث يعمل الكود) | `crewai install` / `uv sync` | `uv add "crewai[...]>=X.Y.Z"` ثم `crewai install` |++يمكن لهما — وغالبًا ما يحدث — أن يخرجا عن التزامن. تشغيل `crewai --version` يُظهر إصدار سطر الأوامر. تشغيل `uv pip show crewai` داخل مشروعك يُظهر إصدار venv. إذا اختلفا، فهذا طبيعي؛ ما يهم بالنسبة للكود قيد التشغيل هو إصدار venv.++## لماذا لا يقوم `crewai install` وحده بالترقية++`crewai install` هو غلاف رفيع حول `uv sync`. يُثبّت بالضبط ما يقوله ملف `uv.lock` الحالي — وهو **لا** يرفع أي قيود إصدار.++إذا كان `pyproject.toml` يقول `crewai>=1.11.1` وقد قام ملف القفل بحلّه إلى `1.11.1`، فإن تشغيل `crewai install` سيُبقيك على `1.11.1` للأبد، حتى وإن كان الإصدار `1.14.4` متاحًا.++للترقية فعلًا، عليك:++1. تحديث قيد الإصدار في `pyproject.toml`+2. إعادة حلّ ملف القفل+3. مزامنة venv++`uv add` يقوم بالثلاثة في خطوة واحدة.++## كيفية ترقية مشروعك++```bash+# يرفع القيد ويعيد القفل في أمر واحد+uv add "crewai[tools]>=1.14.4"++# يزامن venv (crewai install يستدعي uv sync تحت الغطاء)+crewai install++# تحقّق+uv pip show crewai+# → Version: 1.14.4+```++استبدل `[tools]` بأي إضافات يستخدمها مشروعك (مثلًا `[tools,anthropic]`). تحقّق من قائمة `dependencies` في `pyproject.toml` إن لم تكن متأكدًا.++<Note>+ يحدّث `uv add` كلا من `pyproject.toml` **و** `uv.lock` بشكل ذرّي. إذا قمت بتحرير `pyproject.toml` يدويًا، فإنك لا تزال بحاجة إلى تشغيل `uv lock --upgrade-package crewai` لإعادة حلّ ملف القفل قبل أن يلتقط `crewai install` الإصدار الجديد.+</Note>++## ترقية أداة سطر الأوامر العامة++أداة سطر الأوامر العامة منفصلة عن مشروعك. قم بترقيتها عبر:++```bash+uv tool install crewai --upgrade+```++إذا حذّرك الـ shell بشأن `PATH` بعد الترقية، قم بتحديثه:++```bash+uv tool update-shell+```++هذا **لا** يمسّ بيئة venv الخاصة بمشروعك — لا تزال بحاجة إلى `uv add` + `crewai install` داخل المشروع.++## التحقق من تزامن الاثنين++```bash+# إصدار سطر الأوامر العام+crewai --version++# إصدار venv للمشروع+uv pip show crewai | grep Version+```++ليس من الضروري أن يتطابقا — لكن إصدار venv للمشروع هو ما يهم لسلوك التشغيل.++<Note>+ يتطلب CrewAI `Python >=3.10, <3.14`. إذا كان `uv` مثبَّتًا مقابل مفسّر أقدم، فأعد إنشاء venv للمشروع باستخدام إصدار Python مدعوم قبل تشغيل `crewai install`.+</Note>++---++## التغييرات الجذرية وملاحظات الترحيل++تتطلب معظم الترقيات تعديلات صغيرة فقط. المناطق أدناه هي تلك التي تنكسر بصمت أو بتتبعات مكدّس مربكة.++### مسارات الاستيراد: tools و`BaseTool`++الموقع الرسمي لاستيراد الـ tools هو `crewai.tools`. لا تزال المسارات القديمة تظهر في الدروس لكن يجب تحديثها.++```python+# قبل+from crewai_tools import BaseTool+from crewai.agents.tools import tool++# بعد+from crewai.tools import BaseTool, tool+```++كلٌ من المُزخرف `@tool` والفئة الفرعية `BaseTool` يقعان في `crewai.tools`. `AgentFinish` والرموز الأخرى الداخلية للوكيل لم تعد جزءًا من السطح العام — إذا كنت تستوردها، فانتقل إلى event listeners أو callbacks الـ `Task` بدلًا منها.++### تغييرات معاملات `Agent`++```python+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", # اسم نموذج كسلسلة نصية أو كائن LLM+ verbose=True, # bool وليس مستوى عددي صحيح+ max_iter=15, # تغيّر الافتراضي بين الإصدارات — حدّده بشكل صريح+ allow_delegation=False,+)+```++- يقبل `llm` إما اسم نموذج كسلسلة نصية (يُحلَّ عبر المزوّد المهيّأ) أو كائن `LLM` للتحكم الدقيق.+- `verbose` هو `bool` بسيط. تمرير عدد صحيح لم يعد يبدّل مستويات السجل.+- تغيّرت افتراضات `max_iter` بين الإصدارات. إذا توقف وكيلك بصمت عن التكرار بعد أول استدعاء tool، فحدّد `max_iter` صراحةً.++### معاملات `Crew`++```python+from crewai import Crew, Process++crew = Crew(+ agents=[...],+ tasks=[...],+ process=Process.sequential, # أو Process.hierarchical+ memory=True,+ cache=True,+ embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}},+)+```++- يتطلب `process=Process.hierarchical` إما `manager_llm=` أو `manager_agent=`. بدون أحدهما، يرفع kickoff خطأً عند التحقّق.+- `memory=True` مع مزوّد embedding غير افتراضي يحتاج إلى قاموس `embedder` — راجع [إعداد الذاكرة وembedder](#memory-embedder-config) أدناه.++### الإخراج المُهيكل لـ `Task`++استخدم `output_pydantic` أو `output_json` أو `output_file` لإلزام نتيجة المهمة بشكل مكتوب الأنواع:++```python+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, # الفئة، وليس مثيلًا منها+ output_file="output/article.md",+)+```++`output_pydantic` يأخذ **الفئة** نفسها. تمرير `Article(title="", body="")` خطأ شائع ويفشل بخطأ تحقّق مربك.++### إعداد الذاكرة وembedder {#memory-embedder-config}++إذا كان `memory=True` وأنت لا تستخدم embeddings الافتراضية الخاصة بـ OpenAI، فيجب أن تمرّر `embedder`:++```python+crew = Crew(+ agents=[...],+ tasks=[...],+ memory=True,+ embedder={+ "provider": "ollama",+ "config": {"model": "nomic-embed-text"},+ },+)+```++ضع بيانات اعتماد المزوّد المعنيّة (`OPENAI_API_KEY`, `OLLAMA_HOST`, إلخ) في ملف `.env`. مسارات تخزين الذاكرة محلية بالنسبة للمشروع افتراضيًا — احذف مجلد ذاكرة المشروع إذا غيّرت embedders، لأن الأبعاد لا تختلط.diff --git a/docs/docs.json b/docs/docs.jsonindex 60fe1b9da..edd9a19ba 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -144,7 +144,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -1587,7 +1588,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -2068,7 +2070,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -2549,7 +2552,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -3030,7 +3034,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -3511,7 +3516,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -3990,7 +3996,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -4469,7 +4476,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -4949,7 +4957,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -5430,7 +5439,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]@@ -5909,7 +5919,8 @@"group": "Migration","icon": "shuffle","pages": [- "en/guides/migration/migrating-from-langgraph"+ "en/guides/migration/migrating-from-langgraph",+ "en/guides/migration/upgrading-crewai"]}]diff --git a/docs/en/guides/migration/upgrading-crewai.mdx b/docs/en/guides/migration/upgrading-crewai.mdxnew file mode 100644index 000000000..f158bc2c1--- /dev/null+++ b/docs/en/guides/migration/upgrading-crewai.mdx@@ -0,0 +1,190 @@+---+title: "Upgrading CrewAI"+description: "How to upgrade CrewAI in your project and adapt to breaking changes between versions."+icon: "arrow-up-circle"+---++## Overview++CrewAI releases ship new capabilities regularly. This guide walks you through the practical steps to keep your installation up to date — both the CLI and your project's virtual environment.++If you're starting fresh, see [Installation](/en/installation). If you're coming from another framework, see [Migrating from LangGraph](/en/guides/migration/migrating-from-langgraph).++---++## The Two Things You Might Want to Upgrade++CrewAI lives in two places on your machine, and they upgrade independently:++| What | How it's installed | How to upgrade |+|---|---|---|+| The **global `crewai` CLI** | `uv tool install crewai` | `uv tool install crewai --upgrade` |+| The **project venv** (what your code runs) | `crewai install` / `uv sync` | `uv add "crewai[...]>=X.Y.Z"` then `crewai install` |++These can — and often do — get out of sync. Running `crewai --version` tells you the CLI version. Running `uv pip show crewai` inside your project tells you the venv version. If they differ, that's normal; what matters for your running code is the venv version.++## Why `crewai install` Alone Doesn't Upgrade++`crewai install` is a thin wrapper around `uv sync`. It installs exactly what the current `uv.lock` file says — it does **not** bump any version constraints.++If your `pyproject.toml` says `crewai>=1.11.1` and the lock file resolved to `1.11.1`, running `crewai install` will keep you on `1.11.1` forever, even if `1.14.4` is available.++To actually upgrade, you need to:++1. Update the version constraint in `pyproject.toml`+2. Re-solve the lock file+3. Sync the venv++`uv add` does all three in one shot.++## How to Upgrade Your Project++```bash+# Bump the constraint and re-lock in one command+uv add "crewai[tools]>=1.14.4"++# Sync the venv (crewai install calls uv sync under the hood)+crewai install++# Verify+uv pip show crewai+# → Version: 1.14.4+```++Replace `[tools]` with whatever extras your project uses (e.g. `[tools,anthropic]`). Check your `pyproject.toml` `dependencies` list if you're unsure.++<Note>+ `uv add` updates both `pyproject.toml` **and** `uv.lock` atomically. If you edit `pyproject.toml` manually, you still need to run `uv lock --upgrade-package crewai` to re-solve the lock file before `crewai install` will pick up the new version.+</Note>++## Upgrading the Global CLI++The global CLI is separate from your project. Upgrade it with:++```bash+uv tool install crewai --upgrade+```++If your shell warns about `PATH` after the upgrade, refresh it:++```bash+uv tool update-shell+```++This does **not** touch your project's venv — you still need `uv add` + `crewai install` inside the project.++## Verify Both Are in Sync++```bash+# Global CLI version+crewai --version++# Project venv version+uv pip show crewai | grep Version+```++They don't need to match — but your project venv version is what matters for runtime behavior.++<Note>+ CrewAI requires `Python >=3.10, <3.14`. If `uv` was installed against an older interpreter, recreate the project venv with a supported Python before running `crewai install`.+</Note>++---++## Breaking Changes & Migration Notes++Most upgrades only require small adjustments. The areas below are the ones that break silently or with confusing tracebacks.++### Import paths: tools and `BaseTool`++The canonical import location for tools is `crewai.tools`. Older paths still surface in tutorials but should be updated.++```python+# Before+from crewai_tools import BaseTool+from crewai.agents.tools import tool++# After+from crewai.tools import BaseTool, tool+```++The `@tool` decorator and `BaseTool` subclass both live in `crewai.tools`. `AgentFinish` and other internal-agent symbols are no longer part of the public surface — if you were importing them, switch to event listeners or `Task` callbacks instead.++### `Agent` parameter changes++```python+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", # string model name OR an LLM object+ verbose=True, # bool, not an int level+ max_iter=15, # default has changed across versions — set explicitly+ allow_delegation=False,+)+```++- `llm` accepts either a string model name (resolved via the configured provider) or an `LLM` object for fine-grained control.+- `verbose` is a plain `bool`. Passing an integer no longer toggles log levels.+- `max_iter` defaults have shifted between releases. If your agent silently stops looping after the first tool call, set `max_iter` explicitly.++### `Crew` parameters++```python+from crewai import Crew, Process++crew = Crew(+ agents=[...],+ tasks=[...],+ process=Process.sequential, # or Process.hierarchical+ memory=True,+ cache=True,+ embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}},+)+```++- `process=Process.hierarchical` requires either `manager_llm=` or `manager_agent=`. Without one, kickoff raises at validation time.+- `memory=True` with a non-default embedding provider needs an `embedder` dict — see [Memory & embedder config](#memory-embedder-config) below.++### `Task` structured output++Use `output_pydantic`, `output_json`, or `output_file` to coerce a task's result into a typed shape:++```python+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, # the class, NOT an instance+ output_file="output/article.md",+)+```++`output_pydantic` takes the **class** itself. Passing `Article(title="", body="")` is a common mistake and fails with a confusing validation error.++### Memory & embedder config {#memory-embedder-config}++If `memory=True` and you're not using the default OpenAI embeddings, you must pass an `embedder`:++```python+crew = Crew(+ agents=[...],+ tasks=[...],+ memory=True,+ embedder={+ "provider": "ollama",+ "config": {"model": "nomic-embed-text"},+ },+)+```++Set the relevant provider credentials (`OPENAI_API_KEY`, `OLLAMA_HOST`, etc.) in your `.env` file. Memory storage paths are project-local by default — delete the project's memory directory if you change embedders, since dimensions don't mix.diff --git a/docs/en/installation.mdx b/docs/en/installation.mdxindex 50f43ff9d..538ad56d7 100644--- a/docs/en/installation.mdx+++ b/docs/en/installation.mdx@@ -106,6 +106,9 @@ If you haven't installed `uv` yet, follow **step 1** to quickly get it set up on```shelluv tool install crewai --upgrade```+ <Note>+ This upgrades the **global `crewai` CLI tool** only. To upgrade the `crewai` version inside your project's virtual environment, see [Upgrading CrewAI in a project](/en/guides/migration/upgrading-crewai).+ </Note><Check>Installation successful! You're ready to create your first crew! 🎉</Check></Step>diff --git a/docs/ko/guides/migration/upgrading-crewai.mdx b/docs/ko/guides/migration/upgrading-crewai.mdxnew file mode 100644index 000000000..6e96a4480--- /dev/null+++ b/docs/ko/guides/migration/upgrading-crewai.mdx@@ -0,0 +1,190 @@+---+title: "CrewAI 업그레이드"+description: "프로젝트에서 CrewAI를 업그레이드하고 버전 간 브레이킹 체인지에 적응하는 방법."+icon: "arrow-up-circle"+---++## 개요++CrewAI 릴리스는 정기적으로 새로운 기능을 제공합니다. 이 가이드는 CLI와 프로젝트의 가상 환경을 모두 최신 상태로 유지하기 위한 실용적인 단계를 안내합니다.++새로 시작한다면 [설치](/ko/installation)를 참고하세요. 다른 프레임워크에서 옮겨오는 경우라면 [LangGraph에서 마이그레이션](/ko/guides/migration/migrating-from-langgraph)을 참고하세요.++---++## 업그레이드할 수 있는 두 가지++CrewAI는 사용자의 머신에 두 곳에 존재하며, 각각 독립적으로 업그레이드됩니다:++| 무엇 | 설치 방법 | 업그레이드 방법 |+|---|---|---|+| **전역 `crewai` CLI** | `uv tool install crewai` | `uv tool install crewai --upgrade` |+| **프로젝트 venv** (코드가 실행되는 곳) | `crewai install` / `uv sync` | `uv add "crewai[...]>=X.Y.Z"` 후 `crewai install` |++이 둘은 — 그리고 자주 — 동기화가 어긋날 수 있습니다. `crewai --version`은 CLI 버전을 알려줍니다. 프로젝트 안에서 `uv pip show crewai`를 실행하면 venv 버전을 알려줍니다. 둘이 다른 것은 정상이며, 실행 중인 코드에 중요한 것은 venv 버전입니다.++## 왜 `crewai install`만으로는 업그레이드되지 않는가++`crewai install`은 `uv sync`를 감싼 얇은 래퍼입니다. 현재 `uv.lock` 파일이 지시하는 것 그대로를 설치할 뿐이며 — 어떤 버전 제약도 올리지 **않습니다**.++`pyproject.toml`이 `crewai>=1.11.1`이라 적혀 있고 lock 파일이 `1.11.1`로 해소되었다면, `crewai install`을 실행해도 `1.14.4`가 사용 가능하더라도 영원히 `1.11.1`에 머무릅니다.++실제로 업그레이드하려면 다음을 해야 합니다:++1. `pyproject.toml`의 버전 제약 업데이트+2. lock 파일 재해소+3. venv 동기화++`uv add`는 이 세 가지를 한 번에 처리합니다.++## 프로젝트 업그레이드 방법++```bash+# 제약을 올리고 lock을 다시 만드는 한 번의 명령+uv add "crewai[tools]>=1.14.4"++# venv 동기화 (crewai install은 내부적으로 uv sync를 호출)+crewai install++# 확인+uv pip show crewai+# → Version: 1.14.4+```++`[tools]`를 프로젝트에서 사용하는 extras로 바꾸세요 (예: `[tools,anthropic]`). 잘 모르겠다면 `pyproject.toml`의 `dependencies` 목록을 확인하세요.++<Note>+ `uv add`는 `pyproject.toml`과 `uv.lock`을 **둘 다** 원자적으로 업데이트합니다. `pyproject.toml`을 수동으로 편집하는 경우, `crewai install`이 새 버전을 가져가도록 하기 전에 `uv lock --upgrade-package crewai`를 실행해 lock 파일을 다시 해소해야 합니다.+</Note>++## 전역 CLI 업그레이드++전역 CLI는 프로젝트와 분리되어 있습니다. 다음 명령으로 업그레이드하세요:++```bash+uv tool install crewai --upgrade+```++업그레이드 후 셸이 `PATH`에 대해 경고하면 새로고침하세요:++```bash+uv tool update-shell+```++이 명령은 프로젝트의 venv를 **건드리지 않습니다** — 프로젝트 내부에서는 여전히 `uv add` + `crewai install`이 필요합니다.++## 둘이 동기화되었는지 확인++```bash+# 전역 CLI 버전+crewai --version++# 프로젝트 venv 버전+uv pip show crewai | grep Version+```++둘이 일치할 필요는 없지만 — 런타임 동작에 중요한 것은 프로젝트 venv 버전입니다.++<Note>+ CrewAI는 `Python >=3.10, <3.14`를 요구합니다. `uv`가 더 오래된 인터프리터로 설치되어 있다면, `crewai install`을 실행하기 전에 지원되는 Python으로 프로젝트 venv를 다시 만드세요.+</Note>++---++## 브레이킹 체인지 및 마이그레이션 노트++대부분의 업그레이드는 작은 조정만 필요합니다. 아래 항목들은 조용히 깨지거나 헷갈리는 트레이스백을 내는 영역들입니다.++### Import 경로: tools와 `BaseTool`++tools의 정식 import 위치는 `crewai.tools`입니다. 옛 경로들이 아직 튜토리얼에 등장하지만 업데이트해야 합니다.++```python+# 이전+from crewai_tools import BaseTool+from crewai.agents.tools import tool++# 이후+from crewai.tools import BaseTool, tool+```++`@tool` 데코레이터와 `BaseTool` 서브클래스는 모두 `crewai.tools`에 있습니다. `AgentFinish` 등 내부 에이전트 심볼들은 더 이상 공개 표면이 아닙니다 — import 중이었다면 event listener나 `Task` 콜백으로 전환하세요.++### `Agent` 파라미터 변경++```python+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", # 모델명 문자열 또는 LLM 객체+ verbose=True, # 정수 레벨이 아닌 bool+ max_iter=15, # 버전마다 기본값이 바뀌었음 — 명시적으로 지정+ allow_delegation=False,+)+```++- `llm`은 문자열 모델명(설정된 provider를 통해 해소)이나 세밀한 제어를 위한 `LLM` 객체를 받습니다.+- `verbose`는 일반 `bool`입니다. 정수를 전달해도 더 이상 로그 레벨을 토글하지 않습니다.+- `max_iter`의 기본값은 릴리스 사이에 변경되었습니다. 첫 tool 호출 후 에이전트가 조용히 반복을 멈춘다면 `max_iter`를 명시적으로 지정하세요.++### `Crew` 파라미터++```python+from crewai import Crew, Process++crew = Crew(+ agents=[...],+ tasks=[...],+ process=Process.sequential, # 또는 Process.hierarchical+ memory=True,+ cache=True,+ embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}},+)+```++- `process=Process.hierarchical`은 `manager_llm=` 또는 `manager_agent=` 중 하나가 필요합니다. 둘 다 없으면 kickoff 시 검증 단계에서 오류가 발생합니다.+- 기본이 아닌 임베딩 provider와 함께 `memory=True`를 쓰려면 `embedder` dict가 필요합니다 — 아래의 [메모리와 embedder 설정](#memory-embedder-config)을 참고하세요.++### `Task` 구조화된 출력++`output_pydantic`, `output_json`, 또는 `output_file`을 사용해 task 결과를 타입이 지정된 형태로 강제할 수 있습니다:++```python+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, # 인스턴스가 아닌 클래스+ output_file="output/article.md",+)+```++`output_pydantic`은 **클래스** 자체를 받습니다. `Article(title="", body="")`을 전달하는 것은 흔한 실수이며 헷갈리는 검증 오류로 실패합니다.++### 메모리와 embedder 설정 {#memory-embedder-config}++`memory=True`이고 OpenAI의 기본 임베딩을 사용하지 않는다면, `embedder`를 반드시 전달해야 합니다:++```python+crew = Crew(+ agents=[...],+ tasks=[...],+ memory=True,+ embedder={+ "provider": "ollama",+ "config": {"model": "nomic-embed-text"},+ },+)+```++해당 provider의 자격 증명(`OPENAI_API_KEY`, `OLLAMA_HOST` 등)을 `.env` 파일에 설정하세요. 메모리 저장 경로는 기본적으로 프로젝트-로컬입니다 — embedder를 바꾸면 차원이 호환되지 않으므로 프로젝트의 메모리 디렉터리를 삭제하세요.diff --git a/docs/pt-BR/guides/migration/upgrading-crewai.mdx b/docs/pt-BR/guides/migration/upgrading-crewai.mdxnew file mode 100644index 000000000..0c7472d0a--- /dev/null+++ b/docs/pt-BR/guides/migration/upgrading-crewai.mdx@@ -0,0 +1,190 @@+---+title: "Atualizando o CrewAI"+description: "Como atualizar o CrewAI no seu projeto e adaptar-se a breaking changes entre versões."+icon: "arrow-up-circle"+---++## 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](/pt-BR/installation). Se está vindo de outro framework, veja [Migrando do LangGraph](/pt-BR/guides/migration/migrating-from-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:++1. Atualizar a restrição de versão em `pyproject.toml`+2. Re-resolver o lock file+3. Sincronizar o venv++`uv add` faz os três de uma vez só.++## Como Atualizar Seu Projeto++```bash+# 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.++<Note>+ `uv add` atualiza tanto `pyproject.toml` **quanto** `uv.lock` atomicamente. Se você editar `pyproject.toml` manualmente, ainda precisa rodar `uv lock --upgrade-package crewai` para re-resolver o lock file antes que `crewai install` pegue a nova versão.+</Note>++## Atualizando a CLI Global++A CLI global é separada do seu projeto. Atualize com:++```bash+uv tool install crewai --upgrade+```++Se seu shell avisar sobre o `PATH` após a atualização, recarregue-o:++```bash+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++```bash+# 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.++<Note>+ CrewAI requer `Python >=3.10, <3.14`. Se o `uv` foi instalado contra um interpretador mais antigo, recrie o venv do projeto com uma versão suportada do Python antes de rodar `crewai install`.+</Note>++---++## 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.++```python+# 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`++```python+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`++```python+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](#memory-embedder-config) 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:++```python+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 {#memory-embedder-config}++Se `memory=True` e você não está usando os embeddings padrão da OpenAI, é preciso passar um `embedder`:++```python+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.