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.