You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: "كيفية ترقية CrewAI في مشروعك والتكيّف مع التغييرات الجذرية بين الإصدارات."
4
+
icon: "arrow-up-circle"
5
+
---
6
+
7
+
## نظرة عامة
8
+
9
+
تجلب إصدارات CrewAI قدرات جديدة بانتظام. يرشدك هذا الدليل خلال الخطوات العملية للحفاظ على تثبيتك محدّثًا — سواء أداة سطر الأوامر أو البيئة الافتراضية لمشروعك.
10
+
11
+
إذا كنت تبدأ من الصفر، راجع [التثبيت](/ar/installation). إذا كنت قادمًا من إطار عمل آخر، راجع [الترحيل من LangGraph](/ar/guides/migration/migrating-from-langgraph).
12
+
13
+
---
14
+
15
+
## الشيئان اللذان قد ترغب في ترقيتهما
16
+
17
+
يوجد CrewAI في مكانين على جهازك، ويتم ترقيتهما بشكل مستقل:
|**بيئة venv للمشروع** (حيث يعمل الكود) |`crewai install` / `uv sync`|`uv add "crewai[...]>=X.Y.Z"` ثم `crewai install`|
23
+
24
+
يمكن لهما — وغالبًا ما يحدث — أن يخرجا عن التزامن. تشغيل `crewai --version` يُظهر إصدار سطر الأوامر. تشغيل `uv pip show crewai` داخل مشروعك يُظهر إصدار venv. إذا اختلفا، فهذا طبيعي؛ ما يهم بالنسبة للكود قيد التشغيل هو إصدار venv.
25
+
26
+
## لماذا لا يقوم `crewai install` وحده بالترقية
27
+
28
+
`crewai install` هو غلاف رفيع حول `uv sync`. يُثبّت بالضبط ما يقوله ملف `uv.lock` الحالي — وهو **لا** يرفع أي قيود إصدار.
29
+
30
+
إذا كان `pyproject.toml` يقول `crewai>=1.11.1` وقد قام ملف القفل بحلّه إلى `1.11.1`، فإن تشغيل `crewai install` سيُبقيك على `1.11.1` للأبد، حتى وإن كان الإصدار `1.14.4` متاحًا.
31
+
32
+
للترقية فعلًا، عليك:
33
+
34
+
1. تحديث قيد الإصدار في `pyproject.toml`
35
+
2. إعادة حلّ ملف القفل
36
+
3. مزامنة venv
37
+
38
+
`uv add` يقوم بالثلاثة في خطوة واحدة.
39
+
40
+
## كيفية ترقية مشروعك
41
+
42
+
```bash
43
+
# يرفع القيد ويعيد القفل في أمر واحد
44
+
uv add "crewai[tools]>=1.14.4"
45
+
46
+
# يزامن venv (crewai install يستدعي uv sync تحت الغطاء)
47
+
crewai install
48
+
49
+
# تحقّق
50
+
uv pip show crewai
51
+
# → Version: 1.14.4
52
+
```
53
+
54
+
استبدل `[tools]` بأي إضافات يستخدمها مشروعك (مثلًا `[tools,anthropic]`). تحقّق من قائمة `dependencies` في `pyproject.toml` إن لم تكن متأكدًا.
55
+
56
+
<Note>
57
+
يحدّث `uv add` كلا من `pyproject.toml`**و**`uv.lock` بشكل ذرّي. إذا قمت بتحرير `pyproject.toml` يدويًا، فإنك لا تزال بحاجة إلى تشغيل `uv lock --upgrade-package crewai` لإعادة حلّ ملف القفل قبل أن يلتقط `crewai install` الإصدار الجديد.
58
+
</Note>
59
+
60
+
## ترقية أداة سطر الأوامر العامة
61
+
62
+
أداة سطر الأوامر العامة منفصلة عن مشروعك. قم بترقيتها عبر:
63
+
64
+
```bash
65
+
uv tool install crewai --upgrade
66
+
```
67
+
68
+
إذا حذّرك الـ shell بشأن `PATH` بعد الترقية، قم بتحديثه:
69
+
70
+
```bash
71
+
uv tool update-shell
72
+
```
73
+
74
+
هذا **لا** يمسّ بيئة venv الخاصة بمشروعك — لا تزال بحاجة إلى `uv add` + `crewai install` داخل المشروع.
75
+
76
+
## التحقق من تزامن الاثنين
77
+
78
+
```bash
79
+
# إصدار سطر الأوامر العام
80
+
crewai --version
81
+
82
+
# إصدار venv للمشروع
83
+
uv pip show crewai | grep Version
84
+
```
85
+
86
+
ليس من الضروري أن يتطابقا — لكن إصدار venv للمشروع هو ما يهم لسلوك التشغيل.
87
+
88
+
<Note>
89
+
يتطلب CrewAI `Python >=3.10, <3.14`. إذا كان `uv` مثبَّتًا مقابل مفسّر أقدم، فأعد إنشاء venv للمشروع باستخدام إصدار Python مدعوم قبل تشغيل `crewai install`.
90
+
</Note>
91
+
92
+
---
93
+
94
+
## التغييرات الجذرية وملاحظات الترحيل
95
+
96
+
تتطلب معظم الترقيات تعديلات صغيرة فقط. المناطق أدناه هي تلك التي تنكسر بصمت أو بتتبعات مكدّس مربكة.
97
+
98
+
### مسارات الاستيراد: tools و`BaseTool`
99
+
100
+
الموقع الرسمي لاستيراد الـ tools هو `crewai.tools`. لا تزال المسارات القديمة تظهر في الدروس لكن يجب تحديثها.
101
+
102
+
```python
103
+
# قبل
104
+
from crewai_tools import BaseTool
105
+
from crewai.agents.tools import tool
106
+
107
+
# بعد
108
+
from crewai.tools import BaseTool, tool
109
+
```
110
+
111
+
كلٌ من المُزخرف `@tool` والفئة الفرعية `BaseTool` يقعان في `crewai.tools`. `AgentFinish` والرموز الأخرى الداخلية للوكيل لم تعد جزءًا من السطح العام — إذا كنت تستوردها، فانتقل إلى event listeners أو callbacks الـ `Task` بدلًا منها.
112
+
113
+
### تغييرات معاملات `Agent`
114
+
115
+
```python
116
+
from crewai import Agent
117
+
118
+
agent = Agent(
119
+
role="Researcher",
120
+
goal="Find authoritative sources on {topic}",
121
+
backstory="You are a careful, source-driven researcher.",
122
+
llm="gpt-4o-mini", # اسم نموذج كسلسلة نصية أو كائن LLM
123
+
verbose=True, # bool وليس مستوى عددي صحيح
124
+
max_iter=15, # تغيّر الافتراضي بين الإصدارات — حدّده بشكل صريح
125
+
allow_delegation=False,
126
+
)
127
+
```
128
+
129
+
- يقبل `llm` إما اسم نموذج كسلسلة نصية (يُحلَّ عبر المزوّد المهيّأ) أو كائن `LLM` للتحكم الدقيق.
130
+
-`verbose` هو `bool` بسيط. تمرير عدد صحيح لم يعد يبدّل مستويات السجل.
131
+
- تغيّرت افتراضات `max_iter` بين الإصدارات. إذا توقف وكيلك بصمت عن التكرار بعد أول استدعاء tool، فحدّد `max_iter` صراحةً.
132
+
133
+
### معاملات `Crew`
134
+
135
+
```python
136
+
from crewai import Crew, Process
137
+
138
+
crew = Crew(
139
+
agents=[...],
140
+
tasks=[...],
141
+
process=Process.sequential, # أو Process.hierarchical
### إعداد الذاكرة وembedder {#memory-embedder-config}
175
+
176
+
إذا كان `memory=True` وأنت لا تستخدم embeddings الافتراضية الخاصة بـ OpenAI، فيجب أن تمرّر `embedder`:
177
+
178
+
```python
179
+
crew = Crew(
180
+
agents=[...],
181
+
tasks=[...],
182
+
memory=True,
183
+
embedder={
184
+
"provider": "ollama",
185
+
"config": {"model": "nomic-embed-text"},
186
+
},
187
+
)
188
+
```
189
+
190
+
ضع بيانات اعتماد المزوّد المعنيّة (`OPENAI_API_KEY`, `OLLAMA_HOST`, إلخ) في ملف `.env`. مسارات تخزين الذاكرة محلية بالنسبة للمشروع افتراضيًا — احذف مجلد ذاكرة المشروع إذا غيّرت embedders، لأن الأبعاد لا تختلط.
Each tool instance maintains its own persistent sandbox. To share**one** sandbox across two tools, create the first tool, grab its sandbox id via `tool._persistent_sandbox.id`, and pass it to the second tool via `sandbox_id=...`.
81
+
By default, each tool with `persistent=True` lazily creates its**own** sandbox on first use. The pattern above shares a single sandbox across multiple tools by reading the first tool's `active_sandbox_id` after a `.run()` call and passing it to the others via `sandbox_id=...`. With `persistent=False` (the default), every `.run()` call gets a fresh sandbox that's deleted at the end of that call.
77
82
</Note>
78
83
79
84
### Attach to an existing sandbox
@@ -82,7 +87,7 @@ Each tool instance maintains its own persistent sandbox. To share **one** sandbo
|`path`|`str \| None`| ✓ for all actions except `replace`| Absolute path inside the sandbox. |
213
+
|`content`|`str \| None`|✓ for `append`| Content to write or append. |
174
214
|`binary`|`bool`|| If `True`, `content` is base64 on write; returns base64 on read. |
175
215
|`recursive`|`bool`|| For `delete`: remove directories recursively. |
176
-
|`mode`|`str`|| For `mkdir`: octal permission string (default `"0755"`). |
216
+
|`mode`|`str \| None`|| For `mkdir`: octal permissions for the new directory (defaults to `"0755"`). For `chmod`: octal permissions to apply to the target. |
217
+
|`destination`|`str \| None`| ✓ for `move`| Destination path for `move`. |
218
+
|`pattern`|`str \| None`| ✓ for `find`, `search`, `replace`| For `find`: substring matched against file CONTENTS. For `search`: glob matched against file NAMES (e.g. `*.py`). For `replace`: text to replace inside files. |
219
+
|`replacement`|`str \| None`| ✓ for `replace`| Replacement text for `pattern`. |
220
+
|`paths`|`list[str] \| None`| ✓ for `replace`| List of file paths in which to replace text. |
221
+
|`owner`|`str \| None`|| For `chmod`: new file owner. |
222
+
|`group`|`str \| None`|| For `chmod`: new file group. |
223
+
224
+
<Note>
225
+
For `chmod`, pass at least one of `mode`, `owner`, or `group` — any field left as `None` is left unchanged on the target.
226
+
</Note>
177
227
178
228
<Tip>
179
229
For files larger than a few KB, create the file first with `action="write"` and empty content, then send the body via multiple `action="append"` calls of ~4 KB each to stay within tool-call payload limits.
0 commit comments