From e4a91cdc0c019f3077af44ad674509076bfc085d Mon Sep 17 00:00:00 2001 From: iris-clawd Date: Fri, 8 May 2026 18:49:39 -0300 Subject: [PATCH] docs: add OSS upgrade & crew-to-flow migration guide (#5744) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: add OSS upgrade & crew-to-flow migration guide * docs: add upgrading-crewai guide and installation note Co-Authored-By: Claude Opus 4.7 * docs: consolidate upgrade & migration guide into single page Merge the broader root-level upgrade-crewai.mdx into the canonical en/guides/migration/upgrading-crewai.mdx so there is one comprehensive upgrade & migration page covering: project venv vs global CLI, why crewai install alone won't bump versions, breaking changes, and the Crew-to-Flow migration. Removes the orphaned root-level file (which was not referenced in docs.json nav). Co-Authored-By: Claude Opus 4.7 * docs: add pt-BR, ar, ko translations of upgrade/migration guide Co-Authored-By: Claude Opus 4.7 * docs: reduce upgrade guide scope to package upgrade + breaking changes only * docs: soften intro tone — releases ship features, not breaking changes Co-Authored-By: Claude Opus 4.7 * fix: resolve CodeRabbit review comments - Add space between Arabic conjunction and `uv.lock` code span (ar) - Add explicit {#memory-embedder-config} anchors to localized headings so in-page links resolve correctly (ar, ko, pt-BR, en) Co-authored-by: Lucas Gomide --------- Co-authored-by: Claude Opus 4.7 Co-authored-by: Lucas Gomide Co-authored-by: Greyson LaLonde --- docs/ar/guides/migration/upgrading-crewai.mdx | 190 ++++++++++++++++++ docs/docs.json | 33 ++- docs/en/guides/migration/upgrading-crewai.mdx | 190 ++++++++++++++++++ docs/en/installation.mdx | 3 + docs/ko/guides/migration/upgrading-crewai.mdx | 190 ++++++++++++++++++ .../guides/migration/upgrading-crewai.mdx | 190 ++++++++++++++++++ 6 files changed, 785 insertions(+), 11 deletions(-) create mode 100644 docs/ar/guides/migration/upgrading-crewai.mdx create mode 100644 docs/en/guides/migration/upgrading-crewai.mdx create mode 100644 docs/ko/guides/migration/upgrading-crewai.mdx create mode 100644 docs/pt-BR/guides/migration/upgrading-crewai.mdx diff --git a/docs/ar/guides/migration/upgrading-crewai.mdx b/docs/ar/guides/migration/upgrading-crewai.mdx new file mode 100644 index 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` إن لم تكن متأكدًا. + + + يحدّث `uv add` كلا من `pyproject.toml` **و** `uv.lock` بشكل ذرّي. إذا قمت بتحرير `pyproject.toml` يدويًا، فإنك لا تزال بحاجة إلى تشغيل `uv lock --upgrade-package crewai` لإعادة حلّ ملف القفل قبل أن يلتقط `crewai install` الإصدار الجديد. + + +## ترقية أداة سطر الأوامر العامة + +أداة سطر الأوامر العامة منفصلة عن مشروعك. قم بترقيتها عبر: + +```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 للمشروع هو ما يهم لسلوك التشغيل. + + + يتطلب CrewAI `Python >=3.10, <3.14`. إذا كان `uv` مثبَّتًا مقابل مفسّر أقدم، فأعد إنشاء venv للمشروع باستخدام إصدار Python مدعوم قبل تشغيل `crewai install`. + + +--- + +## التغييرات الجذرية وملاحظات الترحيل + +تتطلب معظم الترقيات تعديلات صغيرة فقط. المناطق أدناه هي تلك التي تنكسر بصمت أو بتتبعات مكدّس مربكة. + +### مسارات الاستيراد: 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.json index 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.mdx new file mode 100644 index 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. + + + `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. + + +## 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. + + + 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`. + + +--- + +## 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.mdx index 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 ```shell uv tool install crewai --upgrade ``` + + 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). + Installation successful! You're ready to create your first crew! 🎉 diff --git a/docs/ko/guides/migration/upgrading-crewai.mdx b/docs/ko/guides/migration/upgrading-crewai.mdx new file mode 100644 index 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` 목록을 확인하세요. + + + `uv add`는 `pyproject.toml`과 `uv.lock`을 **둘 다** 원자적으로 업데이트합니다. `pyproject.toml`을 수동으로 편집하는 경우, `crewai install`이 새 버전을 가져가도록 하기 전에 `uv lock --upgrade-package crewai`를 실행해 lock 파일을 다시 해소해야 합니다. + + +## 전역 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 버전입니다. + + + CrewAI는 `Python >=3.10, <3.14`를 요구합니다. `uv`가 더 오래된 인터프리터로 설치되어 있다면, `crewai install`을 실행하기 전에 지원되는 Python으로 프로젝트 venv를 다시 만드세요. + + +--- + +## 브레이킹 체인지 및 마이그레이션 노트 + +대부분의 업그레이드는 작은 조정만 필요합니다. 아래 항목들은 조용히 깨지거나 헷갈리는 트레이스백을 내는 영역들입니다. + +### 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.mdx new file mode 100644 index 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. + + + `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. + + +## 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. + + + 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`. + + +--- + +## 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.