andre/crewAI
1
0
Fork 0
mirror of https://github.com/crewAIInc/crewAI.git synced 2026-07-09 00:45:16 +00:00
Code Issues Actions 6 Packages Projects Releases Wiki Activity

feat: adopt directory-based docs versioning with Edge channel

Browse Source 
Switch docs.crewai.com from navigation-only versioning (every version
selector entry rendered the same docs/<lang>/* source files) to
Mintlify's directory-based versioning so each version selector entry
renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/*
that always reflects main HEAD for unreleased work, eliminating
pre-release leakage onto frozen release labels. External links to
canonical /<lang>/* URLs are preserved via wildcard redirects that
always land on the current default version.

Layout:
- docs/edge/<lang>/*         rolling source (you edit here)
- docs/edge/enterprise-api.*.yaml
- docs/v<X.Y.Z>/<lang>/*     frozen, immutable snapshots
- docs/v<X.Y.Z>/enterprise-api.*.yaml
- docs/images/               shared, append-only
- docs/docs.json             nav + redirects

URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for
Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard
redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links
working, and every freeze rewrites them (plus all per-section/per-page
redirects) so destinations always resolve to the current default
without depending on a second redirect hop.

Release flow integration (devtools release):
- New module crewai_devtools.docs_versioning.freeze() materialises
  docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the
  snapshot, inserts the version into every language block in
  docs.json, and refreshes all redirect destinations.
- _update_docs_and_create_pr() in cli.py now calls that freeze during
  Phase 2 of devtools release. Edge changelogs are updated first (so
  the snapshot freeze picks them up), then the snapshot is staged
  alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR
  is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z>
  — the title prefix the new CI guard reads.
- The PR still gates tag, GitHub release, PyPI publish, and the
  enterprise release as before; no new PRs are added.
- Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride
  Edge — and the docs PR title omits the [docs-freeze] prefix.
- docs_check (AI-generated docs scaffolding) writes to
  docs/edge/<lang>/* so newly-generated unreleased docs land in Edge
  and never accidentally touch a frozen snapshot.

Migration scripts (one-shot):
- scripts/docs/freeze_historical_versions.py reconstructs all 16
  historical snapshots (v1.10.0 .. v1.14.7) from git tags via
  git archive | tar, rewriting openapi: MDX refs so each snapshot
  reads its own enterprise-api YAML rather than the live one.
- scripts/docs/prefix_version_paths.py one-shot-migrates docs.json:
  rewrites every page path in 16 versioned blocks to point under
  docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags
  v1.14.7 as Latest (default), prunes pages whose target file
  doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before
  v1.12.0), and writes the wildcard + per-section redirects.
- scripts/docs/freeze_current_edge.py is now a thin CLI wrapper
  around docs_versioning.freeze for manual one-off freezes (e.g.
  retroactively snapshotting a forgotten release).

CI guards (.github/workflows/docs-snapshots.yml):
- Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose
  title contains [docs-freeze] (i.e. release-cut PRs generated by
  devtools release or the manual wrapper) may modify them.
- Images under docs/images/ are append-only since snapshots share a
  single image directory. Deleting or renaming an image breaks every
  historical snapshot that still references it.

Restored docs/images/crewai-otel-export.png from PR #3673; it was
deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference
it. Restoring instead of editing the snapshots preserves historical
rendering fidelity and validates the new append-only rule
retroactively.

Tests:
- lib/devtools/tests/test_docs_versioning.py covers the freeze: file
  copy, openapi rewrite, version insertion, default demotion, redirect
  upserts, per-section redirect rewriting, idempotency, and invalid
  inputs.

Verified locally with mintlify broken-links: 0 broken links across
the full site (Edge + 16 frozen versions, 4 locales).

AGENTS.md (repo root) is the contributor guide for the new model;
RELEASING.md is the release-cut runbook; README's Contribution
section links to both.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
2026-06-17 09:33:56 -03:00
parent 7bb9bc7e1a
commit 93dafe2637
15793 changed files with 3237032 additions and 16873 deletions
Download Patch File Download Diff File Expand all files Collapse all files

147
docs/edge/ar/concepts/agent-capabilities.mdx Normal file
View File

@@ -0,0 +1,147 @@
---
title: "قدرات الوكيل"
description: "فهم الطرق الخمس لتوسيع وكلاء CrewAI: الأدوات، MCP، التطبيقات، المهارات، والمعرفة."
icon: puzzle-piece
mode: "wide"
---
## نظرة عامة
يمكن توسيع وكلاء CrewAI بـ **خمسة أنواع مميزة من القدرات**، كل منها يخدم غرضًا مختلفًا. فهم متى تستخدم كل نوع — وكيف يعملون معًا — هو المفتاح لبناء وكلاء فعّالين.
<CardGroup cols={2}>
<Card title="الأدوات" icon="wrench" href="/ar/concepts/tools" color="#3B82F6">
**دوال قابلة للاستدعاء** — تمنح الوكلاء القدرة على اتخاذ إجراءات. البحث على الويب، عمليات الملفات، استدعاءات API، تنفيذ الكود.
</Card>
<Card title="خوادم MCP" icon="plug" href="/ar/mcp/overview" color="#8B5CF6">
**خوادم أدوات عن بُعد** — تربط الوكلاء بخوادم أدوات خارجية عبر Model Context Protocol. نفس تأثير الأدوات، لكن مستضافة خارجيًا.
</Card>
<Card title="التطبيقات" icon="grid-2" color="#EC4899">
**تكاملات المنصة** — تربط الوكلاء بتطبيقات SaaS (Gmail، Slack، Jira، Salesforce) عبر منصة CrewAI. تعمل محليًا مع رمز تكامل المنصة.
</Card>
<Card title="المهارات" icon="bolt" href="/ar/concepts/skills" color="#F59E0B">
**خبرة المجال** — تحقن التعليمات والإرشادات والمواد المرجعية في إرشادات الوكلاء. المهارات تخبر الوكلاء *كيف يفكرون*.
</Card>
<Card title="المعرفة" icon="book" href="/ar/concepts/knowledge" color="#10B981">
**حقائق مُسترجعة** — توفر للوكلاء بيانات من المستندات والملفات وعناوين URL عبر البحث الدلالي (RAG). المعرفة تعطي الوكلاء *ما يحتاجون معرفته*.
</Card>
</CardGroup>
---
## التمييز الأساسي
أهم شيء يجب فهمه: **هذه القدرات تنقسم إلى فئتين**.
### قدرات الإجراء (الأدوات، MCP، التطبيقات)
تمنح الوكلاء القدرة على **فعل أشياء** — استدعاء APIs، قراءة الملفات، البحث على الويب، إرسال رسائل البريد الإلكتروني. عند التنفيذ، تتحول الأنواع الثلاثة إلى نفس التنسيق الداخلي (مثيلات `BaseTool`) وتظهر في قائمة أدوات موحدة يمكن للوكيل استدعاؤها.
```python
from crewai import Agent
from crewai_tools import SerperDevTool, FileReadTool
agent = Agent(
role="Researcher",
goal="Find and compile market data",
backstory="Expert market analyst",
tools=[SerperDevTool(), FileReadTool()], # أدوات محلية
mcps=["https://mcp.example.com/sse"], # أدوات خادم MCP عن بُعد
apps=["gmail", "google_sheets"], # تكاملات المنصة
)
```
### قدرات السياق (المهارات، المعرفة)
تُعدّل **إرشادات** الوكيل — بحقن الخبرة أو التعليمات أو البيانات المُسترجعة قبل أن يبدأ الوكيل في التفكير. لا تمنح الوكلاء إجراءات جديدة؛ بل تُشكّل كيف يفكر الوكلاء وما هي المعلومات التي يمكنهم الوصول إليها.
```python
from crewai import Agent
agent = Agent(
role="Security Auditor",
goal="Audit cloud infrastructure for vulnerabilities",
backstory="Expert in cloud security with 10 years of experience",
skills=["./skills/security-audit"], # تعليمات المجال
knowledge_sources=[pdf_source, url_source], # حقائق مُسترجعة
)
```
---
## متى تستخدم ماذا
| تحتاج إلى... | استخدم | مثال |
| :------------------------------------------------------- | :---------------- | :--------------------------------------- |
| الوكيل يبحث على الويب | **الأدوات** | `tools=[SerperDevTool()]` |
| الوكيل يستدعي API عن بُعد عبر MCP | **MCP** | `mcps=["https://api.example.com/sse"]` |
| الوكيل يرسل بريد إلكتروني عبر Gmail | **التطبيقات** | `apps=["gmail"]` |
| الوكيل يتبع إجراءات محددة | **المهارات** | `skills=["./skills/code-review"]` |
| الوكيل يرجع لمستندات الشركة | **المعرفة** | `knowledge_sources=[pdf_source]` |
| الوكيل يبحث على الويب ويتبع إرشادات المراجعة | **الأدوات + المهارات** | استخدم كليهما معًا |
---
## دمج القدرات
في الممارسة العملية، غالبًا ما يستخدم الوكلاء **أنواعًا متعددة من القدرات معًا**. إليك مثال واقعي:
```python
from crewai import Agent
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
# وكيل بحث مجهز بالكامل
researcher = Agent(
role="Senior Research Analyst",
goal="Produce comprehensive market analysis reports",
backstory="Expert analyst with deep industry knowledge",
# الإجراء: ما يمكن للوكيل فعله
tools=[
SerperDevTool(), # البحث على الويب
FileReadTool(), # قراءة الملفات المحلية
CodeInterpreterTool(), # تشغيل كود Python للتحليل
],
mcps=["https://data-api.example.com/sse"], # الوصول لـ API بيانات عن بُعد
apps=["google_sheets"], # الكتابة في Google Sheets
# السياق: ما يعرفه الوكيل
skills=["./skills/research-methodology"], # كيفية إجراء البحث
knowledge_sources=[company_docs], # بيانات خاصة بالشركة
)
```
---
## جدول المقارنة
| الميزة | الأدوات | MCP | التطبيقات | المهارات | المعرفة |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **يمنح الوكيل إجراءات** | ✅ | ✅ | ✅ | ❌ | ❌ |
| **يُعدّل الإرشادات** | ❌ | ❌ | ❌ | ✅ | ✅ |
| **يتطلب كود** | نعم | إعداد فقط | إعداد فقط | Markdown فقط | إعداد فقط |
| **يعمل محليًا** | نعم | يعتمد | نعم (مع متغير بيئة) | غير متاح | نعم |
| **يحتاج مفاتيح API** | لكل أداة | لكل خادم | رمز التكامل | لا | المُضمّن فقط |
| **يُعيَّن على Agent** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` |
| **يُعيَّن على Crew** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` |
---
## تعمّق أكثر
هل أنت مستعد لمعرفة المزيد عن كل نوع من أنواع القدرات؟
<CardGroup cols={2}>
<Card title="الأدوات" icon="wrench" href="/ar/concepts/tools">
إنشاء أدوات مخصصة، استخدام كتالوج OSS مع أكثر من 75 خيارًا، تكوين التخزين المؤقت والتنفيذ غير المتزامن.
</Card>
<Card title="تكامل MCP" icon="plug" href="/ar/mcp/overview">
الاتصال بخوادم MCP عبر stdio أو SSE أو HTTP. تصفية الأدوات، تكوين المصادقة.
</Card>
<Card title="المهارات" icon="bolt" href="/ar/concepts/skills">
بناء حزم المهارات مع SKILL.md، حقن خبرة المجال، استخدام الكشف التدريجي.
</Card>
<Card title="المعرفة" icon="book" href="/ar/concepts/knowledge">
إضافة المعرفة من ملفات PDF وCSV وعناوين URL والمزيد. تكوين المُضمّنات والاسترجاع.
</Card>
</CardGroup>

383
docs/edge/ar/concepts/agents.mdx Normal file
View File

@@ -0,0 +1,383 @@
---
title: الوكلاء
description: دليل تفصيلي حول إنشاء وإدارة الوكلاء ضمن إطار عمل CrewAI.
icon: robot
mode: "wide"
---
## نظرة عامة على الوكيل
في إطار عمل CrewAI، الـ `Agent` هو وحدة مستقلة يمكنها:
- أداء مهام محددة
- اتخاذ قرارات بناءً على دوره وهدفه
- استخدام الأدوات لتحقيق الأهداف
- التواصل والتعاون مع وكلاء آخرين
- الاحتفاظ بذاكرة التفاعلات
- تفويض المهام عند السماح بذلك
<Tip>
فكّر في الوكيل كعضو فريق متخصص بمهارات وخبرات ومسؤوليات محددة.
على سبيل المثال، قد يتفوق وكيل `Researcher` في جمع وتحليل المعلومات،
بينما قد يكون وكيل `Writer` أفضل في إنشاء المحتوى.
</Tip>
<Note type="info" title="تحسين المؤسسات: منشئ الوكلاء المرئي">
يتضمن CrewAI AMP منشئ وكلاء مرئي يبسّط إنشاء وتهيئة الوكلاء بدون كتابة كود. صمم وكلاءك بصريًا واختبرهم في الوقت الفعلي.
![Visual Agent Builder Screenshot](/images/enterprise/crew-studio-interface.png)
يُمكّن منشئ الوكلاء المرئي من:
- تهيئة وكلاء بديهية بواجهات نماذج
- اختبار والتحقق في الوقت الفعلي
- مكتبة قوالب مع أنواع وكلاء مهيأة مسبقًا
- تخصيص سهل لخصائص وسلوكيات الوكيل
</Note>
## خصائص الوكيل
| الخاصية | المعامل | النوع | الوصف |
| :-------------------------------------- | :----------------------- | :------------------------------------ | :------------------------------------------------------------------------------------------------------- |
| **الدور** | `role` | `str` | يحدد وظيفة الوكيل وخبرته ضمن الطاقم. |
| **الهدف** | `goal` | `str` | الهدف الفردي الذي يوجه عملية اتخاذ القرار لدى الوكيل. |
| **الخلفية** | `backstory` | `str` | يوفر سياقًا وشخصية للوكيل، مما يثري التفاعلات. |
| **LLM** _(اختياري)_ | `llm` | `Union[str, LLM, Any]` | نموذج اللغة الذي يشغّل الوكيل. افتراضيًا النموذج المحدد في `OPENAI_MODEL_NAME` أو "gpt-4". |
| **الأدوات** _(اختياري)_ | `tools` | `List[BaseTool]` | القدرات أو الوظائف المتاحة للوكيل. افتراضيًا قائمة فارغة. |
| **LLM استدعاء الدوال** _(اختياري)_ | `function_calling_llm` | `Optional[Any]` | نموذج لغة لاستدعاء الأدوات، يتجاوز LLM الطاقم إذا حُدد. |
| **الحد الأقصى للتكرارات** _(اختياري)_ | `max_iter` | `int` | الحد الأقصى للتكرارات قبل أن يقدم الوكيل أفضل إجابته. الافتراضي 20. |
| **الحد الأقصى لـ RPM** _(اختياري)_ | `max_rpm` | `Optional[int]` | الحد الأقصى للطلبات في الدقيقة لتجنب حدود المعدل. |
| **الحد الأقصى لوقت التنفيذ** _(اختياري)_ | `max_execution_time` | `Optional[int]` | الحد الأقصى للوقت (بالثواني) لتنفيذ المهمة. |
| **الوضع المفصل** _(اختياري)_ | `verbose` | `bool` | تفعيل سجلات التنفيذ المفصلة للتصحيح. الافتراضي False. |
| **السماح بالتفويض** _(اختياري)_ | `allow_delegation` | `bool` | السماح للوكيل بتفويض المهام لوكلاء آخرين. الافتراضي False. |
| **دالة الخطوة** _(اختياري)_ | `step_callback` | `Optional[Any]` | دالة تُستدعى بعد كل خطوة للوكيل، تتجاوز دالة الطاقم. |
| **التخزين المؤقت** _(اختياري)_ | `cache` | `bool` | تفعيل التخزين المؤقت لاستخدام الأدوات. الافتراضي True. |
| **قالب النظام** _(اختياري)_ | `system_template` | `Optional[str]` | قالب أمر نظام مخصص للوكيل. |
| **قالب الأمر** _(اختياري)_ | `prompt_template` | `Optional[str]` | قالب أمر مخصص للوكيل. |
| **قالب الاستجابة** _(اختياري)_ | `response_template` | `Optional[str]` | قالب استجابة مخصص للوكيل. |
| **السماح بتنفيذ الكود** _(اختياري)_ | `allow_code_execution` | `Optional[bool]` | تفعيل تنفيذ الكود للوكيل. الافتراضي False. |
| **الحد الأقصى لإعادة المحاولة** _(اختياري)_ | `max_retry_limit` | `int` | الحد الأقصى لإعادات المحاولة عند حدوث خطأ. الافتراضي 2. |
| **احترام نافذة السياق** _(اختياري)_ | `respect_context_window` | `bool` | إبقاء الرسائل تحت حجم نافذة السياق عبر التلخيص. الافتراضي True. |
| **وضع تنفيذ الكود** _(اختياري)_ | `code_execution_mode` | `Literal["safe", "unsafe"]` | وضع تنفيذ الكود: 'safe' (باستخدام Docker) أو 'unsafe' (مباشر). الافتراضي 'safe'. |
| **متعدد الوسائط** _(اختياري)_ | `multimodal` | `bool` | ما إذا كان الوكيل يدعم القدرات متعددة الوسائط. الافتراضي False. |
| **حقن التاريخ** _(اختياري)_ | `inject_date` | `bool` | ما إذا كان يتم حقن التاريخ الحالي تلقائيًا في المهام. الافتراضي False. |
| **تنسيق التاريخ** _(اختياري)_ | `date_format` | `str` | سلسلة تنسيق التاريخ عند تفعيل inject_date. الافتراضي "%Y-%m-%d" (تنسيق ISO). |
| **الاستدلال** _(اختياري)_ | `reasoning` | `bool` | ما إذا كان يجب على الوكيل التأمل وإنشاء خطة قبل تنفيذ المهمة. الافتراضي False. |
| **الحد الأقصى لمحاولات الاستدلال** _(اختياري)_ | `max_reasoning_attempts` | `Optional[int]` | الحد الأقصى لمحاولات الاستدلال قبل تنفيذ المهمة. إذا None، سيحاول حتى الاستعداد. |
| **المُضمّن** _(اختياري)_ | `embedder` | `Optional[Dict[str, Any]]` | تهيئة المُضمّن المستخدم من قبل الوكيل. |
| **مصادر المعرفة** _(اختياري)_ | `knowledge_sources` | `Optional[List[BaseKnowledgeSource]]` | مصادر المعرفة المتاحة للوكيل. |
| **استخدام أمر النظام** _(اختياري)_ | `use_system_prompt` | `Optional[bool]` | ما إذا كان يُستخدم أمر النظام (لدعم نموذج o1). الافتراضي True. |
## إنشاء الوكلاء
هناك طريقتان شائعتان لإنشاء الوكلاء في CrewAI: باستخدام **تهيئة JSONC (الموصى بها للـ crews الجديدة)** أو تعريفهم **مباشرة في الكود**.
### تهيئة JSONC (موصى بها)
المشاريع الجديدة التي تُنشأ عبر `crewai create crew <name>` تستخدم تهيئة JSON-first. يُعرّف كل Agent في `agents/<agent_name>.jsonc`، ويحدد `crew.jsonc` أي Agents تدخل في الـ crew.
```jsonc agents/researcher.jsonc
{
"role": "{topic} Senior Data Researcher",
"goal": "Uncover cutting-edge developments in {topic}",
"backstory": "You find the most relevant information and present it clearly.",
"llm": "openai/gpt-4o",
"tools": ["SerperDevTool"],
"settings": {
"verbose": true,
"allow_delegation": false
}
}
```
استخدم `{placeholder}` داخل `role` أو `goal` أو `backstory`. ضع القيم الافتراضية في `inputs` داخل `crew.jsonc`؛ وسيطلب `crewai run` أي قيم ناقصة. يمكن وضع حقول السلوك مثل `verbose` و `allow_delegation` و `max_iter` و `memory` و `cache` و `planning_config` في المستوى الأعلى أو داخل `settings`.
<Note>
يدعم JSONC التعليقات والفواصل النهائية. إذا وُجد `agents/<name>.jsonc` و `agents/<name>.json` معًا، يستخدم CrewAI ملف JSONC.
</Note>
### تهيئة YAML الكلاسيكية
المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew <name> --classic` تستخدم `config/agents.yaml` وفئة `@CrewBase` في `crew.py`.
تظل تهيئة YAML مدعومة للمشاريع الحالية المبنية بـ Python/YAML وللفِرق التي تفضل تعريف الوكلاء من خلال فئة `@CrewBase`.
بعد إنشاء مشروع كلاسيكي، انتقل إلى ملف `src/<project_name>/config/agents.yaml` وعدّل القالب ليتوافق مع متطلباتك.
<Note>
ستُستبدل المتغيرات في ملفات YAML (مثل `{topic}`) بقيم من مدخلاتك عند تشغيل الطاقم:
```python Code
crew.kickoff(inputs={'topic': 'AI Agents'})
```
</Note>
إليك مثالًا على كيفية تهيئة الوكلاء باستخدام YAML:
```yaml agents.yaml
# src/<project_name>/config/agents.yaml
researcher:
role: >
{topic} Senior Data Researcher
goal: >
Uncover cutting-edge developments in {topic}
backstory: >
You're a seasoned researcher with a knack for uncovering the latest
developments in {topic}. Known for your ability to find the most relevant
information and present it in a clear and concise manner.
reporting_analyst:
role: >
{topic} Reporting Analyst
goal: >
Create detailed reports based on {topic} data analysis and research findings
backstory: >
You're a meticulous analyst with a keen eye for detail. You're known for
your ability to turn complex data into clear and concise reports, making
it easy for others to understand and act on the information you provide.
```
لاستخدام تهيئة YAML في الكود، أنشئ فئة طاقم ترث من `CrewBase`:
```python Code
# src/<project_name>/crew.py
from crewai import Agent, Crew, Process
from crewai.project import CrewBase, agent, crew
from crewai_tools import SerperDevTool
@CrewBase
class LatestAiDevelopmentCrew():
"""LatestAiDevelopment crew"""
agents_config = "config/agents.yaml"
@agent
def researcher(self) -> Agent:
return Agent(
config=self.agents_config['researcher'], # type: ignore[index]
verbose=True,
tools=[SerperDevTool()]
)
@agent
def reporting_analyst(self) -> Agent:
return Agent(
config=self.agents_config['reporting_analyst'], # type: ignore[index]
verbose=True
)
```
<Note>
يجب أن تتطابق الأسماء المستخدمة في ملفات YAML (`agents.yaml`) مع أسماء
الطرق في كود Python.
</Note>
### تعريف مباشر في الكود
يمكنك إنشاء الوكلاء مباشرة في الكود بإنشاء فئة `Agent`. إليك مثالًا شاملًا يوضح جميع المعاملات المتاحة:
```python Code
from crewai import Agent
from crewai_tools import SerperDevTool
# إنشاء وكيل بجميع المعاملات المتاحة
agent = Agent(
role="Senior Data Scientist",
goal="Analyze and interpret complex datasets to provide actionable insights",
backstory="With over 10 years of experience in data science and machine learning, "
"you excel at finding patterns in complex datasets.",
llm="gpt-4",
function_calling_llm=None,
verbose=False,
allow_delegation=False,
max_iter=20,
max_rpm=None,
max_execution_time=None,
max_retry_limit=2,
allow_code_execution=False,
code_execution_mode="safe",
respect_context_window=True,
use_system_prompt=True,
multimodal=False,
inject_date=False,
date_format="%Y-%m-%d",
reasoning=False,
max_reasoning_attempts=None,
tools=[SerperDevTool()],
knowledge_sources=None,
embedder=None,
system_template=None,
prompt_template=None,
response_template=None,
step_callback=None,
)
```
دعنا نستعرض بعض تركيبات المعاملات الرئيسية لحالات الاستخدام الشائعة:
#### وكيل بحث أساسي
```python Code
research_agent = Agent(
role="Research Analyst",
goal="Find and summarize information about specific topics",
backstory="You are an experienced researcher with attention to detail",
tools=[SerperDevTool()],
verbose=True
)
```
#### وكيل تطوير الكود
```python Code
dev_agent = Agent(
role="Senior Python Developer",
goal="Write and debug Python code",
backstory="Expert Python developer with 10 years of experience",
allow_code_execution=True,
code_execution_mode="safe",
max_execution_time=300,
max_retry_limit=3
)
```
#### وكيل تحليل طويل المدى
```python Code
analysis_agent = Agent(
role="Data Analyst",
goal="Perform deep analysis of large datasets",
backstory="Specialized in big data analysis and pattern recognition",
memory=True,
respect_context_window=True,
max_rpm=10,
function_calling_llm="gpt-4o-mini"
)
```
### تفاصيل المعاملات
#### المعاملات الحرجة
- `role` و `goal` و `backstory` مطلوبة وتشكّل سلوك الوكيل
- `llm` يحدد نموذج اللغة المستخدم (افتراضي: GPT-4 من OpenAI)
#### الذاكرة والسياق
- `memory`: تفعيل للحفاظ على سجل المحادثة
- `respect_context_window`: يمنع مشاكل حد الرموز
- `knowledge_sources`: إضافة قواعد معرفة خاصة بالمجال
#### التحكم في التنفيذ
- `max_iter`: الحد الأقصى للمحاولات قبل تقديم أفضل إجابة
- `max_execution_time`: المهلة بالثواني
- `max_rpm`: تحديد معدل استدعاءات API
- `max_retry_limit`: إعادات المحاولة عند الخطأ
#### تنفيذ الكود
<Warning>
`allow_code_execution` و`code_execution_mode` مهجوران. تمت إزالة `CodeInterpreterTool` من `crewai-tools`. استخدم خدمة بيئة معزولة مخصصة مثل [E2B](https://e2b.dev) أو [Modal](https://modal.com) لتنفيذ الكود بأمان.
</Warning>
- `allow_code_execution` _(مهجور)_: كان يُمكّن تنفيذ الكود المدمج عبر `CodeInterpreterTool`.
- `code_execution_mode` _(مهجور)_: كان يتحكم في وضع التنفيذ (`"safe"` لـ Docker، `"unsafe"` للتنفيذ المباشر).
#### الميزات المتقدمة
- `multimodal`: تفعيل القدرات متعددة الوسائط لمعالجة النص والمحتوى المرئي
- `reasoning`: تمكين الوكيل من التأمل وإنشاء خطط قبل تنفيذ المهام
- `inject_date`: حقن التاريخ الحالي تلقائيًا في أوصاف المهام
#### القوالب
- `system_template`: يحدد السلوك الأساسي للوكيل
- `prompt_template`: ينظم تنسيق الإدخال
- `response_template`: ينسّق استجابات الوكيل
<Note>
عند استخدام القوالب المخصصة، تأكد من تعريف كل من `system_template` و
`prompt_template`. `response_template` اختياري لكن يُوصى به
لتنسيق مخرجات متسق.
</Note>
## أدوات الوكيل
يمكن تجهيز الوكلاء بأدوات متنوعة لتعزيز قدراتهم. يدعم CrewAI أدوات من:
- [مجموعة أدوات CrewAI](https://github.com/joaomdmoura/crewai-tools)
- [أدوات LangChain](https://python.langchain.com/docs/integrations/tools)
إليك كيفية إضافة أدوات لوكيل:
```python Code
from crewai import Agent
from crewai_tools import SerperDevTool, WikipediaTools
# إنشاء الأدوات
search_tool = SerperDevTool()
wiki_tool = WikipediaTools()
# إضافة أدوات للوكيل
researcher = Agent(
role="AI Technology Researcher",
goal="Research the latest AI developments",
tools=[search_tool, wiki_tool],
verbose=True
)
```
## التفاعل المباشر مع الوكيل عبر `kickoff()`
يمكن استخدام الوكلاء مباشرة بدون المرور بمهمة أو سير عمل طاقم باستخدام طريقة `kickoff()`. يوفر هذا طريقة أبسط للتفاعل مع وكيل عندما لا تحتاج إلى إمكانيات تنسيق الطاقم الكاملة.
```python Code
from crewai import Agent
from crewai_tools import SerperDevTool
# إنشاء وكيل
researcher = Agent(
role="AI Technology Researcher",
goal="Research the latest AI developments",
tools=[SerperDevTool()],
verbose=True
)
# استخدام kickoff() للتفاعل مباشرة مع الوكيل
result = researcher.kickoff("What are the latest developments in language models?")
# الوصول إلى الاستجابة الخام
print(result.raw)
```
## اعتبارات مهمة وأفضل الممارسات
### الأمان وتنفيذ الكود
<Warning>
`allow_code_execution` و`code_execution_mode` مهجوران وتمت إزالة `CodeInterpreterTool`. استخدم خدمة بيئة معزولة مخصصة مثل [E2B](https://e2b.dev) أو [Modal](https://modal.com) لتنفيذ الكود بأمان.
</Warning>
### تحسين الأداء
- استخدم `respect_context_window: true` لمنع مشاكل حد الرموز
- عيّن `max_rpm` مناسبًا لتجنب تحديد المعدل
- فعّل `cache: true` لتحسين الأداء للمهام المتكررة
- اضبط `max_iter` و `max_retry_limit` بناءً على تعقيد المهمة
### إدارة الذاكرة والسياق
- استفد من `knowledge_sources` للمعلومات الخاصة بالمجال
- هيّئ `embedder` عند استخدام نماذج تضمين مخصصة
- استخدم القوالب المخصصة للتحكم الدقيق في سلوك الوكيل
### التعاون بين الوكلاء
- فعّل `allow_delegation: true` عندما يحتاج الوكلاء للعمل معًا
- استخدم `step_callback` لمراقبة وتسجيل تفاعلات الوكلاء
- فكّر في استخدام نماذج LLM مختلفة لأغراض مختلفة
### توافق النموذج
- عيّن `use_system_prompt: false` للنماذج القديمة التي لا تدعم رسائل النظام
- تأكد من أن `llm` المختار يدعم الميزات التي تحتاجها

423
docs/edge/ar/concepts/checkpointing.mdx Normal file
View File

@@ -0,0 +1,423 @@
---
title: Checkpointing
description: حفظ حالة التنفيذ تلقائيا حتى تتمكن الطواقم والتدفقات والوكلاء من الاستئناف بعد الفشل.
icon: floppy-disk
mode: "wide"
---
الـ Checkpointing يحفظ لقطة من حالة التنفيذ أثناء التشغيل بحيث يمكن لطاقم أو تدفق أو وكيل الاستئناف بعد الفشل أو التفرع إلى فرع بديل.
<CardGroup cols={2}>
<Card title="الشرح" icon="lightbulb" href="#الشرح">
كيف يعمل الـ Checkpointing: الأحداث والتخزين والوراثة.
</Card>
<Card title="درس تطبيقي" icon="graduation-cap" href="#درس-تطبيقي-استئناف-طاقم-فاشل">
دليل 5 دقائق: تشغيل، إيقاف، استئناف.
</Card>
<Card title="ادلة عملية" icon="screwdriver-wrench" href="#ادلة-عملية">
وصفات مركزة على المهام لسير العمل الشائع.
</Card>
<Card title="المرجع" icon="book" href="#المرجع">
`CheckpointConfig` والأحداث والمزودات وسطر الأوامر.
</Card>
</CardGroup>
## الشرح
### ما هي نقطة الحفظ
تلتقط نقطة الحفظ كل ما يحتاجه CrewAI لإعادة إنشاء تشغيل أثناء سيره: الحالة الكاملة للطاقم أو التدفق أو الوكيل — التكوين، وذاكرة الوكلاء ومصادر المعرفة، وتقدم المهام، والمخرجات الوسيطة، والحالة الداخلية والسمات — إلى جانب مدخلات الـ kickoff، وسجل الأحداث حتى تلك النقطة، ومعرف نسب يربط نقطة الحفظ بالتشغيل الذي جاءت منه.
الاستعادة تعيد بناء تلك الحالة وتستمر. تتخطى المهام المكتملة، وتعاد ترطيب الذاكرة والمعرفة، ويعمل العمل التابع على نفس المخرجات التي أنتجها التشغيل الأصلي. التفرع يجري نفس الاستعادة تحت نسب جديد، بحيث يكتب الفرع الجديد والتشغيل الأصلي نقاط الحفظ جنبا إلى جنب دون أن يطمس أحدهما الآخر.
### متى تكتب نقاط الحفظ
الـ Checkpointing مدفوع بالأحداث. يشترك وقت التشغيل في الأحداث التي تحددها عبر `on_events` ويكتب نقطة حفظ عند إطلاق أحدها. الافتراضي `task_completed` ينتج نقطة حفظ لكل مهمة منتهية — توازن معقول بين الدقة واستخدام القرص. الأحداث عالية التردد مثل `llm_call_completed` متاحة للاستعادة الدقيقة لكنها تكتب ملفات أكثر بكثير.
### التخزين
يتضمن CrewAI مزودين:
- `JsonProvider` يكتب ملفا لكل نقطة حفظ. قابل للقراءة وسهل التفقد.
- `SqliteProvider` يكتب إلى قاعدة بيانات SQLite واحدة. أفضل لنقاط الحفظ عالية التردد.
كلاهما يحذف أقدم نقاط الحفظ عند تحديد `max_checkpoints`.
<Note>
كتابة نقاط الحفظ بأفضل جهد. فشل نقطة حفظ يسجل لكنه لا يقاطع التشغيل.
</Note>
### نموذج الوراثة
`Crew` و`Flow` و`Agent` كلها تقبل وسيط `checkpoint`. يرث الأبناء من الأب ما لم يحددوا قيمتهم الخاصة أو يمرروا `False` للانسحاب. فعل الـ Checkpointing مرة واحدة على الطاقم وتشارك كل الوكلاء، أو استبعد وكيلا واحدا بشكل انتقائي.
## درس تطبيقي: استئناف طاقم فاشل
هذا الدليل يستغرق حوالي 5 دقائق. ستشغل طاقما بمهمتين، توقفه في المنتصف، ثم تستأنف من نقطة الحفظ المحفوظة.
<Steps>
<Step title="أنشئ الطاقم مع تفعيل الـ Checkpointing">
```python
from crewai import Agent, Crew, Task
researcher = Agent(role="Researcher", goal="Research", backstory="Expert")
writer = Agent(role="Writer", goal="Write", backstory="Expert")
crew = Crew(
agents=[researcher, writer],
tasks=[
Task(description="Research AI trends", agent=researcher, expected_output="bullets"),
Task(description="Write a summary", agent=writer, expected_output="paragraph"),
],
checkpoint=True,
)
```
</Step>
<Step title="شغله وأوقفه بعد المهمة الأولى">
```python
result = crew.kickoff()
```
اضغط `Ctrl+C` بعد انتهاء المهمة الأولى. في `./.checkpoints/`، الملف بصيغة `<timestamp>_<uuid>.json` هو نقطة الحفظ.
</Step>
<Step title="استأنف من نقطة الحفظ">
```python
from crewai import CheckpointConfig
result = crew.kickoff(
from_checkpoint=CheckpointConfig(
restore_from="./.checkpoints/<timestamp>_<uuid>.json",
),
)
```
يتم تخطي مهمة البحث، ويعمل الكاتب على مخرجات البحث المحفوظة، وينتهي الطاقم.
</Step>
</Steps>
## ادلة عملية
<AccordionGroup>
<Accordion title="تفعيل الـ Checkpointing بالإعدادات الافتراضية" icon="play">
```python
crew = Crew(agents=[...], tasks=[...], checkpoint=True)
```
يكتب إلى `./.checkpoints/` عند كل `task_completed`.
</Accordion>
<Accordion title="تخصيص التخزين والتردد" icon="sliders">
```python
from crewai import Crew, CheckpointConfig
crew = Crew(
agents=[...],
tasks=[...],
checkpoint=CheckpointConfig(
location="./my_checkpoints",
on_events=["task_completed", "crew_kickoff_completed"],
max_checkpoints=5,
),
)
```
</Accordion>
<Accordion title="اختيار مزود التخزين" icon="database">
<CodeGroup>
```python JsonProvider
from crewai import Crew, CheckpointConfig
from crewai.state import JsonProvider
crew = Crew(
agents=[...],
tasks=[...],
checkpoint=CheckpointConfig(
location="./my_checkpoints",
provider=JsonProvider(),
max_checkpoints=5,
),
)
```
```python SqliteProvider
from crewai import Crew, CheckpointConfig
from crewai.state import SqliteProvider
crew = Crew(
agents=[...],
tasks=[...],
checkpoint=CheckpointConfig(
location="./.checkpoints.db",
provider=SqliteProvider(),
max_checkpoints=50,
),
)
```
</CodeGroup>
<Tip>
SQLite يفعل وضع journal WAL للقراءات المتزامنة. يفضل لنقاط الحفظ عالية التردد.
</Tip>
</Accordion>
<Accordion title="استبعاد وكيل واحد" icon="user-slash">
```python
crew = Crew(
agents=[
Agent(role="Researcher", ...),
Agent(role="Writer", ..., checkpoint=False),
],
tasks=[...],
checkpoint=True,
)
```
</Accordion>
<Accordion title="التفرع إلى فرع جديد" icon="code-branch">
`fork()` يستعيد نقطة حفظ تحت نسب جديد بحيث لا يتصادم التشغيل الجديد مع الأصلي.
```python
config = CheckpointConfig(restore_from="./my_checkpoints/<file>.json")
crew = Crew.fork(config, branch="experiment-a")
result = crew.kickoff(inputs={"strategy": "aggressive"})
```
تسمية `branch` اختيارية؛ يتم إنشاء واحدة إذا أغفلت.
</Accordion>
<Accordion title="Checkpointing لـ Crew أو Flow أو Agent" icon="cubes">
<Tabs>
<Tab title="Crew">
```python
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, write_task, review_task],
checkpoint=CheckpointConfig(location="./crew_cp"),
)
```
المشغل الافتراضي: `task_completed`.
</Tab>
<Tab title="Flow">
```python
from crewai.flow.flow import Flow, start, listen
from crewai import CheckpointConfig
class MyFlow(Flow):
@start()
def step_one(self):
return "data"
@listen(step_one)
def step_two(self, data):
return process(data)
flow = MyFlow(
checkpoint=CheckpointConfig(
location="./flow_cp",
on_events=["method_execution_finished"],
),
)
result = flow.kickoff()
```
</Tab>
<Tab title="Agent">
```python
agent = Agent(
role="Researcher",
goal="Research topics",
backstory="Expert researcher",
checkpoint=CheckpointConfig(
location="./agent_cp",
on_events=["lite_agent_execution_completed"],
),
)
result = agent.kickoff(messages=[{"role": "user", "content": "Research AI trends"}])
```
</Tab>
</Tabs>
</Accordion>
<Accordion title="كتابة نقطة حفظ يدويا" icon="code">
سجل معالجا على أي حدث واستدع `state.checkpoint()`.
<CodeGroup>
```python Sync
from __future__ import annotations
from typing import TYPE_CHECKING, Any
from crewai.events.event_bus import crewai_event_bus
from crewai.events.types.llm_events import LLMCallCompletedEvent
if TYPE_CHECKING:
from crewai.state.runtime import RuntimeState
@crewai_event_bus.on(LLMCallCompletedEvent)
def on_llm_done(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
path = state.checkpoint("./my_checkpoints")
print(f"تم حفظ نقطة الحفظ: {path}")
```
```python Async
from __future__ import annotations
from typing import TYPE_CHECKING, Any
from crewai.events.event_bus import crewai_event_bus
from crewai.events.types.llm_events import LLMCallCompletedEvent
if TYPE_CHECKING:
from crewai.state.runtime import RuntimeState
@crewai_event_bus.on(LLMCallCompletedEvent)
async def on_llm_done_async(source: Any, event: LLMCallCompletedEvent, state: RuntimeState) -> None:
path = await state.acheckpoint("./my_checkpoints")
print(f"تم حفظ نقطة الحفظ: {path}")
```
</CodeGroup>
يتم تمرير وسيط `state` تلقائيا عندما يقبل المعالج ثلاثة معاملات. راجع [Event Listeners](/ar/concepts/event-listener) لقائمة الأحداث الكاملة.
</Accordion>
<Accordion title="التصفح والاستئناف والتفرع من سطر الأوامر" icon="terminal">
```bash
crewai checkpoint
crewai checkpoint --location ./my_checkpoints
crewai checkpoint --location ./.checkpoints.db
```
<Frame caption="شجرة نقاط الحفظ — الفروع والتفرعات تتداخل تحت أبيها.">
<img src="/images/checkpoint-tui-tree.png" alt="Checkpoint TUI tree view" />
</Frame>
اللوحة اليسرى تجمع نقاط الحفظ حسب الفرع؛ التفرعات تتداخل تحت أبيها. اختيار نقطة حفظ يفتح لوحة التفاصيل مع بياناتها الوصفية وحالة الكيان وتقدم المهام. **Resume** يكمل التشغيل؛ **Fork** يبدأ فرعا جديدا.
<Frame caption="تبويب النظرة العامة — البيانات الوصفية وحالة الكيان وملخص التشغيل.">
<img src="/images/checkpoint-tui-detail-overview.png" alt="Checkpoint detail overview tab" />
</Frame>
لوحة التفاصيل تعرض منطقتين قابلتين للتحرير:
- **Inputs** — مدخلات الـ kickoff الأصلية، معبأة مسبقا وقابلة للتحرير.
<Frame>
<img src="/images/checkpoint-tui-detail-inputs.png" alt="Editable kickoff inputs" />
</Frame>
- **مخرجات المهام** — مخرجات المهام المكتملة. تحرير مخرج والضغط على **Fork** يبطل المهام التابعة لتعاد بالسياق المعدل.
<Frame>
<img src="/images/checkpoint-tui-detail-tasks.png" alt="Editable task outputs" />
</Frame>
<Frame caption="عرض التفرع — تأكيد فرع جديد من نقطة الحفظ المختارة.">
<img src="/images/checkpoint-tui-details-fork.png" alt="Fork confirmation panel" />
</Frame>
<Tip>
مفيد لاستكشاف "ماذا لو": تفرع، عدل، راقب.
</Tip>
</Accordion>
<Accordion title="تفقد نقاط الحفظ بدون TUI" icon="magnifying-glass">
```bash
crewai checkpoint list ./my_checkpoints
crewai checkpoint info ./my_checkpoints/<file>.json
crewai checkpoint info ./.checkpoints.db
```
</Accordion>
</AccordionGroup>
## المرجع
### `CheckpointConfig`
<ParamField path="location" type="str" default='"./.checkpoints"'>
وجهة التخزين. مجلد لـ `JsonProvider`، مسار ملف قاعدة بيانات لـ `SqliteProvider`.
</ParamField>
<ParamField path="on_events" type='list[CheckpointEventType | Literal["*"]]' default='["task_completed"]'>
أنواع الأحداث التي تطلق نقطة حفظ. `CheckpointEventType` هو `Literal` — مدقق الأنواع يكمل تلقائيا ويرفض القيم غير المدعومة. راجع [أنواع الأحداث](#أنواع-الأحداث) للقائمة الكاملة.
</ParamField>
<ParamField path="provider" type="BaseProvider" default="JsonProvider()">
واجهة التخزين. `JsonProvider` أو `SqliteProvider`.
</ParamField>
<ParamField path="max_checkpoints" type="int | None" default="None">
الحد الاقصى لنقاط الحفظ المحتفظ بها. الأقدم تحذف بعد كل كتابة.
</ParamField>
<ParamField path="restore_from" type="Path | str | None" default="None">
نقطة الحفظ المراد استعادتها عند تمريرها عبر `from_checkpoint`.
</ParamField>
### قيم حقل `checkpoint`
مقبولة في `Crew` و`Flow` و`Agent`.
<ParamField path="None" type="افتراضي">
يرث من الأب.
</ParamField>
<ParamField path="True" type="bool">
تفعيل بالإعدادات الافتراضية.
</ParamField>
<ParamField path="False" type="bool">
انسحاب صريح. يوقف الوراثة.
</ParamField>
<ParamField path="CheckpointConfig(...)" type="CheckpointConfig">
إعدادات مخصصة.
</ParamField>
### أنواع الأحداث
يقبل `on_events` أي مجموعة من قيم `CheckpointEventType`. الافتراضي `["task_completed"]` يكتب نقطة حفظ لكل مهمة منتهية، و`["*"]` يطابق جميع الأحداث.
<Warning>
`["*"]` والأحداث عالية التردد مثل `llm_call_completed` تكتب نقاط حفظ كثيرة وقد تضر بالاداء. استخدمها مع `max_checkpoints`.
</Warning>
<Expandable title="جميع الأحداث المدعومة">
- **Task** — `task_started`, `task_completed`, `task_failed`, `task_evaluation`
- **Crew** — `crew_kickoff_started`, `crew_kickoff_completed`, `crew_kickoff_failed`, `crew_train_started`, `crew_train_completed`, `crew_train_failed`, `crew_test_started`, `crew_test_completed`, `crew_test_failed`, `crew_test_result`
- **Agent** — `agent_execution_started`, `agent_execution_completed`, `agent_execution_error`, `lite_agent_execution_started`, `lite_agent_execution_completed`, `lite_agent_execution_error`, `agent_evaluation_started`, `agent_evaluation_completed`, `agent_evaluation_failed`
- **Flow** — `flow_created`, `flow_started`, `flow_finished`, `flow_paused`, `method_execution_started`, `method_execution_finished`, `method_execution_failed`, `method_execution_paused`, `human_feedback_requested`, `human_feedback_received`, `flow_input_requested`, `flow_input_received`
- **LLM** — `llm_call_started`, `llm_call_completed`, `llm_call_failed`, `llm_stream_chunk`, `llm_thinking_chunk`
- **LLM Guardrail** — `llm_guardrail_started`, `llm_guardrail_completed`, `llm_guardrail_failed`
- **Tool** — `tool_usage_started`, `tool_usage_finished`, `tool_usage_error`, `tool_validate_input_error`, `tool_selection_error`, `tool_execution_error`
- **Memory** — `memory_save_started`, `memory_save_completed`, `memory_save_failed`, `memory_query_started`, `memory_query_completed`, `memory_query_failed`, `memory_retrieval_started`, `memory_retrieval_completed`, `memory_retrieval_failed`
- **Knowledge** — `knowledge_search_query_started`, `knowledge_search_query_completed`, `knowledge_query_started`, `knowledge_query_completed`, `knowledge_query_failed`, `knowledge_search_query_failed`
- **Reasoning** — `agent_reasoning_started`, `agent_reasoning_completed`, `agent_reasoning_failed`
- **MCP** — `mcp_connection_started`, `mcp_connection_completed`, `mcp_connection_failed`, `mcp_tool_execution_started`, `mcp_tool_execution_completed`, `mcp_tool_execution_failed`, `mcp_config_fetch_failed`
- **Observation** — `step_observation_started`, `step_observation_completed`, `step_observation_failed`, `plan_refinement`, `plan_replan_triggered`, `goal_achieved_early`
- **Skill** — `skill_discovery_started`, `skill_discovery_completed`, `skill_loaded`, `skill_activated`, `skill_load_failed`
- **Logging** — `agent_logs_started`, `agent_logs_execution`
- **A2A** — `a2a_delegation_started`, `a2a_delegation_completed`, `a2a_conversation_started`, `a2a_conversation_completed`, `a2a_message_sent`, `a2a_response_received`, `a2a_polling_started`, `a2a_polling_status`, `a2a_push_notification_registered`, `a2a_push_notification_received`, `a2a_push_notification_sent`, `a2a_push_notification_timeout`, `a2a_streaming_started`, `a2a_streaming_chunk`, `a2a_agent_card_fetched`, `a2a_authentication_failed`, `a2a_artifact_received`, `a2a_connection_error`, `a2a_server_task_started`, `a2a_server_task_completed`, `a2a_server_task_canceled`, `a2a_server_task_failed`, `a2a_parallel_delegation_started`, `a2a_parallel_delegation_completed`, `a2a_transport_negotiated`, `a2a_content_type_negotiated`, `a2a_context_created`, `a2a_context_expired`, `a2a_context_idle`, `a2a_context_completed`, `a2a_context_pruned`
- **إشارات النظام** — `SIGTERM`, `SIGINT`, `SIGHUP`, `SIGTSTP`, `SIGCONT`
- **حرف بدل** — `"*"` يطابق جميع الأحداث.
</Expandable>
### مزودات التخزين
<ParamField path="JsonProvider" type="provider">
ملف واحد لكل نقطة حفظ بصيغة `<timestamp>_<uuid>.json` داخل `location`.
</ParamField>
<ParamField path="SqliteProvider" type="provider">
ملف قاعدة بيانات واحد في `location` مع journaling WAL.
</ParamField>
### سطر الأوامر
| الامر | الغرض |
|:------|:------|
| `crewai checkpoint` | تشغيل TUI؛ كشف التخزين تلقائيا. |
| `crewai checkpoint --location <path>` | تشغيل TUI على موقع محدد. |
| `crewai checkpoint list <path>` | سرد نقاط الحفظ. |
| `crewai checkpoint info <path>` | تفقد ملف نقطة حفظ أو آخر مدخل في قاعدة بيانات SQLite. |

302
docs/edge/ar/concepts/cli.mdx Normal file
View File

@@ -0,0 +1,302 @@
---
title: واجهة سطر الأوامر
description: تعرّف على كيفية استخدام واجهة سطر أوامر CrewAI للتفاعل مع CrewAI.
icon: terminal
mode: "wide"
---
<Warning>
منذ الإصدار 0.140.0، بدأ CrewAI AMP عملية نقل مزود تسجيل الدخول.
لذلك، تم تحديث تدفق المصادقة عبر CLI. المستخدمون الذين يسجلون الدخول
باستخدام Google، أو الذين أنشأوا حساباتهم بعد 3 يوليو 2025 لن يتمكنوا
من تسجيل الدخول مع الإصدارات القديمة من مكتبة `crewai`.
</Warning>
## نظرة عامة
توفر واجهة سطر أوامر CrewAI مجموعة من الأوامر للتفاعل مع CrewAI، مما يتيح لك إنشاء وتدريب وتشغيل وإدارة الأطقم والتدفقات.
## التثبيت
لاستخدام واجهة سطر أوامر CrewAI، تأكد من تثبيت CrewAI:
```shell Terminal
pip install crewai
```
## الاستخدام الأساسي
الهيكل الأساسي لأمر CrewAI CLI هو:
```shell Terminal
crewai [COMMAND] [OPTIONS] [ARGUMENTS]
```
## الأوامر المتاحة
### 1. إنشاء
إنشاء طاقم أو تدفق جديد.
```shell Terminal
crewai create [OPTIONS] TYPE NAME
```
- `TYPE`: اختر بين "crew" أو "flow"
- `NAME`: اسم الطاقم أو التدفق
مثال:
```shell Terminal
crewai create crew my_new_crew
crewai create flow my_new_flow
```
افتراضيًا، ينشئ `crewai create crew` مشروعًا JSON-first يحتوي على `crew.jsonc` و `agents/*.jsonc`. استخدم `crewai create crew my_new_crew --classic` فقط إذا أردت البنية القديمة Python/YAML مع `crew.py` و `config/agents.yaml` و `config/tasks.yaml`.
### 2. الإصدار
عرض الإصدار المثبت من CrewAI.
```shell Terminal
crewai version [OPTIONS]
```
- `--tools`: (اختياري) عرض الإصدار المثبت من أدوات CrewAI
### 3. التدريب
تدريب الطاقم لعدد محدد من التكرارات.
```shell Terminal
crewai train [OPTIONS]
```
- `-n, --n_iterations INTEGER`: عدد تكرارات التدريب (افتراضي: 5)
- `-f, --filename TEXT`: مسار ملف مخصص للتدريب (افتراضي: "trained_agents_data.pkl")
### 4. الإعادة
إعادة تنفيذ الطاقم من مهمة محددة.
```shell Terminal
crewai replay [OPTIONS]
```
- `-t, --task_id TEXT`: إعادة تنفيذ الطاقم من معرّف المهمة هذا، بما في ذلك جميع المهام اللاحقة
### 5. سجل مخرجات المهام
استرجاع أحدث مخرجات مهام crew.kickoff().
```shell Terminal
crewai log-tasks-outputs
```
### 6. إعادة تعيين الذاكرة
إعادة تعيين ذاكرة الطاقم (طويلة، قصيرة، الكيانات، أحدث مخرجات التشغيل).
```shell Terminal
crewai reset-memories [OPTIONS]
```
- `-l, --long`: إعادة تعيين الذاكرة طويلة المدى
- `-s, --short`: إعادة تعيين الذاكرة قصيرة المدى
- `-e, --entities`: إعادة تعيين ذاكرة الكيانات
- `-k, --kickoff-outputs`: إعادة تعيين أحدث مخرجات التشغيل
- `-kn, --knowledge`: إعادة تعيين تخزين المعرفة
- `-akn, --agent-knowledge`: إعادة تعيين تخزين معرفة الوكيل
- `-a, --all`: إعادة تعيين جميع الذاكرات
### 7. الاختبار
اختبار الطاقم وتقييم النتائج.
```shell Terminal
crewai test [OPTIONS]
```
- `-n, --n_iterations INTEGER`: عدد تكرارات الاختبار (افتراضي: 3)
- `-m, --model TEXT`: نموذج LLM لتشغيل الاختبارات (افتراضي: "gpt-4o-mini")
### 8. التشغيل
تشغيل الطاقم أو التدفق.
```shell Terminal
crewai run
```
<Note>
بدءًا من الإصدار 0.103.0، يمكن استخدام أمر `crewai run` لتشغيل
كل من الأطقم القياسية والتدفقات. للتدفقات، يكتشف تلقائيًا النوع
من pyproject.toml ويشغّل الأمر المناسب. هذه هي الطريقة الموصى بها
لتشغيل كل من الأطقم والتدفقات.
</Note>
### 9. الدردشة
بدءًا من الإصدار `0.98.0`، عند تشغيل أمر `crewai chat`، تبدأ جلسة تفاعلية مع طاقمك. سيرشدك المساعد الذكي بطلب المدخلات اللازمة لتنفيذ الطاقم. بمجرد توفير جميع المدخلات، سينفذ الطاقم مهامه.
```shell Terminal
crewai chat
```
<Note>
مهم: عيّن خاصية `chat_llm` في تعريف الـ crew لتفعيل هذا الأمر.
للـ crews بنمط JSON-first، أضفها إلى `crew.jsonc`:
```jsonc
{
"name": "My Crew",
"agents": ["researcher"],
"tasks": [],
"chat_llm": "openai/gpt-4o"
}
```
للـ crews الكلاسيكية Python/YAML، عيّنها في `crew.py`:
```python
@crew
def crew(self) -> Crew:
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
chat_llm="gpt-4o",
)
```
</Note>
### 10. النشر
نشر الطاقم أو التدفق إلى [CrewAI AMP](https://app.crewai.com).
- **المصادقة**: تحتاج لتكون مصادقًا للنشر إلى CrewAI AMP.
```shell Terminal
crewai login
```
- **إنشاء نشر**:
```shell Terminal
crewai deploy create
```
- **نشر الطاقم**:
```shell Terminal
crewai deploy push
```
- **حالة النشر**:
```shell Terminal
crewai deploy status
```
- **سجلات النشر**:
```shell Terminal
crewai deploy logs
```
- **عرض النشرات**:
```shell Terminal
crewai deploy list
```
- **حذف النشر**:
```shell Terminal
crewai deploy remove
```
### 11. إدارة المؤسسة
إدارة مؤسسات CrewAI AMP.
```shell Terminal
crewai org [COMMAND] [OPTIONS]
```
- `list`: عرض جميع المؤسسات
- `current`: عرض المؤسسة النشطة حاليًا
- `switch`: التبديل إلى مؤسسة محددة
### 12. تسجيل الدخول
المصادقة مع CrewAI AMP باستخدام تدفق رمز الجهاز الآمن.
```shell Terminal
crewai login
```
### 13. إدارة التهيئة
إدارة إعدادات تهيئة CLI لـ CrewAI.
```shell Terminal
crewai config [COMMAND] [OPTIONS]
```
- `list`: عرض جميع معاملات التهيئة
- `set`: تعيين معامل تهيئة
- `reset`: إعادة تعيين جميع المعاملات إلى القيم الافتراضية
### 14. إدارة التتبع
إدارة تفضيلات جمع التتبع لعمليات الطاقم والتدفق.
```shell Terminal
crewai traces [COMMAND]
```
- `enable`: تفعيل جمع التتبع
- `disable`: تعطيل جمع التتبع
- `status`: عرض حالة جمع التتبع الحالية
#### كيف يعمل التتبع
يتم التحكم في جمع التتبع بفحص ثلاثة إعدادات بترتيب الأولوية:
1. **علامة صريحة في الكود** (الأولوية الأعلى):
```python
crew = Crew(agents=[...], tasks=[...], tracing=True) # تفعيل دائمًا
crew = Crew(agents=[...], tasks=[...], tracing=False) # تعطيل دائمًا
crew = Crew(agents=[...], tasks=[...]) # فحص الأولويات الأدنى
```
2. **متغير البيئة** (الأولوية الثانية):
```env
CREWAI_TRACING_ENABLED=true
```
3. **تفضيل المستخدم** (الأولوية الأدنى):
```shell Terminal
crewai traces enable
```
<Note>
**لتفعيل التتبع**، استخدم أيًا من هذه الطرق:
- عيّن `tracing=True` في كود الطاقم/التدفق، أو
- أضف `CREWAI_TRACING_ENABLED=true` إلى ملف `.env`، أو
- شغّل `crewai traces enable`
**لتعطيل التتبع**، استخدم أيًا من هذه الطرق:
- عيّن `tracing=False` في كود الطاقم/التدفق، أو
- أزل أو عيّن `false` لمتغير `CREWAI_TRACING_ENABLED`، أو
- شغّل `crewai traces disable`
</Note>
<Tip>
يتعامل CrewAI CLI مع المصادقة لمستودع الأدوات تلقائيًا عند
إضافة حزم إلى مشروعك. فقط أضف `crewai` قبل أي أمر `uv`
لاستخدامه. مثلًا `crewai uv add requests`.
</Tip>
<Note>
تُخزن إعدادات التهيئة في `~/.config/crewai/settings.json`. بعض
الإعدادات مثل اسم المؤسسة ومعرّفها للقراءة فقط وتُدار من خلال
أوامر المصادقة والمؤسسة.
</Note>

363
docs/edge/ar/concepts/collaboration.mdx Normal file
View File

@@ -0,0 +1,363 @@
---
title: التعاون
description: كيفية تمكين الوكلاء من العمل معًا وتفويض المهام والتواصل بفعالية داخل فرق CrewAI.
icon: screen-users
mode: "wide"
---
## نظرة عامة
يُمكّن التعاون في CrewAI الوكلاء من العمل معًا كفريق عن طريق تفويض المهام وطرح الأسئلة للاستفادة من خبرات بعضهم البعض. عندما يكون `allow_delegation=True`، يحصل الوكلاء تلقائيًا على أدوات تعاون قوية.
## البدء السريع: تفعيل التعاون
```python
from crewai import Agent, Crew, Task
# تفعيل التعاون للوكلاء
researcher = Agent(
role="Research Specialist",
goal="Conduct thorough research on any topic",
backstory="Expert researcher with access to various sources",
allow_delegation=True, # الإعداد الرئيسي للتعاون
verbose=True
)
writer = Agent(
role="Content Writer",
goal="Create engaging content based on research",
backstory="Skilled writer who transforms research into compelling content",
allow_delegation=True, # يُمكّن طرح الأسئلة على الوكلاء الآخرين
verbose=True
)
# يمكن للوكلاء الآن التعاون تلقائيًا
crew = Crew(
agents=[researcher, writer],
tasks=[...],
verbose=True
)
```
## كيف يعمل تعاون الوكلاء
عندما يكون `allow_delegation=True`، يوفر CrewAI تلقائيًا للوكلاء أداتين قويتين:
### 1. **أداة تفويض العمل**
تسمح للوكلاء بتعيين مهام لزملاء الفريق ذوي الخبرة المحددة.
```python
# يحصل الوكيل تلقائيًا على هذه الأداة:
# Delegate work to coworker(task: str, context: str, coworker: str)
```
### 2. **أداة طرح الأسئلة**
تُمكّن الوكلاء من طرح أسئلة محددة لجمع المعلومات من الزملاء.
```python
# يحصل الوكيل تلقائيًا على هذه الأداة:
# Ask question to coworker(question: str, context: str, coworker: str)
```
## التعاون في الممارسة
إليك مثالًا كاملًا يوضح تعاون الوكلاء في مهمة إنشاء المحتوى:
```python
from crewai import Agent, Crew, Task, Process
# إنشاء وكلاء تعاونيين
researcher = Agent(
role="Research Specialist",
goal="Find accurate, up-to-date information on any topic",
backstory="""You're a meticulous researcher with expertise in finding
reliable sources and fact-checking information across various domains.""",
allow_delegation=True,
verbose=True
)
writer = Agent(
role="Content Writer",
goal="Create engaging, well-structured content",
backstory="""You're a skilled content writer who excels at transforming
research into compelling, readable content for different audiences.""",
allow_delegation=True,
verbose=True
)
editor = Agent(
role="Content Editor",
goal="Ensure content quality and consistency",
backstory="""You're an experienced editor with an eye for detail,
ensuring content meets high standards for clarity and accuracy.""",
allow_delegation=True,
verbose=True
)
# إنشاء مهمة تشجع التعاون
article_task = Task(
description="""Write a comprehensive 1000-word article about 'The Future of AI in Healthcare'.
The article should include:
- Current AI applications in healthcare
- Emerging trends and technologies
- Potential challenges and ethical considerations
- Expert predictions for the next 5 years
Collaborate with your teammates to ensure accuracy and quality.""",
expected_output="A well-researched, engaging 1000-word article with proper structure and citations",
agent=writer # الكاتب يقود، لكن يمكنه تفويض البحث إلى الباحث
)
# إنشاء طاقم تعاوني
crew = Crew(
agents=[researcher, writer, editor],
tasks=[article_task],
process=Process.sequential,
verbose=True
)
result = crew.kickoff()
```
## أنماط التعاون
### النمط 1: بحث ← كتابة ← تحرير
```python
research_task = Task(
description="Research the latest developments in quantum computing",
expected_output="Comprehensive research summary with key findings and sources",
agent=researcher
)
writing_task = Task(
description="Write an article based on the research findings",
expected_output="Engaging 800-word article about quantum computing",
agent=writer,
context=[research_task] # يحصل على مخرجات البحث كسياق
)
editing_task = Task(
description="Edit and polish the article for publication",
expected_output="Publication-ready article with improved clarity and flow",
agent=editor,
context=[writing_task] # يحصل على مسودة المقال كسياق
)
```
### النمط 2: مهمة واحدة تعاونية
```python
collaborative_task = Task(
description="""Create a marketing strategy for a new AI product.
Writer: Focus on messaging and content strategy
Researcher: Provide market analysis and competitor insights
Work together to create a comprehensive strategy.""",
expected_output="Complete marketing strategy with research backing",
agent=writer # الوكيل القائد، لكن يمكنه التفويض إلى الباحث
)
```
## التعاون الهرمي
للمشاريع المعقدة، استخدم عملية هرمية مع وكيل مدير:
```python
from crewai import Agent, Crew, Task, Process
# وكيل المدير ينسق الفريق
manager = Agent(
role="Project Manager",
goal="Coordinate team efforts and ensure project success",
backstory="Experienced project manager skilled at delegation and quality control",
allow_delegation=True,
verbose=True
)
# وكلاء متخصصون
researcher = Agent(
role="Researcher",
goal="Provide accurate research and analysis",
backstory="Expert researcher with deep analytical skills",
allow_delegation=False, # المتخصصون يركزون على خبرتهم
verbose=True
)
writer = Agent(
role="Writer",
goal="Create compelling content",
backstory="Skilled writer who creates engaging content",
allow_delegation=False,
verbose=True
)
# مهمة يقودها المدير
project_task = Task(
description="Create a comprehensive market analysis report with recommendations",
expected_output="Executive summary, detailed analysis, and strategic recommendations",
agent=manager # المدير سيفوّض إلى المتخصصين
)
# طاقم هرمي
crew = Crew(
agents=[manager, researcher, writer],
tasks=[project_task],
process=Process.hierarchical, # المدير ينسق كل شيء
manager_llm="gpt-4o", # تحديد LLM للمدير
verbose=True
)
```
## أفضل ممارسات التعاون
### 1. **تحديد الأدوار بوضوح**
```python
# جيد: أدوار محددة ومتكاملة
researcher = Agent(role="Market Research Analyst", ...)
writer = Agent(role="Technical Content Writer", ...)
# تجنب: أدوار متداخلة أو غامضة
agent1 = Agent(role="General Assistant", ...)
agent2 = Agent(role="Helper", ...)
```
### 2. **تفعيل التفويض الاستراتيجي**
```python
# فعّل التفويض للمنسقين والعامين
lead_agent = Agent(
role="Content Lead",
allow_delegation=True, # يمكنه التفويض إلى المتخصصين
...
)
# عطّل للمتخصصين المركّزين (اختياري)
specialist_agent = Agent(
role="Data Analyst",
allow_delegation=False, # يركز على الخبرة الأساسية
...
)
```
### 3. **مشاركة السياق**
```python
# استخدم معامل context لاعتماديات المهام
writing_task = Task(
description="Write article based on research",
agent=writer,
context=[research_task], # يشارك نتائج البحث
...
)
```
### 4. **أوصاف المهام الواضحة**
```python
# أوصاف محددة وقابلة للتنفيذ
Task(
description="""Research competitors in the AI chatbot space.
Focus on: pricing models, key features, target markets.
Provide data in a structured format.""",
...
)
# تجنب: أوصاف غامضة لا توجه التعاون
Task(description="Do some research about chatbots", ...)
```
## استكشاف أخطاء التعاون وإصلاحها
### المشكلة: الوكلاء لا يتعاونون
**الأعراض:** يعمل الوكلاء بمعزل، لا يحدث تفويض
```python
# الحل: تأكد من تفعيل التفويض
agent = Agent(
role="...",
allow_delegation=True, # هذا مطلوب!
...
)
```
### المشكلة: كثرة الذهاب والإياب
**الأعراض:** يطرح الوكلاء أسئلة مفرطة، تقدم بطيء
```python
# الحل: وفّر سياقًا أفضل وأدوارًا محددة
Task(
description="""Write a technical blog post about machine learning.
Context: Target audience is software developers with basic ML knowledge.
Length: 1200 words
Include: code examples, practical applications, best practices
If you need specific technical details, delegate research to the researcher.""",
...
)
```
### المشكلة: حلقات التفويض
**الأعراض:** يفوّض الوكلاء ذهابًا وإيابًا بلا نهاية
```python
# الحل: تسلسل هرمي واضح ومسؤوليات
manager = Agent(role="Manager", allow_delegation=True)
specialist1 = Agent(role="Specialist A", allow_delegation=False) # لا إعادة تفويض
specialist2 = Agent(role="Specialist B", allow_delegation=False)
```
## ميزات التعاون المتقدمة
### قواعد التعاون المخصصة
```python
# تعيين إرشادات تعاون محددة في خلفية الوكيل
agent = Agent(
role="Senior Developer",
backstory="""You lead development projects and coordinate with team members.
Collaboration guidelines:
- Delegate research tasks to the Research Analyst
- Ask the Designer for UI/UX guidance
- Consult the QA Engineer for testing strategies
- Only escalate blocking issues to the Project Manager""",
allow_delegation=True
)
```
### مراقبة التعاون
```python
def track_collaboration(output):
"""تتبع أنماط التعاون"""
if "Delegate work to coworker" in output.raw:
print("Delegation occurred")
if "Ask question to coworker" in output.raw:
print("Question asked")
crew = Crew(
agents=[...],
tasks=[...],
step_callback=track_collaboration, # مراقبة التعاون
verbose=True
)
```
## الذاكرة والتعلم
تمكين الوكلاء من تذكر التعاونات السابقة:
```python
agent = Agent(
role="Content Lead",
memory=True, # يتذكر التفاعلات السابقة
allow_delegation=True,
verbose=True
)
```
مع تفعيل الذاكرة، يتعلم الوكلاء من التعاونات السابقة ويحسّنون قرارات التفويض بمرور الوقت.
## الخطوات التالية
- **جرّب الأمثلة**: ابدأ بمثال التعاون الأساسي
- **جرّب أدوارًا مختلفة**: اختبر تركيبات أدوار وكلاء مختلفة
- **راقب التفاعلات**: استخدم `verbose=True` لرؤية التعاون في العمل
- **حسّن أوصاف المهام**: المهام الواضحة تؤدي إلى تعاون أفضل
- **وسّع النطاق**: جرّب العمليات الهرمية للمشاريع المعقدة
يحوّل التعاون وكلاء الذكاء الاصطناعي الفرديين إلى فرق قوية يمكنها معالجة التحديات المعقدة ومتعددة الأوجه معًا.

245
docs/edge/ar/concepts/crews.mdx Normal file
View File

@@ -0,0 +1,245 @@
---
title: الأطقم
description: فهم واستخدام الأطقم في إطار عمل CrewAI مع خصائص ووظائف شاملة.
icon: people-group
mode: "wide"
---
## نظرة عامة
يمثل الطاقم في CrewAI مجموعة تعاونية من الوكلاء يعملون معًا لتحقيق مجموعة من المهام. يحدد كل طاقم استراتيجية تنفيذ المهام وتعاون الوكلاء وسير العمل العام.
## خصائص الطاقم
| الخاصية | المعامل | الوصف |
| :------------------------------------ | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **المهام** | `tasks` | قائمة المهام المعيّنة للطاقم. |
| **الوكلاء** | `agents` | قائمة الوكلاء الذين يشكلون جزءًا من الطاقم. |
| **العملية** _(اختياري)_ | `process` | تدفق العملية (مثل تسلسلي، هرمي) الذي يتبعه الطاقم. الافتراضي `sequential`. |
| **الوضع المفصل** _(اختياري)_ | `verbose` | مستوى التفصيل في التسجيل أثناء التنفيذ. الافتراضي `False`. |
| **LLM المدير** _(اختياري)_ | `manager_llm` | نموذج اللغة المستخدم بواسطة وكيل المدير في العملية الهرمية. **مطلوب عند استخدام العملية الهرمية.** |
| **LLM استدعاء الدوال** _(اختياري)_ | `function_calling_llm` | إذا مُرر، سيستخدم الطاقم هذا LLM لاستدعاء دوال الأدوات لجميع الوكلاء. يمكن لكل وكيل أن يكون له LLM خاص يتجاوز LLM الطاقم. |
| **التهيئة** _(اختياري)_ | `config` | إعدادات تهيئة اختيارية للطاقم، بتنسيق `Json` أو `Dict[str, Any]`. |
| **الحد الأقصى لـ RPM** _(اختياري)_ | `max_rpm` | الحد الأقصى للطلبات في الدقيقة. الافتراضي `None`. |
| **الذاكرة** _(اختياري)_ | `memory` | تُستخدم لتخزين ذاكرات التنفيذ (قصيرة المدى، طويلة المدى، ذاكرة الكيانات). |
| **التخزين المؤقت** _(اختياري)_ | `cache` | يحدد ما إذا كان يُستخدم تخزين مؤقت لنتائج تنفيذ الأدوات. الافتراضي `True`. |
| **المُضمّن** _(اختياري)_ | `embedder` | تهيئة المُضمّن المستخدم من قبل الطاقم. الافتراضي `{"provider": "openai"}`. |
| **دالة الخطوة** _(اختياري)_ | `step_callback` | دالة تُستدعى بعد كل خطوة لكل وكيل. |
| **دالة المهمة** _(اختياري)_ | `task_callback` | دالة تُستدعى بعد اكتمال كل مهمة. |
| **مشاركة الطاقم** _(اختياري)_ | `share_crew` | ما إذا كنت تريد مشاركة معلومات الطاقم الكاملة وتنفيذه مع فريق CrewAI. |
| **ملف سجل المخرجات** _(اختياري)_ | `output_log_file` | عيّن True لحفظ السجلات كـ logs.txt أو وفّر مسار ملف. الافتراضي `None`. |
| **وكيل المدير** _(اختياري)_ | `manager_agent` | يعيّن وكيلًا مخصصًا سيُستخدم كمدير. |
| **التخطيط** *(اختياري)* | `planning` | يضيف قدرة التخطيط للطاقم. |
| **LLM التخطيط** *(اختياري)* | `planning_llm` | نموذج اللغة المستخدم بواسطة AgentPlanner في عملية التخطيط. |
| **مصادر المعرفة** _(اختياري)_ | `knowledge_sources` | مصادر المعرفة المتاحة على مستوى الطاقم، يمكن لجميع الوكلاء الوصول إليها. |
| **البث** _(اختياري)_ | `stream` | تفعيل مخرجات البث لتلقي تحديثات في الوقت الفعلي. الافتراضي `False`. |
<Tip>
**الحد الأقصى لـ RPM للطاقم**: تعيّن خاصية `max_rpm` الحد الأقصى للطلبات في الدقيقة التي يمكن للطاقم تنفيذها لتجنب حدود المعدل وستتجاوز إعدادات `max_rpm` الفردية للوكلاء إذا عيّنتها.
</Tip>
## إنشاء الأطقم
هناك طريقتان رئيسيتان لإنشاء الأطقم في CrewAI: باستخدام **تهيئة JSONC (الموصى بها للـ crews الجديدة)** أو تعريفها **مباشرة في الكود** للمشاريع الكلاسيكية والحالات المتقدمة.
### تهيئة JSONC (موصى بها)
المشاريع الجديدة التي تُنشأ عبر `crewai create crew <name>` تستخدم `crew.jsonc` لإعدادات الـ crew والمهام، وملفًا منفصلًا لكل Agent داخل `agents/`. يكتشف `crewai run` ملف `crew.jsonc` أو `crew.json`، ويحمّل الـ Agents المشار إليها، ويطلب قيم placeholders الناقصة، ثم يبدأ الـ crew.
```jsonc crew.jsonc
{
"name": "Market Research Crew",
"agents": ["researcher", "analyst"],
"tasks": [
{
"name": "research",
"description": "Research {topic} and collect the most relevant facts.",
"expected_output": "Structured research notes about {topic}.",
"agent": "researcher"
},
{
"name": "analysis",
"description": "Analyze the research and write a concise report.",
"expected_output": "A markdown report with findings and recommendations.",
"agent": "analyst",
"context": ["research"],
"output_file": "output/report.md"
}
],
"process": "sequential",
"verbose": true,
"memory": true,
"inputs": {
"topic": "AI Agents"
}
}
```
كل عنصر في `agents` يُحل أولًا إلى `agents/<name>.jsonc` ثم إلى `agents/<name>.json`. للـ crews الهرمية، استخدم `"process": "hierarchical"` مع `manager_llm` أو `manager_agent`.
<Warning>
شغّل مشاريع JSON crew من مصادر تثق بها فقط. أدوات `custom:<name>` ومراجع `{"python": "module.attribute"}` تنفذ كود Python محليًا عند تحميل الـ crew.
</Warning>
### تهيئة YAML الكلاسيكية
المشاريع الكلاسيكية التي تُنشأ عبر `crewai create crew <name> --classic` تستخدم `crew.py` و `config/agents.yaml` و `config/tasks.yaml` والمزيّنات `@CrewBase` و `@agent` و `@task` و `@crew`.
تظل هذه الطريقة مدعومة للمشاريع الحالية المبنية بـ Python/YAML وللفِرق التي تحتاج تحكمًا صريحًا عبر decorators.
```python code
from crewai import Agent, Crew, Task, Process
from crewai.project import CrewBase, agent, task, crew, before_kickoff, after_kickoff
from crewai.agents.agent_builder.base_agent import BaseAgent
from typing import List
@CrewBase
class YourCrewName:
"""Description of your crew"""
agents: List[BaseAgent]
tasks: List[Task]
agents_config = 'config/agents.yaml'
tasks_config = 'config/tasks.yaml'
@before_kickoff
def prepare_inputs(self, inputs):
inputs['additional_data'] = "Some extra information"
return inputs
@after_kickoff
def process_output(self, output):
output.raw += "\nProcessed after kickoff."
return output
@agent
def agent_one(self) -> Agent:
return Agent(
config=self.agents_config['agent_one'], # type: ignore[index]
verbose=True
)
@task
def task_one(self) -> Task:
return Task(
config=self.tasks_config['task_one'] # type: ignore[index]
)
@crew
def crew(self) -> Crew:
return Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
verbose=True,
)
```
<Note>
سيتم تنفيذ المهام بالترتيب الذي عُرّفت به.
</Note>
فئة `CrewBase`، مع هذه المزيّنات، تؤتمت جمع الوكلاء والمهام، مما يقلل الحاجة للإدارة اليدوية.
### تعريف مباشر في الكود (بديل)
بدلاً من ذلك، يمكنك تعريف الطاقم مباشرة في الكود بدون ملفات تهيئة YAML.
## مخرجات الطاقم
تُغلّف مخرجات الطاقم في فئة `CrewOutput`. توفر هذه الفئة طريقة منظمة للوصول إلى نتائج تنفيذ الطاقم، بما في ذلك تنسيقات متنوعة مثل السلاسل النصية الخام وJSON ونماذج Pydantic.
### خصائص مخرجات الطاقم
| الخاصية | المعامل | النوع | الوصف |
| :--------------- | :------------- | :------------------------- | :--------------------------------------------------------------------------------------------------- |
| **Raw** | `raw` | `str` | المخرجات الخام للطاقم. هذا هو التنسيق الافتراضي. |
| **Pydantic** | `pydantic` | `Optional[BaseModel]` | كائن نموذج Pydantic يمثل المخرجات المنظمة. |
| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | قاموس يمثل مخرجات JSON. |
| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | قائمة كائنات `TaskOutput`، كل منها يمثل مخرجات مهمة. |
| **Token Usage** | `token_usage` | `Dict[str, Any]` | ملخص استخدام الرموز. |
## استخدام الذاكرة
يمكن للأطقم استخدام الذاكرة (قصيرة المدى، طويلة المدى، وذاكرة الكيانات) لتحسين تنفيذها وتعلمها بمرور الوقت.
## استخدام التخزين المؤقت
يمكن استخدام التخزين المؤقت لتخزين نتائج تنفيذ الأدوات، مما يجعل العملية أكثر كفاءة.
## مقاييس استخدام الطاقم
بعد تنفيذ الطاقم، يمكنك الوصول إلى خاصية `usage_metrics` لعرض مقاييس استخدام نموذج اللغة (LLM) لجميع المهام المنفذة.
```python Code
crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])
crew.kickoff()
print(crew.usage_metrics)
```
## عملية تنفيذ الطاقم
- **العملية التسلسلية**: تُنفذ المهام واحدة تلو الأخرى، مما يسمح بتدفق عمل خطي.
- **العملية الهرمية**: ينسق وكيل مدير الطاقم، ويفوّض المهام ويتحقق من النتائج.
### تشغيل الطاقم
بمجرد تجميع طاقمك، ابدأ سير العمل بطريقة `kickoff()`.
```python Code
result = my_crew.kickoff()
print(result)
```
### طرق مختلفة لتشغيل الطاقم
#### الطرق المتزامنة
- `kickoff()`: يبدأ عملية التنفيذ وفقًا لتدفق العملية المحدد.
- `kickoff_for_each()`: ينفذ المهام بالتتابع لكل مدخل.
#### الطرق غير المتزامنة
| الطريقة | النوع | الوصف |
|--------|------|-------------|
| `akickoff()` | غير متزامن أصلي | async/await أصلي عبر سلسلة التنفيذ بأكملها |
| `akickoff_for_each()` | غير متزامن أصلي | تنفيذ غير متزامن أصلي لكل مدخل في قائمة |
| `kickoff_async()` | مبني على الخيوط | يغلّف التنفيذ المتزامن في `asyncio.to_thread` |
| `kickoff_for_each_async()` | مبني على الخيوط | غير متزامن مبني على الخيوط لكل مدخل في قائمة |
<Note>
لأحمال العمل عالية التزامن، يُوصى بـ `akickoff()` و `akickoff_for_each()` لأنها تستخدم async أصلي.
</Note>
### بث تنفيذ الطاقم
للرؤية في الوقت الفعلي لتنفيذ الطاقم، يمكنك تفعيل البث:
```python Code
crew = Crew(
agents=[researcher],
tasks=[task],
stream=True
)
streaming = crew.kickoff(inputs={"topic": "AI"})
for chunk in streaming:
print(chunk.content, end="", flush=True)
result = streaming.result
```
### الإعادة من مهمة محددة
يمكنك الآن الإعادة من مهمة محددة باستخدام أمر CLI `replay`.
```shell
crewai log-tasks-outputs
```
ثم للإعادة من مهمة محددة:
```shell
crewai replay -t <task_id>
```

236
docs/edge/ar/concepts/event-listener.mdx Normal file
View File

@@ -0,0 +1,236 @@
---
title: "مستمعو الأحداث"
description: "الاستفادة من أحداث CrewAI لبناء تكاملات مخصصة ومراقبة"
icon: spinner
mode: "wide"
---
## نظرة عامة
يوفر CrewAI نظام أحداث قوي يتيح لك الاستماع والتفاعل مع الأحداث المختلفة التي تحدث أثناء تنفيذ طاقمك. تُمكّنك هذه الميزة من بناء تكاملات مخصصة وحلول مراقبة وأنظمة تسجيل أو أي وظائف أخرى تحتاج للتشغيل بناءً على أحداث CrewAI الداخلية.
## كيف يعمل
يستخدم CrewAI بنية ناقل أحداث لإرسال الأحداث طوال دورة حياة التنفيذ. يُبنى نظام الأحداث على المكونات التالية:
1. **CrewAIEventsBus**: ناقل أحداث فريد يدير تسجيل الأحداث وإرسالها
2. **BaseEvent**: الفئة الأساسية لجميع الأحداث في النظام
3. **BaseEventListener**: فئة أساسية مجردة لإنشاء مستمعي أحداث مخصصين
عندما تحدث إجراءات محددة في CrewAI (مثل بدء تنفيذ طاقم، أو إكمال وكيل لمهمة، أو استخدام أداة)، يرسل النظام أحداثًا مقابلة. يمكنك تسجيل معالجات لهذه الأحداث لتنفيذ كود مخصص عند حدوثها.
<Note type="info" title="تحسين المؤسسات: تتبع الأوامر">
يوفر CrewAI AMP ميزة تتبع أوامر مدمجة تستفيد من نظام الأحداث لتتبع وتخزين وتصور جميع الأوامر والاستكمالات والبيانات الوصفية المرتبطة.
![Prompt Tracing Dashboard](/images/enterprise/traces-overview.png)
مع تتبع الأوامر يمكنك:
- عرض السجل الكامل لجميع الأوامر المرسلة إلى LLM
- تتبع استخدام الرموز والتكاليف
- تصحيح إخفاقات استدلال الوكيل
- مشاركة تسلسلات الأوامر مع فريقك
- مقارنة استراتيجيات الأوامر المختلفة
- تصدير التتبعات للامتثال والتدقيق
</Note>
## إنشاء مستمع أحداث مخصص
لإنشاء مستمع أحداث مخصص، تحتاج إلى:
1. إنشاء فئة ترث من `BaseEventListener`
2. تنفيذ طريقة `setup_listeners`
3. تسجيل معالجات للأحداث التي تهمك
4. إنشاء مثيل من مستمعك في الملف المناسب
إليك مثالًا بسيطًا:
```python
from crewai.events import (
CrewKickoffStartedEvent,
CrewKickoffCompletedEvent,
AgentExecutionCompletedEvent,
)
from crewai.events import BaseEventListener
class MyCustomListener(BaseEventListener):
def __init__(self):
super().__init__()
def setup_listeners(self, crewai_event_bus):
@crewai_event_bus.on(CrewKickoffStartedEvent)
def on_crew_started(source, event):
print(f"Crew '{event.crew_name}' has started execution!")
@crewai_event_bus.on(CrewKickoffCompletedEvent)
def on_crew_completed(source, event):
print(f"Crew '{event.crew_name}' has completed execution!")
print(f"Output: {event.output}")
@crewai_event_bus.on(AgentExecutionCompletedEvent)
def on_agent_execution_completed(source, event):
print(f"Agent '{event.agent.role}' completed task")
print(f"Output: {event.output}")
```
## تسجيل المستمع بشكل صحيح
مجرد تعريف فئة المستمع ليس كافيًا. تحتاج لإنشاء مثيل منه والتأكد من استيراده في تطبيقك.
```python
# في ملف crew.py
from crewai import Agent, Crew, Task
from my_listeners import MyCustomListener
# إنشاء مثيل من المستمع
my_listener = MyCustomListener()
class MyCustomCrew:
def crew(self):
return Crew(
agents=[...],
tasks=[...],
)
```
## أنواع الأحداث المتاحة
يوفر CrewAI مجموعة واسعة من الأحداث يمكنك الاستماع إليها:
### أحداث الطاقم
- **CrewKickoffStartedEvent**: يُرسل عند بدء تنفيذ الطاقم
- **CrewKickoffCompletedEvent**: يُرسل عند اكتمال تنفيذ الطاقم
- **CrewKickoffFailedEvent**: يُرسل عند فشل تنفيذ الطاقم
- **CrewTestStartedEvent**: يُرسل عند بدء اختبار الطاقم
- **CrewTestCompletedEvent**: يُرسل عند اكتمال اختبار الطاقم
- **CrewTestFailedEvent**: يُرسل عند فشل اختبار الطاقم
- **CrewTrainStartedEvent**: يُرسل عند بدء تدريب الطاقم
- **CrewTrainCompletedEvent**: يُرسل عند اكتمال تدريب الطاقم
- **CrewTrainFailedEvent**: يُرسل عند فشل تدريب الطاقم
### أحداث الوكيل
- **AgentExecutionStartedEvent**: يُرسل عند بدء تنفيذ وكيل لمهمة
- **AgentExecutionCompletedEvent**: يُرسل عند اكتمال تنفيذ وكيل لمهمة
- **AgentExecutionErrorEvent**: يُرسل عند مواجهة وكيل لخطأ أثناء التنفيذ
- **LiteAgentExecutionStartedEvent**: يُرسل عند بدء تنفيذ LiteAgent
- **LiteAgentExecutionCompletedEvent**: يُرسل عند اكتمال تنفيذ LiteAgent
### أحداث المهام
- **TaskStartedEvent**: يُرسل عند بدء تنفيذ مهمة
- **TaskCompletedEvent**: يُرسل عند اكتمال تنفيذ مهمة
- **TaskFailedEvent**: يُرسل عند فشل تنفيذ مهمة
### أحداث استخدام الأدوات
- **ToolUsageStartedEvent**: يُرسل عند بدء تنفيذ أداة
- **ToolUsageFinishedEvent**: يُرسل عند اكتمال تنفيذ أداة
- **ToolUsageErrorEvent**: يُرسل عند مواجهة خطأ في تنفيذ أداة
### أحداث MCP
- **MCPConnectionStartedEvent**: يُرسل عند بدء الاتصال بخادم MCP
- **MCPConnectionCompletedEvent**: يُرسل عند اكتمال الاتصال بخادم MCP
- **MCPConnectionFailedEvent**: يُرسل عند فشل الاتصال بخادم MCP
- **MCPToolExecutionStartedEvent**: يُرسل عند بدء تنفيذ أداة MCP
- **MCPToolExecutionCompletedEvent**: يُرسل عند اكتمال تنفيذ أداة MCP
- **MCPToolExecutionFailedEvent**: يُرسل عند فشل تنفيذ أداة MCP
### أحداث المعرفة
- **KnowledgeRetrievalStartedEvent**: يُرسل عند بدء استرجاع المعرفة
- **KnowledgeRetrievalCompletedEvent**: يُرسل عند اكتمال استرجاع المعرفة
- **KnowledgeQueryStartedEvent**: يُرسل عند بدء استعلام المعرفة
- **KnowledgeQueryCompletedEvent**: يُرسل عند اكتمال استعلام المعرفة
- **KnowledgeQueryFailedEvent**: يُرسل عند فشل استعلام المعرفة
### أحداث حواجز LLM
- **LLMGuardrailStartedEvent**: يُرسل عند بدء التحقق من الحاجز
- **LLMGuardrailCompletedEvent**: يُرسل عند اكتمال التحقق من الحاجز
- **LLMGuardrailFailedEvent**: يُرسل عند فشل التحقق من الحاجز
### أحداث التدفق
- **FlowCreatedEvent**: يُرسل عند إنشاء تدفق
- **FlowStartedEvent**: يُرسل عند بدء تنفيذ تدفق
- **FlowFinishedEvent**: يُرسل عند اكتمال تنفيذ تدفق
- **FlowPausedEvent**: يُرسل عند إيقاف تدفق مؤقتًا بانتظار ملاحظات بشرية
### أحداث LLM
- **LLMCallStartedEvent**: يُرسل عند بدء استدعاء LLM
- **LLMCallCompletedEvent**: يُرسل عند اكتمال استدعاء LLM
- **LLMCallFailedEvent**: يُرسل عند فشل استدعاء LLM
- **LLMStreamChunkEvent**: يُرسل لكل جزء مستلم أثناء بث استجابات LLM
### أحداث الذاكرة
- **MemoryQueryStartedEvent**: يُرسل عند بدء استعلام الذاكرة
- **MemoryQueryCompletedEvent**: يُرسل عند اكتمال استعلام الذاكرة
- **MemorySaveStartedEvent**: يُرسل عند بدء حفظ الذاكرة
- **MemorySaveCompletedEvent**: يُرسل عند اكتمال حفظ الذاكرة
### أحداث الاستدلال
- **AgentReasoningStartedEvent**: يُرسل عند بدء وكيل الاستدلال حول مهمة
- **AgentReasoningCompletedEvent**: يُرسل عند انتهاء عملية الاستدلال
- **AgentReasoningFailedEvent**: يُرسل عند فشل عملية الاستدلال
### أحداث A2A (وكيل إلى وكيل)
- **A2ADelegationStartedEvent**: يُرسل عند بدء تفويض A2A
- **A2ADelegationCompletedEvent**: يُرسل عند اكتمال تفويض A2A
- **A2AConversationStartedEvent**: يُرسل عند بدء محادثة A2A متعددة الأدوار
- **A2AConversationCompletedEvent**: يُرسل عند انتهاء محادثة A2A
## هيكل معالج الأحداث
يستقبل كل معالج حدث معاملين:
1. **source**: الكائن الذي أرسل الحدث
2. **event**: مثيل الحدث، يحتوي على بيانات خاصة بالحدث
هيكل كائن الحدث يعتمد على نوع الحدث، لكن جميع الأحداث ترث من `BaseEvent` وتتضمن:
- **timestamp**: الوقت الذي أُرسل فيه الحدث
- **type**: معرّف نصي لنوع الحدث
## الاستخدام المتقدم: المعالجات المحددة النطاق
لمعالجة الأحداث المؤقتة، يمكنك استخدام مدير سياق `scoped_handlers`:
```python
from crewai.events import crewai_event_bus, CrewKickoffStartedEvent
with crewai_event_bus.scoped_handlers():
@crewai_event_bus.on(CrewKickoffStartedEvent)
def temp_handler(source, event):
print("This handler only exists within this context")
# قم بشيء يرسل أحداثًا
# خارج السياق، يتم إزالة المعالج المؤقت
```
## حالات الاستخدام
يمكن استخدام مستمعي الأحداث لأغراض متنوعة:
1. **التسجيل والمراقبة**: تتبع تنفيذ طاقمك وتسجيل الأحداث المهمة
2. **التحليلات**: جمع بيانات عن أداء وسلوك طاقمك
3. **التصحيح**: إعداد مستمعين مؤقتين لتصحيح مشاكل محددة
4. **التكامل**: ربط CrewAI بأنظمة خارجية مثل منصات المراقبة وقواعد البيانات أو خدمات الإشعارات
5. **السلوك المخصص**: تشغيل إجراءات مخصصة بناءً على أحداث محددة
## أفضل الممارسات
1. **اجعل المعالجات خفيفة**: يجب أن تكون معالجات الأحداث خفيفة وتتجنب العمليات الحاجبة
2. **معالجة الأخطاء**: أدرج معالجة أخطاء مناسبة في معالجات الأحداث لمنع الاستثناءات من التأثير على التنفيذ الرئيسي
3. **التنظيف**: إذا خصص مستمعك موارد، تأكد من تنظيفها بشكل صحيح
4. **الاستماع الانتقائي**: استمع فقط للأحداث التي تحتاج فعلاً لمعالجتها
5. **الاختبار**: اختبر مستمعي الأحداث بمعزل لضمان سلوكهم كما هو متوقع
بالاستفادة من نظام أحداث CrewAI، يمكنك توسيع وظائفه ودمجه بسلاسة مع بنيتك التحتية الحالية.

267
docs/edge/ar/concepts/files.mdx Normal file
View File

@@ -0,0 +1,267 @@
---
title: الملفات
description: تمرير الصور وملفات PDF والصوت والفيديو والنصوص إلى وكلائك للمعالجة متعددة الوسائط.
icon: file-image
---
## نظرة عامة
يدعم CrewAI مدخلات الملفات متعددة الوسائط الأصلية، مما يتيح لك تمرير الصور وملفات PDF والصوت والفيديو والنصوص مباشرة إلى وكلائك. يتم تنسيق الملفات تلقائيًا وفقًا لمتطلبات API لكل مزود LLM.
<Note type="info" title="اعتمادية اختيارية">
يتطلب دعم الملفات حزمة `crewai-files` الاختيارية. ثبّتها بـ:
```bash
uv add 'crewai[file-processing]'
```
</Note>
<Note type="warning" title="وصول مبكر">
واجهة معالجة الملفات حاليًا في مرحلة الوصول المبكر.
</Note>
## أنواع الملفات
يدعم CrewAI خمسة أنواع ملفات محددة بالإضافة إلى فئة `File` العامة التي تكتشف النوع تلقائيًا:
| النوع | الفئة | حالات الاستخدام |
|:-----|:------|:----------|
| **صورة** | `ImageFile` | صور، لقطات شاشة، مخططات، رسوم بيانية |
| **PDF** | `PDFFile` | مستندات، تقارير، أوراق بحثية |
| **صوت** | `AudioFile` | تسجيلات صوتية، بودكاست، اجتماعات |
| **فيديو** | `VideoFile` | تسجيلات شاشة، عروض تقديمية |
| **نص** | `TextFile` | ملفات كود، سجلات، ملفات بيانات |
| **عام** | `File` | اكتشاف تلقائي للنوع من المحتوى |
```python
from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile
image = ImageFile(source="screenshot.png")
pdf = PDFFile(source="report.pdf")
audio = AudioFile(source="meeting.mp3")
video = VideoFile(source="demo.mp4")
text = TextFile(source="data.csv")
file = File(source="document.pdf")
```
## مصادر الملفات
يقبل معامل `source` أنواع إدخال متعددة ويكتشف تلقائيًا المعالج المناسب:
### من مسار
```python
from crewai_files import ImageFile
image = ImageFile(source="./images/chart.png")
```
### من عنوان URL
```python
from crewai_files import ImageFile
image = ImageFile(source="https://example.com/image.png")
```
### من بايتات
```python
from crewai_files import ImageFile, FileBytes
image_bytes = download_image_from_api()
image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png"))
image = ImageFile(source=image_bytes)
```
## استخدام الملفات
يمكن تمرير الملفات على مستويات متعددة، حيث تأخذ المستويات الأكثر تحديدًا الأولوية.
### مع الأطقم
مرر الملفات عند تشغيل طاقم:
```python
from crewai import Crew
from crewai_files import ImageFile
crew = Crew(agents=[analyst], tasks=[analysis_task])
result = crew.kickoff(
inputs={"topic": "Q4 Sales"},
input_files={
"chart": ImageFile(source="sales_chart.png"),
"report": PDFFile(source="quarterly_report.pdf"),
}
)
```
### مع المهام
أرفق الملفات بمهام محددة:
```python
from crewai import Task
from crewai_files import ImageFile
task = Task(
description="Analyze the sales chart and identify trends in {chart}",
expected_output="A summary of key trends",
input_files={
"chart": ImageFile(source="sales_chart.png"),
}
)
```
### مع التدفقات
مرر الملفات إلى التدفقات، والتي تنتقل تلقائيًا إلى الأطقم:
```python
from crewai.flow.flow import Flow, start
from crewai_files import ImageFile
class AnalysisFlow(Flow):
@start()
def analyze(self):
return self.analysis_crew.kickoff()
flow = AnalysisFlow()
result = flow.kickoff(
input_files={"image": ImageFile(source="data.png")}
)
```
### مع الوكلاء المستقلين
مرر الملفات مباشرة إلى تشغيل الوكيل:
```python
from crewai import Agent
from crewai_files import ImageFile
agent = Agent(
role="Image Analyst",
goal="Analyze images",
backstory="Expert at visual analysis",
llm="gpt-4o",
)
result = agent.kickoff(
messages="What's in this image?",
input_files={"photo": ImageFile(source="photo.jpg")},
)
```
## أولوية الملفات
عند تمرير الملفات على مستويات متعددة، تتجاوز المستويات الأكثر تحديدًا المستويات الأوسع:
```
Flow input_files < Crew input_files < Task input_files
```
على سبيل المثال، إذا عرّف كل من التدفق والمهمة ملفًا باسم `"chart"`، تُستخدم نسخة المهمة.
## دعم المزودين
تدعم المزودات المختلفة أنواع ملفات مختلفة. يقوم CrewAI تلقائيًا بتنسيق الملفات وفقًا لواجهة كل مزود.
| المزود | صورة | PDF | صوت | فيديو | نص |
|:---------|:-----:|:---:|:-----:|:-----:|:----:|
| **OpenAI** (completions API) | ✓ | | | | |
| **OpenAI** (responses API) | ✓ | ✓ | ✓ | | |
| **Anthropic** (claude-3.x) | ✓ | ✓ | | | |
| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ |
| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | |
| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | |
<Note type="info" title="Gemini لأقصى دعم للملفات">
تدعم نماذج Google Gemini جميع أنواع الملفات بما في ذلك الفيديو (حتى ساعة واحدة، 2 جيجابايت). استخدم Gemini عندما تحتاج لمعالجة محتوى الفيديو.
</Note>
<Note type="warning" title="أنواع الملفات غير المدعومة">
إذا مررت نوع ملف لا يدعمه المزود (مثل الفيديو إلى OpenAI)، ستتلقى خطأ `UnsupportedFileTypeError`. اختر مزودك بناءً على أنواع الملفات التي تحتاج لمعالجتها.
</Note>
## كيف تُرسل الملفات
يختار CrewAI تلقائيًا الطريقة المثلى لإرسال الملفات إلى كل مزود:
| الطريقة | الوصف | متى تُستخدم |
|:-------|:------------|:----------|
| **Inline Base64** | الملف مضمّن مباشرة في الطلب | ملفات صغيرة (< 5 ميجابايت عادة) |
| **File Upload API** | الملف يُرفع بشكل منفصل، يُشار إليه بمعرّف | ملفات كبيرة تتجاوز العتبة |
| **URL Reference** | عنوان URL مباشر يُمرر إلى النموذج | مصدر الملف هو عنوان URL بالفعل |
### طرق الإرسال حسب المزود
| المزود | Inline Base64 | File Upload API | URL References |
|:---------|:-------------:|:---------------:|:--------------:|
| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ |
| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ |
| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ |
| **AWS Bedrock** | ✓ | | ✓ (S3 URIs) |
| **Azure OpenAI** | ✓ | | ✓ |
<Note type="info" title="تحسين تلقائي">
لا تحتاج لإدارة هذا بنفسك. يستخدم CrewAI تلقائيًا الطريقة الأكثر كفاءة بناءً على حجم الملف وقدرات المزود. المزودات بدون واجهات رفع الملفات تستخدم inline base64 لجميع الملفات.
</Note>
## أوضاع معالجة الملفات
تحكم في كيفية معالجة الملفات عندما تتجاوز حدود المزود:
```python
from crewai_files import ImageFile, PDFFile
image = ImageFile(source="large.png", mode="strict")
image = ImageFile(source="large.png", mode="auto")
image = ImageFile(source="large.png", mode="warn")
pdf = PDFFile(source="large.pdf", mode="chunk")
```
## قيود المزودين
لكل مزود حدود محددة لأحجام الملفات والأبعاد:
### OpenAI
- **الصور**: حد أقصى 20 ميجابايت، حتى 10 صور لكل طلب
- **PDF**: حد أقصى 32 ميجابايت، حتى 100 صفحة
- **الصوت**: حد أقصى 25 ميجابايت، حتى 25 دقيقة
### Anthropic
- **الصور**: حد أقصى 5 ميجابايت، أقصى 8000x8000 بكسل، حتى 100 صورة
- **PDF**: حد أقصى 32 ميجابايت، حتى 100 صفحة
### Google Gemini
- **الصور**: حد أقصى 100 ميجابايت
- **PDF**: حد أقصى 50 ميجابايت
- **الصوت**: حد أقصى 100 ميجابايت، حتى 9.5 ساعة
- **الفيديو**: حد أقصى 2 جيجابايت، حتى ساعة واحدة
### AWS Bedrock
- **الصور**: حد أقصى 4.5 ميجابايت، أقصى 8000x8000 بكسل
- **PDF**: حد أقصى 3.75 ميجابايت، حتى 100 صفحة
## الإشارة إلى الملفات في الأوامر
استخدم اسم مفتاح الملف في أوصاف المهام للإشارة إلى الملفات:
```python
task = Task(
description="""
Analyze the provided materials:
1. Review the chart in {sales_chart}
2. Cross-reference with data in {quarterly_report}
3. Summarize key findings
""",
expected_output="Analysis summary with key insights",
input_files={
"sales_chart": ImageFile(source="chart.png"),
"quarterly_report": PDFFile(source="report.pdf"),
}
)
```

1169
docs/edge/ar/concepts/flows.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

1095
docs/edge/ar/concepts/knowledge.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

1513
docs/edge/ar/concepts/llms.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

878
docs/edge/ar/concepts/memory.mdx Normal file
View File

@@ -0,0 +1,878 @@
---
title: الذاكرة
description: الاستفادة من نظام الذاكرة الموحد في CrewAI لتعزيز قدرات الوكلاء.
icon: database
mode: "wide"
---
## نظرة عامة
يوفر CrewAI **نظام ذاكرة موحد** -- فئة `Memory` واحدة تستبدل أنواع الذاكرة المنفصلة (قصيرة المدى، طويلة المدى، ذاكرة الكيانات، والخارجية) بواجهة برمجة تطبيقات ذكية واحدة. تستخدم الذاكرة LLM لتحليل المحتوى عند الحفظ (استنتاج النطاق والفئات والأهمية) وتدعم الاسترجاع متعدد العمق مع تسجيل مركب يمزج بين التشابه الدلالي والحداثة والأهمية.
يمكنك استخدام الذاكرة بأربع طرق: **مستقلة** (سكربتات، دفاتر ملاحظات)، **مع فرق Crew**، **مع Agents**، أو **داخل التدفقات**.
## البدء السريع
```python
from crewai import Memory
memory = Memory()
# Store -- the LLM infers scope, categories, and importance
memory.remember("We decided to use PostgreSQL for the user database.")
# Retrieve -- results ranked by composite score (semantic + recency + importance)
matches = memory.recall("What database did we choose?")
for m in matches:
print(f"[{m.score:.2f}] {m.record.content}")
# Tune scoring for a fast-moving project
memory = Memory(recency_weight=0.5, recency_half_life_days=7)
# Forget
memory.forget(scope="/project/old")
# Explore the self-organized scope tree
print(memory.tree())
print(memory.info("/"))
```
## أربع طرق لاستخدام الذاكرة
### مستقلة
استخدم الذاكرة في السكربتات ودفاتر الملاحظات وأدوات سطر الأوامر أو كقاعدة معرفة مستقلة -- لا حاجة لوكلاء أو فرق Crew.
```python
from crewai import Memory
memory = Memory()
# Build up knowledge
memory.remember("The API rate limit is 1000 requests per minute.")
memory.remember("Our staging environment uses port 8080.")
memory.remember("The team agreed to use feature flags for all new releases.")
# Later, recall what you need
matches = memory.recall("What are our API limits?", limit=5)
for m in matches:
print(f"[{m.score:.2f}] {m.record.content}")
# Extract atomic facts from a longer text
raw = """Meeting notes: We decided to migrate from MySQL to PostgreSQL
next quarter. The budget is $50k. Sarah will lead the migration."""
facts = memory.extract_memories(raw)
# ["Migration from MySQL to PostgreSQL planned for next quarter",
# "Database migration budget is $50k",
# "Sarah will lead the database migration"]
for fact in facts:
memory.remember(fact)
```
### مع فرق Crew
مرّر `memory=True` للإعدادات الافتراضية، أو مرّر مثيل `Memory` مُعدّ للسلوك المخصص.
```python
from crewai import Crew, Agent, Task, Process, Memory
# Option 1: Default memory
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, writing_task],
process=Process.sequential,
memory=True,
verbose=True,
)
# Option 2: Custom memory with tuned scoring
memory = Memory(
recency_weight=0.4,
semantic_weight=0.4,
importance_weight=0.2,
recency_half_life_days=14,
)
crew = Crew(
agents=[researcher, writer],
tasks=[research_task, writing_task],
memory=memory,
)
```
عند استخدام `memory=True`، ينشئ الفريق مثيل `Memory()` افتراضيًا ويمرر إعداد `embedder` الخاص بالفريق تلقائيًا. يشترك جميع الوكلاء في الفريق في ذاكرة الفريق ما لم يكن لدى الوكيل ذاكرته الخاصة.
بعد كل مهمة، يستخرج الفريق تلقائيًا حقائق منفصلة من مخرجات المهمة ويخزّنها. قبل كل مهمة، يسترجع الوكيل السياق ذا الصلة من الذاكرة ويحقنه في موجّه المهمة.
### مع Agents
يمكن للوكلاء استخدام ذاكرة الفريق المشتركة (افتراضيًا) أو تلقي عرض محدد النطاق للسياق الخاص.
```python
from crewai import Agent, Memory
memory = Memory()
# Researcher gets a private scope -- only sees /agent/researcher
researcher = Agent(
role="Researcher",
goal="Find and analyze information",
backstory="Expert researcher with attention to detail",
memory=memory.scope("/agent/researcher"),
)
# Writer uses crew shared memory (no agent-level memory set)
writer = Agent(
role="Writer",
goal="Produce clear, well-structured content",
backstory="Experienced technical writer",
# memory not set -- uses crew._memory when crew has memory enabled
)
```
يمنح هذا النمط الباحث نتائج خاصة بينما يقرأ الكاتب من ذاكرة الفريق المشتركة.
### مع التدفقات
كل تدفق يحتوي على ذاكرة مدمجة. استخدم `self.remember()` و `self.recall()` و `self.extract_memories()` داخل أي دالة تدفق.
```python
from crewai.flow.flow import Flow, listen, start
class ResearchFlow(Flow):
@start()
def gather_data(self):
findings = "PostgreSQL handles 10k concurrent connections. MySQL caps at 5k."
self.remember(findings, scope="/research/databases")
return findings
@listen(gather_data)
def write_report(self, findings):
# Recall past research to provide context
past = self.recall("database performance benchmarks")
context = "\n".join(f"- {m.record.content}" for m in past)
return f"Report:\nNew findings: {findings}\nPrevious context:\n{context}"
```
انظر [وثائق التدفقات](/concepts/flows) لمزيد من المعلومات حول الذاكرة في التدفقات.
## النطاقات الهرمية
### ما هي النطاقات
يتم تنظيم الذكريات في شجرة هرمية من النطاقات، مشابهة لنظام الملفات. كل نطاق هو مسار مثل `/` أو `/project/alpha` أو `/agent/researcher/findings`.
```
/
/company
/company/engineering
/company/product
/project
/project/alpha
/project/beta
/agent
/agent/researcher
/agent/writer
```
توفر النطاقات **ذاكرة تعتمد على السياق** -- عند الاسترجاع ضمن نطاق، تبحث فقط في ذلك الفرع من الشجرة، مما يحسّن كلًا من الدقة والأداء.
### كيف يعمل استنتاج النطاق
عند استدعاء `remember()` دون تحديد نطاق، يحلل LLM المحتوى وشجرة النطاقات الحالية، ثم يقترح أفضل موضع. إذا لم يكن هناك نطاق حالي مناسب، ينشئ واحدًا جديدًا. بمرور الوقت، تنمو شجرة النطاقات عضويًا من المحتوى نفسه -- لا تحتاج إلى تصميم مخطط مسبقًا.
```python
memory = Memory()
# LLM infers scope from content
memory.remember("We chose PostgreSQL for the user database.")
# -> might be placed under /project/decisions or /engineering/database
# You can also specify scope explicitly
memory.remember("Sprint velocity is 42 points", scope="/team/metrics")
```
### تصوير شجرة النطاقات
```python
print(memory.tree())
# / (15 records)
# /project (8 records)
# /project/alpha (5 records)
# /project/beta (3 records)
# /agent (7 records)
# /agent/researcher (4 records)
# /agent/writer (3 records)
print(memory.info("/project/alpha"))
# ScopeInfo(path='/project/alpha', record_count=5,
# categories=['architecture', 'database'],
# oldest_record=datetime(...), newest_record=datetime(...),
# child_scopes=[])
```
### MemoryScope: عروض الأشجار الفرعية
يقيّد `MemoryScope` جميع العمليات على فرع من الشجرة. يمكن للوكيل أو الكود الذي يستخدمه الرؤية والكتابة فقط ضمن تلك الشجرة الفرعية.
```python
memory = Memory()
# Create a scope for a specific agent
agent_memory = memory.scope("/agent/researcher")
# Everything is relative to /agent/researcher
agent_memory.remember("Found three relevant papers on LLM memory.")
# -> stored under /agent/researcher
agent_memory.recall("relevant papers")
# -> searches only under /agent/researcher
# Narrow further with subscope
project_memory = agent_memory.subscope("project-alpha")
# -> /agent/researcher/project-alpha
```
### أفضل الممارسات لتصميم النطاقات
- **ابدأ بشكل مسطح، ودع LLM ينظّم.** لا تبالغ في هندسة تسلسل النطاقات مسبقًا. ابدأ بـ `memory.remember(content)` ودع استنتاج النطاق في LLM ينشئ الهيكل مع تراكم المحتوى.
- **استخدم أنماط `/{entity_type}/{identifier}`.** تنشأ التسلسلات الطبيعية من أنماط مثل `/project/alpha` و `/agent/researcher` و `/company/engineering` و `/customer/acme-corp`.
- **حدد النطاق حسب الاهتمام، وليس حسب نوع البيانات.** استخدم `/project/alpha/decisions` بدلاً من `/decisions/project/alpha`. هذا يبقي المحتوى ذا الصلة معًا.
- **حافظ على العمق ضحلًا (2-3 مستويات).** النطاقات المتداخلة بعمق تصبح متفرقة جدًا. `/project/alpha/architecture` جيد؛ `/project/alpha/architecture/decisions/databases/postgresql` عميق جدًا.
- **استخدم النطاقات الصريحة عندما تعرف، ودع LLM يستنتج عندما لا تعرف.** إذا كنت تخزّن قرار مشروع معروف، مرّر `scope="/project/alpha/decisions"`. إذا كنت تخزّن مخرجات وكيل حرة الشكل، اترك النطاق ودع LLM يحدده.
### أمثلة حالات الاستخدام
**فريق متعدد المشاريع:**
```python
memory = Memory()
# Each project gets its own branch
memory.remember("Using microservices architecture", scope="/project/alpha/architecture")
memory.remember("GraphQL API for client apps", scope="/project/beta/api")
# Recall across all projects
memory.recall("API design decisions")
# Or within a specific project
memory.recall("API design", scope="/project/beta")
```
**سياق خاص لكل وكيل مع معرفة مشتركة:**
```python
memory = Memory()
# Researcher has private findings
researcher_memory = memory.scope("/agent/researcher")
# Writer can read from both its own scope and shared company knowledge
writer_view = memory.slice(
scopes=["/agent/writer", "/company/knowledge"],
read_only=True,
)
```
**دعم العملاء (سياق لكل عميل):**
```python
memory = Memory()
# Each customer gets isolated context
memory.remember("Prefers email communication", scope="/customer/acme-corp")
memory.remember("On enterprise plan, 50 seats", scope="/customer/acme-corp")
# Shared product docs are accessible to all agents
memory.remember("Rate limit is 1000 req/min on enterprise plan", scope="/product/docs")
```
## شرائح الذاكرة
### ما هي الشرائح
`MemorySlice` هو عرض عبر نطاقات متعددة، ربما متباعدة. على عكس النطاق (الذي يقيّد على شجرة فرعية واحدة)، تتيح لك الشريحة الاسترجاع من عدة فروع في وقت واحد.
### متى تستخدم الشرائح مقابل النطاقات
- **النطاق**: استخدمه عندما يجب تقييد وكيل أو كتلة كود على شجرة فرعية واحدة. مثال: وكيل يرى فقط `/agent/researcher`.
- **الشريحة**: استخدمها عندما تحتاج إلى دمج السياق من عدة فروع. مثال: وكيل يقرأ من نطاقه الخاص بالإضافة إلى معرفة الشركة المشتركة.
### شرائح القراءة فقط
النمط الأكثر شيوعًا: منح وكيل إمكانية القراءة من فروع متعددة دون السماح له بالكتابة في المناطق المشتركة.
```python
memory = Memory()
# Agent can recall from its own scope AND company knowledge,
# but cannot write to company knowledge
agent_view = memory.slice(
scopes=["/agent/researcher", "/company/knowledge"],
read_only=True,
)
matches = agent_view.recall("company security policies", limit=5)
# Searches both /agent/researcher and /company/knowledge, merges and ranks results
agent_view.remember("new finding") # Raises PermissionError (read-only)
```
### شرائح القراءة والكتابة
عند تعطيل القراءة فقط، يمكنك الكتابة في أي من النطاقات المضمّنة، لكن يجب تحديد النطاق صراحة.
```python
view = memory.slice(scopes=["/team/alpha", "/team/beta"], read_only=False)
# Must specify scope when writing
view.remember("Cross-team decision", scope="/team/alpha", categories=["decisions"])
```
## التسجيل المركب
يتم ترتيب نتائج الاسترجاع بواسطة مزيج مرجّح من ثلاث إشارات:
```
composite = semantic_weight * similarity + recency_weight * decay + importance_weight * importance
```
حيث:
- **similarity** = `1 / (1 + distance)` من فهرس المتجهات (0 إلى 1)
- **decay** = `0.5^(age_days / half_life_days)` -- اضمحلال أُسي (1.0 لليوم، 0.5 عند نصف العمر)
- **importance** = درجة أهمية السجل (0 إلى 1)، يتم تعيينها وقت الترميز
قم بإعدادها مباشرة على منشئ `Memory`:
```python
# Sprint retrospective: favor recent memories, short half-life
memory = Memory(
recency_weight=0.5,
semantic_weight=0.3,
importance_weight=0.2,
recency_half_life_days=7,
)
# Architecture knowledge base: favor important memories, long half-life
memory = Memory(
recency_weight=0.1,
semantic_weight=0.5,
importance_weight=0.4,
recency_half_life_days=180,
)
```
يتضمن كل `MemoryMatch` قائمة `match_reasons` حتى تتمكن من رؤية سبب ترتيب نتيجة معينة في موضعها (مثل `["semantic", "recency", "importance"]`).
## طبقة تحليل LLM
تستخدم الذاكرة LLM بثلاث طرق:
1. **عند الحفظ** -- عندما تحذف النطاق أو الفئات أو الأهمية، يحلل LLM المحتوى ويقترح النطاق والفئات والأهمية والبيانات الوصفية (الكيانات والتواريخ والموضوعات).
2. **عند الاسترجاع** -- للاسترجاع العميق/التلقائي، يحلل LLM الاستعلام (الكلمات المفتاحية، تلميحات الوقت، النطاقات المقترحة، التعقيد) لتوجيه الاسترجاع.
3. **استخراج الذكريات** -- `extract_memories(content)` يقسم النص الخام (مثل مخرجات المهمة) إلى عبارات ذاكرة منفصلة. يستخدم الوكلاء هذا قبل استدعاء `remember()` على كل عبارة حتى يتم تخزين حقائق ذرية بدلاً من كتلة كبيرة واحدة.
جميع التحليلات تتدهور بسلاسة عند فشل LLM -- انظر [سلوك الفشل](#سلوك-الفشل).
## توحيد الذاكرة
عند حفظ محتوى جديد، يتحقق خط أنابيب الترميز تلقائيًا من وجود سجلات مماثلة في التخزين. إذا كان التشابه أعلى من `consolidation_threshold` (الافتراضي 0.85)، يقرر LLM ما يجب فعله:
- **keep** -- السجل الحالي لا يزال دقيقًا وغير مكرر.
- **update** -- يجب تحديث السجل الحالي بمعلومات جديدة (يوفر LLM المحتوى المدمج).
- **delete** -- السجل الحالي قديم أو تم استبداله أو تناقضه.
- **insert_new** -- ما إذا كان يجب إدراج المحتوى الجديد أيضًا كسجل منفصل.
هذا يمنع تراكم النسخ المكررة. على سبيل المثال، إذا حفظت "CrewAI ensures reliable operation" ثلاث مرات، يتعرف التوحيد على النسخ المكررة ويحتفظ بسجل واحد فقط.
### إزالة التكرار داخل الدفعة
عند استخدام `remember_many()`، تتم مقارنة العناصر داخل نفس الدفعة مع بعضها البعض قبل الوصول إلى التخزين. إذا كان تشابه جيب التمام >= `batch_dedup_threshold` (الافتراضي 0.98)، يتم إسقاط العنصر الأحدث بصمت. هذا يلتقط النسخ المكررة الدقيقة أو شبه الدقيقة داخل دفعة واحدة دون أي استدعاءات LLM (رياضيات متجهات خالصة).
```python
# Only 2 records are stored (the third is a near-duplicate of the first)
memory.remember_many([
"CrewAI supports complex workflows.",
"Python is a great language.",
"CrewAI supports complex workflows.", # dropped by intra-batch dedup
])
```
## الحفظ غير الحاجب
`remember_many()` **غير حاجب** -- يقدم خط أنابيب الترميز إلى خيط خلفي ويعود فورًا. هذا يعني أن الوكيل يمكنه المتابعة إلى المهمة التالية بينما يتم حفظ الذكريات.
```python
# Returns immediately -- save happens in background
memory.remember_many(["Fact A.", "Fact B.", "Fact C."])
# recall() automatically waits for pending saves before searching
matches = memory.recall("facts") # sees all 3 records
```
### حاجز القراءة
كل استدعاء `recall()` يستدعي تلقائيًا `drain_writes()` قبل البحث، مما يضمن أن الاستعلام يرى دائمًا أحدث السجلات المستمرة. هذا شفاف -- لا تحتاج أبدًا إلى التفكير فيه.
### إيقاف الفريق
عند انتهاء الفريق، يستنزف `kickoff()` جميع عمليات حفظ الذاكرة المعلقة في كتلة `finally` الخاصة به، لذا لا تُفقد أي عمليات حفظ حتى لو اكتمل الفريق بينما عمليات الحفظ الخلفية قيد التنفيذ.
### الاستخدام المستقل
للسكربتات أو دفاتر الملاحظات حيث لا توجد دورة حياة فريق، استدعِ `drain_writes()` أو `close()` صراحة:
```python
memory = Memory()
memory.remember_many(["Fact A.", "Fact B."])
# Option 1: Wait for pending saves
memory.drain_writes()
# Option 2: Drain and shut down the background pool
memory.close()
```
## المصدر والخصوصية
يمكن لكل سجل ذاكرة أن يحمل علامة `source` لتتبع المصدر وعلامة `private` للتحكم في الوصول.
### تتبع المصدر
يحدد معامل `source` من أين جاءت الذاكرة:
```python
# Tag memories with their origin
memory.remember("User prefers dark mode", source="user:alice")
memory.remember("System config updated", source="admin")
memory.remember("Agent found a bug", source="agent:debugger")
# Recall only memories from a specific source
matches = memory.recall("user preferences", source="user:alice")
```
### الذكريات الخاصة
الذكريات الخاصة مرئية فقط للاسترجاع عندما يتطابق `source`:
```python
# Store a private memory
memory.remember("Alice's API key is sk-...", source="user:alice", private=True)
# This recall sees the private memory (source matches)
matches = memory.recall("API key", source="user:alice")
# This recall does NOT see it (different source)
matches = memory.recall("API key", source="user:bob")
# Admin access: see all private records regardless of source
matches = memory.recall("API key", include_private=True)
```
هذا مفيد بشكل خاص في النشرات متعددة المستخدمين أو المؤسسية حيث يجب عزل ذكريات المستخدمين المختلفين.
## RecallFlow (الاسترجاع العميق)
يدعم `recall()` عمقين:
- **`depth="shallow"`** -- بحث متجهي مباشر مع تسجيل مركب. سريع (~200 مللي ثانية)، بدون استدعاءات LLM.
- **`depth="deep"` (افتراضي)** -- يشغل RecallFlow متعدد الخطوات: تحليل الاستعلام، اختيار النطاق، بحث متجهي متوازٍ، توجيه قائم على الثقة، واستكشاف متكرر اختياري عندما تكون الثقة منخفضة.
**تخطي LLM الذكي**: الاستعلامات الأقصر من `query_analysis_threshold` (الافتراضي 200 حرف) تتخطى تحليل LLM للاستعلام بالكامل، حتى في الوضع العميق. الاستعلامات القصيرة مثل "ما قاعدة البيانات التي نستخدمها؟" هي بالفعل عبارات بحث جيدة -- تحليل LLM يضيف قيمة قليلة. هذا يوفر ~1-3 ثوانٍ لكل استرجاع للاستعلامات القصيرة النموذجية. فقط الاستعلامات الأطول (مثل أوصاف المهام الكاملة) تمر عبر تقطير LLM إلى استعلامات فرعية مستهدفة.
```python
# Shallow: pure vector search, no LLM
matches = memory.recall("What did we decide?", limit=10, depth="shallow")
# Deep (default): intelligent retrieval with LLM analysis for long queries
matches = memory.recall(
"Summarize all architecture decisions from this quarter",
limit=10,
depth="deep",
)
```
عتبات الثقة التي تتحكم في موجّه RecallFlow قابلة للإعداد:
```python
memory = Memory(
confidence_threshold_high=0.9, # Only synthesize when very confident
confidence_threshold_low=0.4, # Explore deeper more aggressively
exploration_budget=2, # Allow up to 2 exploration rounds
query_analysis_threshold=200, # Skip LLM for queries shorter than this
)
```
## إعداد المُضمِّن
تحتاج الذاكرة إلى نموذج تضمين لتحويل النص إلى متجهات للبحث الدلالي. يمكنك إعداده بثلاث طرق.
### التمرير إلى Memory مباشرة
```python
from crewai import Memory
# As a config dict
memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}})
# As a pre-built callable
from crewai.rag.embeddings.factory import build_embedder
embedder = build_embedder({"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}})
memory = Memory(embedder=embedder)
```
### عبر إعداد مُضمِّن Crew
عند استخدام `memory=True`، يتم تمرير إعداد `embedder` الخاص بالفريق:
```python
from crewai import Crew
crew = Crew(
agents=[...],
tasks=[...],
memory=True,
embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}},
)
```
### أمثلة المزودين
<AccordionGroup>
<Accordion title="OpenAI (افتراضي)">
```python
memory = Memory(embedder={
"provider": "openai",
"config": {
"model_name": "text-embedding-3-small",
# "api_key": "sk-...", # or set OPENAI_API_KEY env var
},
})
```
</Accordion>
<Accordion title="Ollama (محلي، خاص)">
```python
memory = Memory(embedder={
"provider": "ollama",
"config": {
"model_name": "mxbai-embed-large",
"url": "http://localhost:11434/api/embeddings",
},
})
```
</Accordion>
<Accordion title="Azure OpenAI">
```python
memory = Memory(embedder={
"provider": "azure",
"config": {
"deployment_id": "your-embedding-deployment",
"api_key": "your-azure-api-key",
"api_base": "https://your-resource.openai.azure.com",
"api_version": "2024-02-01",
},
})
```
</Accordion>
<Accordion title="Google AI">
```python
memory = Memory(embedder={
"provider": "google-generativeai",
"config": {
"model_name": "gemini-embedding-001",
# "api_key": "...", # or set GOOGLE_API_KEY env var
},
})
```
</Accordion>
<Accordion title="Google Vertex AI">
```python
memory = Memory(embedder={
"provider": "google-vertex",
"config": {
"model_name": "gemini-embedding-001",
"project_id": "your-gcp-project-id",
"location": "us-central1",
},
})
```
</Accordion>
<Accordion title="Cohere">
```python
memory = Memory(embedder={
"provider": "cohere",
"config": {
"model_name": "embed-english-v3.0",
# "api_key": "...", # or set COHERE_API_KEY env var
},
})
```
</Accordion>
<Accordion title="VoyageAI">
```python
memory = Memory(embedder={
"provider": "voyageai",
"config": {
"model": "voyage-3",
# "api_key": "...", # or set VOYAGE_API_KEY env var
},
})
```
</Accordion>
<Accordion title="AWS Bedrock">
```python
memory = Memory(embedder={
"provider": "amazon-bedrock",
"config": {
"model_name": "amazon.titan-embed-text-v1",
# Uses default AWS credentials (boto3 session)
},
})
```
</Accordion>
<Accordion title="Hugging Face">
```python
memory = Memory(embedder={
"provider": "huggingface",
"config": {
"model_name": "sentence-transformers/all-MiniLM-L6-v2",
},
})
```
</Accordion>
<Accordion title="Jina">
```python
memory = Memory(embedder={
"provider": "jina",
"config": {
"model_name": "jina-embeddings-v2-base-en",
# "api_key": "...", # or set JINA_API_KEY env var
},
})
```
</Accordion>
<Accordion title="IBM WatsonX">
```python
memory = Memory(embedder={
"provider": "watsonx",
"config": {
"model_id": "ibm/slate-30m-english-rtrvr",
"api_key": "your-watsonx-api-key",
"project_id": "your-project-id",
"url": "https://us-south.ml.cloud.ibm.com",
},
})
```
</Accordion>
<Accordion title="مُضمِّن مخصص">
```python
# Pass any callable that takes a list of strings and returns a list of vectors
def my_embedder(texts: list[str]) -> list[list[float]]:
# Your embedding logic here
return [[0.1, 0.2, ...] for _ in texts]
memory = Memory(embedder=my_embedder)
```
</Accordion>
</AccordionGroup>
### مرجع المزودين
| المزود | المفتاح | النموذج النموذجي | ملاحظات |
| :--- | :--- | :--- | :--- |
| OpenAI | `openai` | `text-embedding-3-small` | افتراضي. عيّن `OPENAI_API_KEY`. |
| Ollama | `ollama` | `mxbai-embed-large` | محلي، لا حاجة لمفتاح API. |
| Azure OpenAI | `azure` | `text-embedding-ada-002` | يتطلب `deployment_id`. |
| Google AI | `google-generativeai` | `gemini-embedding-001` | عيّن `GOOGLE_API_KEY`. |
| Google Vertex | `google-vertex` | `gemini-embedding-001` | يتطلب `project_id`. |
| Cohere | `cohere` | `embed-english-v3.0` | دعم قوي متعدد اللغات. |
| VoyageAI | `voyageai` | `voyage-3` | محسّن للاسترجاع. |
| AWS Bedrock | `amazon-bedrock` | `amazon.titan-embed-text-v1` | يستخدم بيانات اعتماد boto3. |
| Hugging Face | `huggingface` | `all-MiniLM-L6-v2` | sentence-transformers محلي. |
| Jina | `jina` | `jina-embeddings-v2-base-en` | عيّن `JINA_API_KEY`. |
| IBM WatsonX | `watsonx` | `ibm/slate-30m-english-rtrvr` | يتطلب `project_id`. |
| Sentence Transformer | `sentence-transformer` | `all-MiniLM-L6-v2` | محلي، لا حاجة لمفتاح API. |
| مخصص | `custom` | -- | يتطلب `embedding_callable`. |
## إعداد LLM
تستخدم الذاكرة LLM لتحليل الحفظ (استنتاج النطاق والفئات والأهمية)، وقرارات التوحيد، وتحليل استعلام الاسترجاع العميق. يمكنك إعداد النموذج المُستخدم.
```python
from crewai import Memory, LLM
# Default: gpt-4o-mini
memory = Memory()
# Use a different OpenAI model
memory = Memory(llm="gpt-4o")
# Use Anthropic
memory = Memory(llm="anthropic/claude-3-haiku-20240307")
# Use Ollama for fully local/private analysis
memory = Memory(llm="ollama/llama3.2")
# Use Google Gemini
memory = Memory(llm="gemini/gemini-2.0-flash")
# Pass a pre-configured LLM instance with custom settings
llm = LLM(model="gpt-4o", temperature=0)
memory = Memory(llm=llm)
```
يتم تهيئة LLM **بشكل كسول** -- يتم إنشاؤه فقط عند الحاجة لأول مرة. هذا يعني أن `Memory()` لا يفشل أبدًا في وقت الإنشاء، حتى لو لم تكن مفاتيح API مُعيّنة. تظهر الأخطاء فقط عند استدعاء LLM فعليًا (مثلاً عند الحفظ بدون نطاق/فئات صريحة، أو أثناء الاسترجاع العميق).
للتشغيل المحلي/الخاص بالكامل، استخدم نموذجًا محليًا لكل من LLM والمُضمِّن:
```python
memory = Memory(
llm="ollama/llama3.2",
embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}},
)
```
## واجهة التخزين
- **الافتراضي**: LanceDB، مخزّن تحت `./.crewai/memory` (أو `$CREWAI_STORAGE_DIR/memory` إذا تم تعيين متغير البيئة، أو المسار الذي تمرره كـ `storage="path/to/dir"`).
- **واجهة مخصصة**: نفّذ بروتوكول `StorageBackend` (انظر `crewai.memory.storage.backend`) ومرّر مثيلًا إلى `Memory(storage=your_backend)`.
## الاستكشاف
فحص التسلسل الهرمي للنطاقات والفئات والسجلات:
```python
memory.tree() # Formatted tree of scopes and record counts
memory.tree("/project", max_depth=2) # Subtree view
memory.info("/project") # ScopeInfo: record_count, categories, oldest/newest
memory.list_scopes("/") # Immediate child scopes
memory.list_categories() # Category names and counts
memory.list_records(scope="/project/alpha", limit=20) # Records in a scope, newest first
```
## سلوك الفشل
إذا فشل LLM أثناء التحليل (خطأ شبكة، حد معدل، استجابة غير صالحة)، تتدهور الذاكرة بسلاسة:
- **تحليل الحفظ** -- يتم تسجيل تحذير ولا يزال يتم تخزين الذاكرة مع النطاق الافتراضي `/`، فئات فارغة، وأهمية `0.5`.
- **استخراج الذكريات** -- يتم تخزين المحتوى الكامل كذاكرة واحدة حتى لا يُفقد شيء.
- **تحليل الاستعلام** -- يتراجع الاسترجاع إلى اختيار نطاق بسيط وبحث متجهي حتى تستمر في الحصول على نتائج.
لا يتم رفع أي استثناء لفشل التحليل هذه؛ فقط فشل التخزين أو المُضمِّن سيرفع استثناءً.
## ملاحظة حول الخصوصية
يتم إرسال محتوى الذاكرة إلى LLM المُعدّ للتحليل (النطاق/الفئات/الأهمية عند الحفظ، تحليل الاستعلام والاسترجاع العميق الاختياري). للبيانات الحساسة، استخدم LLM محليًا (مثل Ollama) أو تأكد من أن مزودك يلبي متطلبات الامتثال الخاصة بك.
## أحداث الذاكرة
جميع عمليات الذاكرة تُصدر أحداثًا مع `source_type="unified_memory"`. يمكنك الاستماع للتوقيت والأخطاء والمحتوى.
| الحدث | الوصف | الخصائص الرئيسية |
| :---- | :---------- | :------------- |
| **MemoryQueryStartedEvent** | بداية الاستعلام | `query`, `limit` |
| **MemoryQueryCompletedEvent** | نجاح الاستعلام | `query`, `results`, `query_time_ms` |
| **MemoryQueryFailedEvent** | فشل الاستعلام | `query`, `error` |
| **MemorySaveStartedEvent** | بداية الحفظ | `value`, `metadata` |
| **MemorySaveCompletedEvent** | نجاح الحفظ | `value`, `save_time_ms` |
| **MemorySaveFailedEvent** | فشل الحفظ | `value`, `error` |
| **MemoryRetrievalStartedEvent** | بداية استرجاع الوكيل | `task_id` |
| **MemoryRetrievalCompletedEvent** | اكتمال استرجاع الوكيل | `task_id`, `memory_content`, `retrieval_time_ms` |
مثال: مراقبة وقت الاستعلام:
```python
from crewai.events import BaseEventListener, MemoryQueryCompletedEvent
class MemoryMonitor(BaseEventListener):
def setup_listeners(self, crewai_event_bus):
@crewai_event_bus.on(MemoryQueryCompletedEvent)
def on_done(source, event):
if getattr(event, "source_type", None) == "unified_memory":
print(f"Query '{event.query}' completed in {event.query_time_ms:.0f}ms")
```
## استكشاف المشاكل
**الذاكرة لا تستمر؟**
- تأكد من أن مسار التخزين قابل للكتابة (الافتراضي `./.crewai/memory`). مرّر `storage="./your_path"` لاستخدام مجلد مختلف، أو عيّن متغير البيئة `CREWAI_STORAGE_DIR`.
- عند استخدام فريق، تأكد من تعيين `memory=True` أو `memory=Memory(...)`.
**الاسترجاع بطيء؟**
- استخدم `depth="shallow"` لسياق الوكيل الروتيني. احتفظ بـ `depth="deep"` للاستعلامات المعقدة.
- زد `query_analysis_threshold` لتخطي تحليل LLM لمزيد من الاستعلامات.
**أخطاء تحليل LLM في السجلات؟**
- لا تزال الذاكرة تحفظ/تسترجع بإعدادات افتراضية آمنة. تحقق من مفاتيح API وحدود المعدل وتوفر النموذج إذا كنت تريد تحليل LLM كاملاً.
**أخطاء حفظ خلفية في السجلات؟**
- عمليات حفظ الذاكرة تعمل في خيط خلفي. تُصدر الأخطاء كـ `MemorySaveFailedEvent` لكنها لا تعطل الوكيل. تحقق من السجلات للسبب الجذري (عادة مشاكل اتصال LLM أو المُضمِّن).
**تعارضات الكتابة المتزامنة؟**
- عمليات LanceDB مُتسلسلة بقفل مشترك وتُعاد تلقائيًا عند التعارض. هذا يتعامل مع مثيلات `Memory` المتعددة التي تشير إلى نفس قاعدة البيانات (مثل ذاكرة وكيل + ذاكرة فريق). لا حاجة لإجراء.
**تصفح الذاكرة من الطرفية:**
```bash
crewai memory # Opens the TUI browser
crewai memory --storage-path ./my_memory # Point to a specific directory
```
**إعادة تعيين الذاكرة (مثلاً للاختبارات):**
```python
crew.reset_memories(command_type="memory") # Resets unified memory
# Or on a Memory instance:
memory.reset() # All scopes
memory.reset(scope="/project/old") # Only that subtree
```
## مرجع الإعداد
جميع الإعدادات تُمرر كمعاملات كلمة مفتاحية إلى `Memory(...)`. كل معامل له قيمة افتراضية معقولة.
| المعامل | الافتراضي | الوصف |
| :--- | :--- | :--- |
| `llm` | `"gpt-4o-mini"` | LLM للتحليل (اسم نموذج أو مثيل `BaseLLM`). |
| `storage` | `"lancedb"` | واجهة التخزين (`"lancedb"`، سلسلة مسار، أو مثيل `StorageBackend`). |
| `embedder` | `None` (افتراضي OpenAI) | المُضمِّن (قاموس إعداد، دالة قابلة للاستدعاء، أو `None` لافتراضي OpenAI). |
| `recency_weight` | `0.3` | وزن الحداثة في الدرجة المركبة. |
| `semantic_weight` | `0.5` | وزن التشابه الدلالي في الدرجة المركبة. |
| `importance_weight` | `0.2` | وزن الأهمية في الدرجة المركبة. |
| `recency_half_life_days` | `30` | أيام لتنصيف درجة الحداثة (اضمحلال أُسي). |
| `consolidation_threshold` | `0.85` | التشابه الذي يُشغّل فوقه التوحيد عند الحفظ. عيّن إلى `1.0` للتعطيل. |
| `consolidation_limit` | `5` | أقصى عدد سجلات حالية للمقارنة أثناء التوحيد. |
| `default_importance` | `0.5` | الأهمية المُعيّنة عندما لا تُوفَّر ويتم تخطي تحليل LLM. |
| `batch_dedup_threshold` | `0.98` | تشابه جيب التمام لإسقاط النسخ شبه المكررة داخل دفعة `remember_many()`. |
| `confidence_threshold_high` | `0.8` | ثقة الاسترجاع التي تُعاد فوقها النتائج مباشرة. |
| `confidence_threshold_low` | `0.5` | ثقة الاسترجاع التي يُشغّل تحتها استكشاف أعمق. |
| `complex_query_threshold` | `0.7` | للاستعلامات المعقدة، استكشف أعمق تحت هذه الثقة. |
| `exploration_budget` | `1` | عدد جولات الاستكشاف المدفوعة بـ LLM أثناء الاسترجاع العميق. |
| `query_analysis_threshold` | `200` | الاستعلامات الأقصر من هذا (بالأحرف) تتخطى تحليل LLM أثناء الاسترجاع العميق. |

155
docs/edge/ar/concepts/planning.mdx Normal file
View File

@@ -0,0 +1,155 @@
---
title: التخطيط
description: تعرّف على كيفية إضافة التخطيط إلى طاقم CrewAI وتحسين أدائه.
icon: ruler-combined
mode: "wide"
---
## نظرة عامة
تتيح لك ميزة التخطيط في CrewAI إضافة قدرة التخطيط إلى طاقمك. عند تفعيلها، قبل كل تكرار للطاقم،
يتم إرسال جميع معلومات الطاقم إلى AgentPlanner الذي يخطط للمهام خطوة بخطوة، ويُضاف هذا المخطط إلى وصف كل مهمة.
### استخدام ميزة التخطيط
البدء بميزة التخطيط سهل جدًا، الخطوة الوحيدة المطلوبة هي إضافة `planning=True` إلى طاقمك:
<CodeGroup>
```python Code
from crewai import Crew, Agent, Task, Process
# تجميع طاقمك مع قدرات التخطيط
my_crew = Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
planning=True,
)
```
</CodeGroup>
من هذه النقطة فصاعدًا، سيكون التخطيط مفعّلًا في طاقمك، وسيتم تخطيط المهام قبل كل تكرار.
<Warning>
عند تفعيل التخطيط، سيستخدم CrewAI `gpt-4o-mini` كنموذج LLM افتراضي للتخطيط، مما يتطلب مفتاح API صالحًا من OpenAI. نظرًا لأن وكلاءك قد يستخدمون نماذج LLM مختلفة، فقد يسبب ذلك ارتباكًا إذا لم يكن لديك مفتاح OpenAI API مهيأ أو إذا كنت تواجه سلوكًا غير متوقع متعلقًا باستدعاءات LLM API.
</Warning>
#### LLM التخطيط
يمكنك الآن تحديد نموذج LLM الذي سيُستخدم لتخطيط المهام.
عند تشغيل مثال الحالة الأساسية، سترى شيئًا مشابهًا للمخرجات أدناه، والتي تمثل مخرجات `AgentPlanner`
المسؤول عن إنشاء المنطق التدريجي لإضافته إلى مهام الوكلاء.
<CodeGroup>
```python Code
from crewai import Crew, Agent, Task, Process
# تجميع طاقمك مع قدرات التخطيط ونموذج LLM مخصص
my_crew = Crew(
agents=self.agents,
tasks=self.tasks,
process=Process.sequential,
planning=True,
planning_llm="gpt-4o"
)
# تشغيل الطاقم
my_crew.kickoff()
```
```markdown Result
[2024-07-15 16:49:11][INFO]: Planning the crew execution
**Step-by-Step Plan for Task Execution**
**Task Number 1: Conduct a thorough research about AI LLMs**
**Agent:** AI LLMs Senior Data Researcher
**Agent Goal:** Uncover cutting-edge developments in AI LLMs
**Task Expected Output:** A list with 10 bullet points of the most relevant information about AI LLMs
**Task Tools:** None specified
**Agent Tools:** None specified
**Step-by-Step Plan:**
1. **Define Research Scope:**
- Determine the specific areas of AI LLMs to focus on, such as advancements in architecture, use cases, ethical considerations, and performance metrics.
2. **Identify Reliable Sources:**
- List reputable sources for AI research, including academic journals, industry reports, conferences (e.g., NeurIPS, ACL), AI research labs (e.g., OpenAI, Google AI), and online databases (e.g., IEEE Xplore, arXiv).
3. **Collect Data:**
- Search for the latest papers, articles, and reports published in 2024 and early 2025.
- Use keywords like "Large Language Models 2025", "AI LLM advancements", "AI ethics 2025", etc.
4. **Analyze Findings:**
- Read and summarize the key points from each source.
- Highlight new techniques, models, and applications introduced in the past year.
5. **Organize Information:**
- Categorize the information into relevant topics (e.g., new architectures, ethical implications, real-world applications).
- Ensure each bullet point is concise but informative.
6. **Create the List:**
- Compile the 10 most relevant pieces of information into a bullet point list.
- Review the list to ensure clarity and relevance.
**Expected Output:**
A list with 10 bullet points of the most relevant information about AI LLMs.
---
**Task Number 2: Review the context you got and expand each topic into a full section for a report**
**Agent:** AI LLMs Reporting Analyst
**Agent Goal:** Create detailed reports based on AI LLMs data analysis and research findings
**Task Expected Output:** A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```'
**Task Tools:** None specified
**Agent Tools:** None specified
**Step-by-Step Plan:**
1. **Review the Bullet Points:**
- Carefully read through the list of 10 bullet points provided by the AI LLMs Senior Data Researcher.
2. **Outline the Report:**
- Create an outline with each bullet point as a main section heading.
- Plan sub-sections under each main heading to cover different aspects of the topic.
3. **Research Further Details:**
- For each bullet point, conduct additional research if necessary to gather more detailed information.
- Look for case studies, examples, and statistical data to support each section.
4. **Write Detailed Sections:**
- Expand each bullet point into a comprehensive section.
- Ensure each section includes an introduction, detailed explanation, examples, and a conclusion.
- Use markdown formatting for headings, subheadings, lists, and emphasis.
5. **Review and Edit:**
- Proofread the report for clarity, coherence, and correctness.
- Make sure the report flows logically from one section to the next.
- Format the report according to markdown standards.
6. **Finalize the Report:**
- Ensure the report is complete with all sections expanded and detailed.
- Double-check formatting and make any necessary adjustments.
**Expected Output:**
A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```'.
```
</CodeGroup>

66
docs/edge/ar/concepts/processes.mdx Normal file
View File

@@ -0,0 +1,66 @@
---
title: العمليات
description: دليل تفصيلي حول إدارة سير العمل من خلال العمليات في CrewAI، مع تفاصيل التنفيذ المحدّثة.
icon: bars-staggered
mode: "wide"
---
## نظرة عامة
<Tip>
تنسّق العمليات تنفيذ المهام بواسطة الوكلاء، على غرار إدارة المشاريع في الفرق البشرية.
تضمن هذه العمليات توزيع المهام وتنفيذها بكفاءة، وفقًا لاستراتيجية محددة مسبقًا.
</Tip>
## تنفيذات العمليات
- **تسلسلي**: ينفذ المهام بالتتابع، مما يضمن إكمال المهام بتقدم منظم.
- **هرمي**: ينظم المهام في تسلسل إداري هرمي، حيث يتم تفويض المهام وتنفيذها بناءً على سلسلة أوامر منظمة. يجب تحديد نموذج لغة المدير (`manager_llm`) أو وكيل مدير مخصص (`manager_agent`) في الطاقم لتفعيل العملية الهرمية، مما يسهّل إنشاء وإدارة المهام من قبل المدير.
## دور العمليات في العمل الجماعي
تُمكّن العمليات الوكلاء الأفراد من العمل كوحدة متماسكة، مما يبسّط جهودهم لتحقيق أهداف مشتركة بكفاءة وتناسق.
## تعيين العمليات للطاقم
لتعيين عملية لطاقم، حدد نوع العملية عند إنشاء الطاقم لتعيين استراتيجية التنفيذ. للعملية الهرمية، تأكد من تحديد `manager_llm` أو `manager_agent` لوكيل المدير.
```python
from crewai import Crew, Process
# مثال: إنشاء طاقم بعملية تسلسلية
crew = Crew(
agents=my_agents,
tasks=my_tasks,
process=Process.sequential
)
# مثال: إنشاء طاقم بعملية هرمية
# تأكد من توفير manager_llm أو manager_agent
crew = Crew(
agents=my_agents,
tasks=my_tasks,
process=Process.hierarchical,
manager_llm="gpt-4o"
# أو
# manager_agent=my_manager_agent
)
```
**ملاحظة:** تأكد من تعريف `my_agents` و `my_tasks` قبل إنشاء كائن `Crew`، وللعملية الهرمية، يُعد `manager_llm` أو `manager_agent` مطلوبًا أيضًا.
## العملية التسلسلية
تعكس هذه الطريقة سير عمل الفريق الديناميكي، وتتقدم عبر المهام بطريقة مدروسة ومنهجية. يتبع تنفيذ المهام الترتيب المحدد مسبقًا في قائمة المهام، حيث يعمل ناتج مهمة واحدة كسياق للمهمة التالية.
لتخصيص سياق المهمة، استخدم معامل `context` في فئة `Task` لتحديد المخرجات التي يجب استخدامها كسياق للمهام اللاحقة.
## العملية الهرمية
تحاكي التسلسل الهرمي المؤسسي، حيث يسمح CrewAI بتحديد وكيل مدير مخصص أو إنشاء واحد تلقائيًا، مما يتطلب تحديد نموذج لغة المدير (`manager_llm`). يشرف هذا الوكيل على تنفيذ المهام، بما في ذلك التخطيط والتفويض والتحقق. لا يتم تعيين المهام مسبقًا؛ يخصص المدير المهام للوكلاء بناءً على قدراتهم، ويراجع المخرجات، ويقيّم اكتمال المهام.
## فئة Process: نظرة عامة مفصلة
تم تنفيذ فئة `Process` كتعداد (`Enum`)، مما يضمن أمان الأنواع ويقيّد قيم العملية على الأنواع المحددة (`sequential`، `hierarchical`).
## الخلاصة
التعاون المنظم الذي تسهّله العمليات داخل CrewAI ضروري لتمكين العمل الجماعي المنهجي بين الوكلاء.
تم تحديث هذه الوثائق لتعكس أحدث الميزات والتحسينات، مما يضمن وصول المستخدمين إلى أحدث المعلومات وأكثرها شمولاً.

162
docs/edge/ar/concepts/production-architecture.mdx Normal file
View File

@@ -0,0 +1,162 @@
---
title: بنية الإنتاج
description: أفضل الممارسات لبناء تطبيقات ذكاء اصطناعي جاهزة للإنتاج مع CrewAI
icon: server
mode: "wide"
---
# عقلية التدفق أولاً
عند بناء تطبيقات ذكاء اصطناعي إنتاجية مع CrewAI، **نوصي بالبدء بتدفق (Flow)**.
بينما يمكن تشغيل أطقم أو وكلاء فرديين، فإن تغليفهم في تدفق يوفر الهيكل اللازم لتطبيق متين وقابل للتوسع.
## لماذا التدفقات؟
1. **إدارة الحالة**: توفر التدفقات طريقة مدمجة لإدارة الحالة عبر مراحل مختلفة من تطبيقك. هذا ضروري لتمرير البيانات بين الأطقم والحفاظ على السياق ومعالجة مدخلات المستخدم.
2. **التحكم**: تتيح لك التدفقات تحديد مسارات تنفيذ دقيقة، بما في ذلك الحلقات والشرطيات ومنطق التفريع. هذا أساسي لمعالجة الحالات الاستثنائية وضمان سلوك تطبيقك بشكل متوقع.
3. **المراقبة**: توفر التدفقات هيكلًا واضحًا يسهّل تتبع التنفيذ وتصحيح الأخطاء ومراقبة الأداء. نوصي باستخدام [تتبع CrewAI](/ar/observability/tracing) للحصول على رؤى تفصيلية. ما عليك سوى تشغيل `crewai login` لتفعيل ميزات المراقبة المجانية.
## البنية
يبدو تطبيق CrewAI الإنتاجي النموذجي هكذا:
```mermaid
graph TD
Start((Start)) --> Flow[Flow Orchestrator]
Flow --> State{State Management}
State --> Step1[Step 1: Data Gathering]
Step1 --> Crew1[Research Crew]
Crew1 --> State
State --> Step2{Condition Check}
Step2 -- "Valid" --> Step3[Step 3: Execution]
Step3 --> Crew2[Action Crew]
Step2 -- "Invalid" --> End((End))
Crew2 --> End
```
### 1. فئة التدفق
فئة `Flow` هي نقطة الدخول. تحدد مخطط الحالة والطرق التي تنفذ منطقك.
```python
from crewai.flow.flow import Flow, listen, start
from pydantic import BaseModel
class AppState(BaseModel):
user_input: str = ""
research_results: str = ""
final_report: str = ""
class ProductionFlow(Flow[AppState]):
@start()
def gather_input(self):
# ... منطق الحصول على المدخلات ...
pass
@listen(gather_input)
def run_research_crew(self):
# ... تشغيل طاقم ...
pass
```
### 2. إدارة الحالة
استخدم نماذج Pydantic لتعريف حالتك. يضمن هذا أمان الأنواع ويوضح البيانات المتاحة في كل مرحلة.
- **اجعلها بسيطة**: خزّن فقط ما تحتاجه للاستمرار بين المراحل.
- **استخدم بيانات منظمة**: تجنب القواميس غير المنظمة قدر الإمكان.
### 3. الأطقم كوحدات عمل
فوّض المهام المعقدة إلى الأطقم. يجب أن يكون الطاقم مركّزًا على هدف محدد (مثل "البحث في موضوع"، "كتابة مقال مدونة").
- **لا تبالغ في هندسة الأطقم**: اجعلها مركّزة.
- **مرر الحالة بشكل صريح**: مرر البيانات الضرورية من حالة التدفق إلى مدخلات الطاقم.
```python
@listen(gather_input)
def run_research_crew(self):
crew = ResearchCrew()
result = crew.kickoff(inputs={"topic": self.state.user_input})
self.state.research_results = result.raw
```
## عناصر التحكم الأولية
استفد من عناصر التحكم الأولية في CrewAI لإضافة المتانة والتحكم إلى أطقمك.
### 1. حواجز المهام
استخدم [حواجز المهام](/ar/concepts/tasks#task-guardrails) للتحقق من مخرجات المهام قبل قبولها. يضمن هذا أن وكلاءك ينتجون نتائج عالية الجودة.
```python
def validate_content(result: TaskOutput) -> Tuple[bool, Any]:
if len(result.raw) < 100:
return (False, "Content is too short. Please expand.")
return (True, result.raw)
task = Task(
...,
guardrail=validate_content
)
```
### 2. المخرجات المنظمة
استخدم دائمًا المخرجات المنظمة (`output_pydantic` أو `output_json`) عند تمرير البيانات بين المهام أو إلى تطبيقك. يمنع هذا أخطاء التحليل ويضمن أمان الأنواع.
```python
class ResearchResult(BaseModel):
summary: str
sources: List[str]
task = Task(
...,
output_pydantic=ResearchResult
)
```
### 3. خطافات LLM
استخدم [خطافات LLM](/ar/learn/llm-hooks) لفحص أو تعديل الرسائل قبل إرسالها إلى LLM، أو لتنقية الاستجابات.
```python
@before_llm_call
def log_request(context):
print(f"Agent {context.agent.role} is calling the LLM...")
```
## أنماط النشر
عند نشر تدفقك، ضع في اعتبارك ما يلي:
### CrewAI Enterprise
أسهل طريقة لنشر تدفقك هي استخدام CrewAI Enterprise. تتعامل مع البنية التحتية والمصادقة والمراقبة نيابة عنك.
راجع [دليل النشر](/ar/enterprise/guides/deploy-to-amp) للبدء.
```bash
crewai deploy create
```
### التنفيذ غير المتزامن
للمهام طويلة التشغيل، استخدم `kickoff_async` لتجنب حظر واجهتك البرمجية.
### الاستمرارية
استخدم مزيّن `@persist` لحفظ حالة تدفقك في قاعدة بيانات. يتيح لك هذا استئناف التنفيذ إذا تعطلت العملية أو إذا كنت بحاجة لانتظار مدخلات بشرية.
```python
@persist
class ProductionFlow(Flow[AppState]):
# ...
```
افتراضيًا، يستأنف `@persist` تدفقًا عند توفير `kickoff(inputs={"id": <uuid>})`، مما يمدّ نفس تاريخ `flow_uuid`. لـ **تفرع** تدفق مستمر إلى نسبٍ جديد — ترطيب الحالة من تشغيل سابق ولكن الكتابة تحت `state.id` جديد — مرّر `restore_from_state_id`:
```python
flow.kickoff(restore_from_state_id="<previous-run-state-id>")
```
يحصل التشغيل الجديد على `state.id` جديد (مولّد تلقائيًا، أو `inputs["id"]` إذا تم تثبيته) لذا لا تمتد كتابات `@persist` الخاصة به إلى تاريخ المصدر. الجمع مع `from_checkpoint` يطلق `ValueError`؛ اختر مصدر ترطيب واحدًا.
## الخلاصة
- **ابدأ بتدفق.**
- **حدد حالة واضحة.**
- **استخدم الأطقم للمهام المعقدة.**
- **انشر مع API واستمرارية.**

148
docs/edge/ar/concepts/reasoning.mdx Normal file
View File

@@ -0,0 +1,148 @@
---
title: الاستدلال
description: "تعرّف على كيفية تفعيل واستخدام استدلال الوكيل لتحسين تنفيذ المهام."
icon: brain
mode: "wide"
---
## نظرة عامة
استدلال الوكيل هو ميزة تتيح للوكلاء التأمل في المهمة وإنشاء خطة قبل التنفيذ. يساعد هذا الوكلاء على التعامل مع المهام بشكل أكثر منهجية ويضمن استعدادهم لأداء العمل المطلوب.
## الاستخدام
لتفعيل الاستدلال لوكيل، ما عليك سوى تعيين `reasoning=True` عند إنشاء الوكيل:
```python
from crewai import Agent
agent = Agent(
role="Data Analyst",
goal="Analyze complex datasets and provide insights",
backstory="You are an experienced data analyst with expertise in finding patterns in complex data.",
reasoning=True, # تفعيل الاستدلال
max_reasoning_attempts=3 # اختياري: تعيين حد أقصى لمحاولات الاستدلال
)
```
## كيف يعمل
عند تفعيل الاستدلال، قبل تنفيذ المهمة، سيقوم الوكيل بما يلي:
1. التأمل في المهمة وإنشاء خطة مفصلة
2. تقييم ما إذا كان مستعدًا لتنفيذ المهمة
3. تحسين الخطة حسب الحاجة حتى يصبح مستعدًا أو يصل إلى max_reasoning_attempts
4. حقن خطة الاستدلال في وصف المهمة قبل التنفيذ
تساعد هذه العملية الوكيل على تقسيم المهام المعقدة إلى خطوات يمكن إدارتها وتحديد التحديات المحتملة قبل البدء.
## خيارات التهيئة
<ParamField body="reasoning" type="bool" default="False">
تفعيل أو تعطيل الاستدلال
</ParamField>
<ParamField body="max_reasoning_attempts" type="int" default="None">
الحد الأقصى لعدد المحاولات لتحسين الخطة قبل المتابعة بالتنفيذ. إذا كانت القيمة None (الافتراضي)، سيستمر الوكيل في التحسين حتى يصبح مستعدًا.
</ParamField>
## مثال
إليك مثالًا كاملًا:
```python
from crewai import Agent, Task, Crew
# إنشاء وكيل مع تفعيل الاستدلال
analyst = Agent(
role="Data Analyst",
goal="Analyze data and provide insights",
backstory="You are an expert data analyst.",
reasoning=True,
max_reasoning_attempts=3 # اختياري: تعيين حد لمحاولات الاستدلال
)
# إنشاء مهمة
analysis_task = Task(
description="Analyze the provided sales data and identify key trends.",
expected_output="A report highlighting the top 3 sales trends.",
agent=analyst
)
# إنشاء طاقم وتشغيل المهمة
crew = Crew(agents=[analyst], tasks=[analysis_task])
result = crew.kickoff()
print(result)
```
## معالجة الأخطاء
صُممت عملية الاستدلال لتكون متينة، مع معالجة أخطاء مدمجة. إذا حدث خطأ أثناء الاستدلال، سيتابع الوكيل تنفيذ المهمة بدون خطة الاستدلال. يضمن هذا إمكانية تنفيذ المهام حتى في حالة فشل عملية الاستدلال.
إليك كيفية التعامل مع الأخطاء المحتملة في الكود الخاص بك:
```python
from crewai import Agent, Task
import logging
# إعداد التسجيل لالتقاط أي أخطاء في الاستدلال
logging.basicConfig(level=logging.INFO)
# إنشاء وكيل مع تفعيل الاستدلال
agent = Agent(
role="Data Analyst",
goal="Analyze data and provide insights",
reasoning=True,
max_reasoning_attempts=3
)
# إنشاء مهمة
task = Task(
description="Analyze the provided sales data and identify key trends.",
expected_output="A report highlighting the top 3 sales trends.",
agent=agent
)
# تنفيذ المهمة
# إذا حدث خطأ أثناء الاستدلال، سيتم تسجيله وسيستمر التنفيذ
result = agent.execute_task(task)
```
## مثال على مخرجات الاستدلال
إليك مثالًا على شكل خطة الاستدلال لمهمة تحليل البيانات:
```
Task: Analyze the provided sales data and identify key trends.
Reasoning Plan:
I'll analyze the sales data to identify the top 3 trends.
1. Understanding of the task:
I need to analyze sales data to identify key trends that would be valuable for business decision-making.
2. Key steps I'll take:
- First, I'll examine the data structure to understand what fields are available
- Then I'll perform exploratory data analysis to identify patterns
- Next, I'll analyze sales by time periods to identify temporal trends
- I'll also analyze sales by product categories and customer segments
- Finally, I'll identify the top 3 most significant trends
3. Approach to challenges:
- If the data has missing values, I'll decide whether to fill or filter them
- If the data has outliers, I'll investigate whether they're valid data points or errors
- If trends aren't immediately obvious, I'll apply statistical methods to uncover patterns
4. Use of available tools:
- I'll use data analysis tools to explore and visualize the data
- I'll use statistical tools to identify significant patterns
- I'll use knowledge retrieval to access relevant information about sales analysis
5. Expected outcome:
A concise report highlighting the top 3 sales trends with supporting evidence from the data.
READY: I am ready to execute the task.
```
تساعد خطة الاستدلال هذه الوكيل على تنظيم نهجه تجاه المهمة، والنظر في التحديات المحتملة، وضمان تقديم المخرجات المتوقعة.

306
docs/edge/ar/concepts/skills.mdx Normal file
View File

@@ -0,0 +1,306 @@
---
title: المهارات
description: حزم المهارات المبنية على نظام الملفات التي تحقن خبرة المجال والتعليمات في إرشادات الوكلاء.
icon: bolt
mode: "wide"
---
## نظرة عامة
المهارات هي مجلدات مستقلة توفر للوكلاء **تعليمات وإرشادات ومواد مرجعية خاصة بالمجال**. تُعرّف كل مهارة بملف `SKILL.md` يحتوي على بيانات وصفية YAML ومحتوى Markdown.
عند التفعيل، يتم حقن تعليمات المهارة مباشرة في إرشادات مهمة الوكيل — مما يمنح الوكيل خبرة دون الحاجة لأي تغييرات في الكود.
<Note type="info" title="المهارات مقابل الأدوات — التمييز الأساسي">
**المهارات ليست أدوات.** هذه هي نقطة الارتباك الأكثر شيوعًا.
- **المهارات** تحقن *تعليمات وسياق* في إرشادات الوكيل. تخبر الوكيل *كيف يفكر* في مشكلة ما.
- **الأدوات** تمنح الوكيل *دوال قابلة للاستدعاء* لاتخاذ إجراءات (البحث، قراءة الملفات، استدعاء APIs).
غالبًا ما تحتاج **كليهما**: مهارات للخبرة، وأدوات للإجراء. يتم تكوينهما بشكل مستقل ويُكمّلان بعضهما.
</Note>
---
## البداية السريعة
### 1. إنشاء مجلد المهارة
```
skills/
└── code-review/
├── SKILL.md # مطلوب — التعليمات
├── references/ # اختياري — مستندات مرجعية
│ └── style-guide.md
└── scripts/ # اختياري — سكربتات قابلة للتنفيذ
```
### 2. كتابة SKILL.md الخاص بك
```markdown
---
name: code-review
description: Guidelines for conducting thorough code reviews with focus on security and performance.
metadata:
author: your-team
version: "1.0"
---
## إرشادات مراجعة الكود
عند مراجعة الكود، اتبع قائمة التحقق هذه:
1. **الأمان**: تحقق من ثغرات الحقن وتجاوز المصادقة وكشف البيانات
2. **الأداء**: ابحث عن استعلامات N+1 والتخصيصات غير الضرورية والاستدعاءات المحظورة
3. **القابلية للقراءة**: تأكد من وضوح التسمية والتعليقات المناسبة والأسلوب المتسق
4. **الاختبارات**: تحقق من تغطية اختبار كافية للوظائف الجديدة
### مستويات الخطورة
- **حرج**: ثغرات أمنية، مخاطر فقدان البيانات → حظر الدمج
- **رئيسي**: مشاكل أداء، أخطاء منطقية → طلب تغييرات
- **ثانوي**: مسائل أسلوبية، اقتراحات تسمية → الموافقة مع تعليقات
```
### 3. ربطها بوكيل
```python
from crewai import Agent
from crewai_tools import GithubSearchTool, FileReadTool
reviewer = Agent(
role="Senior Code Reviewer",
goal="Review pull requests for quality and security issues",
backstory="Staff engineer with expertise in secure coding practices.",
skills=["./skills"], # يحقن إرشادات المراجعة
tools=[GithubSearchTool(), FileReadTool()], # يسمح للوكيل بقراءة الكود
)
```
الوكيل الآن لديه **خبرة** (من المهارة) و**قدرات** (من الأدوات) معًا.
---
## المهارات + الأدوات: العمل معًا
إليك أنماط شائعة توضح كيف تُكمّل المهارات والأدوات بعضهما:
### النمط 1: مهارات فقط (خبرة المجال، بدون إجراءات مطلوبة)
استخدم عندما يحتاج الوكيل لتعليمات محددة لكن لا يحتاج لاستدعاء خدمات خارجية:
```python
agent = Agent(
role="Technical Writer",
goal="Write clear API documentation",
backstory="Expert technical writer",
skills=["./skills/api-docs-style"], # إرشادات وقوالب الكتابة
# لا حاجة لأدوات — الوكيل يكتب بناءً على السياق المقدم
)
```
### النمط 2: أدوات فقط (إجراءات، بدون خبرة خاصة)
استخدم عندما يحتاج الوكيل لاتخاذ إجراءات لكن لا يحتاج لتعليمات مجال محددة:
```python
from crewai_tools import SerperDevTool, ScrapeWebsiteTool
agent = Agent(
role="Web Researcher",
goal="Find information about a topic",
backstory="Skilled at finding information online",
tools=[SerperDevTool(), ScrapeWebsiteTool()], # يمكنه البحث والاستخراج
# لا حاجة لمهارات — البحث العام لا يحتاج إرشادات خاصة
)
```
### النمط 3: مهارات + أدوات (خبرة وإجراءات)
النمط الأكثر شيوعًا في العالم الحقيقي. المهارة توفر *كيف* تقترب من العمل؛ الأدوات توفر *ما* يمكن للوكيل فعله:
```python
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool
analyst = Agent(
role="Security Analyst",
goal="Audit infrastructure for vulnerabilities",
backstory="Expert in cloud security and compliance",
skills=["./skills/security-audit"], # منهجية وقوائم تحقق التدقيق
tools=[
SerperDevTool(), # البحث عن ثغرات معروفة
FileReadTool(), # قراءة ملفات التكوين
CodeInterpreterTool(), # تشغيل سكربتات التحليل
],
)
```
### النمط 4: مهارات + MCP
المهارات تعمل مع خوادم MCP بنفس الطريقة التي تعمل بها مع الأدوات:
```python
agent = Agent(
role="Data Analyst",
goal="Analyze customer data and generate reports",
backstory="Expert data analyst with strong statistical background",
skills=["./skills/data-analysis"], # منهجية التحليل
mcps=["https://data-warehouse.example.com/sse"], # وصول بيانات عن بُعد
)
```
### النمط 5: مهارات + تطبيقات
المهارات يمكن أن توجّه كيف يستخدم الوكيل تكاملات المنصة:
```python
agent = Agent(
role="Customer Support Agent",
goal="Respond to customer inquiries professionally",
backstory="Experienced support representative",
skills=["./skills/support-playbook"], # قوالب الردود وقواعد التصعيد
apps=["gmail", "zendesk"], # يمكنه إرسال رسائل بريد وتحديث التذاكر
)
```
---
## المهارات على مستوى الطاقم
يمكن تعيين المهارات على الطاقم لتُطبّق على **جميع الوكلاء**:
```python
from crewai import Crew
crew = Crew(
agents=[researcher, writer, reviewer],
tasks=[research_task, write_task, review_task],
skills=["./skills"], # جميع الوكلاء يحصلون على هذه المهارات
)
```
المهارات على مستوى الوكيل لها الأولوية — إذا تم اكتشاف نفس المهارة في كلا المستويين، يتم استخدام نسخة الوكيل.
---
## تنسيق SKILL.md
```markdown
---
name: my-skill
description: وصف قصير لما تفعله هذه المهارة ومتى تُستخدم.
license: Apache-2.0 # اختياري
compatibility: crewai>=0.1.0 # اختياري
metadata: # اختياري
author: your-name
version: "1.0"
allowed-tools: web-search file-read # اختياري، تجريبي
---
التعليمات للوكيل تُكتب هنا. يتم حقن محتوى Markdown هذا
في إرشادات الوكيل عند تفعيل المهارة.
```
### حقول البيانات الوصفية
| الحقل | مطلوب | الوصف |
| :-------------- | :------- | :----------------------------------------------------------------------- |
| `name` | نعم | 1-64 حرف. أحرف صغيرة أبجدية رقمية وشرطات. يجب أن يطابق اسم المجلد. |
| `description` | نعم | 1-1024 حرف. يصف ما تفعله المهارة ومتى تُستخدم. |
| `license` | لا | اسم الترخيص أو مرجع لملف ترخيص مضمّن. |
| `compatibility` | لا | حد أقصى 500 حرف. متطلبات البيئة (منتجات، حزم، شبكة). |
| `metadata` | لا | تعيين مفتاح-قيمة نصي عشوائي. |
| `allowed-tools` | لا | قائمة أدوات معتمدة مسبقًا مفصولة بمسافات. تجريبي. |
---
## هيكل المجلد
```
my-skill/
├── SKILL.md # مطلوب — البيانات الوصفية + التعليمات
├── scripts/ # اختياري — سكربتات قابلة للتنفيذ
├── references/ # اختياري — مستندات مرجعية
└── assets/ # اختياري — ملفات ثابتة (إعدادات، بيانات)
```
يجب أن يتطابق اسم المجلد مع حقل `name` في `SKILL.md`. مجلدات `scripts/` و `references/` و `assets/` متاحة في مسار المهارة `path` للوكلاء الذين يحتاجون للإشارة إلى الملفات مباشرة.
---
## المهارات المحمّلة مسبقًا
للمزيد من التحكم، يمكنك اكتشاف المهارات وتفعيلها برمجيًا:
```python
from pathlib import Path
from crewai.skills import discover_skills, activate_skill
# اكتشاف جميع المهارات في مجلد
skills = discover_skills(Path("./skills"))
# تفعيلها (تحميل محتوى SKILL.md الكامل)
activated = [activate_skill(s) for s in skills]
# تمرير إلى وكيل
agent = Agent(
role="Researcher",
goal="Find relevant information",
backstory="An expert researcher.",
skills=activated,
)
```
---
## كيف يتم تحميل المهارات
تستخدم المهارات **الكشف التدريجي** — تحمّل فقط ما هو مطلوب في كل مرحلة:
| المرحلة | ما يتم تحميله | متى |
| :--------- | :------------------------------------ | :------------------ |
| الاكتشاف | الاسم، الوصف، حقول البيانات الوصفية | `discover_skills()` |
| التفعيل | نص محتوى SKILL.md الكامل | `activate_skill()` |
أثناء التنفيذ العادي للوكيل (تمرير مسارات المجلدات عبر `skills=["./skills"]`)، يتم اكتشاف المهارات وتفعيلها تلقائيًا. التحميل التدريجي مهم فقط عند استخدام الواجهة البرمجية.
---
## المهارات مقابل المعرفة
كلا المهارات والمعرفة تُعدّل إرشادات الوكيل، لكنهما يخدمان أغراضًا مختلفة:
| الجانب | المهارات | المعرفة |
| :--- | :--- | :--- |
| **ما توفره** | تعليمات، إجراءات، إرشادات | حقائق، بيانات، معلومات |
| **كيف تُخزّن** | ملفات Markdown (SKILL.md) | مُضمّنة في مخزن متجهي (ChromaDB) |
| **كيف تُسترجع** | يتم حقن المحتوى الكامل في الإرشادات | البحث الدلالي يجد الأجزاء ذات الصلة |
| **الأفضل لـ** | المنهجيات، قوائم التحقق، أدلة الأسلوب | مستندات الشركة، معلومات المنتج، بيانات مرجعية |
| **يُعيّن عبر** | `skills=["./skills"]` | `knowledge_sources=[source]` |
**القاعدة العامة:** إذا كان الوكيل يحتاج لاتباع *عملية*، استخدم مهارة. إذا كان يحتاج للرجوع إلى *بيانات*، استخدم المعرفة.
---
## الأسئلة الشائعة
<AccordionGroup>
<Accordion title="هل أحتاج لتعيين المهارات والأدوات معًا؟">
يعتمد على حالة الاستخدام. المهارات والأدوات **مستقلتان** — يمكنك استخدام أيّ منهما أو كليهما أو لا شيء.
- **مهارات فقط**: عندما يحتاج الوكيل خبرة لكن لا يحتاج إجراءات خارجية (مثال: الكتابة بإرشادات أسلوبية)
- **أدوات فقط**: عندما يحتاج الوكيل إجراءات لكن لا يحتاج منهجية خاصة (مثال: بحث بسيط على الويب)
- **كليهما**: عندما يحتاج الوكيل خبرة وإجراءات (مثال: تدقيق أمني بقوائم تحقق محددة وقدرة على فحص الكود)
</Accordion>
<Accordion title="هل توفر المهارات أدوات تلقائيًا؟">
**لا.** حقل `allowed-tools` في SKILL.md هو بيانات وصفية تجريبية فقط — لا يُنشئ أو يحقن أي أدوات. يجب عليك دائمًا تعيين الأدوات بشكل منفصل عبر `tools=[]` أو `mcps=[]` أو `apps=[]`.
</Accordion>
<Accordion title="ماذا يحدث إذا عيّنت نفس المهارة على كل من الوكيل والطاقم؟">
المهارة على مستوى الوكيل لها الأولوية. يتم إزالة التكرار حسب الاسم — مهارات الوكيل تُعالج أولاً، لذا إذا ظهر نفس اسم المهارة في كلا المستويين، تُستخدم نسخة الوكيل.
</Accordion>
<Accordion title="ما الحجم الأقصى لمحتوى SKILL.md؟">
هناك تحذير ناعم عند 50,000 حرف، لكن بدون حد صارم. حافظ على تركيز المهارات وإيجازها للحصول على أفضل النتائج — الحقن الكبيرة في الإرشادات قد تُشتت انتباه الوكيل.
</Accordion>
</AccordionGroup>

1120
docs/edge/ar/concepts/tasks.mdx Normal file
View File

File diff suppressed because it is too large Load Diff

49
docs/edge/ar/concepts/testing.mdx Normal file
View File

@@ -0,0 +1,49 @@
---
title: الاختبار
description: تعرّف على كيفية اختبار طاقم CrewAI وتقييم أدائه.
icon: vial
mode: "wide"
---
## نظرة عامة
يُعد الاختبار جزءًا حيويًا من عملية التطوير، ومن الضروري التأكد من أن طاقمك يعمل كما هو متوقع. مع CrewAI، يمكنك اختبار طاقمك وتقييم أدائه بسهولة باستخدام إمكانيات الاختبار المدمجة.
### استخدام ميزة الاختبار
أضفنا أمر CLI `crewai test` لتسهيل اختبار طاقمك. سيقوم هذا الأمر بتشغيل طاقمك لعدد محدد من التكرارات وتوفير مقاييس أداء مفصلة. المعاملات هي `n_iterations` و `model`، وهي اختيارية وتكون قيمها الافتراضية 2 و `gpt-4o-mini` على التوالي. حاليًا، المزود الوحيد المتاح هو OpenAI.
```bash
crewai test
```
إذا أردت تشغيل المزيد من التكرارات أو استخدام نموذج مختلف، يمكنك تحديد المعاملات هكذا:
```bash
crewai test --n_iterations 5 --model gpt-4o
```
أو باستخدام الصيغة المختصرة:
```bash
crewai test -n 5 -m gpt-4o
```
عند تشغيل أمر `crewai test`، سيتم تنفيذ الطاقم للعدد المحدد من التكرارات، وستُعرض مقاييس الأداء في نهاية التشغيل.
سيظهر جدول الدرجات في النهاية لعرض أداء الطاقم من حيث المقاييس التالية:
<center>**درجات المهام (1-10 الأعلى أفضل)**</center>
| المهام/الطاقم/الوكلاء | التشغيل 1 | التشغيل 2 | المجموع المتوسط | الوكلاء | معلومات إضافية |
|:------------------|:-----:|:-----:|:----------:|:------------------------------:|:---------------------------------|
| المهمة 1 | 9.0 | 9.5 | **9.2** | Professional Insights | |
| | | | | Researcher | |
| المهمة 2 | 9.0 | 10.0 | **9.5** | Company Profile Investigator | |
| المهمة 3 | 9.0 | 9.0 | **9.0** | Automation Insights | |
| | | | | Specialist | |
| المهمة 4 | 9.0 | 9.0 | **9.0** | Final Report Compiler | Automation Insights Specialist |
| الطاقم | 9.00 | 9.38 | **9.2** | | |
| زمن التنفيذ (ثانية) | 126 | 145 | **135** | | |
يوضح المثال أعلاه نتائج الاختبار لتشغيلين للطاقم مع مهمتين، مع الدرجة الإجمالية المتوسطة لكل مهمة والطاقم ككل.

290
docs/edge/ar/concepts/tools.mdx Normal file
View File

@@ -0,0 +1,290 @@
---
title: الأدوات
description: فهم واستخدام الأدوات ضمن إطار عمل CrewAI لتعاون الوكلاء وتنفيذ المهام.
icon: screwdriver-wrench
mode: "wide"
---
## نظرة عامة
تُمكّن أدوات CrewAI الوكلاء بقدرات تتراوح من البحث على الويب وتحليل البيانات إلى التعاون وتفويض المهام بين الزملاء.
توضح هذه الوثائق كيفية إنشاء هذه الأدوات ودمجها والاستفادة منها ضمن إطار عمل CrewAI، بما في ذلك التركيز على أدوات التعاون.
<Note type="info" title="الأدوات هي أحد أنواع قدرات الوكيل الخمسة">
الأدوات تمنح الوكلاء **دوال قابلة للاستدعاء** لاتخاذ إجراءات. تعمل جنبًا إلى جنب مع [MCP](/ar/mcp/overview) (خوادم أدوات عن بُعد) و[التطبيقات](/ar/concepts/agent-capabilities) (تكاملات المنصة) و[المهارات](/ar/concepts/skills) (خبرة المجال) و[المعرفة](/ar/concepts/knowledge) (حقائق مُسترجعة). راجع نظرة عامة على [قدرات الوكيل](/ar/concepts/agent-capabilities) لفهم متى تستخدم كل نوع.
</Note>
## ما هي الأداة؟
الأداة في CrewAI هي مهارة أو وظيفة يمكن للوكلاء استخدامها لأداء إجراءات مختلفة.
يشمل ذلك أدوات من [مجموعة أدوات CrewAI](https://github.com/joaomdmoura/crewai-tools) و[أدوات LangChain](https://python.langchain.com/docs/integrations/tools)،
مما يُمكّن كل شيء من عمليات البحث البسيطة إلى التفاعلات المعقدة والعمل الجماعي الفعال بين الوكلاء.
<Note type="info" title="تحسين المؤسسات: مستودع الأدوات">
يوفر CrewAI AMP مستودع أدوات شامل مع تكاملات جاهزة لأنظمة الأعمال الشائعة وواجهات API. انشر الوكلاء مع أدوات المؤسسة في دقائق بدلاً من أيام.
يتضمن مستودع أدوات المؤسسة:
- موصلات جاهزة لأنظمة المؤسسة الشائعة
- واجهة إنشاء أدوات مخصصة
- إمكانيات التحكم في الإصدارات والمشاركة
- ميزات الأمان والامتثال
</Note>
## الخصائص الرئيسية للأدوات
- **المنفعة**: مصممة لمهام مثل البحث على الويب وتحليل البيانات وإنشاء المحتوى وتعاون الوكلاء.
- **التكامل**: تعزز قدرات الوكلاء من خلال دمج الأدوات بسلاسة في سير عملهم.
- **القابلية للتخصيص**: توفر المرونة لتطوير أدوات مخصصة أو استخدام الأدوات الموجودة، لتلبية الاحتياجات المحددة للوكلاء.
- **معالجة الأخطاء**: تتضمن آليات معالجة أخطاء قوية لضمان التشغيل السلس.
- **آلية التخزين المؤقت**: تتميز بتخزين مؤقت ذكي لتحسين الأداء وتقليل العمليات المتكررة.
- **الدعم غير المتزامن**: تتعامل مع الأدوات المتزامنة وغير المتزامنة، مما يُمكّن العمليات غير الحاجبة.
## استخدام أدوات CrewAI
لتعزيز قدرات وكلائك بأدوات CrewAI، ابدأ بتثبيت حزمة الأدوات الإضافية:
```bash
pip install 'crewai[tools]'
```
إليك مثالًا يوضح استخدامها:
```python Code
import os
from crewai import Agent, Task, Crew
# استيراد أدوات crewAI
from crewai_tools import (
DirectoryReadTool,
FileReadTool,
SerperDevTool,
WebsiteSearchTool
)
# إعداد مفاتيح API
os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key
os.environ["OPENAI_API_KEY"] = "Your Key"
# إنشاء الأدوات
docs_tool = DirectoryReadTool(directory='./blog-posts')
file_tool = FileReadTool()
search_tool = SerperDevTool()
web_rag_tool = WebsiteSearchTool()
# إنشاء الوكلاء
researcher = Agent(
role='Market Research Analyst',
goal='Provide up-to-date market analysis of the AI industry',
backstory='An expert analyst with a keen eye for market trends.',
tools=[search_tool, web_rag_tool],
verbose=True
)
writer = Agent(
role='Content Writer',
goal='Craft engaging blog posts about the AI industry',
backstory='A skilled writer with a passion for technology.',
tools=[docs_tool, file_tool],
verbose=True
)
# تعريف المهام
research = Task(
description='Research the latest trends in the AI industry and provide a summary.',
expected_output='A summary of the top 3 trending developments in the AI industry with a unique perspective on their significance.',
agent=researcher
)
write = Task(
description='Write an engaging blog post about the AI industry, based on the research analyst\'s summary. Draw inspiration from the latest blog posts in the directory.',
expected_output='A 4-paragraph blog post formatted in markdown with engaging, informative, and accessible content, avoiding complex jargon.',
agent=writer,
output_file='blog-posts/new_post.md'
)
# تجميع طاقم مع تفعيل التخطيط
crew = Crew(
agents=[researcher, writer],
tasks=[research, write],
verbose=True,
planning=True,
)
# تنفيذ المهام
crew.kickoff()
```
## أدوات CrewAI المتاحة
- **معالجة الأخطاء**: جميع الأدوات مبنية بقدرات معالجة الأخطاء، مما يسمح للوكلاء بإدارة الاستثناءات بسلاسة ومتابعة مهامهم.
- **آلية التخزين المؤقت**: جميع الأدوات تدعم التخزين المؤقت، مما يُمكّن الوكلاء من إعادة استخدام النتائج المحصلة سابقًا بكفاءة، مما يقلل الحمل على الموارد الخارجية ويسرّع وقت التنفيذ. يمكنك أيضًا تحديد تحكم أدق في آلية التخزين المؤقت باستخدام خاصية `cache_function` على الأداة.
إليك قائمة بالأدوات المتاحة وأوصافها:
| الأداة | الوصف |
| :------------------------------- | :--------------------------------------------------------------------------------------------- |
| **ApifyActorsTool** | أداة تدمج Apify Actors مع سير عملك لمهام استخراج البيانات من الويب والأتمتة. |
| **BrowserbaseLoadTool** | أداة للتفاعل مع المتصفحات واستخراج البيانات منها. |
| **CodeDocsSearchTool** | أداة RAG محسّنة للبحث في وثائق الكود والمستندات التقنية ذات الصلة. |
| **CodeInterpreterTool** | أداة لتفسير كود Python. |
| **ComposioTool** | تُمكّن استخدام أدوات Composio. |
| **CSVSearchTool** | أداة RAG مصممة للبحث في ملفات CSV، مخصصة للتعامل مع البيانات المنظمة. |
| **DALL-E Tool** | أداة لإنشاء الصور باستخدام DALL-E API. |
| **DirectorySearchTool** | أداة RAG للبحث في المجلدات، مفيدة للتنقل في أنظمة الملفات. |
| **DOCXSearchTool** | أداة RAG للبحث في مستندات DOCX، مثالية لمعالجة ملفات Word. |
| **DirectoryReadTool** | تسهّل قراءة ومعالجة هياكل المجلدات ومحتوياتها. |
| **ExaSearchTool** | أداة مصممة لإجراء عمليات بحث شاملة عبر مصادر بيانات متنوعة. |
| **FileReadTool** | تُمكّن قراءة واستخراج البيانات من الملفات، مع دعم تنسيقات ملفات متنوعة. |
| **FirecrawlSearchTool** | أداة للبحث في صفحات الويب باستخدام Firecrawl وإرجاع النتائج. |
| **FirecrawlCrawlWebsiteTool** | أداة لزحف صفحات الويب باستخدام Firecrawl. |
| **FirecrawlScrapeWebsiteTool** | أداة لاستخراج محتوى عناوين URL لصفحات الويب باستخدام Firecrawl. |
| **GithubSearchTool** | أداة RAG للبحث في مستودعات GitHub، مفيدة لبحث الكود والوثائق. |
| **SerperDevTool** | أداة متخصصة لأغراض التطوير، مع وظائف محددة قيد التطوير. |
| **TXTSearchTool** | أداة RAG مركّزة على البحث في ملفات النص (.txt)، مناسبة للبيانات غير المنظمة. |
| **JSONSearchTool** | أداة RAG مصممة للبحث في ملفات JSON، تخدم التعامل مع البيانات المنظمة. |
| **LlamaIndexTool** | تُمكّن استخدام أدوات LlamaIndex. |
| **MDXSearchTool** | أداة RAG مخصصة للبحث في ملفات Markdown (MDX)، مفيدة للوثائق. |
| **PDFSearchTool** | أداة RAG للبحث في مستندات PDF، مثالية لمعالجة المستندات الممسوحة ضوئيًا. |
| **PGSearchTool** | أداة RAG محسّنة للبحث في قواعد بيانات PostgreSQL، مناسبة لاستعلامات قواعد البيانات. |
| **Vision Tool** | أداة لإنشاء الصور باستخدام DALL-E API. |
| **RagTool** | أداة RAG للأغراض العامة قادرة على التعامل مع مصادر وأنواع بيانات متنوعة. |
| **ScrapeElementFromWebsiteTool** | تُمكّن استخراج عناصر محددة من المواقع، مفيدة لاستخراج البيانات المستهدف. |
| **ScrapeWebsiteTool** | تسهّل استخراج المواقع بالكامل، مثالية لجمع البيانات الشامل. |
| **WebsiteSearchTool** | أداة RAG للبحث في محتوى المواقع، محسّنة لاستخراج بيانات الويب. |
| **XMLSearchTool** | أداة RAG مصممة للبحث في ملفات XML، مناسبة لتنسيقات البيانات المنظمة. |
| **YoutubeChannelSearchTool** | أداة RAG للبحث في قنوات YouTube، مفيدة لتحليل محتوى الفيديو. |
| **YoutubeVideoSearchTool** | أداة RAG للبحث في مقاطع فيديو YouTube، مثالية لاستخراج بيانات الفيديو. |
## إنشاء أدواتك الخاصة
<Tip>
يمكن للمطورين إنشاء `أدوات مخصصة` مصممة خصيصًا لاحتياجات وكلائهم أو
استخدام الخيارات الجاهزة.
</Tip>
هناك طريقتان رئيسيتان لإنشاء أداة CrewAI:
### الوراثة من `BaseTool`
```python Code
from crewai.tools import BaseTool
from pydantic import BaseModel, Field
class MyToolInput(BaseModel):
"""Input schema for MyCustomTool."""
argument: str = Field(..., description="Description of the argument.")
class MyCustomTool(BaseTool):
name: str = "Name of my tool"
description: str = "What this tool does. It's vital for effective utilization."
args_schema: Type[BaseModel] = MyToolInput
def _run(self, argument: str) -> str:
# منطق أداتك هنا
return "Tool's result"
```
## دعم الأدوات غير المتزامنة
يدعم CrewAI الأدوات غير المتزامنة، مما يتيح لك تنفيذ أدوات تجري عمليات غير حاجبة مثل طلبات الشبكة وعمليات الإدخال/الإخراج على الملفات أو عمليات async أخرى بدون حجب مسار التنفيذ الرئيسي.
### إنشاء أدوات غير متزامنة
يمكنك إنشاء أدوات غير متزامنة بطريقتين:
#### 1. استخدام مزيّن `tool` مع دوال Async
```python Code
from crewai.tools import tool
@tool("fetch_data_async")
async def fetch_data_async(query: str) -> str:
"""Asynchronously fetch data based on the query."""
# محاكاة عملية غير متزامنة
await asyncio.sleep(1)
return f"Data retrieved for {query}"
```
#### 2. تنفيذ طرق Async في فئات الأدوات المخصصة
```python Code
from crewai.tools import BaseTool
class AsyncCustomTool(BaseTool):
name: str = "async_custom_tool"
description: str = "An asynchronous custom tool"
async def _run(self, query: str = "") -> str:
"""Asynchronously run the tool"""
# تنفيذك غير المتزامن هنا
await asyncio.sleep(1)
return f"Processed {query} asynchronously"
```
### استخدام الأدوات غير المتزامنة
تعمل الأدوات غير المتزامنة بسلاسة في كل من سير عمل الطاقم القياسي وسير عمل التدفق:
```python Code
# في طاقم قياسي
agent = Agent(role="researcher", tools=[async_custom_tool])
# في تدفق
class MyFlow(Flow):
@start()
async def begin(self):
crew = Crew(agents=[agent])
result = await crew.kickoff_async()
return result
```
يتعامل إطار عمل CrewAI تلقائيًا مع تنفيذ الأدوات المتزامنة وغير المتزامنة، لذا لا تحتاج للقلق بشأن كيفية استدعائها بشكل مختلف.
### استخدام مزيّن `tool`
```python Code
from crewai.tools import tool
@tool("Name of my tool")
def my_tool(question: str) -> str:
"""Clear description for what this tool is useful for, your agent will need this information to use it."""
# منطق الدالة هنا
return "Result from your custom tool"
```
### آلية التخزين المؤقت المخصصة
<Tip>
يمكن للأدوات اختياريًا تنفيذ `cache_function` لضبط سلوك
التخزين المؤقت. تحدد هذه الدالة متى يتم تخزين النتائج مؤقتًا بناءً على شروط
محددة، مما يوفر تحكمًا دقيقًا في منطق التخزين المؤقت.
</Tip>
```python Code
from crewai.tools import tool
@tool
def multiplication_tool(first_number: int, second_number: int) -> str:
"""Useful for when you need to multiply two numbers together."""
return first_number * second_number
def cache_func(args, result):
# في هذه الحالة، نخزّن النتيجة مؤقتًا فقط إذا كانت من مضاعفات 2
cache = result % 2 == 0
return cache
multiplication_tool.cache_function = cache_func
writer1 = Agent(
role="Writer",
goal="You write lessons of math for kids.",
backstory="You're an expert in writing and you love to teach kids but you know nothing of math.",
tools=[multiplication_tool],
allow_delegation=False,
)
#...
```
## الخلاصة
الأدوات محورية في توسيع قدرات وكلاء CrewAI، مما يمكّنهم من تنفيذ مجموعة واسعة من المهام والتعاون بفعالية.
عند بناء حلول مع CrewAI، استفد من كل من الأدوات المخصصة والموجودة لتمكين وكلائك وتعزيز نظام الذكاء الاصطناعي البيئي. فكّر في استخدام معالجة الأخطاء وآليات التخزين المؤقت ومرونة معاملات الأدوات لتحسين أداء وقدرات وكلائك.

197
docs/edge/ar/concepts/training.mdx Normal file
View File

@@ -0,0 +1,197 @@
---
title: التدريب
description: تعرّف على كيفية تدريب وكلاء CrewAI من خلال تقديم ملاحظات مبكرة والحصول على نتائج متسقة.
icon: dumbbell
mode: "wide"
---
## نظرة عامة
تتيح لك ميزة التدريب في CrewAI تدريب وكلاء الذكاء الاصطناعي باستخدام واجهة سطر الأوامر (CLI).
بتشغيل الأمر `crewai train -n <n_iterations>`، يمكنك تحديد عدد التكرارات لعملية التدريب.
أثناء التدريب، يستخدم CrewAI تقنيات لتحسين أداء وكلائك مع التغذية الراجعة البشرية.
يساعد هذا الوكلاء على تحسين فهمهم واتخاذ القرارات وحل المشكلات.
### تدريب طاقمك باستخدام CLI
لاستخدام ميزة التدريب، اتبع الخطوات التالية:
1. افتح الطرفية أو موجه الأوامر.
2. انتقل إلى المجلد حيث يقع مشروع CrewAI.
3. شغّل الأمر التالي:
```shell
crewai train -n <n_iterations> -f <filename.pkl>
```
<Tip>
استبدل `<n_iterations>` بعدد تكرارات التدريب المرغوب و`<filename>` باسم الملف المناسب المنتهي بـ `.pkl`.
</Tip>
<Note>
إذا حذفت `-f`، فإن المخرجات تُحفظ افتراضيًا في `trained_agents_data.pkl` في مجلد العمل الحالي. يمكنك تمرير مسار مطلق للتحكم في مكان كتابة الملف.
</Note>
### تدريب طاقمك برمجيًا
لتدريب طاقمك برمجيًا، استخدم الخطوات التالية:
1. حدد عدد التكرارات للتدريب.
2. حدد معاملات الإدخال لعملية التدريب.
3. نفّذ أمر التدريب داخل كتلة try-except للتعامل مع الأخطاء المحتملة.
```python Code
n_iterations = 2
inputs = {"topic": "CrewAI Training"}
filename = "your_model.pkl"
try:
YourCrewName_Crew().crew().train(
n_iterations=n_iterations,
inputs=inputs,
filename=filename
)
except Exception as e:
raise Exception(f"An error occurred while training the crew: {e}")
```
## كيف تُستخدم بيانات التدريب من قبل الوكلاء
يستخدم CrewAI مخرجات التدريب بطريقتين: أثناء التدريب لدمج ملاحظاتك البشرية، وبعد التدريب لتوجيه الوكلاء باقتراحات موحدة.
### تدفق بيانات التدريب
```mermaid
flowchart TD
A["Start training<br/>CLI: crewai train -n -f<br/>or Python: crew.train(...)"] --> B["Setup training mode<br/>- task.human_input = true<br/>- disable delegation<br/>- init training_data.pkl + trained file"]
subgraph "Iterations"
direction LR
C["Iteration i<br/>initial_output"] --> D["User human_feedback"]
D --> E["improved_output"]
E --> F["Append to training_data.pkl<br/>by agent_id and iteration"]
end
B --> C
F --> G{"More iterations?"}
G -- "Yes" --> C
G -- "No" --> H["Evaluate per agent<br/>aggregate iterations"]
H --> I["Consolidate<br/>suggestions[] + quality + final_summary"]
I --> J["Save by agent role to trained file<br/>(default: trained_agents_data.pkl)"]
J --> K["Normal (non-training) runs"]
K --> L["Auto-load suggestions<br/>from trained_agents_data.pkl"]
L --> M["Append to prompt<br/>for consistent improvements"]
```
### أثناء تشغيلات التدريب
- في كل تكرار، يسجل النظام لكل وكيل:
- `initial_output`: الإجابة الأولى للوكيل
- `human_feedback`: ملاحظاتك المضمّنة عند الطلب
- `improved_output`: إجابة المتابعة للوكيل بعد الملاحظات
- تُخزن هذه البيانات في ملف عمل باسم `training_data.pkl` مفهرس بمعرّف الوكيل الداخلي والتكرار.
- أثناء نشاط التدريب، يُلحق الوكيل تلقائيًا ملاحظاتك البشرية السابقة بأمره لتطبيق تلك التعليمات في المحاولات اللاحقة ضمن جلسة التدريب.
التدريب تفاعلي: تُعيّن المهام `human_input = true`، لذا سيتوقف التشغيل في بيئة غير تفاعلية بانتظار مدخلات المستخدم.
### بعد اكتمال التدريب
- عند انتهاء `train(...)`، يقيّم CrewAI بيانات التدريب المجمعة لكل وكيل وينتج نتيجة موحدة تحتوي على:
- `suggestions`: تعليمات واضحة وقابلة للتنفيذ مستخلصة من ملاحظاتك والفرق بين المخرجات الأولية/المحسنة
- `quality`: درجة من 0-10 تعكس التحسن
- `final_summary`: مجموعة خطوات عمل تفصيلية للمهام المستقبلية
- تُحفظ هذه النتائج الموحدة في اسم الملف الذي تمرره إلى `train(...)` (الافتراضي عبر CLI هو `trained_agents_data.pkl`). تُفهرس الإدخالات بدور الوكيل `role` لتطبيقها عبر الجلسات.
- أثناء التنفيذ العادي (غير التدريب)، يحمّل كل وكيل تلقائيًا `suggestions` الموحدة ويلحقها بأمر المهمة كتعليمات إلزامية. يمنحك هذا تحسينات متسقة بدون تغيير تعريفات الوكلاء.
### ملخص الملفات
- `training_data.pkl` (مؤقت، لكل جلسة):
- الهيكل: `agent_id -> { iteration_number: { initial_output, human_feedback, improved_output } }`
- الغرض: التقاط البيانات الخام والملاحظات البشرية أثناء التدريب
- الموقع: يُحفظ في مجلد العمل الحالي (CWD)
- `trained_agents_data.pkl` (أو اسم ملفك المخصص):
- الهيكل: `agent_role -> { suggestions: string[], quality: number, final_summary: string }`
- الغرض: استمرار التوجيه الموحد للتشغيلات المستقبلية
- الموقع: يُكتب في CWD افتراضيًا؛ استخدم `-f` لتعيين مسار مخصص (بما في ذلك المطلق)
## اعتبارات نماذج اللغة الصغيرة
<Warning>
عند استخدام نماذج لغة أصغر (≤7 مليار معامل) لتقييم بيانات التدريب، كن على علم أنها قد تواجه تحديات في إنتاج مخرجات منظمة واتباع التعليمات المعقدة.
</Warning>
### قيود النماذج الصغيرة في تقييم التدريب
<CardGroup cols={2}>
<Card title="دقة مخرجات JSON" icon="triangle-exclamation">
غالبًا ما تواجه النماذج الأصغر صعوبة في إنتاج استجابات JSON صالحة مطلوبة لتقييمات التدريب المنظمة، مما يؤدي إلى أخطاء تحليل وبيانات غير مكتملة.
</Card>
<Card title="جودة التقييم" icon="chart-line">
قد توفر النماذج تحت 7 مليار معامل تقييمات أقل دقة مع عمق استدلال محدود مقارنة بالنماذج الأكبر.
</Card>
<Card title="اتباع التعليمات" icon="list-check">
قد لا تُتبع معايير تقييم التدريب المعقدة بالكامل أو تُراعى من قبل النماذج الأصغر.
</Card>
<Card title="الاتساق" icon="rotate">
قد تفتقر التقييمات عبر تكرارات تدريب متعددة إلى الاتساق مع النماذج الأصغر.
</Card>
</CardGroup>
### توصيات للتدريب
<Tabs>
<Tab title="أفضل ممارسة">
لجودة تدريب مثالية وتقييمات موثوقة، نوصي بشدة باستخدام نماذج بحد أدنى 7 مليار معامل أو أكبر:
```python
from crewai import Agent, Crew, Task, LLM
# الحد الأدنى الموصى به لتقييم التدريب
llm = LLM(model="mistral/open-mistral-7b")
# خيارات أفضل لتقييم تدريب موثوق
llm = LLM(model="anthropic/claude-3-sonnet-20240229-v1:0")
llm = LLM(model="gpt-4o")
# استخدم هذا LLM مع وكلائك
agent = Agent(
role="Training Evaluator",
goal="Provide accurate training feedback",
llm=llm
)
```
<Tip>
توفر النماذج الأكثر قوة ملاحظات أعلى جودة مع استدلال أفضل، مما يؤدي إلى تكرارات تدريب أكثر فعالية.
</Tip>
</Tab>
<Tab title="استخدام النماذج الصغيرة">
إذا كان يجب عليك استخدام نماذج أصغر لتقييم التدريب، كن على علم بهذه القيود:
```python
# استخدام نموذج أصغر (توقع بعض القيود)
llm = LLM(model="huggingface/microsoft/Phi-3-mini-4k-instruct")
```
<Warning>
بينما يتضمن CrewAI تحسينات للنماذج الصغيرة، توقع نتائج تقييم أقل موثوقية ودقة قد تتطلب تدخلاً بشريًا أكبر أثناء التدريب.
</Warning>
</Tab>
</Tabs>
### نقاط مهمة يجب ملاحظتها
- **متطلب العدد الصحيح الموجب:** تأكد من أن عدد التكرارات (`n_iterations`) هو عدد صحيح موجب. سيرمي الكود `ValueError` إذا لم يتحقق هذا الشرط.
- **متطلب اسم الملف:** تأكد من أن اسم الملف ينتهي بـ `.pkl`. سيرمي الكود `ValueError` إذا لم يتحقق هذا الشرط.
- **معالجة الأخطاء:** يتعامل الكود مع أخطاء العمليات الفرعية والاستثناءات غير المتوقعة، ويوفر رسائل خطأ للمستخدم.
- يُطبق التوجيه المدرّب في وقت الأمر؛ لا يعدّل تهيئة وكيل Python/YAML.
- يحمّل الوكلاء تلقائيًا الاقتراحات المدربة من ملف باسم `trained_agents_data.pkl` الموجود في مجلد العمل الحالي. إذا درّبت إلى اسم ملف مختلف، أعد تسميته إلى `trained_agents_data.pkl` قبل التشغيل، أو اضبط المحمّل في الكود.
- يمكنك تغيير اسم ملف المخرجات عند استدعاء `crewai train` بـ `-f/--filename`. المسارات المطلقة مدعومة إذا أردت الحفظ خارج CWD.
من المهم ملاحظة أن عملية التدريب قد تستغرق بعض الوقت، اعتمادًا على تعقيد وكلائك وستتطلب أيضًا ملاحظاتك في كل تكرار.
بمجرد اكتمال التدريب، سيكون وكلاؤك مجهزين بقدرات ومعرفة محسّنة، وجاهزين لمعالجة المهام المعقدة وتقديم رؤى أكثر اتساقًا وقيمة.
تذكر تحديث وإعادة تدريب وكلائك بانتظام لضمان بقائهم على اطلاع بأحدث المعلومات والتطورات في المجال.