Merge branch 'main' into feat/deploy-create-failure-span

`create_project_zip` only wrapped the ZIP write, so an `OSError` while
staging files or creating the temporary archive escaped as a bare
`OSError` and the deploy command recorded it as `unexpected` instead of
`zip_error`. The archive boundary now covers staging, temp-file creation
and the write; the staging directory is removed on every path, and no
partial archive is left behind.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

.github/CONTRIBUTING.md

@@ -29,7 +29,7 @@ uv run pre-commit install
 
 ## Repository Structure
 
-This is a uv workspace with four packages under `lib/`:
+This is a uv workspace with six packages under `lib/`:
 
 | Package | Path | Description |
 |---------|------|-------------|
@@ -37,6 +37,8 @@ This is a uv workspace with four packages under `lib/`:
 | `crewai-tools` | `lib/crewai-tools/` | Tool integrations |
 | `crewai-files` | `lib/crewai-files/` | File handling |
 | `devtools` | `lib/devtools/` | Internal release tooling |
+| `crewai-cli` | `lib/cli/` | Command-line interface |
+| `crewai-core` | `lib/crewai-core/` | Shared core utilities |
 
 Documentation lives in `docs/` with translations under `docs/{en,ar,ko,pt-BR}/`.
 
@@ -104,7 +106,7 @@ chore(deps): bump pydantic to 2.11
 - PRs over 500 lines are labeled `size/XL` automatically
 - Title must follow the same conventional commit format
 - Link related issues where applicable (`#123`, `Fixes #123`, or the issue URL)
-- First-time contributors must open or pick an existing **open** issue first, then mention it in the PR title or body (for example `#123`). PRs without a linked open issue are closed automatically.
+- First-time contributors must open or pick an existing **open** issue first, then mention it in the PR title or body (for example `#123`). PRs without a linked open issue are closed automatically and labeled `needs-issue`.
 
 ## Testing
 

.github/pull_request_template.md

@@ -4,7 +4,8 @@ Fixes #
 
 <!--
 First-time contributors must mention an existing open issue in this repo
-(for example #123). PRs without a linked open issue are closed automatically.
+(for example #123). PRs without a linked open issue are closed automatically
+and labeled needs-issue.
 -->
 
 ## Summary

.github/workflows/first-contributor-welcome.yml

@@ -0,0 +1,88 @@
+name: Welcome First-Time Contributors
+
+on:
+  pull_request_target:
+    types: [closed]
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  welcome:
+    # Match the first-time contributor definition used by ftc-require-issue.
+    if: >
+      github.event.pull_request.merged == true &&
+      github.event.pull_request.user.type != 'Bot' &&
+      !contains(fromJSON('["MEMBER","OWNER","COLLABORATOR","CONTRIBUTOR"]'),
+                github.event.pull_request.author_association)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Thank first-time contributors
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        with:
+          script: |
+            const pullRequest = context.payload.pull_request;
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const marker = "<!-- crewai-first-merged-pr-welcome -->";
+
+            const existingComments = await github.paginate(
+              github.rest.issues.listComments,
+              {
+                owner,
+                repo,
+                issue_number: pullRequest.number,
+                per_page: 100,
+              },
+            );
+            if (existingComments.some((comment) => comment.body?.includes(marker))) {
+              core.info("Welcome comment already exists; skipping duplicate.");
+              return;
+            }
+
+            const prUrl = pullRequest.html_url;
+            const shareText = [
+              "I just made my first contribution to @crewAIInc!",
+              "",
+              "Excited to help build the future of AI agents with CrewAI.",
+              "",
+              prUrl,
+              "",
+              "#OpenSource #AI #CrewAI",
+            ].join("\n");
+            const xShareUrl = `https://x.com/intent/post?text=${encodeURIComponent(shareText)}`;
+            const linkedInShareUrl = `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(prUrl)}`;
+
+            const body = [
+              marker,
+              "",
+              `## Thanks for your first contribution to CrewAI, @${pullRequest.user.login}!`,
+              "",
+              "We really appreciate the time and care you put into this PR. Your work is now part of CrewAI — welcome to the contributor community.",
+              "",
+              "Want to share your contribution? Totally optional:",
+              "",
+              `[Share on X](${xShareUrl}) · [Share the PR on LinkedIn](${linkedInShareUrl})`,
+              "",
+              "If the links don't work, feel free to copy and personalize this:",
+              "",
+              "```text",
+              "I just made my first contribution to @crewAIInc!",
+              "",
+              "Excited to help build the future of AI agents with CrewAI.",
+              "",
+              prUrl,
+              "",
+              "#OpenSource #AI #CrewAI",
+              "```",
+              "",
+              "If you share, we'd love to see it — tag **@crewAIInc** on X and **CrewAI** on LinkedIn.",
+            ].join("\n");
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: pullRequest.number,
+              body,
+            });

.github/workflows/ftc-require-issue.yml

@@ -6,7 +6,7 @@ on:
 
 permissions:
   pull-requests: write
-  issues: read
+  issues: write
 
 concurrency:
   group: ftc-require-issue-${{ github.event.pull_request.number }}
@@ -114,6 +114,19 @@ jobs:
               ],
               check=True,
           )
+          subprocess.run(
+              [
+                  "gh",
+                  "pr",
+                  "edit",
+                  pr_number,
+                  "--repo",
+                  repo,
+                  "--add-label",
+                  "needs-issue",
+              ],
+              check=True,
+          )
           subprocess.run(
               ["gh", "pr", "close", pr_number, "--repo", repo],
               check=True,

.github/workflows/vulnerability-scan.yml

@@ -107,6 +107,16 @@ jobs:
             # TODO: drop this ignore when bumping nltk past 3.10.3 to a patched
             # release; keep the ignore list in sync with .pre-commit-config.yaml.
             --ignore-vuln GHSA-8mgp-746c-j5xp
+            # accelerate <=1.14.0: GHSA-4j2p-28q2-5m79 (CVE-2026-69112): path
+            # traversal / FIFO DoS via unsanitized sharded-checkpoint weight_map
+            # entries. No patched PyPI release yet (fix is huggingface/accelerate
+            # #4138, not shipped). Transitive via docling extras
+            # (docling-ibm-models / docling-slim[standard]); CrewAI does not load
+            # untrusted checkpoints through those APIs.
+            # TODO: drop this ignore when bumping accelerate past 1.14.0 to a
+            # patched release; keep the ignore list in sync with
+            # .pre-commit-config.yaml.
+            --ignore-vuln GHSA-4j2p-28q2-5m79
           )
           uv run pip-audit "${pip_audit_args[@]}"
         continue-on-error: true

.pre-commit-config.yaml

@@ -3,19 +3,19 @@ repos:
     hooks:
       - id: ruff
         name: ruff
-        entry: bash -c 'source .venv/bin/activate && uv run ruff check --config pyproject.toml "$@"' --
+        entry: bash -c 'case "$OSTYPE" in msys*|cygwin*|win32*) source .venv/Scripts/activate ;; *) source .venv/bin/activate ;; esac && uv run ruff check --config pyproject.toml "$@"' --
         language: system
         pass_filenames: true
         types: [python]
       - id: ruff-format
         name: ruff-format
-        entry: bash -c 'source .venv/bin/activate && uv run ruff format --config pyproject.toml "$@"' --
+        entry: bash -c 'case "$OSTYPE" in msys*|cygwin*|win32*) source .venv/Scripts/activate ;; *) source .venv/bin/activate ;; esac && uv run ruff format --config pyproject.toml "$@"' --
         language: system
         pass_filenames: true
         types: [python]
       - id: mypy
         name: mypy
-        entry: bash -c 'source .venv/bin/activate && uv run mypy --config-file pyproject.toml "$@"' --
+        entry: bash -c 'case "$OSTYPE" in msys*|cygwin*|win32*) source .venv/Scripts/activate ;; *) source .venv/bin/activate ;; esac && uv run mypy --config-file pyproject.toml "$@"' --
         language: system
         pass_filenames: true
         types: [python]
@@ -30,8 +30,9 @@ repos:
         name: pip-audit
         # Keep this ignore list in sync with .github/workflows/vulnerability-scan.yml.
         # TODO: drop --ignore-vuln GHSA-8mgp-746c-j5xp when bumping nltk past 3.10.3.
+        # TODO: drop --ignore-vuln GHSA-4j2p-28q2-5m79 when bumping accelerate past 1.14.0.
         entry: >-
-          bash -c 'source .venv/bin/activate && uv run pip-audit --skip-editable
+          bash -c 'case "$OSTYPE" in msys*|cygwin*|win32*) source .venv/Scripts/activate ;; *) source .venv/bin/activate ;; esac && uv run pip-audit --skip-editable
           --ignore-vuln PYSEC-2024-277
           --ignore-vuln PYSEC-2026-89
           --ignore-vuln PYSEC-2026-97
@@ -61,7 +62,8 @@ repos:
           --ignore-vuln GHSA-2wm9-hf6c-p5cr
           --ignore-vuln GHSA-36p7-vc44-83pf
           --ignore-vuln GHSA-xph7-9rjv-w5fr
-          --ignore-vuln GHSA-8mgp-746c-j5xp' --
+          --ignore-vuln GHSA-8mgp-746c-j5xp
+          --ignore-vuln GHSA-4j2p-28q2-5m79' --
         language: system
         pass_filenames: false
         stages: [pre-push, manual]

conftest.py

@@ -202,6 +202,38 @@ def cleanup_event_handlers() -> Generator[None, Any, None]:
         pass
 
 
+@pytest.fixture(autouse=True, scope="function")
+def reset_tracing_state() -> Generator[None, Any, None]:
+    """Drop the tracing singleton and its context after each test.
+
+    `TraceCollectionListener` is a singleton, so without this three things leak
+    for the rest of the xdist worker:
+
+    - `TraceBatchManager.trace_batch_id`, which moves later trace POSTs from
+      `/tracing/ephemeral/batches` to `/tracing/batches/<id>/events` until some
+      unrelated cassette stops matching, naming neither the leak nor its source.
+    - `_listeners_setup`, which makes `setup_listeners` return early
+      (`trace_listener.py:208`) after `cleanup_event_handlers` has wiped the bus,
+      so tracing silently registers nothing and collects no events.
+    - the `_tracing_enabled` context var, which leaves tracing on for later tests
+      and re-registers `on_task_failed` alongside telemetry's — breaking
+      `test_task_failure_instrumentation`, which requires one handler per event.
+
+    All three go together: clearing the context vars is what makes dropping the
+    singleton safe, because the replacement listener then sees tracing disabled
+    and registers nothing. Dropping the singleton alone re-registers handlers and
+    breaks the telemetry test.
+    """
+    yield
+
+    from crewai.events.listeners.tracing import utils as tracing_utils
+    from crewai.events.listeners.tracing.trace_listener import TraceCollectionListener
+
+    tracing_utils._tracing_enabled.set(None)
+    tracing_utils._tui_mode.set(False)
+    TraceCollectionListener._instance = None
+
+
 @pytest.fixture(autouse=True, scope="function")
 def reset_event_state() -> None:
     """Reset event system state before each test for isolation."""

docs/edge/ar/changelog.mdx

@@ -4,6 +4,96 @@ description: "تحديثات المنتج والتحسينات وإصلاحات
 icon: "clock"
 mode: "wide"
 ---
+<Update label="9 سبتمبر 2026">
+  ## v1.15.21
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.21)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة بيانات تتبع لتتبع وقت تشغيل نقاط التحقق واستخدام واجهة سطر الأوامر.
+
+  ### إصلاحات الأخطاء
+  - إصلاح أخطاء البوابة المبلغ عنها داخل استجابة HTTP 200.
+  - الحفاظ على دفع النشر عند إنشاء مصدر AMP.
+  - الإبلاغ عن فشل السحب بدلاً من رفع IndexError في تكامل Oxylabs.
+  - توجيه جميع نماذج DashScope عبر المزود الأصلي.
+  - الاحتفاظ بنقاط تحقق JSON كـ UTF-8.
+  - إزالة $ الزائدة في عناوين URL الخاصة بالبحث في f-string لـ BrightData.
+  - دعم مصفوفات نوع القائمة في تحويل مخطط JSON.
+  - تصحيح نافذة السياق لـ gpt-4o-mini من 200000 إلى 128000.
+  - الحفاظ على وسائط استدعاء أداة البث عند contentBlockStop.
+  - جعل خطافات ما قبل الالتزام قابلة للنقل على Windows.
+
+  ### الوثائق
+  - توضيح أن تتبع البيانات يتم إدارته بشكل منفصل عن بيانات التتبع.
+  - إصلاح رابط مرجع البحث المتوازي.
+  - إزالة المعلمات القديمة من سلسلة توثيق handle_llm_stream_chunk.
+  - إصلاح أمثلة سلسلة توثيق مخرجات البث.
+  - استخدام UUIDs الخاصة بالمنظمة في مرجع تثبيت المهارة.
+
+  ## المساهمون
+
+  @Alphaxiaoteng, @DrewWhittleNZ, @Ghraven, @Shxiao101, @Vaishnavi220506, @Vidit-Ostwal, @danielfsbarreto, @georgeatparallel, @github-actions[bot], @jessemiller, @joaomdmoura, @kimnamu, @kiwoongyoon, @liang0417, @lorenzejay, @oxy-giedrius, @simpleqt, @uoparaji
+
+</Update>
+
+<Update label="4 سبتمبر 2026">
+  ## v1.15.20
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.20)
+
+  ## ما الذي تغير
+
+  ### إصلاحات الأخطاء
+  - إصلاح اكتشاف اسم مستعار لأداة المنصة القديمة
+
+  ### الوثائق
+  - تحديث اللقطة وسجل التغييرات للإصدار v1.15.19
+
+  ## المساهمون
+
+  @joaomdmoura, @vinibrsl
+
+</Update>
+
+<Update label="4 سبتمبر 2026">
+  ## v1.15.19
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.19)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - إضافة عميل تكامل Clipper
+  - إضافة `now()` إلى بيئة تعبير CEL
+  - تسجيل كيفية انتهاء تشغيل الطاقم لكل مستخدم
+  - الإبلاغ عن حجم الآلة كحزام خشن، وليس عدد النوى
+  - إضافة عميل قابل للحقن لأدوات منصة CrewAI
+
+  ### إصلاحات الأخطاء
+  - إصلاح قراءة عناوين octet-stream و xlsx في `urlreadtool`
+  - إصلاح إضافة دوران المستخدم المتأخر في موفر Gemini الأصلي
+  - تطبيع المخطط والمنفذ في عنوان URL الأساسي لـ Ollama
+  - الحفاظ على تكوينات النطاق القابلة لإعادة الاستخدام في الذاكرة
+  - تحديث `pypdf` إلى 6.16.2 لمعالجة ثغرة أمنية
+  - تحديث `nltk` إلى 3.10.3 لمعالجة ثغرة أمنية
+  - إصلاح المخرجات الهيكلية الأصلية لنماذج Claude الحالية وسقف CVE لـ Snowflake
+  - تشغيل روابط استدعاء النموذج على كل مسار ونشر رفض
+
+  ### الوثائق
+  - إزالة `CodeInterpreterTool` من أمثلة نظرة عامة على الذكاء الاصطناعي/التعلم الآلي
+  - توجيه رابط `prompt-template` إلى مساره الحالي
+  - تحديث دليل القنوات إلى واجهة برمجة التطبيقات الحالية لقنوات CopilotKit
+  - تحديث معرفات نماذج Gemini المتقاعدة
+
+  ## المساهمون
+
+  @Vidit-Ostwal, @a-yeyang, @github-actions[bot], @hvlcrs, @joaomdmoura, @kikifrost, @lorenzejay, @lucasgomide, @parthiban-sivakumar, @ranst91, @tandede, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="27 أغسطس 2026">
   ## v1.15.18
 

docs/edge/ar/concepts/cli.mdx

@@ -201,6 +201,7 @@ def crew(self) -> Crew:
   ```shell Terminal
   crewai deploy push
   ```
+  يحافظ الدفع على المصدر المستخدم عند الإنشاء. إضافة `origin` لاحقًا لا تحوّل نشر ZIP إلى git.
 
 - **حالة النشر**:
   ```shell Terminal
@@ -286,6 +287,7 @@ crewai traces [COMMAND]
    ```shell Terminal
    crewai traces enable
    ```
+   - يحدّث موجه التشغيل الأول (`Would you like to view your execution traces?`) هذا التفضيل أيضاً
 
 <Note>
 **لتفعيل التتبع**، استخدم أيًا من هذه الطرق:

docs/edge/ar/concepts/knowledge.mdx

@@ -636,6 +636,21 @@ agent = Agent(
         }
     }
 )
+
+# Option 4: Use OpenRouter embeddings (supports models across providers)
+# Set OPENROUTER_API_KEY environment variable if api_key is omitted in config
+crew = Crew(
+    agents=[agent],
+    tasks=[...],
+    knowledge_sources=[knowledge_source],
+    embedder={
+        "provider": "openrouter",
+        "config": {
+            "model_name": "openai/text-embedding-3-small",
+            "api_key": "your-openrouter-api-key"  # Optional if OPENROUTER_API_KEY is set
+        }
+    }
+)
 ```
 
 #### إعداد تضمينات Azure OpenAI

docs/edge/ar/concepts/llms.mdx

@@ -1339,6 +1339,38 @@ llm = LLM(
     llm = LLM(model="gpt-4")
     ```
   </Tab>
+  <Tab title="أخطاء البوابة">
+    <Tip>
+      تُعيد البوابات مثل OpenRouter الرمز `200 OK` بمجرد قبول المزود الأساسي للطلب، لذلك يصل انتهاء مهلة المزود داخل جسم الاستجابة بدلًا من رمز الحالة.
+    </Tip>
+
+    تُطلق CrewAI الاستثناء نفسه الذي كان رمز الحالة الأصلي سيُنتجه، ومن ثم يلتقط منطق إعادة المحاولة الموجود لديك هذا الفشل المُقنَّع:
+
+    ```python
+    import openai
+    from pydantic import BaseModel
+
+    from crewai import LLM
+
+
+    class Report(BaseModel):
+        summary: str
+
+
+    llm = LLM(model="openrouter/z-ai/glm-5.3", response_format=Report)
+
+    try:
+        result = llm.call("Summarize the incident", response_model=Report)
+    except openai.InternalServerError as e:
+        # "z-ai/glm-5.3 via openrouter.ai returned HTTP 200 with an upstream error
+        #  and no choices: The operation was aborted (upstream code 504)"
+        print(f"Upstream provider failed, safe to retry: {e}")
+    ```
+
+    <Warning>
+      إن استخدام `response_model` كبير أو متداخل بعمق يزيد احتمال انتهاء مهلة المزود. تعامل مع هذه الحالات كأعطال مؤقتة في المزود، وليس كإنتاج النموذج مخرجات منظمة تالفة.
+    </Warning>
+  </Tab>
   <Tab title="طول السياق">
     <Tip>
       استخدم نماذج سياق أكبر للمهام الواسعة

docs/edge/ar/concepts/skills.mdx

@@ -202,13 +202,17 @@ crewai skill publish
 
 ### التثبيت
 
-ثبّت مهارة منشورة عبر مرجعها `@org/name`:
+ثبّت مهارة منشورة عبر مرجعها `@org-uuid/name`:
 
 ```shell Terminal
-crewai skill install @acme/code-review
+crewai skill install @your-org-uuid/code-review
 ```
 
-داخل مشروع الطاقم تُثبَّت المهارة في `./skills/{name}/`؛ وخارج المشروع تذهب إلى ذاكرة التخزين المؤقتة المشتركة في `~/.crewai/skills/{org}/{name}/`.
+<Note>
+  استخدم **UUID** الخاص بمؤسستك وليس اسمها — فأسماء المؤسسات ليست فريدة، وقد يشير الاسم إلى مؤسسة خاطئة فيفشل التثبيت برسالة "غير موجود". شغّل `crewai org list` لعرض الـ UUID (عمود `ID`) لكل مؤسسة تنتمي إليها.
+</Note>
+
+داخل مشروع الطاقم تُثبَّت المهارة في `./skills/{name}/`؛ وخارج المشروع تذهب إلى ذاكرة التخزين المؤقتة المشتركة في `~/.crewai/skills/{org-uuid}/{name}/`.
 
 يمكن للوكلاء أيضًا الإشارة إلى مهارات السجل مباشرة — يتم حلّها من ذاكرة التخزين المؤقتة المحلية (أو من مجلد `skills/` في المشروع) وقت التشغيل:
 
@@ -217,7 +221,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review"],  # registry ref, resolved locally
+    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
 )
 ```
 

docs/edge/ar/observability/tracing.mdx

@@ -9,7 +9,7 @@ mode: "wide"
 
 يوفر CrewAI إمكانيات تتبع مدمجة تتيح لك مراقبة وتصحيح أخطاء الطواقم والتدفقات في الوقت الفعلي. يوضح هذا الدليل كيفية تفعيل التتبع لكل من **الطواقم** و**التدفقات** باستخدام منصة المراقبة المتكاملة في CrewAI.
 
-> **ما هو تتبع CrewAI؟** يوفر التتبع المدمج في CrewAI مراقبة شاملة لوكلاء الذكاء الاصطناعي، بما في ذلك قرارات الوكلاء وجداول تنفيذ المهام واستخدام الأدوات واستدعاءات LLM - كل ذلك متاح عبر [منصة CrewAI AMP](https://app.crewai.com).
+> **ما هو تتبع CrewAI؟** يوفر التتبع المدمج في CrewAI مراقبة شاملة لوكلاء الذكاء الاصطناعي، بما في ذلك قرارات الوكلاء وجداول تنفيذ المهام واستخدام الأدوات واستدعاءات LLM - كل ذلك متاح عبر [منصة CrewAI AMP](https://app.crewai.com). يتم إدارة التتبع بشكل مستقل عن [القياس عن بُعد](/ar/telemetry).
 
 ![واجهة تتبع CrewAI](/images/crewai-tracing.png)
 
@@ -170,6 +170,18 @@ CREWAI_TRACING_ENABLED=true
 
 عند تعيين متغير البيئة هذا، ستُفعّل جميع الطواقم والتدفقات التتبع تلقائياً، حتى بدون تعيين `tracing=True` صراحةً.
 
+## عرض التتبعات بعد أول تشغيل
+
+في المرة الأولى التي تشغّل فيها طاقماً أو تدفقاً، قد يسألك طرف تفاعلي:
+
+```text
+Would you like to view your execution traces? [y/N]
+```
+
+اختر **yes** لفتح رابط العرض. يمكنك تغيير ذلك لاحقاً باستخدام
+`crewai traces enable` أو `crewai traces disable`، أو بتعيين `tracing`
+على الطاقم أو التدفق.
+
 ## عرض التتبعات
 
 ### الوصول إلى لوحة تحكم CrewAI AMP

docs/edge/ar/telemetry.mdx

@@ -24,6 +24,7 @@ mode: "wide"
 لتوفير رؤى أعمق. قد يتضمن جمع البيانات الموسع هذا معلومات شخصية إذا دمجها المستخدمون في طواقمهم أو مهامهم.
 يجب على المستخدمين النظر بعناية في محتوى طواقمهم ومهامهم قبل تفعيل `share_crew`.
 يمكن للمستخدمين تعطيل القياس عن بُعد في CrewAI عبر تعيين `CREWAI_DISABLE_TELEMETRY` إلى `true` أو `1` أو `yes` أو `on` (بغض النظر عن حالة الأحرف). `OTEL_SDK_DISABLED` بنفس القيم يعطّل أيضاً مُصدِّر CrewAI. مجموعة أدوات OpenTelemetry نفسها ما تزال تقبل `true` فقط لتعطيل بقية أدوات القياس في العملية.
+تتبع AMP مشمول بشكل منفصل في [التتبع](/ar/observability/tracing).
 
 ### أمثلة:
 ```python
@@ -62,7 +63,7 @@ os.environ['OTEL_SDK_DISABLED'] = 'true'
 | نعم       | بيانات دورة حياة المهمة | تشمل: أوقات الإنشاء وبدء/انتهاء التنفيذ، معرّفات الطاقم والمهمة، وما إذا نجحت المهمة أو فشلت. وعند فشل المهمة، يُسجَّل **اسم صنف** الاستثناء (مثل `TimeoutError`) بحيث يمكن عدّ حالات الفشل وتشخيصها — وليس رسالة الخطأ أبدًا، فهي قد تحتوي على مطالبات أو مخرجات نموذج أو مسارات ملفات أو بيانات اعتماد. مخزنة كنطاقات مع طوابع زمنية. لا بيانات شخصية. |
 | نعم       | سمات LLM | تشمل: الاسم، model_name، model، top_k، temperature، واسم فئة LLM. كلها بيانات تقنية غير شخصية. |
 | نعم       | إنشاء مشروع باستخدام CLI الخاص بـ CrewAI | تشمل: أن مشروعًا جديدًا أُنشئ عبر `crewai create`، ونوعه (`crew` أو `json_crew` أو `flow`)، ومعرّف المشروع الذي تم توليده لهذا المشروع الجديد وكُتب في ملف `pyproject.toml` الخاص به. وهو معرّف المشروع الجديد نفسه، ويُسجَّل بشكل منفصل عن `project_id` الخاص بالمجلد الذي شُغّل منه الأمر — وقد يختلفان. لا اسم مشروع، ولا محتويات ملفات، ولا شيفرة. لا بيانات شخصية. |
-| نعم       | محاولة نشر الطاقم باستخدام CLI الخاص بـ CrewAI | تشمل: حقيقة إجراء النشر ومعرّف الطاقم، وما إذا كان يحاول سحب السجلات، وما إذا بدأ النشر من أمر CLI أو من واجهة التشغيل TUI. لا تُسجَّل محتويات المشروع أو الطاقم. لا توجد بيانات شخصية. |
+| نعم       | محاولة نشر الطاقم باستخدام CLI الخاص بـ CrewAI | تشمل: حقيقة إجراء النشر ومعرّف الطاقم، وما إذا كان يحاول سحب السجلات، وما إذا بدأ النشر من أمر CLI أو من واجهة التشغيل TUI. إذا فشل إنشاء النشر، تُسجَّل فئة الفشل (واحدة من قائمة ثابتة مثل `api_4xx` أو `network_error` أو `user_declined`) ورمز حالة HTTP لاستجابة API إن وُجدت — ولا تُسجَّل رسالة الخطأ أبدًا. لا تُسجَّل محتويات المشروع أو الطاقم. لا توجد بيانات شخصية. |
 | نعم       | بيئة التنفيذ | تشمل: مساعد البرمجة بالذكاء الاصطناعي الذي يشغّل العملية إن وُجد (واحد من قائمة ثابتة مثل `claude_code` أو `codex` أو `cursor` أو `unknown`)، ومكان تشغيل العملية (واحد من قائمة ثابتة مثل `ci` أو `container` أو `serverless` أو `interactive`)، و`project_id` من ملف `pyproject.toml` عند ضبطه، ونطاقًا تقريبيًا لحجم الجهاز (واحد من `1-2` أو `3-4` أو `5-8` أو `9-16` أو `17-32` أو `33+` أو `unknown`). النطاق مجال وليس العدد الدقيق للأنوية أبدًا — العدد الدقيق اختياري فقط، ضمن «معلومات البيئة» أدناه. تأتي فئة الحجم من عدد أنوية المضيف؛ ويتحقق اكتشاف المساعد وموقع التشغيل فقط مما إذا كانت متغيرات البيئة المعروفة مضبوطة، ولا يقرأ قيمها أبدًا. لا بيانات شخصية. |
 | نعم       | إشارات دورة حياة التدفق | تشمل: بدء التدفق، وما إذا اكتمل أو فشل، وما إذا فشلت إحدى طرقه، وما إذا توقف مؤقتًا لانتظار إدخال أو ملاحظات بشرية، وما إذا كان البدء تشغيلًا مستأنفًا، وما إذا فشل دور محادثة، ومدة تشغيل التدفق، وما إذا كان التدفق مما تشغّله CrewAI داخليًا أو مما كتبته أنت. ويُسجَّل اسم التدفق، كما هو الحال بالفعل لإنشاء التدفق وتنفيذه. وعند فشل تدفق أو إحدى طرقه، يُسجَّل **اسم فئة** الاستثناء (مثل `TimeoutError`) لتشخيص الأعطال — ولا تُسجَّل أبدًا رسالة الخطأ، التي قد تحتوي على مطالبات أو مخرجات النموذج أو مسارات ملفات أو بيانات اعتماد. ولا تُسجَّل أبدًا أسماء الطرق أو حالة التدفق. لا توجد بيانات شخصية. |
 | نعم       | إشارة مشاركة التتبع | تشمل: نجاح مشاركة دفعة من عمليات التتبع مع CrewAI AMP، وما إذا تمت المشاركة بشكل مجهول (قبل إنشاء حساب) أو مرتبطة بحسابك. ومثل كل span، تحمل أيضًا سمات بيئة التنفيذ الموضحة أعلاه (`project_id` عند تكوينه، ومساعد البرمجة، وبيئة التشغيل). يصف هذا الصف بيانات القياس عن بُعد الخاصة بالمشاركة فقط — وليس محتويات التتبع أو الوصول الذي تمنحه روابط التتبع المشتركة. لا تُسجَّل محتويات التتبع أو المدخلات أو المخرجات في هذه الإشارة. قبل مشاركة التتبعات، راجع الأسرار والبيانات الشخصية وإعدادات التنقيح والاحتفاظ في AMP. |

docs/edge/ar/tools/ai-ml/ragtool.mdx

@@ -460,7 +460,7 @@ rag_tool = RagTool(config=config, summarize=True)
 
     **خيارات الإعداد:**
     - `model_name` (str): معرّف نموذج HuggingFace. القيمة الافتراضية: `hkunlp/instructor-base`. الخيارات: `hkunlp/instructor-xl`، `hkunlp/instructor-large`، `hkunlp/instructor-base`
-    - `device` (str): الجهاز للتشغيل. القيمة الافتراضية: `cpu`. الخيارات: `cpu`، `cuda`، `mps`
+    - `device` (str): الجهاز للتشغيل. القيمة الافتراضية: `cpu`. الخيارات: `cpu`، `cuda`، `mps`، `xpu`
     - `instruction` (str): بادئة التعليمات للتضمينات
 
     **متغيرات البيئة:**
@@ -485,7 +485,7 @@ rag_tool = RagTool(config=config, summarize=True)
 
     **خيارات الإعداد:**
     - `model_name` (str): اسم نموذج Sentence Transformers. القيمة الافتراضية: `all-MiniLM-L6-v2`. الخيارات: `all-mpnet-base-v2`، `all-MiniLM-L6-v2`، `paraphrase-multilingual-MiniLM-L12-v2`
-    - `device` (str): الجهاز للتشغيل. القيمة الافتراضية: `cpu`. الخيارات: `cpu`، `cuda`، `mps`
+    - `device` (str): الجهاز للتشغيل. القيمة الافتراضية: `cpu`. الخيارات: `cpu`، `cuda`، `mps`، `xpu`
     - `normalize_embeddings` (bool): ما إذا كان يتم تطبيع التضمينات. القيمة الافتراضية: `False`
 
     **متغيرات البيئة:**

docs/edge/ar/tools/ai-ml/visiontool.mdx

@@ -12,6 +12,16 @@ mode: "wide"
 تُستخدم هذه الأداة لاستخراج النص من الصور. عند تمريرها إلى الوكيل، ستستخرج النص من الصورة ثم تستخدمه لتوليد استجابة أو تقرير أو أي مخرج آخر.
 يجب تمرير عنوان URL أو مسار الصورة إلى الوكيل.
 
+يمكنك أيضًا طرح استعلام `query` مخصص حول الصورة واختيار مستوى تعقيد `complexity_level` يقوم تلقائيًا باختيار النموذج الأنسب للطلب:
+
+| مستوى التعقيد | النموذج         |
+| :--------------- | :------------ |
+| `easy`           | `gpt-5.6-luna`  |
+| `medium` (افتراضي) | `gpt-5.6-terra` |
+| `hard`           | `gpt-5.6-sol`   |
+
+عند تمرير `llm` أو `model` بشكل صريح إلى الأداة، فإنه يأخذ الأولوية على اختيار النموذج المستند إلى مستوى التعقيد.
+
 ## التثبيت
 
 ثبّت حزمة crewai_tools
@@ -43,8 +53,10 @@ def researcher(self) -> Agent:
 
 ## المعاملات
 
-تتطلب VisionTool المعاملات التالية:
+تقبل VisionTool المعاملات التالية:
 
 | المعامل           | النوع     | الوصف                                                                      |
 | :----------------- | :------- | :------------------------------------------------------------------------------- |
-| **image_path_url** | `string` | **إلزامي**. مسار ملف الصورة المراد استخراج النص منها. |
+| **image_path_url** | `string` | **إلزامي**. مسار ملف الصورة (أو عنوان URL) المراد استخراج النص منها. |
+| **query**          | `string` | **اختياري**. السؤال أو التعليمات المراد طرحها على النموذج حول الصورة. القيمة الافتراضية هي `"What's in this image?"`. |
+| **complexity_level** | `string` | **اختياري**. مستوى تعقيد الطلب، والذي يحدد النموذج: `easy` أو `medium` أو `hard`. القيمة الافتراضية هي `medium`. |

docs/edge/ar/tools/web-scraping/oxylabsscraperstool.mdx

@@ -4,7 +4,7 @@ description: >
   تتيح أدوات استخراج Oxylabs الوصول بسهولة إلى المعلومات من المصادر المعنية. يرجى الاطلاع على قائمة المصادر المتاحة أدناه:
     - `Amazon Product`
     - `Amazon Search`
-    - `Google Seach`
+    - `Google Search`
     - `Universal`
 icon: globe
 mode: "wide"
@@ -87,7 +87,7 @@ print(result)
 ### المعاملات
 
 - `query` - مصطلح بحث Amazon.
-- `domain` - توطين النطاق لـ Bestbuy.
+- `domain` - توطين النطاق لـ Amazon.
 - `start_page` - رقم صفحة البداية.
 - `pages` - عدد الصفحات المراد استرجاعها.
 - `geo_location` - موقع _التوصيل إلى_.

docs/edge/en/changelog.mdx

@@ -4,6 +4,96 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Sep 09, 2026">
+  ## v1.15.21
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.21)
+
+  ## What's Changed
+
+  ### Features
+  - Add telemetry to track checkpoint runtime and CLI usage.
+
+  ### Bug Fixes
+  - Fix gateway errors reported inside an HTTP 200 response.
+  - Keep deploy push on the AMP create source.
+  - Report scrape failures instead of raising IndexError in the Oxylabs integration.
+  - Route all DashScope models through the native provider.
+  - Persist JSON checkpoints as UTF-8.
+  - Drop stray $ in f-string search URLs for BrightData.
+  - Support list-form type arrays in JSON schema conversion.
+  - Correct gpt-4o-mini context window from 200000 to 128000.
+  - Preserve streaming tool call arguments at contentBlockStop.
+  - Make pre-commit hooks portable on Windows.
+
+  ### Documentation
+  - Clarify that tracing is managed separately from telemetry.
+  - Fix parallel search reference link.
+  - Remove stale parameters from handle_llm_stream_chunk docstring.
+  - Fix streaming output docstring examples.
+  - Use organization UUIDs in the skill install reference.
+
+  ## Contributors
+
+  @Alphaxiaoteng, @DrewWhittleNZ, @Ghraven, @Shxiao101, @Vaishnavi220506, @Vidit-Ostwal, @danielfsbarreto, @georgeatparallel, @github-actions[bot], @jessemiller, @joaomdmoura, @kimnamu, @kiwoongyoon, @liang0417, @lorenzejay, @oxy-giedrius, @simpleqt, @uoparaji
+
+</Update>
+
+<Update label="Sep 04, 2026">
+  ## v1.15.20
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.20)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Fix legacy platform tool alias discovery
+
+  ### Documentation
+  - Update snapshot and changelog for v1.15.19
+
+  ## Contributors
+
+  @joaomdmoura, @vinibrsl
+
+</Update>
+
+<Update label="Sep 04, 2026">
+  ## v1.15.19
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.19)
+
+  ## What's Changed
+
+  ### Features
+  - Add Clipper integrations client
+  - Add `now()` to the CEL expression environment
+  - Record how a crew run ended for every user
+  - Report machine size as a coarse band, not a core count
+  - Add injectable client for CrewAI platform tools
+
+  ### Bug Fixes
+  - Fix reading of octet-stream and xlsx URLs in `urlreadtool`
+  - Fix appending trailing user turn in native Gemini provider
+  - Normalize scheme and port in Ollama base URL
+  - Preserve reusable scope configs in memory
+  - Bump `pypdf` to 6.16.2 for security vulnerability
+  - Bump `nltk` to 3.10.3 for security vulnerability
+  - Fix native structured outputs for current Claude models and Snowflake CVE floor
+  - Run model call hooks on every path and propagate a deny
+
+  ### Documentation
+  - Remove `CodeInterpreterTool` from AI/ML overview examples
+  - Point `prompt-template` link at its current path
+  - Update channels guide to current CopilotKit channels API
+  - Refresh retired Gemini model IDs
+
+  ## Contributors
+
+  @Vidit-Ostwal, @a-yeyang, @github-actions[bot], @hvlcrs, @joaomdmoura, @kikifrost, @lorenzejay, @lucasgomide, @parthiban-sivakumar, @ranst91, @tandede, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="Aug 27, 2026">
   ## v1.15.18
 

docs/edge/en/concepts/cli.mdx

@@ -338,6 +338,7 @@ crewai org switch <organization_id>
 
   - Initiates the deployment process on the CrewAI AMP platform.
   - Upon successful initiation, it will output the Deployment created successfully! message along with the Deployment Name and a unique Deployment ID (UUID).
+  - Push keeps the source used at create. Adding a git `origin` later does not switch a ZIP deployment to git.
 
 - **Deployment Status**: You can check the status of your deployment with:
 
@@ -578,6 +579,7 @@ Trace collection is controlled by checking three settings in priority order:
    ```
    - Checked only if `tracing` is not set in code and `CREWAI_TRACING_ENABLED` is not set to `true`
    - Running `crewai traces enable` is sufficient to enable tracing by itself
+   - The first-run prompt (`Would you like to view your execution traces?`) also updates this preference
 
 <Note>
 **To enable tracing**, use any one of these methods:

docs/edge/en/concepts/crews.mdx

@@ -37,7 +37,7 @@ A crew in crewAI represents a collaborative group of agents working together to
 | **Chat LLM** _(optional)_                      | `chat_llm`                    | The language model used to orchestrate `crewai chat` CLI interactions with the crew. Accepts a model name string or `LLM` instance. Defaults to `None`.                                                                                                    |
 | **Before Kickoff Callbacks** _(optional)_      | `before_kickoff_callbacks`    | A list of callable functions executed **before** the crew starts. Each callback receives and can modify the inputs dict. Distinct from the `@before_kickoff` decorator. Defaults to `[]`.                                                                   |
 | **After Kickoff Callbacks** _(optional)_       | `after_kickoff_callbacks`     | A list of callable functions executed **after** the crew finishes. Each callback receives and can modify the `CrewOutput`. Distinct from the `@after_kickoff` decorator. Defaults to `[]`.                                                                  |
-| **Tracing** _(optional)_                       | `tracing`                     | Controls OpenTelemetry tracing for the crew. `True` = always enable, `False` = always disable, `None` = inherit from environment / user settings. Defaults to `None`.                                                                                      |
+| **Tracing** _(optional)_                       | `tracing`                     | Controls tracing for the crew. `True` = always enable, `False` = always disable, `None` = inherit from environment / user settings. Defaults to `None`.                                                                                      |
 | **Skills** _(optional)_                        | `skills`                      | A list of `Path` objects (skill search directories) or pre-loaded `Skill` objects applied to all agents in the crew. Defaults to `None`.                                                                                                                    |
 | **Security Config** _(optional)_               | `security_config`              | A `SecurityConfig` instance managing crew fingerprinting and identity. Defaults to `SecurityConfig()`.                                                                                                                                                      |
 | **Checkpoint** _(optional)_                    | `checkpoint`                  | Enables automatic checkpointing. Pass `True` for sensible defaults, a `CheckpointConfig` for full control, `False` to opt out, or `None` to inherit. See the [Checkpointing](#checkpointing) section below. Defaults to `None`.                             |

docs/edge/en/concepts/knowledge.mdx

@@ -636,6 +636,21 @@ agent = Agent(
         }
     }
 )
+
+# Option 4: Use OpenRouter embeddings (supports models across providers)
+# Set OPENROUTER_API_KEY environment variable if api_key is omitted in config
+crew = Crew(
+    agents=[agent],
+    tasks=[...],
+    knowledge_sources=[knowledge_source],
+    embedder={
+        "provider": "openrouter",
+        "config": {
+            "model_name": "openai/text-embedding-3-small",
+            "api_key": "your-openrouter-api-key"  # Optional if OPENROUTER_API_KEY is set
+        }
+    }
+)
 ```
 
 #### Configuring Azure OpenAI Embeddings

docs/edge/en/concepts/llms.mdx

@@ -1487,6 +1487,38 @@ llm = LLM(
     llm = LLM(model="gpt-4")
     ```
   </Tab>
+  <Tab title="Gateway Errors">
+    <Tip>
+      Gateways such as OpenRouter return `200 OK` as soon as the upstream provider accepts the request, so a provider timeout arrives in the response body instead of the status code.
+    </Tip>
+
+    CrewAI raises the same exception the upstream code would have produced as a real HTTP status, so a masked failure is caught by the retry handling you already have:
+
+    ```python
+    import openai
+    from pydantic import BaseModel
+
+    from crewai import LLM
+
+
+    class Report(BaseModel):
+        summary: str
+
+
+    llm = LLM(model="openrouter/z-ai/glm-5.3", response_format=Report)
+
+    try:
+        result = llm.call("Summarize the incident", response_model=Report)
+    except openai.InternalServerError as e:
+        # "z-ai/glm-5.3 via openrouter.ai returned HTTP 200 with an upstream error
+        #  and no choices: The operation was aborted (upstream code 504)"
+        print(f"Upstream provider failed, safe to retry: {e}")
+    ```
+
+    <Warning>
+      A large or deeply nested `response_model` makes upstream timeouts more likely. Treat these as transient provider failures, not as the model producing malformed structured output.
+    </Warning>
+  </Tab>
   <Tab title="Context Length">
     <Tip>
       Use larger context models for extensive tasks

docs/edge/en/concepts/skills.mdx

@@ -210,13 +210,17 @@ Publishing reads `name`, `description`, and `metadata.version` from the `SKILL.m
 
 ### Install
 
-Install a published skill by its `@org/name` reference:
+Install a published skill by its `@org-uuid/name` reference:
 
 ```shell Terminal
-crewai skill install @acme/code-review
+crewai skill install @your-org-uuid/code-review
 ```
 
-Inside a crew project the skill lands in `./skills/{name}/`; outside a project it goes to the shared cache at `~/.crewai/skills/{org}/{name}/`.
+<Note>
+  Use your organization's **UUID**, not its name — organization names are not unique, so a name can resolve to the wrong organization and the install fails with a "not found" error. Run `crewai org list` to see the UUID (the `ID` column) of every organization you belong to.
+</Note>
+
+Inside a crew project the skill lands in `./skills/{name}/`; outside a project it goes to the shared cache at `~/.crewai/skills/{org-uuid}/{name}/`.
 
 Agents can also reference registry skills directly — they resolve from the local cache (or project `skills/` directory) at runtime:
 
@@ -225,7 +229,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review"],  # registry ref, resolved locally
+    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
 )
 ```
 
@@ -240,7 +244,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review@1.2.0"],  # pinned; a leading "v" also works
+    skills=["@your-org-uuid/code-review@1.2.0"],  # pinned; a leading "v" also works
 )
 ```
 

docs/edge/en/observability/tracing.mdx

@@ -9,7 +9,7 @@ mode: "wide"
 
 CrewAI provides built-in tracing capabilities that allow you to monitor and debug your Crews and Flows in real-time. This guide demonstrates how to enable tracing for both **Crews** and **Flows** using CrewAI's integrated observability platform.
 
-> **What is CrewAI Tracing?** CrewAI's built-in tracing provides comprehensive observability for your AI agents, including agent decisions, task execution timelines, tool usage, and LLM calls - all accessible through the [CrewAI AMP platform](https://app.crewai.com).
+> **What is CrewAI Tracing?** CrewAI's built-in tracing provides comprehensive observability for your AI agents, including agent decisions, task execution timelines, tool usage, and LLM calls - all accessible through the [CrewAI AMP platform](https://app.crewai.com). Tracing is managed independently from [telemetry](/en/telemetry).
 
 ![CrewAI Tracing Interface](/images/crewai-tracing.png)
 
@@ -170,6 +170,18 @@ CREWAI_TRACING_ENABLED=true
 
 When this environment variable is set, all Crews and Flows will automatically have tracing enabled, even without explicitly setting `tracing=True`.
 
+## Viewing traces after your first run
+
+The first time you run a Crew or Flow, an interactive terminal may ask:
+
+```text
+Would you like to view your execution traces? [y/N]
+```
+
+Choose **yes** to open a view link. You can change this later with
+`crewai traces enable` or `crewai traces disable`, or by setting `tracing`
+on the Crew or Flow.
+
 ## Viewing Your Traces
 
 ### Access the CrewAI AMP Dashboard

docs/edge/en/telemetry.mdx

@@ -24,6 +24,7 @@ When the `share_crew` feature is enabled, detailed data including task descripti
 to provide deeper insights. This expanded data collection may include personal information if users have incorporated it into their crews or tasks. 
 Users should carefully consider the content of their crews and tasks before enabling `share_crew`. 
 Users can disable CrewAI telemetry by setting `CREWAI_DISABLE_TELEMETRY` to `true`, `1`, `yes`, or `on` (any case). `OTEL_SDK_DISABLED` with the same values also disables CrewAI's exporter. The OpenTelemetry SDK itself still only honors `true` for disabling other instrumentation in the process.
+AMP tracing is covered separately in [Tracing](/en/observability/tracing).
 
 ### Examples:
 ```python
@@ -62,7 +63,7 @@ own tracer provider, which is independent of the one described here.
 | Yes       | Task Lifecycle Data | Includes: creation and execution start/end times, crew and task identifiers, and whether the task succeeded or failed. When a task fails, the **class name** of the exception is recorded (for example `TimeoutError`) so failures can be counted and diagnosed — never the error message, which can contain prompts, model output, file paths or credentials. Stored as spans with timestamps. No personal data. |
 | Yes       | LLM Attributes | Includes: name, model_name, model, top_k, temperature, and class name of the LLM. All technical, non-personal data. |
 | Yes       | Project Creation using crewAI CLI | Includes: that a new project was scaffolded by `crewai create`, which kind it was (`crew`, `json_crew` or `flow`), and the project ID minted for that new project and written into its own `pyproject.toml`. That is the new project's own ID, recorded separately from the `project_id` of the directory the command was run from — the two can differ. No project name, no file contents, no code. No personal data. |
-| Yes       | Crew Deployment attempt using crewAI CLI | Includes: The fact a deploy is being made and crew id, whether it's trying to pull logs, and whether the deploy was started from a CLI command or from the run TUI. No project or crew contents. No personal data. |
+| Yes       | Crew Deployment attempt using crewAI CLI | Includes: The fact a deploy is being made and crew id, whether it's trying to pull logs, and whether the deploy was started from a CLI command or from the run TUI. If creating a deployment fails, the failure category (one of a fixed list such as `api_4xx`, `network_error` or `user_declined`) and the HTTP status code of the API response, when there was one, are recorded — never the error message. No project or crew contents. No personal data. |
 | Yes       | Execution Environment | Includes: which AI coding assistant is running the process, if any (one of a fixed list such as `claude_code`, `codex`, `cursor`, or `unknown`), where the process runs (one of a fixed list such as `ci`, `container`, `serverless`, `interactive`), the `project_id` from your `pyproject.toml` when one is configured, and a coarse size band for the machine (one of `1-2`, `3-4`, `5-8`, `9-16`, `17-32`, `33+`, or `unknown`). The band is a range, never the exact core count — the exact count is opt-in only, under Environment Information below. The size band comes from the host CPU count; assistant and location detection reads only whether known environment variables are set, never their values. No personal data. |
 | Yes       | Flow Lifecycle Signals | Includes: that a flow started, whether it completed or failed, whether one of its methods failed, whether it paused for human input or feedback, whether the start was a resumed run, whether a conversation turn failed, how long the flow ran, and whether the flow is one CrewAI runs internally or one you wrote. The flow name is recorded, as it already is for flow creation and execution. When a flow or one of its methods fails, the **class name** of the exception is recorded (for example `TimeoutError`) so that failures can be diagnosed — never the error message, which can contain prompts, model output, file paths or credentials. Method names and flow state are never recorded. No personal data. |
 | Yes       | Trace Sharing Signal | Includes: that a batch of traces was successfully shared with CrewAI AMP, and whether it was shared anonymously (before you have an account) or linked to your account. Like every span, it also carries the Execution Environment attributes described above (`project_id` when configured, the coding assistant, and the runtime). This row describes sharing telemetry only — not the trace contents or access granted by shared trace links. Trace contents, inputs, and outputs are never recorded on this signal. Before sharing traces, review secrets, personal data, and AMP redaction and retention settings. |

docs/edge/en/tools/ai-ml/ragtool.mdx

@@ -460,7 +460,7 @@ The `embedding_model` parameter accepts a `crewai.rag.embeddings.types.ProviderS
 
     **Config Options:**
     - `model_name` (str): HuggingFace model ID. Default: `hkunlp/instructor-base`. Options: `hkunlp/instructor-xl`, `hkunlp/instructor-large`, `hkunlp/instructor-base`
-    - `device` (str): Device to run on. Default: `cpu`. Options: `cpu`, `cuda`, `mps`
+    - `device` (str): Device to run on. Default: `cpu`. Options: `cpu`, `cuda`, `mps`, `xpu`
     - `instruction` (str): Instruction prefix for embeddings
 
     **Environment Variables:**
@@ -485,7 +485,7 @@ The `embedding_model` parameter accepts a `crewai.rag.embeddings.types.ProviderS
 
     **Config Options:**
     - `model_name` (str): Sentence Transformers model name. Default: `all-MiniLM-L6-v2`. Options: `all-mpnet-base-v2`, `all-MiniLM-L6-v2`, `paraphrase-multilingual-MiniLM-L12-v2`
-    - `device` (str): Device to run on. Default: `cpu`. Options: `cpu`, `cuda`, `mps`
+    - `device` (str): Device to run on. Default: `cpu`. Options: `cpu`, `cuda`, `mps`, `xpu`
     - `normalize_embeddings` (bool): Whether to normalize embeddings. Default: `False`
 
     **Environment Variables:**

docs/edge/en/tools/ai-ml/visiontool.mdx

@@ -12,6 +12,16 @@ mode: "wide"
 This tool is used to extract text from images. When passed to the agent it will extract the text from the image and then use it to generate a response, report or any other output.
 The URL or the PATH of the image should be passed to the Agent.
 
+You can also ask a custom `query` about the image and pick a `complexity_level` that automatically selects the model best suited for the request:
+
+| Complexity level | Model         |
+| :--------------- | :------------ |
+| `easy`           | `gpt-5.6-luna`  |
+| `medium` (default) | `gpt-5.6-terra` |
+| `hard`           | `gpt-5.6-sol`   |
+
+When an explicit `llm` or `model` is provided to the tool, it takes precedence over the complexity-based model selection.
+
 ## Installation
 
 Install the crewai_tools package
@@ -43,8 +53,10 @@ def researcher(self) -> Agent:
 
 ## Arguments
 
-The VisionTool requires the following arguments:
+The VisionTool accepts the following arguments:
 
-| Argument           | Type     | Description                                                                      |
-| :----------------- | :------- | :------------------------------------------------------------------------------- |
-| **image_path_url** | `string` | **Mandatory**. The path to the image file from which text needs to be extracted. |
+| Argument             | Type     | Description                                                                                                   |
+| :------------------- | :------- | :----------------------------------------------------------------------------------------------------------- |
+| **image_path_url**   | `string` | **Mandatory**. The path to the image file (or URL) from which text needs to be extracted.                    |
+| **query**            | `string` | **Optional**. The question or instruction to ask the model about the image. Defaults to `"What's in this image?"`. |
+| **complexity_level** | `string` | **Optional**. The complexity of the request, which selects the model: `easy`, `medium`, or `hard`. Defaults to `medium`. |

docs/edge/en/tools/web-scraping/oxylabsscraperstool.mdx

@@ -4,7 +4,7 @@ description: >
   Oxylabs Scrapers allow to easily access the information from the respective sources. Please see the list of available sources below:
     - `Amazon Product`
     - `Amazon Search`
-    - `Google Seach`
+    - `Google Search`
     - `Universal`
 icon: globe
 mode: "wide"
@@ -87,7 +87,7 @@ print(result)
 ### Parameters
 
 - `query` - Amazon search term.
-- `domain` - Domain localization for Bestbuy.
+- `domain` - domain localization for Amazon.
 - `start_page` - starting page number.
 - `pages` - number of pages to retrieve.
 - `geo_location` - the _Deliver to_ location.

docs/edge/ko/changelog.mdx

@@ -4,6 +4,96 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 9월 9일">
+  ## v1.15.21
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.21)
+
+  ## 변경 사항
+
+  ### 기능
+  - 체크포인트 실행 시간 및 CLI 사용을 추적하기 위한 텔레메트리 추가.
+
+  ### 버그 수정
+  - HTTP 200 응답 내에서 보고된 게이트웨이 오류 수정.
+  - AMP 소스 생성 시 배포 푸시 유지.
+  - Oxylabs 통합에서 IndexError를 발생시키는 대신 스크랩 실패 보고.
+  - 모든 DashScope 모델을 네이티브 제공자를 통해 라우팅.
+  - JSON 체크포인트를 UTF-8로 유지.
+  - BrightData의 f-string 검색 URL에서 이탈한 $ 제거.
+  - JSON 스키마 변환에서 리스트 형태의 배열 지원.
+  - gpt-4o-mini 컨텍스트 창 크기를 200000에서 128000으로 수정.
+  - contentBlockStop에서 스트리밍 도구 호출 인수 유지.
+  - Windows에서 pre-commit 훅을 휴대 가능하게 만듦.
+
+  ### 문서
+  - 추적이 텔레메트리와 별도로 관리됨을 명확히 함.
+  - 병렬 검색 참조 링크 수정.
+  - handle_llm_stream_chunk 문서 문자열에서 오래된 매개변수 제거.
+  - 스트리밍 출력 문서 문자열 예제 수정.
+  - 기술 설치 참조에서 조직 UUID 사용.
+
+  ## 기여자
+
+  @Alphaxiaoteng, @DrewWhittleNZ, @Ghraven, @Shxiao101, @Vaishnavi220506, @Vidit-Ostwal, @danielfsbarreto, @georgeatparallel, @github-actions[bot], @jessemiller, @joaomdmoura, @kimnamu, @kiwoongyoon, @liang0417, @lorenzejay, @oxy-giedrius, @simpleqt, @uoparaji
+
+</Update>
+
+<Update label="2026년 9월 4일">
+  ## v1.15.20
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.20)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - 레거시 플랫폼 도구 별칭 검색 수정
+
+  ### 문서
+  - v1.15.19에 대한 스냅샷 및 변경 로그 업데이트
+
+  ## 기여자
+
+  @joaomdmoura, @vinibrsl
+
+</Update>
+
+<Update label="2026년 9월 4일">
+  ## v1.15.19
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.19)
+
+  ## 변경 사항
+
+  ### 기능
+  - Clipper 통합 클라이언트 추가
+  - CEL 표현식 환경에 `now()` 추가
+  - 모든 사용자에 대해 크루 실행이 어떻게 종료되었는지 기록
+  - 기계 크기를 코어 수가 아닌 대략적인 범위로 보고
+  - CrewAI 플랫폼 도구를 위한 주입 가능한 클라이언트 추가
+
+  ### 버그 수정
+  - `urlreadtool`에서 octet-stream 및 xlsx URL 읽기 수정
+  - 네이티브 Gemini 제공자에서 후행 사용자 전환 추가 수정
+  - Ollama 기본 URL에서 스킴 및 포트 정규화
+  - 메모리에서 재사용 가능한 범위 구성 유지
+  - 보안 취약성을 위해 `pypdf`를 6.16.2로 업데이트
+  - 보안 취약성을 위해 `nltk`를 3.10.3으로 업데이트
+  - 현재 Claude 모델 및 Snowflake CVE 바닥을 위한 네이티브 구조화된 출력 수정
+  - 모든 경로에서 모델 호출 후크 실행 및 거부 전파
+
+  ### 문서
+  - AI/ML 개요 예제에서 `CodeInterpreterTool` 제거
+  - `prompt-template` 링크를 현재 경로로 지정
+  - 현재 CopilotKit 채널 API에 맞게 채널 가이드 업데이트
+  - 퇴역한 Gemini 모델 ID 새로 고침
+
+  ## 기여자
+
+  @Vidit-Ostwal, @a-yeyang, @github-actions[bot], @hvlcrs, @joaomdmoura, @kikifrost, @lorenzejay, @lucasgomide, @parthiban-sivakumar, @ranst91, @tandede, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="2026년 8월 27일">
   ## v1.15.18
 

docs/edge/ko/concepts/cli.mdx

@@ -286,6 +286,7 @@ crewai org switch <organization_id>
 
   - CrewAI AMP 플랫폼에서 배포 프로세스를 시작합니다.
   - 성공적으로 시작되면, Deployment created successfully! 메시지와 함께 Deployment Name 및 고유한 Deployment ID(UUID)가 출력됩니다.
+  - Push는 생성 시 사용한 소스를 유지합니다. 나중에 git `origin`을 추가해도 ZIP 배포가 git으로 바뀌지 않습니다.
 
 - **배포 상태**: 배포 상태를 확인하려면 다음을 사용합니다:
 

docs/edge/ko/concepts/knowledge.mdx

@@ -603,6 +603,21 @@ agent = Agent(
         }
     }
 )
+
+# Option 4: Use OpenRouter embeddings (supports models across providers)
+# Set OPENROUTER_API_KEY environment variable if api_key is omitted in config
+crew = Crew(
+    agents=[agent],
+    tasks=[...],
+    knowledge_sources=[knowledge_source],
+    embedder={
+        "provider": "openrouter",
+        "config": {
+            "model_name": "openai/text-embedding-3-small",
+            "api_key": "your-openrouter-api-key"  # Optional if OPENROUTER_API_KEY is set
+        }
+    }
+)
 ```
 
 #### Azure OpenAI 임베딩 구성

docs/edge/ko/concepts/llms.mdx

@@ -995,6 +995,38 @@ LLM 설정을 최대한 활용하는 방법을 알아보세요:
     llm = LLM(model="gpt-4")
     ```
   </Tab>
+  <Tab title="게이트웨이 오류">
+    <Tip>
+      OpenRouter와 같은 게이트웨이는 업스트림 공급자가 요청을 수락하는 즉시 `200 OK`를 반환하므로, 공급자 타임아웃은 상태 코드가 아니라 응답 본문에 담겨 도착합니다.
+    </Tip>
+
+    CrewAI는 해당 업스트림 코드가 실제 HTTP 상태로 왔을 때 발생시킬 예외와 동일한 예외를 발생시키므로, 이미 구성해 둔 재시도 처리로 가려진 실패를 잡을 수 있습니다:
+
+    ```python
+    import openai
+    from pydantic import BaseModel
+
+    from crewai import LLM
+
+
+    class Report(BaseModel):
+        summary: str
+
+
+    llm = LLM(model="openrouter/z-ai/glm-5.3", response_format=Report)
+
+    try:
+        result = llm.call("Summarize the incident", response_model=Report)
+    except openai.InternalServerError as e:
+        # "z-ai/glm-5.3 via openrouter.ai returned HTTP 200 with an upstream error
+        #  and no choices: The operation was aborted (upstream code 504)"
+        print(f"Upstream provider failed, safe to retry: {e}")
+    ```
+
+    <Warning>
+      크거나 깊게 중첩된 `response_model`은 업스트림 타임아웃 가능성을 높입니다. 이를 모델이 잘못된 구조화 출력을 생성한 것으로 보지 말고, 일시적인 공급자 장애로 처리하세요.
+    </Warning>
+  </Tab>
   <Tab title="컨텍스트 길이">
     <Tip>
       대규모 작업에는 더 큰 컨텍스트 모델을 사용하세요.

docs/edge/ko/concepts/skills.mdx

@@ -202,13 +202,17 @@ crewai skill publish
 
 ### 설치
 
-게시된 스킬을 `@org/name` 참조로 설치합니다:
+게시된 스킬을 `@org-uuid/name` 참조로 설치합니다:
 
 ```shell Terminal
-crewai skill install @acme/code-review
+crewai skill install @your-org-uuid/code-review
 ```
 
-크루 프로젝트 내부에서는 스킬이 `./skills/{name}/`에 설치되고, 프로젝트 외부에서는 공유 캐시인 `~/.crewai/skills/{org}/{name}/`에 저장됩니다.
+<Note>
+  조직 이름이 아니라 조직 **UUID**를 사용하세요 — 조직 이름은 고유하지 않아서 잘못된 조직으로 해석될 수 있고, 그러면 설치가 "찾을 수 없음" 오류로 실패합니다. `crewai org list`를 실행하면 소속된 각 조직의 UUID(`ID` 열)를 확인할 수 있습니다.
+</Note>
+
+크루 프로젝트 내부에서는 스킬이 `./skills/{name}/`에 설치되고, 프로젝트 외부에서는 공유 캐시인 `~/.crewai/skills/{org-uuid}/{name}/`에 저장됩니다.
 
 에이전트는 레지스트리 스킬을 직접 참조할 수도 있습니다 — 런타임에 로컬 캐시(또는 프로젝트 `skills/` 디렉터리)에서 해석됩니다:
 
@@ -217,7 +221,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review"],  # registry ref, resolved locally
+    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
 )
 ```
 

docs/edge/ko/observability/tracing.mdx

@@ -9,7 +9,7 @@ mode: "wide"
 
 CrewAI는 Crews와 Flows를 실시간으로 모니터링하고 디버깅할 수 있는 내장 추적 기능을 제공합니다. 이 가이드는 CrewAI의 통합 관측 가능성 플랫폼을 사용하여 **Crews**와 **Flows** 모두에 대한 추적을 활성화하는 방법을 보여줍니다.
 
-> **CrewAI Tracing이란?** CrewAI의 내장 추적은 agent 결정, 작업 실행 타임라인, 도구 사용, LLM 호출을 포함한 AI agent에 대한 포괄적인 관측 가능성을 제공하며, 모두 [CrewAI AMP 플랫폼](https://app.crewai.com)을 통해 액세스할 수 있습니다.
+> **CrewAI Tracing이란?** CrewAI의 내장 추적은 agent 결정, 작업 실행 타임라인, 도구 사용, LLM 호출을 포함한 AI agent에 대한 포괄적인 관측 가능성을 제공하며, 모두 [CrewAI AMP 플랫폼](https://app.crewai.com)을 통해 액세스할 수 있습니다. 추적은 [텔레메트리](/ko/telemetry)와 별도로 관리됩니다.
 
 ![CrewAI Tracing Interface](/images/crewai-tracing.png)
 
@@ -170,6 +170,17 @@ CREWAI_TRACING_ENABLED=true
 
 이 환경 변수가 설정되면 `tracing=True`를 명시적으로 설정하지 않아도 모든 Crews와 Flows에 자동으로 추적이 활성화됩니다.
 
+## 첫 실행 후 추적 보기
+
+Crew 또는 Flow를 처음 실행하면 대화형 터미널에서 다음을 물을 수 있습니다:
+
+```text
+Would you like to view your execution traces? [y/N]
+```
+
+보기 링크를 열려면 **yes**를 선택하세요. 나중에 `crewai traces enable` 또는
+`crewai traces disable`로 바꾸거나, Crew 또는 Flow에서 `tracing`을 설정할 수 있습니다.
+
 ## 추적 보기
 
 ### CrewAI AMP 대시보드 액세스

docs/edge/ko/telemetry.mdx

@@ -23,6 +23,7 @@ CrewAI는 익명 텔레메트리를 활용하여 사용 통계를 수집하며,
 이 확대된 데이터 수집에는 사용자가 crew나 작업에 개인정보를 포함한 경우, 개인정보가 포함될 수 있습니다.
 사용자는 `share_crew`를 활성화하기 전에 crew와 작업의 내용을 신중하게 검토해야 합니다.
 사용자는 `CREWAI_DISABLE_TELEMETRY`를 `true`, `1`, `yes`, `on` 중 하나로 설정하여 CrewAI 텔레메트리를 비활성화할 수 있습니다(대소문자 무관). 같은 값의 `OTEL_SDK_DISABLED`도 CrewAI exporter를 끕니다. 프로세스 내 다른 OpenTelemetry 계측을 끄려면 OpenTelemetry SDK는 여전히 `true`만 인식합니다.
+AMP 추적은 [Tracing](/ko/observability/tracing)에서 별도로 다룹니다.
 
 ### 예시:
 ```python
@@ -60,7 +61,7 @@ provider로 등록하지 않습니다. 이를 통해 양방향이 분리됩니
 | 예      | 작업 라이프사이클 데이터                   | 생성 및 실행 시작/종료 시각, crew 및 작업 식별자, 그리고 작업의 성공 또는 실패 여부가 포함됩니다. 작업이 실패하면 실패를 집계하고 진단할 수 있도록 예외의 **클래스 이름**(예: `TimeoutError`)이 기록되며, 프롬프트·모델 출력·파일 경로·자격 증명이 포함될 수 있는 오류 메시지는 결코 기록되지 않습니다. 타임스탬프를 포함한 span으로 저장됩니다. 개인 정보 없음. |
 | 예      | LLM 속성                                  | LLM의 이름, model_name, 모델, top_k, temperature 및 클래스명이 포함됩니다. 모두 기술적이고 비개인 정보입니다. |
 | 예      | crewAI CLI를 통한 프로젝트 생성 | 포함 항목: `crewai create`로 새 프로젝트가 생성되었다는 사실, 그 종류(`crew`, `json_crew` 또는 `flow`), 그리고 그 새 프로젝트에 발급되어 해당 프로젝트의 `pyproject.toml`에 기록된 프로젝트 ID. 이는 새 프로젝트 자체의 ID이며, 명령을 실행한 디렉터리의 `project_id`와는 별개로 기록됩니다 — 두 값은 다를 수 있습니다. 프로젝트 이름, 파일 내용, 코드는 기록되지 않습니다. 개인 정보 없음. |
-| 예      | crewAI CLI를 통한 Crew 배포 시도 | 포함 항목: 배포가 시도되고 있다는 사실과 crew id, 로그를 가져오려고 하는지 여부, 그리고 배포가 CLI 명령에서 시작되었는지 실행 TUI에서 시작되었는지 여부. 프로젝트나 crew의 내용은 기록되지 않습니다. 개인 정보 없음. |
+| 예      | crewAI CLI를 통한 Crew 배포 시도 | 포함 항목: 배포가 시도되고 있다는 사실과 crew id, 로그를 가져오려고 하는지 여부, 그리고 배포가 CLI 명령에서 시작되었는지 실행 TUI에서 시작되었는지 여부. 배포 생성이 실패하면 실패 범주(`api_4xx`, `network_error`, `user_declined` 등 고정된 목록 중 하나)와 API 응답의 HTTP 상태 코드(있는 경우)가 기록되며, 오류 메시지는 절대 기록되지 않습니다. 프로젝트나 crew의 내용은 기록되지 않습니다. 개인 정보 없음. |
 | 예      | 실행 환경                                  | 포함: 프로세스를 실행 중인 AI 코딩 어시스턴트(있는 경우, `claude_code`, `codex`, `cursor`, `unknown` 등 고정 목록 중 하나), 프로세스가 실행되는 위치(`ci`, `container`, `serverless`, `interactive` 등 고정 목록 중 하나), `pyproject.toml`에 설정된 경우 `project_id`, 그리고 머신 크기의 대략적인 구간(`1-2`, `3-4`, `5-8`, `9-16`, `17-32`, `33+`, `unknown` 중 하나). 구간은 범위이며 정확한 코어 수는 절대 포함하지 않습니다 — 정확한 코어 수는 아래 환경 정보에서 옵트인한 경우에만 수집됩니다. 크기 구간은 호스트 CPU 수에서 가져오며, 어시스턴트와 실행 위치 감지는 알려진 환경 변수의 설정 여부만 확인하고 값은 읽지 않음. 개인 데이터 없음. |
 | 예      | Flow 라이프사이클 신호 | 포함 항목: flow의 시작, 완료 또는 실패 여부, 해당 메서드의 실패 여부, 사람의 입력이나 피드백을 위해 일시 중지되었는지 여부, 해당 시작이 재개된 실행이었는지 여부, 대화 턴의 실패 여부, flow 실행 시간, 그리고 해당 flow가 CrewAI가 내부적으로 실행하는 것인지 사용자가 작성한 것인지 여부. flow 이름은 flow 생성 및 실행에서와 마찬가지로 기록됩니다. flow 또는 해당 메서드가 실패하면 장애 진단을 위해 예외의 **클래스 이름**(예: `TimeoutError`)이 기록되며, 프롬프트·모델 출력·파일 경로·자격 증명이 포함될 수 있는 오류 메시지는 절대 기록되지 않습니다. 메서드 이름과 flow 상태는 절대 기록되지 않습니다. 개인 정보 없음. |
 | 예      | 트레이스 공유 신호 | 포함 항목: 트레이스 배치가 CrewAI AMP에 성공적으로 공유되었는지 여부와, 익명으로(계정 생성 전) 공유되었는지 또는 계정에 연결되어 공유되었는지 여부. 모든 span과 마찬가지로 위에서 설명한 실행 환경 속성(구성된 경우 `project_id`, 코딩 어시스턴트, 런타임)도 함께 기록됩니다. 이 행은 공유 텔레메트리만 설명하며 — 트레이스 내용이나 공유된 트레이스 링크로 부여되는 접근 권한은 설명하지 않습니다. 트레이스 내용, 입력, 출력은 이 신호에는 기록되지 않습니다. 트레이스를 공유하기 전에 비밀 정보, 개인 데이터, AMP 편집 및 보존 설정을 검토하세요. |

docs/edge/ko/tools/ai-ml/ragtool.mdx

@@ -1,6 +1,6 @@
 ---
 title: RAG 도구
-description: RagTool은 Retrieval-Augmented Generation을 사용하여 질문에 답변하는 동적 지식 기반 도구입니다.
+description: `RagTool`은 Retrieval-Augmented Generation을 사용하여 질문에 답변하는 동적 지식 기반 도구입니다.
 icon: vector-square
 mode: "wide"
 ---
@@ -9,7 +9,7 @@ mode: "wide"
 
 ## 설명
 
-`RagTool`은 EmbedChain을 통한 RAG(Retrieval-Augmented Generation)의 강력함을 활용하여 질문에 답하도록 설계되었습니다.
+`RagTool`은 CrewAI의 네이티브 RAG 시스템을 통해 RAG(Retrieval-Augmented Generation)의 강력함을 활용하여 질문에 답하도록 설계되었습니다.
 이는 다양한 데이터 소스에서 관련 정보를 검색할 수 있는 동적 지식 기반을 제공합니다.
 이 도구는 방대한 정보에 접근해야 하고 맥락에 맞는 답변을 제공해야 하는 애플리케이션에 특히 유용합니다.
 
@@ -76,24 +76,24 @@ def knowledge_expert(self) -> Agent:
 `RagTool`은 다음과 같은 매개변수를 허용합니다:
 
 - **summarize**: 선택 사항. 검색된 콘텐츠를 요약할지 여부입니다. 기본값은 `False`입니다.
-- **adapter**: 선택 사항. 지식 베이스에 대한 사용자 지정 어댑터입니다. 제공되지 않은 경우 EmbedchainAdapter가 사용됩니다.
-- **config**: 선택 사항. 내부 EmbedChain App의 구성입니다.
+- **adapter**: 선택 사항. 지식 기반을 위한 사용자 지정 어댑터입니다. 제공하지 않으면 CrewAIRagAdapter가 사용됩니다.
+- **config**: 선택 사항. 내부 CrewAI RAG 시스템에 대한 구성입니다. 선택적 `embedding_model`(ProviderSpec) 및 `vectordb`(VectorDbConfig) 키를 포함하는 `RagToolConfig` TypedDict를 허용합니다. 프로그래밍 방식으로 제공된 모든 구성 값은 환경 변수보다 우선합니다.
 
 ## 콘텐츠 추가
 
 `add` 메서드를 사용하여 지식 베이스에 콘텐츠를 추가할 수 있습니다:
 
 ```python Code
-# PDF 파일 추가
+# Add a PDF file
 rag_tool.add(data_type="file", path="path/to/your/document.pdf")
 
-# 웹 페이지 추가
+# Add a web page
 rag_tool.add(data_type="web_page", url="https://example.com")
 
-# YouTube 비디오 추가
+# Add a YouTube video
 rag_tool.add(data_type="youtube_video", url="https://www.youtube.com/watch?v=VIDEO_ID")
 
-# 파일이 있는 디렉터리 추가
+# Add a directory of files
 rag_tool.add(data_type="directory", path="path/to/your/directory")
 ```
 
@@ -123,51 +123,532 @@ def knowledge_expert(self) -> Agent:
 
 ## 고급 구성
 
-`RagTool`의 동작을 구성 사전을 제공하여 사용자 지정할 수 있습니다.
+구성 딕셔너리를 제공하여 `RagTool`의 동작을 사용자 지정할 수 있습니다.
 
 ```python Code
 from crewai_tools import RagTool
+from crewai_tools.tools.rag import RagToolConfig, VectorDbConfig, ProviderSpec
 
-# 사용자 지정 구성으로 RAG 도구 생성
-config = {
-    "app": {
-        "name": "custom_app",
-    },
-    "llm": {
-        "provider": "openai",
-        "config": {
-            "model": "gpt-4",
-        }
-    },
-    "embedding_model": {
-        "provider": "openai",
-        "config": {
-            "model": "text-embedding-ada-002"
-        }
-    },
-    "vectordb": {
-        "provider": "elasticsearch",
-        "config": {
-            "collection_name": "my-collection",
-            "cloud_id": "deployment-name:xxxx",
-            "api_key": "your-key",
-            "verify_certs": False
-        }
-    },
-    "chunker": {
-        "chunk_size": 400,
-        "chunk_overlap": 100,
-        "length_function": "len",
-        "min_chunk_size": 0
+# Create a RAG tool with custom configuration
+
+vectordb: VectorDbConfig = {
+    "provider": "qdrant",
+    "config": {
+        "collection_name": "my-collection"
     }
 }
 
+embedding_model: ProviderSpec = {
+    "provider": "openai",
+    "config": {
+        "model_name": "text-embedding-3-small"
+    }
+}
+
+config: RagToolConfig = {
+    "vectordb": vectordb,
+    "embedding_model": embedding_model
+}
+
 rag_tool = RagTool(config=config, summarize=True)
 ```
 
-내부 RAG 도구는 Embedchain 어댑터를 사용하므로 Embedchain에서 지원하는 모든 구성 옵션을 전달할 수 있습니다.
-자세한 내용은 [Embedchain 문서](https://docs.embedchain.ai/components/introduction)를 참조하세요.
-.yaml 파일에서 제공되는 구성 옵션을 반드시 검토하시기 바랍니다.
+## 임베딩 모델 구성
+
+`embedding_model` 매개변수는 다음 구조의 `crewai.rag.embeddings.types.ProviderSpec` 딕셔너리를 허용합니다.
+
+```python
+{
+    "provider": "provider-name",  # Required
+    "config": {                    # Optional
+        # Provider-specific configuration
+    }
+}
+```
+
+### 지원되는 프로바이더
+
+<AccordionGroup>
+  <Accordion title="OpenAI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.openai.types import OpenAIProviderSpec
+
+    embedding_model: OpenAIProviderSpec = {
+        "provider": "openai",
+        "config": {
+            "api_key": "your-api-key",
+            "model_name": "text-embedding-ada-002",
+            "dimensions": 1536,
+            "organization_id": "your-org-id",
+            "api_base": "https://api.openai.com/v1",
+            "api_version": "v1",
+            "default_headers": {"Custom-Header": "value"}
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `api_key` (str): OpenAI API 키
+    - `model_name` (str): 사용할 모델. 기본값: `text-embedding-ada-002`. 옵션: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
+    - `dimensions` (int): 임베딩 차원 수
+    - `organization_id` (str): OpenAI 조직 ID
+    - `api_base` (str): 사용자 지정 API 기본 URL
+    - `api_version` (str): API 버전
+    - `default_headers` (dict): API 요청을 위한 사용자 지정 헤더
+
+    **환경 변수:**
+    - `OPENAI_API_KEY` 또는 `EMBEDDINGS_OPENAI_API_KEY`: `api_key`
+    - `OPENAI_ORGANIZATION_ID` 또는 `EMBEDDINGS_OPENAI_ORGANIZATION_ID`: `organization_id`
+    - `OPENAI_MODEL_NAME` 또는 `EMBEDDINGS_OPENAI_MODEL_NAME`: `model_name`
+    - `OPENAI_API_BASE` 또는 `EMBEDDINGS_OPENAI_API_BASE`: `api_base`
+    - `OPENAI_API_VERSION` 또는 `EMBEDDINGS_OPENAI_API_VERSION`: `api_version`
+    - `OPENAI_DIMENSIONS` 또는 `EMBEDDINGS_OPENAI_DIMENSIONS`: `dimensions`
+  </Accordion>
+
+  <Accordion title="Cohere">
+    ```python main.py
+    from crewai.rag.embeddings.providers.cohere.types import CohereProviderSpec
+
+    embedding_model: CohereProviderSpec = {
+        "provider": "cohere",
+        "config": {
+            "api_key": "your-api-key",
+            "model_name": "embed-english-v3.0"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `api_key` (str): Cohere API 키
+    - `model_name` (str): 사용할 모델. 기본값: `large`. 옵션: `embed-english-v3.0`, `embed-multilingual-v3.0`, `large`, `small`
+
+    **환경 변수:**
+    - `COHERE_API_KEY` 또는 `EMBEDDINGS_COHERE_API_KEY`: `api_key`
+    - `EMBEDDINGS_COHERE_MODEL_NAME`: `model_name`
+  </Accordion>
+
+  <Accordion title="VoyageAI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.voyageai.types import VoyageAIProviderSpec
+
+    embedding_model: VoyageAIProviderSpec = {
+        "provider": "voyageai",
+        "config": {
+            "api_key": "your-api-key",
+            "model": "voyage-3",
+            "input_type": "document",
+            "truncation": True,
+            "output_dtype": "float32",
+            "output_dimension": 1024,
+            "max_retries": 3,
+            "timeout": 60.0
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `api_key` (str): VoyageAI API 키
+    - `model` (str): 사용할 모델. 기본값: `voyage-2`. 옵션: `voyage-3`, `voyage-3-lite`, `voyage-code-3`, `voyage-large-2`
+    - `input_type` (str): 입력 유형. 옵션: `document`(저장용), `query`(검색용)
+    - `truncation` (bool): 최대 길이를 초과하는 입력을 잘라낼지 여부. 기본값: `True`
+    - `output_dtype` (str): 출력 데이터 유형
+    - `output_dimension` (int): 출력 임베딩 차원
+    - `max_retries` (int): 최대 재시도 횟수. 기본값: `0`
+    - `timeout` (float): 요청 시간 제한(초)
+
+    **환경 변수:**
+    - `VOYAGEAI_API_KEY` 또는 `EMBEDDINGS_VOYAGEAI_API_KEY`: `api_key`
+    - `VOYAGEAI_MODEL` 또는 `EMBEDDINGS_VOYAGEAI_MODEL`: `model`
+    - `VOYAGEAI_INPUT_TYPE` 또는 `EMBEDDINGS_VOYAGEAI_INPUT_TYPE`: `input_type`
+    - `VOYAGEAI_TRUNCATION` 또는 `EMBEDDINGS_VOYAGEAI_TRUNCATION`: `truncation`
+    - `VOYAGEAI_OUTPUT_DTYPE` 또는 `EMBEDDINGS_VOYAGEAI_OUTPUT_DTYPE`: `output_dtype`
+    - `VOYAGEAI_OUTPUT_DIMENSION` 또는 `EMBEDDINGS_VOYAGEAI_OUTPUT_DIMENSION`: `output_dimension`
+    - `VOYAGEAI_MAX_RETRIES` 또는 `EMBEDDINGS_VOYAGEAI_MAX_RETRIES`: `max_retries`
+    - `VOYAGEAI_TIMEOUT` 또는 `EMBEDDINGS_VOYAGEAI_TIMEOUT`: `timeout`
+  </Accordion>
+
+  <Accordion title="Ollama">
+    ```python main.py
+    from crewai.rag.embeddings.providers.ollama.types import OllamaProviderSpec
+
+    embedding_model: OllamaProviderSpec = {
+        "provider": "ollama",
+        "config": {
+            "model_name": "llama2",
+            "url": "http://localhost:11434/api/embeddings"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `model_name` (str): Ollama 모델 이름(예: `llama2`, `mistral`, `nomic-embed-text`)
+    - `url` (str): Ollama API 엔드포인트 URL. 기본값: `http://localhost:11434/api/embeddings`
+
+    **환경 변수:**
+    - `OLLAMA_MODEL` 또는 `EMBEDDINGS_OLLAMA_MODEL`: `model_name`
+    - `OLLAMA_URL` 또는 `EMBEDDINGS_OLLAMA_URL`: `url`
+  </Accordion>
+
+  <Accordion title="Amazon Bedrock">
+    ```python main.py
+    from crewai.rag.embeddings.providers.aws.types import BedrockProviderSpec
+
+    embedding_model: BedrockProviderSpec = {
+        "provider": "amazon-bedrock",
+        "config": {
+            "model_name": "amazon.titan-embed-text-v2:0",
+            "session": boto3_session
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `model_name` (str): Bedrock 모델 ID. 기본값: `amazon.titan-embed-text-v1`. 옵션: `amazon.titan-embed-text-v1`, `amazon.titan-embed-text-v2:0`, `cohere.embed-english-v3`, `cohere.embed-multilingual-v3`
+    - `session` (Any): AWS 인증을 위한 Boto3 세션 객체
+
+    **환경 변수:**
+    - `AWS_ACCESS_KEY_ID`: AWS 액세스 키
+    - `AWS_SECRET_ACCESS_KEY`: AWS 비밀 키
+    - `AWS_REGION`: AWS 리전(예: `us-east-1`)
+  </Accordion>
+
+  <Accordion title="Azure OpenAI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.microsoft.types import AzureProviderSpec
+
+    embedding_model: AzureProviderSpec = {
+        "provider": "azure",
+        "config": {
+            "deployment_id": "your-deployment-id",
+            "api_key": "your-api-key",
+            "api_base": "https://your-resource.openai.azure.com",
+            "api_version": "2024-02-01",
+            "model_name": "text-embedding-ada-002",
+            "api_type": "azure"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `deployment_id` (str): **필수** - Azure OpenAI 배포 ID
+    - `api_key` (str): Azure OpenAI API 키
+    - `api_base` (str): Azure OpenAI 리소스 엔드포인트
+    - `api_version` (str): API 버전. 예: `2024-02-01`
+    - `model_name` (str): 모델 이름. 기본값: `text-embedding-ada-002`
+    - `api_type` (str): API 유형. 기본값: `azure`
+    - `dimensions` (int): 출력 차원
+    - `default_headers` (dict): 사용자 지정 헤더
+
+    **환경 변수:**
+    - `AZURE_OPENAI_API_KEY` 또는 `EMBEDDINGS_AZURE_API_KEY`: `api_key`
+    - `AZURE_OPENAI_ENDPOINT` 또는 `EMBEDDINGS_AZURE_API_BASE`: `api_base`
+    - `EMBEDDINGS_AZURE_DEPLOYMENT_ID`: `deployment_id`
+    - `EMBEDDINGS_AZURE_API_VERSION`: `api_version`
+    - `EMBEDDINGS_AZURE_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_AZURE_API_TYPE`: `api_type`
+    - `EMBEDDINGS_AZURE_DIMENSIONS`: `dimensions`
+  </Accordion>
+
+  <Accordion title="Google Generative AI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.google.types import GenerativeAiProviderSpec
+
+    embedding_model: GenerativeAiProviderSpec = {
+        "provider": "google-generativeai",
+        "config": {
+            "api_key": "your-api-key",
+            "model_name": "gemini-embedding-001",
+            "task_type": "RETRIEVAL_DOCUMENT"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `api_key` (str): Google AI API 키
+    - `model_name` (str): 모델 이름. 기본값: `gemini-embedding-001`. 옵션: `gemini-embedding-001`, `text-embedding-005`, `text-multilingual-embedding-002`
+    - `task_type` (str): 임베딩 작업 유형. 기본값: `RETRIEVAL_DOCUMENT`. 옵션: `RETRIEVAL_DOCUMENT`, `RETRIEVAL_QUERY`
+
+    **환경 변수:**
+    - `GOOGLE_API_KEY`, `GEMINI_API_KEY` 또는 `EMBEDDINGS_GOOGLE_API_KEY`: `api_key`
+    - `EMBEDDINGS_GOOGLE_GENERATIVE_AI_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_GOOGLE_GENERATIVE_AI_TASK_TYPE`: `task_type`
+  </Accordion>
+
+  <Accordion title="Google Vertex AI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.google.types import VertexAIProviderSpec
+
+    embedding_model: VertexAIProviderSpec = {
+        "provider": "google-vertex",
+        "config": {
+            "model_name": "text-embedding-004",
+            "project_id": "your-project-id",
+            "region": "us-central1",
+            "api_key": "your-api-key"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `model_name` (str): 모델 이름. 기본값: `textembedding-gecko`. 옵션: `text-embedding-004`, `textembedding-gecko`, `textembedding-gecko-multilingual`
+    - `project_id` (str): Google Cloud 프로젝트 ID. 기본값: `cloud-large-language-models`
+    - `region` (str): Google Cloud 리전. 기본값: `us-central1`
+    - `api_key` (str): 인증을 위한 API 키
+
+    **환경 변수:**
+    - `GOOGLE_APPLICATION_CREDENTIALS`: 서비스 계정 JSON 파일 경로
+    - `GOOGLE_CLOUD_PROJECT` 또는 `EMBEDDINGS_GOOGLE_VERTEX_PROJECT_ID`: `project_id`
+    - `EMBEDDINGS_GOOGLE_VERTEX_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_GOOGLE_VERTEX_REGION`: `region`
+    - `EMBEDDINGS_GOOGLE_VERTEX_API_KEY`: `api_key`
+  </Accordion>
+
+  <Accordion title="Jina AI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.jina.types import JinaProviderSpec
+
+    embedding_model: JinaProviderSpec = {
+        "provider": "jina",
+        "config": {
+            "api_key": "your-api-key",
+            "model_name": "jina-embeddings-v3"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `api_key` (str): Jina AI API 키
+    - `model_name` (str): 모델 이름. 기본값: `jina-embeddings-v2-base-en`. 옵션: `jina-embeddings-v3`, `jina-embeddings-v2-base-en`, `jina-embeddings-v2-small-en`
+
+    **환경 변수:**
+    - `JINA_API_KEY` 또는 `EMBEDDINGS_JINA_API_KEY`: `api_key`
+    - `EMBEDDINGS_JINA_MODEL_NAME`: `model_name`
+  </Accordion>
+
+  <Accordion title="HuggingFace">
+    ```python main.py
+    from crewai.rag.embeddings.providers.huggingface.types import HuggingFaceProviderSpec
+
+    embedding_model: HuggingFaceProviderSpec = {
+        "provider": "huggingface",
+        "config": {
+            "url": "https://api-inference.huggingface.co/models/sentence-transformers/all-MiniLM-L6-v2"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `url` (str): HuggingFace 추론 API 엔드포인트의 전체 URL
+
+    **환경 변수:**
+    - `HUGGINGFACE_URL` 또는 `EMBEDDINGS_HUGGINGFACE_URL`: `url`
+  </Accordion>
+
+  <Accordion title="Instructor">
+    ```python main.py
+    from crewai.rag.embeddings.providers.instructor.types import InstructorProviderSpec
+
+    embedding_model: InstructorProviderSpec = {
+        "provider": "instructor",
+        "config": {
+            "model_name": "hkunlp/instructor-xl",
+            "device": "cuda",
+            "instruction": "Represent the document"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `model_name` (str): HuggingFace 모델 ID. 기본값: `hkunlp/instructor-base`. 옵션: `hkunlp/instructor-xl`, `hkunlp/instructor-large`, `hkunlp/instructor-base`
+    - `device` (str): 실행할 장치. 기본값: `cpu`. 옵션: `cpu`, `cuda`, `mps`, `xpu`
+    - `instruction` (str): 임베딩을 위한 명령어 접두사
+
+    **환경 변수:**
+    - `EMBEDDINGS_INSTRUCTOR_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_INSTRUCTOR_DEVICE`: `device`
+    - `EMBEDDINGS_INSTRUCTOR_INSTRUCTION`: `instruction`
+  </Accordion>
+
+  <Accordion title="Sentence Transformer">
+    ```python main.py
+    from crewai.rag.embeddings.providers.sentence_transformer.types import SentenceTransformerProviderSpec
+
+    embedding_model: SentenceTransformerProviderSpec = {
+        "provider": "sentence-transformer",
+        "config": {
+            "model_name": "all-mpnet-base-v2",
+            "device": "cuda",
+            "normalize_embeddings": True
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `model_name` (str): Sentence Transformers 모델 이름. 기본값: `all-MiniLM-L6-v2`. 옵션: `all-mpnet-base-v2`, `all-MiniLM-L6-v2`, `paraphrase-multilingual-MiniLM-L12-v2`
+    - `device` (str): 실행할 장치. 기본값: `cpu`. 옵션: `cpu`, `cuda`, `mps`, `xpu`
+    - `normalize_embeddings` (bool): 임베딩을 정규화할지 여부. 기본값: `False`
+
+    **환경 변수:**
+    - `EMBEDDINGS_SENTENCE_TRANSFORMER_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_SENTENCE_TRANSFORMER_DEVICE`: `device`
+    - `EMBEDDINGS_SENTENCE_TRANSFORMER_NORMALIZE_EMBEDDINGS`: `normalize_embeddings`
+  </Accordion>
+
+  <Accordion title="ONNX">
+    ```python main.py
+    from crewai.rag.embeddings.providers.onnx.types import ONNXProviderSpec
+
+    embedding_model: ONNXProviderSpec = {
+        "provider": "onnx",
+        "config": {
+            "preferred_providers": ["CUDAExecutionProvider", "CPUExecutionProvider"]
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `preferred_providers` (list[str]): 선호도 순으로 나열한 ONNX 실행 프로바이더 목록
+
+    **환경 변수:**
+    - `EMBEDDINGS_ONNX_PREFERRED_PROVIDERS`: `preferred_providers`(쉼표로 구분된 목록)
+  </Accordion>
+
+  <Accordion title="OpenCLIP">
+    ```python main.py
+    from crewai.rag.embeddings.providers.openclip.types import OpenCLIPProviderSpec
+
+    embedding_model: OpenCLIPProviderSpec = {
+        "provider": "openclip",
+        "config": {
+            "model_name": "ViT-B-32",
+            "checkpoint": "laion2b_s34b_b79k",
+            "device": "cuda"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `model_name` (str): OpenCLIP 모델 아키텍처. 기본값: `ViT-B-32`. 옵션: `ViT-B-32`, `ViT-B-16`, `ViT-L-14`
+    - `checkpoint` (str): 사전 학습된 체크포인트 이름. 기본값: `laion2b_s34b_b79k`. 옵션: `laion2b_s34b_b79k`, `laion400m_e32`, `openai`
+    - `device` (str): 실행할 장치. 기본값: `cpu`. 옵션: `cpu`, `cuda`
+
+    **환경 변수:**
+    - `EMBEDDINGS_OPENCLIP_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_OPENCLIP_CHECKPOINT`: `checkpoint`
+    - `EMBEDDINGS_OPENCLIP_DEVICE`: `device`
+  </Accordion>
+
+  <Accordion title="Text2Vec">
+    ```python main.py
+    from crewai.rag.embeddings.providers.text2vec.types import Text2VecProviderSpec
+
+    embedding_model: Text2VecProviderSpec = {
+        "provider": "text2vec",
+        "config": {
+            "model_name": "shibing624/text2vec-base-multilingual"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `model_name` (str): HuggingFace의 Text2Vec 모델 이름. 기본값: `shibing624/text2vec-base-chinese`. 옵션: `shibing624/text2vec-base-multilingual`, `shibing624/text2vec-base-chinese`
+
+    **환경 변수:**
+    - `EMBEDDINGS_TEXT2VEC_MODEL_NAME`: `model_name`
+  </Accordion>
+
+  <Accordion title="Roboflow">
+    ```python main.py
+    from crewai.rag.embeddings.providers.roboflow.types import RoboflowProviderSpec
+
+    embedding_model: RoboflowProviderSpec = {
+        "provider": "roboflow",
+        "config": {
+            "api_key": "your-api-key",
+            "api_url": "https://infer.roboflow.com"
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `api_key` (str): Roboflow API 키. 기본값: `""`(빈 문자열)
+    - `api_url` (str): Roboflow 추론 API URL. 기본값: `https://infer.roboflow.com`
+
+    **환경 변수:**
+    - `ROBOFLOW_API_KEY` 또는 `EMBEDDINGS_ROBOFLOW_API_KEY`: `api_key`
+    - `ROBOFLOW_API_URL` 또는 `EMBEDDINGS_ROBOFLOW_API_URL`: `api_url`
+  </Accordion>
+
+  <Accordion title="WatsonX (IBM)">
+    ```python main.py
+    from crewai.rag.embeddings.providers.ibm.types import WatsonXProviderSpec
+
+    embedding_model: WatsonXProviderSpec = {
+        "provider": "watsonx",
+        "config": {
+            "model_id": "ibm/slate-125m-english-rtrvr",
+            "url": "https://us-south.ml.cloud.ibm.com",
+            "api_key": "your-api-key",
+            "project_id": "your-project-id",
+            "batch_size": 100,
+            "concurrency_limit": 10,
+            "persistent_connection": True
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `model_id` (str): WatsonX 모델 식별자
+    - `url` (str): WatsonX API 엔드포인트
+    - `api_key` (str): IBM Cloud API 키
+    - `project_id` (str): WatsonX 프로젝트 ID
+    - `space_id` (str): WatsonX 공간 ID(project_id의 대안)
+    - `batch_size` (int): 임베딩 배치 크기. 기본값: `100`
+    - `concurrency_limit` (int): 최대 동시 요청 수. 기본값: `10`
+    - `persistent_connection` (bool): 지속 연결 사용 여부. 기본값: `True`
+    - 그 외 20개 이상의 추가 인증 및 구성 옵션
+
+    **환경 변수:**
+    - `WATSONX_API_KEY` 또는 `EMBEDDINGS_WATSONX_API_KEY`: `api_key`
+    - `WATSONX_URL` 또는 `EMBEDDINGS_WATSONX_URL`: `url`
+    - `WATSONX_PROJECT_ID` 또는 `EMBEDDINGS_WATSONX_PROJECT_ID`: `project_id`
+    - `EMBEDDINGS_WATSONX_MODEL_ID`: `model_id`
+    - `EMBEDDINGS_WATSONX_SPACE_ID`: `space_id`
+    - `EMBEDDINGS_WATSONX_BATCH_SIZE`: `batch_size`
+    - `EMBEDDINGS_WATSONX_CONCURRENCY_LIMIT`: `concurrency_limit`
+    - `EMBEDDINGS_WATSONX_PERSISTENT_CONNECTION`: `persistent_connection`
+  </Accordion>
+
+  <Accordion title="사용자 지정">
+    ```python main.py
+    from crewai.rag.core.base_embeddings_callable import EmbeddingFunction
+    from crewai.rag.embeddings.providers.custom.types import CustomProviderSpec
+
+    class MyEmbeddingFunction(EmbeddingFunction):
+        def __call__(self, input):
+            # Your custom embedding logic
+            return embeddings
+
+    embedding_model: CustomProviderSpec = {
+        "provider": "custom",
+        "config": {
+            "embedding_callable": MyEmbeddingFunction
+        }
+    }
+    ```
+
+    **구성 옵션:**
+    - `embedding_callable` (type[EmbeddingFunction]): 사용자 지정 임베딩 함수 클래스
+
+    **참고:** 사용자 지정 임베딩 함수는 `crewai.rag.core.base_embeddings_callable`에 정의된 `EmbeddingFunction` 프로토콜을 구현해야 합니다. `__call__` 메서드는 입력 데이터를 받아 numpy 배열 목록(또는 정규화할 수 있는 호환 형식)으로 임베딩을 반환해야 합니다. 반환된 임베딩은 자동으로 정규화되고 검증됩니다.
+  </Accordion>
+</AccordionGroup>
+
+### 참고
+- **필수**로 표시되지 않은 모든 구성 필드는 선택 사항입니다.
+- 일반적으로 API 키는 구성 대신 환경 변수를 통해 제공할 수 있습니다.
+- 해당하는 경우 기본값이 표시됩니다.
+
 
 ## 결론
 `RagTool`은 다양한 데이터 소스에서 지식 베이스를 생성하고 질의할 수 있는 강력한 방법을 제공합니다. Retrieval-Augmented Generation을 활용하여, 에이전트가 관련 정보를 효율적으로 접근하고 검색할 수 있게 하여, 보다 정확하고 상황에 맞는 응답을 제공하는 능력을 향상시킵니다.

docs/edge/ko/tools/ai-ml/visiontool.mdx

@@ -12,6 +12,16 @@ mode: "wide"
 이 도구는 이미지에서 텍스트를 추출하는 데 사용됩니다. 에이전트에 전달되면 이미지에서 텍스트를 추출한 후 이를 사용하여 응답, 보고서 또는 기타 출력을 생성합니다.
 이미지의 URL 또는 경로(PATH)를 에이전트에 전달해야 합니다.
 
+이미지에 대한 사용자 지정 `query`를 요청하고, 요청에 가장 적합한 모델을 자동으로 선택하는 `complexity_level`을 지정할 수도 있습니다:
+
+| 복잡도 수준 | 모델         |
+| :--------------- | :------------ |
+| `easy`           | `gpt-5.6-luna`  |
+| `medium` (기본값) | `gpt-5.6-terra` |
+| `hard`           | `gpt-5.6-sol`   |
+
+도구에 명시적인 `llm` 또는 `model`을 제공하면, 복잡도 기반 모델 선택보다 우선합니다.
+
 ## 설치
 
 crewai_tools 패키지를 설치하세요
@@ -43,8 +53,10 @@ def researcher(self) -> Agent:
 
 ## 인수
 
-VisionTool은 다음과 같은 인수가 필요합니다:
+VisionTool은 다음과 같은 인수를 받습니다:
 
 | 인수                | 타입     | 설명                                                                              |
 | :------------------ | :------- | :-------------------------------------------------------------------------------- |
-| **image_path_url**  | `string` | **필수**. 텍스트를 추출해야 하는 이미지 파일의 경로입니다.                         |
+| **image_path_url**  | `string` | **필수**. 텍스트를 추출해야 하는 이미지 파일의 경로(또는 URL)입니다.               |
+| **query**           | `string` | **선택**. 이미지에 대해 모델에 묻는 질문 또는 지시입니다. 기본값은 `"What's in this image?"`입니다. |
+| **complexity_level** | `string` | **선택**. 모델을 선택하는 요청의 복잡도입니다: `easy`, `medium`, `hard`. 기본값은 `medium`입니다. |

docs/edge/ko/tools/web-scraping/oxylabsscraperstool.mdx

@@ -4,7 +4,7 @@ description: >
   Oxylabs 스크래퍼를 사용하면 해당 소스에서 정보를 쉽게 접근할 수 있습니다. 아래에서 사용 가능한 소스 목록을 확인하세요:
     - `Amazon Product`
     - `Amazon Search`
-    - `Google Seach`
+    - `Google Search`
     - `Universal`
 icon: globe
 mode: "wide"
@@ -87,7 +87,7 @@ print(result)
 ### 파라미터
 
 - `query` - Amazon 검색어.
-- `domain` - Bestbuy의 도메인 로컬라이제이션.
+- `domain` - Amazon의 도메인 로컬라이제이션.
 - `start_page` - 시작 페이지 번호.
 - `pages` - 가져올 페이지 수.
 - `geo_location` - _배송지_ 위치.

docs/edge/pt-BR/changelog.mdx

@@ -4,6 +4,96 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="09 set 2026">
+  ## v1.15.21
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.21)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar telemetria para rastrear o tempo de execução de checkpoints e o uso do CLI.
+
+  ### Correções de Bugs
+  - Corrigir erros de gateway relatados dentro de uma resposta HTTP 200.
+  - Manter o deploy push na criação de fonte AMP.
+  - Relatar falhas de raspagem em vez de levantar IndexError na integração com Oxylabs.
+  - Roteirizar todos os modelos DashScope através do provedor nativo.
+  - Persistir checkpoints JSON como UTF-8.
+  - Remover $ soltos nas URLs de busca de f-string para BrightData.
+  - Suportar arrays do tipo lista na conversão de esquema JSON.
+  - Corrigir a janela de contexto do gpt-4o-mini de 200000 para 128000.
+  - Preservar os argumentos de chamada da ferramenta de streaming em contentBlockStop.
+  - Tornar os hooks de pré-compromisso portáteis no Windows.
+
+  ### Documentação
+  - Esclarecer que o rastreamento é gerenciado separadamente da telemetria.
+  - Corrigir o link de referência de busca paralela.
+  - Remover parâmetros obsoletos da docstring de handle_llm_stream_chunk.
+  - Corrigir exemplos de docstring de saída de streaming.
+  - Usar UUIDs de organização na referência de instalação de habilidades.
+
+  ## Contribuidores
+
+  @Alphaxiaoteng, @DrewWhittleNZ, @Ghraven, @Shxiao101, @Vaishnavi220506, @Vidit-Ostwal, @danielfsbarreto, @georgeatparallel, @github-actions[bot], @jessemiller, @joaomdmoura, @kimnamu, @kiwoongyoon, @liang0417, @lorenzejay, @oxy-giedrius, @simpleqt, @uoparaji
+
+</Update>
+
+<Update label="04 set 2026">
+  ## v1.15.20
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.20)
+
+  ## O que Mudou
+
+  ### Correções de Bugs
+  - Corrigir a descoberta de alias da ferramenta da plataforma legada
+
+  ### Documentação
+  - Atualizar snapshot e changelog para v1.15.19
+
+  ## Contribuidores
+
+  @joaomdmoura, @vinibrsl
+
+</Update>
+
+<Update label="04 set 2026">
+  ## v1.15.19
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.19)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Adicionar cliente de integrações Clipper
+  - Adicionar `now()` ao ambiente de expressão CEL
+  - Registrar como uma execução de equipe terminou para cada usuário
+  - Relatar o tamanho da máquina como uma faixa grosseira, não uma contagem de núcleos
+  - Adicionar cliente injetável para ferramentas da plataforma CrewAI
+
+  ### Correções de Bugs
+  - Corrigir leitura de URLs de octet-stream e xlsx em `urlreadtool`
+  - Corrigir a adição de turno de usuário final em provedor nativo Gemini
+  - Normalizar esquema e porta na URL base do Ollama
+  - Preservar configurações de escopo reutilizáveis na memória
+  - Atualizar `pypdf` para 6.16.2 devido a vulnerabilidade de segurança
+  - Atualizar `nltk` para 3.10.3 devido a vulnerabilidade de segurança
+  - Corrigir saídas estruturadas nativas para os modelos atuais do Claude e piso CVE do Snowflake
+  - Executar ganchos de chamada de modelo em cada caminho e propagar uma negação
+
+  ### Documentação
+  - Remover `CodeInterpreterTool` dos exemplos de visão geral de IA/ML
+  - Apontar o link `prompt-template` para seu caminho atual
+  - Atualizar guia de canais para a API atual de canais do CopilotKit
+  - Atualizar IDs de modelos Gemini aposentados
+
+  ## Contribuidores
+
+  @Vidit-Ostwal, @a-yeyang, @github-actions[bot], @hvlcrs, @joaomdmoura, @kikifrost, @lorenzejay, @lucasgomide, @parthiban-sivakumar, @ranst91, @tandede, @thiagomoretto, @vinibrsl
+
+</Update>
+
 <Update label="27 ago 2026">
   ## v1.15.18
 

docs/edge/pt-BR/concepts/cli.mdx

@@ -307,6 +307,7 @@ crewai org switch <organization_id>
 
   - Inicia o processo de deployment na plataforma CrewAI AMP.
   - Após a iniciação bem-sucedida, será exibida a mensagem Deployment created successfully! juntamente com o Nome do Deployment e um Deployment ID (UUID) único.
+  - O push mantém a origem usada na criação. Adicionar um `origin` git depois não troca um deployment ZIP por git.
 
 - **Status do Deployment**: Você pode verificar o status do seu deployment com:
 

docs/edge/pt-BR/concepts/knowledge.mdx

@@ -601,6 +601,21 @@ agent = Agent(
         }
     }
 )
+
+# Option 4: Use OpenRouter embeddings (supports models across providers)
+# Set OPENROUTER_API_KEY environment variable if api_key is omitted in config
+crew = Crew(
+    agents=[agent],
+    tasks=[...],
+    knowledge_sources=[knowledge_source],
+    embedder={
+        "provider": "openrouter",
+        "config": {
+            "model_name": "openai/text-embedding-3-small",
+            "api_key": "your-openrouter-api-key"  # Optional if OPENROUTER_API_KEY is set
+        }
+    }
+)
 ```
 
 #### Configurando Embeddings do Azure OpenAI

docs/edge/pt-BR/concepts/llms.mdx

@@ -919,6 +919,38 @@ Saiba como obter o máximo da configuração do seu LLM:
     llm = LLM(model="gpt-4")
     ```
   </Tab>
+  <Tab title="Erros de Gateway">
+    <Tip>
+      Gateways como o OpenRouter retornam `200 OK` assim que o provedor upstream aceita a requisição, então um timeout do provedor chega no corpo da resposta em vez do código de status.
+    </Tip>
+
+    O CrewAI lança a mesma exceção que o código upstream produziria como um status HTTP real, portanto uma falha mascarada é capturada pelo tratamento de retry que você já possui:
+
+    ```python
+    import openai
+    from pydantic import BaseModel
+
+    from crewai import LLM
+
+
+    class Report(BaseModel):
+        summary: str
+
+
+    llm = LLM(model="openrouter/z-ai/glm-5.3", response_format=Report)
+
+    try:
+        result = llm.call("Summarize the incident", response_model=Report)
+    except openai.InternalServerError as e:
+        # "z-ai/glm-5.3 via openrouter.ai returned HTTP 200 with an upstream error
+        #  and no choices: The operation was aborted (upstream code 504)"
+        print(f"Upstream provider failed, safe to retry: {e}")
+    ```
+
+    <Warning>
+      Um `response_model` grande ou profundamente aninhado aumenta a chance de timeouts upstream. Trate esses casos como falhas transitórias do provedor, e não como o modelo produzindo saída estruturada malformada.
+    </Warning>
+  </Tab>
   <Tab title="Comprimento do Contexto">
     <Tip>
       Use modelos de contexto expandido para tarefas extensas

docs/edge/pt-BR/concepts/skills.mdx

@@ -202,13 +202,17 @@ A publicação lê `name`, `description` e `metadata.version` do frontmatter do
 
 ### Instalar
 
-Instale uma skill publicada pela sua referência `@org/name`:
+Instale uma skill publicada pela sua referência `@org-uuid/name`:
 
 ```shell Terminal
-crewai skill install @acme/code-review
+crewai skill install @your-org-uuid/code-review
 ```
 
-Dentro de um projeto de crew, a skill é colocada em `./skills/{name}/`; fora de um projeto, vai para o cache compartilhado em `~/.crewai/skills/{org}/{name}/`.
+<Note>
+  Use o **UUID** da sua organização, não o nome — nomes de organização não são únicos, então um nome pode resolver para a organização errada e a instalação falha com um erro de "não encontrado". Execute `crewai org list` para ver o UUID (a coluna `ID`) de cada organização à qual você pertence.
+</Note>
+
+Dentro de um projeto de crew, a skill é colocada em `./skills/{name}/`; fora de um projeto, vai para o cache compartilhado em `~/.crewai/skills/{org-uuid}/{name}/`.
 
 Agentes também podem referenciar skills do registro diretamente — elas são resolvidas a partir do cache local (ou do diretório `skills/` do projeto) em tempo de execução:
 
@@ -217,7 +221,7 @@ agent = Agent(
     role="Senior Code Reviewer",
     goal="Review pull requests for quality and security issues",
     backstory="Staff engineer with expertise in secure coding practices.",
-    skills=["@acme/code-review"],  # registry ref, resolved locally
+    skills=["@your-org-uuid/code-review"],  # registry ref, resolved locally
 )
 ```
 

docs/edge/pt-BR/observability/tracing.mdx

@@ -9,7 +9,7 @@ mode: "wide"
 
 O CrewAI fornece recursos de rastreamento integrados que permitem monitorar e depurar seus Crews e Flows em tempo real. Este guia demonstra como habilitar o rastreamento para **Crews** e **Flows** usando a plataforma de observabilidade integrada do CrewAI.
 
-> **O que é o CrewAI Tracing?** O rastreamento integrado do CrewAI fornece observabilidade abrangente para seus agentes de IA, incluindo decisões de agentes, cronogramas de execução de tarefas, uso de ferramentas e chamadas de LLM - tudo acessível através da [plataforma CrewAI AMP](https://app.crewai.com).
+> **O que é o CrewAI Tracing?** O rastreamento integrado do CrewAI fornece observabilidade abrangente para seus agentes de IA, incluindo decisões de agentes, cronogramas de execução de tarefas, uso de ferramentas e chamadas de LLM - tudo acessível através da [plataforma CrewAI AMP](https://app.crewai.com). O rastreamento é gerenciado de forma independente da [telemetria](/pt-BR/telemetry).
 
 ![CrewAI Tracing Interface](/images/crewai-tracing.png)
 
@@ -170,6 +170,18 @@ CREWAI_TRACING_ENABLED=true
 
 Quando esta variável de ambiente estiver definida, todos os Crews e Flows terão automaticamente o rastreamento habilitado, mesmo sem definir explicitamente `tracing=True`.
 
+## Visualizando rastreamentos após a primeira execução
+
+Na primeira vez que você executa um Crew ou Flow, um terminal interativo pode perguntar:
+
+```text
+Would you like to view your execution traces? [y/N]
+```
+
+Escolha **yes** para abrir um link de visualização. Você pode alterar isso depois com
+`crewai traces enable` ou `crewai traces disable`, ou definindo `tracing`
+no Crew ou Flow.
+
 ## Visualizando seus Rastreamentos
 
 ### Acesse o Painel CrewAI AMP

docs/edge/pt-BR/telemetry.mdx

@@ -24,6 +24,7 @@ Quando o recurso `share_crew` está ativado, dados detalhados, incluindo descri
 para fornecer insights mais detalhados. Essa coleta expandida pode incluir informações pessoais caso o usuário as tenha inserido em seus crews ou tarefas.
 Usuários devem considerar cuidadosamente o conteúdo de seus crews e tarefas antes de habilitar o `share_crew`.
 A telemetria do CrewAI pode ser desabilitada ao definir `CREWAI_DISABLE_TELEMETRY` como `true`, `1`, `yes` ou `on` (qualquer capitalização). `OTEL_SDK_DISABLED` com os mesmos valores também desabilita o exportador do CrewAI. O SDK do OpenTelemetry em si ainda só reconhece `true` para desabilitar as demais instrumentações do processo.
+O rastreamento AMP é tratado em [Tracing](/pt-BR/observability/tracing).
 
 ### Exemplos:
 ```python
@@ -62,7 +63,7 @@ por meio do próprio tracer provider, que é independente do descrito aqui.
 | Sim    | Dados do Ciclo de Vida da Tarefa           | Inclui: horários de criação, início/fim de execução, identificadores de crew e tarefa, e se a tarefa foi bem-sucedida ou falhou. Quando uma tarefa falha, o **nome da classe** da exceção é registrado (por exemplo `TimeoutError`) para que as falhas possam ser contadas e diagnosticadas — nunca a mensagem de erro, que pode conter prompts, saída do modelo, caminhos de arquivos ou credenciais. Armazenado como spans com timestamps. Sem dados pessoais.            |
 | Sim    | Atributos do LLM                           | Inclui: nome, model_name, model, top_k, temperatura e nome da classe do LLM. Todos técnicos, sem dados pessoais.                  |
 | Sim    | Criação de Projeto pelo CLI do crewAI | Inclui: o fato de um novo projeto ter sido criado por `crewai create`, de qual tipo ele é (`crew`, `json_crew` ou `flow`) e o ID de projeto gerado para esse novo projeto e gravado no `pyproject.toml` dele. É o ID do próprio projeto novo, registrado separadamente do `project_id` do diretório de onde o comando foi executado — os dois podem diferir. Sem nome de projeto, sem conteúdo de arquivos, sem código. Sem dados pessoais. |
-| Sim    | Tentativa de Deploy do Crew pelo CLI do crewAI | Inclui: O fato de um deploy estar sendo realizado e o crew id, se está tentando buscar logs, e se o deploy foi iniciado por um comando do CLI ou pela TUI de execução. Não inclui conteúdo do projeto ou do crew nem dados pessoais. |
+| Sim    | Tentativa de Deploy do Crew pelo CLI do crewAI | Inclui: O fato de um deploy estar sendo realizado e o crew id, se está tentando buscar logs, e se o deploy foi iniciado por um comando do CLI ou pela TUI de execução. Se a criação de um deploy falhar, são registradas a categoria da falha (uma de uma lista fixa, como `api_4xx`, `network_error` ou `user_declined`) e o código de status HTTP da resposta da API, quando houver — nunca a mensagem de erro. Não inclui conteúdo do projeto ou do crew nem dados pessoais. |
 | Sim    | Ambiente de Execução                       | Inclui: qual assistente de código com IA está executando o processo, se houver (um valor de uma lista fixa como `claude_code`, `codex`, `cursor` ou `unknown`), onde o processo é executado (um valor de uma lista fixa como `ci`, `container`, `serverless`, `interactive`), o `project_id` do seu `pyproject.toml` quando houver um configurado e uma faixa aproximada de tamanho da máquina (uma de `1-2`, `3-4`, `5-8`, `9-16`, `17-32`, `33+` ou `unknown`). A faixa é um intervalo, nunca a contagem exata de núcleos — a contagem exata é opcional, em Informações de Ambiente abaixo. A faixa de tamanho vem da contagem de núcleos do host; a detecção do assistente e do local de execução lê apenas se variáveis de ambiente conhecidas estão definidas, nunca seus valores. Sem dados pessoais. |
 | Sim    | Sinais de Ciclo de Vida do Flow | Inclui: que um flow iniciou, se foi concluído ou falhou, se um de seus métodos falhou, se pausou para entrada ou feedback humano, se o início foi uma execução retomada, se um turno de conversa falhou, quanto tempo o flow executou, e se o flow é um que a CrewAI executa internamente ou um que você escreveu. O nome do flow é registrado, como já é para criação e execução de flow. Quando um flow ou um de seus métodos falha, o **nome da classe** da exceção é registrado (por exemplo `TimeoutError`) para permitir o diagnóstico de falhas — nunca a mensagem de erro, que pode conter prompts, saída do modelo, caminhos de arquivo ou credenciais. Nomes de métodos e estado do flow nunca são registrados. Nenhum dado pessoal. |
 | Sim    | Sinal de Compartilhamento de Trace | Inclui: que um lote de traces foi compartilhado com sucesso com o CrewAI AMP, e se foi compartilhado anonimamente (antes de você ter uma conta) ou vinculado à sua conta. Como todo span, também carrega os atributos de Ambiente de Execução descritos acima (`project_id` quando configurado, o assistente de programação e o runtime). Esta linha descreve apenas a telemetria do compartilhamento — não o conteúdo dos traces nem o acesso concedido por links de traces compartilhados. O conteúdo dos traces, entradas e saídas nunca são registrados neste sinal. Antes de compartilhar traces, revise segredos, dados pessoais e as configurações de redação e retenção do AMP. |

docs/edge/pt-BR/tools/ai-ml/ragtool.mdx

@@ -9,7 +9,7 @@ mode: "wide"
 
 ## Descrição
 
-O `RagTool` foi desenvolvido para responder perguntas aproveitando o poder da Geração Aumentada por Recuperação (RAG) através do EmbedChain.
+O `RagTool` foi desenvolvido para responder perguntas aproveitando o poder da Geração Aumentada por Recuperação (RAG) por meio do sistema RAG nativo da CrewAI.
 Ele fornece uma base de conhecimento dinâmica que pode ser consultada para recuperar informações relevantes de várias fontes de dados.
 Esta ferramenta é particularmente útil para aplicações que exigem acesso a uma ampla variedade de informações e precisam fornecer respostas contextualmente relevantes.
 
@@ -76,8 +76,8 @@ O `RagTool` pode ser utilizado com uma grande variedade de fontes de dados, incl
 O `RagTool` aceita os seguintes parâmetros:
 
 - **summarize**: Opcional. Indica se o conteúdo recuperado deve ser resumido. O padrão é `False`.
-- **adapter**: Opcional. Um adaptador personalizado para a base de conhecimento. Se não for fornecido, será utilizado o EmbedchainAdapter.
-- **config**: Opcional. Configuração para o aplicativo EmbedChain subjacente.
+- **adapter**: Opcional. Um adaptador personalizado para a base de conhecimento. Se não for fornecido, será utilizado o CrewAIRagAdapter.
+- **config**: Opcional. Configuração do sistema RAG subjacente da CrewAI. Aceita um TypedDict `RagToolConfig` com as chaves opcionais `embedding_model` (ProviderSpec) e `vectordb` (VectorDbConfig). Todos os valores de configuração fornecidos programaticamente têm precedência sobre as variáveis de ambiente.
 
 ## Adicionando Conteúdo
 
@@ -127,47 +127,528 @@ def knowledge_expert(self) -> Agent:
 
 ```python Code
 from crewai_tools import RagTool
+from crewai_tools.tools.rag import RagToolConfig, VectorDbConfig, ProviderSpec
 
 # Create a RAG tool with custom configuration
-config = {
-    "app": {
-        "name": "custom_app",
-    },
-    "llm": {
-        "provider": "openai",
-        "config": {
-            "model": "gpt-4",
-        }
-    },
-    "embedding_model": {
-        "provider": "openai",
-        "config": {
-            "model": "text-embedding-ada-002"
-        }
-    },
-    "vectordb": {
-        "provider": "elasticsearch",
-        "config": {
-            "collection_name": "my-collection",
-            "cloud_id": "deployment-name:xxxx",
-            "api_key": "your-key",
-            "verify_certs": False
-        }
-    },
-    "chunker": {
-        "chunk_size": 400,
-        "chunk_overlap": 100,
-        "length_function": "len",
-        "min_chunk_size": 0
+
+vectordb: VectorDbConfig = {
+    "provider": "qdrant",
+    "config": {
+        "collection_name": "my-collection"
     }
 }
 
+embedding_model: ProviderSpec = {
+    "provider": "openai",
+    "config": {
+        "model_name": "text-embedding-3-small"
+    }
+}
+
+config: RagToolConfig = {
+    "vectordb": vectordb,
+    "embedding_model": embedding_model
+}
+
 rag_tool = RagTool(config=config, summarize=True)
 ```
 
-A ferramenta RAG interna utiliza o adaptador Embedchain, possibilitando que você forneça quaisquer opções de configuração suportadas pelo Embedchain.
-Você pode consultar a [documentação do Embedchain](https://docs.embedchain.ai/components/introduction) para mais detalhes.
-Certifique-se de revisar as opções de configuração disponíveis no arquivo .yaml.
+## Configuração do Modelo de Embedding
+
+O parâmetro `embedding_model` aceita um dicionário `crewai.rag.embeddings.types.ProviderSpec` com a seguinte estrutura:
+
+```python
+{
+    "provider": "provider-name",  # Required
+    "config": {                    # Optional
+        # Provider-specific configuration
+    }
+}
+```
+
+### Provedores Suportados
+
+<AccordionGroup>
+  <Accordion title="OpenAI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.openai.types import OpenAIProviderSpec
+
+    embedding_model: OpenAIProviderSpec = {
+        "provider": "openai",
+        "config": {
+            "api_key": "your-api-key",
+            "model_name": "text-embedding-ada-002",
+            "dimensions": 1536,
+            "organization_id": "your-org-id",
+            "api_base": "https://api.openai.com/v1",
+            "api_version": "v1",
+            "default_headers": {"Custom-Header": "value"}
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `api_key` (str): Chave da API OpenAI
+    - `model_name` (str): Modelo a ser utilizado. Padrão: `text-embedding-ada-002`. Opções: `text-embedding-3-small`, `text-embedding-3-large`, `text-embedding-ada-002`
+    - `dimensions` (int): Número de dimensões do embedding
+    - `organization_id` (str): ID da organização OpenAI
+    - `api_base` (str): URL base personalizada da API
+    - `api_version` (str): Versão da API
+    - `default_headers` (dict): Cabeçalhos personalizados para solicitações à API
+
+    **Variáveis de Ambiente:**
+    - `OPENAI_API_KEY` ou `EMBEDDINGS_OPENAI_API_KEY`: `api_key`
+    - `OPENAI_ORGANIZATION_ID` ou `EMBEDDINGS_OPENAI_ORGANIZATION_ID`: `organization_id`
+    - `OPENAI_MODEL_NAME` ou `EMBEDDINGS_OPENAI_MODEL_NAME`: `model_name`
+    - `OPENAI_API_BASE` ou `EMBEDDINGS_OPENAI_API_BASE`: `api_base`
+    - `OPENAI_API_VERSION` ou `EMBEDDINGS_OPENAI_API_VERSION`: `api_version`
+    - `OPENAI_DIMENSIONS` ou `EMBEDDINGS_OPENAI_DIMENSIONS`: `dimensions`
+  </Accordion>
+
+  <Accordion title="Cohere">
+    ```python main.py
+    from crewai.rag.embeddings.providers.cohere.types import CohereProviderSpec
+
+    embedding_model: CohereProviderSpec = {
+        "provider": "cohere",
+        "config": {
+            "api_key": "your-api-key",
+            "model_name": "embed-english-v3.0"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `api_key` (str): Chave da API Cohere
+    - `model_name` (str): Modelo a ser utilizado. Padrão: `large`. Opções: `embed-english-v3.0`, `embed-multilingual-v3.0`, `large`, `small`
+
+    **Variáveis de Ambiente:**
+    - `COHERE_API_KEY` ou `EMBEDDINGS_COHERE_API_KEY`: `api_key`
+    - `EMBEDDINGS_COHERE_MODEL_NAME`: `model_name`
+  </Accordion>
+
+  <Accordion title="VoyageAI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.voyageai.types import VoyageAIProviderSpec
+
+    embedding_model: VoyageAIProviderSpec = {
+        "provider": "voyageai",
+        "config": {
+            "api_key": "your-api-key",
+            "model": "voyage-3",
+            "input_type": "document",
+            "truncation": True,
+            "output_dtype": "float32",
+            "output_dimension": 1024,
+            "max_retries": 3,
+            "timeout": 60.0
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `api_key` (str): Chave da API VoyageAI
+    - `model` (str): Modelo a ser utilizado. Padrão: `voyage-2`. Opções: `voyage-3`, `voyage-3-lite`, `voyage-code-3`, `voyage-large-2`
+    - `input_type` (str): Tipo de entrada. Opções: `document` (para armazenamento), `query` (para pesquisa)
+    - `truncation` (bool): Indica se entradas que excedem o comprimento máximo devem ser truncadas. Padrão: `True`
+    - `output_dtype` (str): Tipo de dados da saída
+    - `output_dimension` (int): Dimensão dos embeddings de saída
+    - `max_retries` (int): Número máximo de tentativas. Padrão: `0`
+    - `timeout` (float): Tempo limite da solicitação em segundos
+
+    **Variáveis de Ambiente:**
+    - `VOYAGEAI_API_KEY` ou `EMBEDDINGS_VOYAGEAI_API_KEY`: `api_key`
+    - `VOYAGEAI_MODEL` ou `EMBEDDINGS_VOYAGEAI_MODEL`: `model`
+    - `VOYAGEAI_INPUT_TYPE` ou `EMBEDDINGS_VOYAGEAI_INPUT_TYPE`: `input_type`
+    - `VOYAGEAI_TRUNCATION` ou `EMBEDDINGS_VOYAGEAI_TRUNCATION`: `truncation`
+    - `VOYAGEAI_OUTPUT_DTYPE` ou `EMBEDDINGS_VOYAGEAI_OUTPUT_DTYPE`: `output_dtype`
+    - `VOYAGEAI_OUTPUT_DIMENSION` ou `EMBEDDINGS_VOYAGEAI_OUTPUT_DIMENSION`: `output_dimension`
+    - `VOYAGEAI_MAX_RETRIES` ou `EMBEDDINGS_VOYAGEAI_MAX_RETRIES`: `max_retries`
+    - `VOYAGEAI_TIMEOUT` ou `EMBEDDINGS_VOYAGEAI_TIMEOUT`: `timeout`
+  </Accordion>
+
+  <Accordion title="Ollama">
+    ```python main.py
+    from crewai.rag.embeddings.providers.ollama.types import OllamaProviderSpec
+
+    embedding_model: OllamaProviderSpec = {
+        "provider": "ollama",
+        "config": {
+            "model_name": "llama2",
+            "url": "http://localhost:11434/api/embeddings"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `model_name` (str): Nome do modelo Ollama (por exemplo, `llama2`, `mistral`, `nomic-embed-text`)
+    - `url` (str): URL do endpoint da API Ollama. Padrão: `http://localhost:11434/api/embeddings`
+
+    **Variáveis de Ambiente:**
+    - `OLLAMA_MODEL` ou `EMBEDDINGS_OLLAMA_MODEL`: `model_name`
+    - `OLLAMA_URL` ou `EMBEDDINGS_OLLAMA_URL`: `url`
+  </Accordion>
+
+  <Accordion title="Amazon Bedrock">
+    ```python main.py
+    from crewai.rag.embeddings.providers.aws.types import BedrockProviderSpec
+
+    embedding_model: BedrockProviderSpec = {
+        "provider": "amazon-bedrock",
+        "config": {
+            "model_name": "amazon.titan-embed-text-v2:0",
+            "session": boto3_session
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `model_name` (str): ID do modelo Bedrock. Padrão: `amazon.titan-embed-text-v1`. Opções: `amazon.titan-embed-text-v1`, `amazon.titan-embed-text-v2:0`, `cohere.embed-english-v3`, `cohere.embed-multilingual-v3`
+    - `session` (Any): Objeto de sessão Boto3 para autenticação da AWS
+
+    **Variáveis de Ambiente:**
+    - `AWS_ACCESS_KEY_ID`: Chave de acesso da AWS
+    - `AWS_SECRET_ACCESS_KEY`: Chave secreta da AWS
+    - `AWS_REGION`: Região da AWS (por exemplo, `us-east-1`)
+  </Accordion>
+
+  <Accordion title="Azure OpenAI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.microsoft.types import AzureProviderSpec
+
+    embedding_model: AzureProviderSpec = {
+        "provider": "azure",
+        "config": {
+            "deployment_id": "your-deployment-id",
+            "api_key": "your-api-key",
+            "api_base": "https://your-resource.openai.azure.com",
+            "api_version": "2024-02-01",
+            "model_name": "text-embedding-ada-002",
+            "api_type": "azure"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `deployment_id` (str): **Obrigatório** - ID de implantação do Azure OpenAI
+    - `api_key` (str): Chave da API Azure OpenAI
+    - `api_base` (str): Endpoint do recurso Azure OpenAI
+    - `api_version` (str): Versão da API. Exemplo: `2024-02-01`
+    - `model_name` (str): Nome do modelo. Padrão: `text-embedding-ada-002`
+    - `api_type` (str): Tipo de API. Padrão: `azure`
+    - `dimensions` (int): Dimensões da saída
+    - `default_headers` (dict): Cabeçalhos personalizados
+
+    **Variáveis de Ambiente:**
+    - `AZURE_OPENAI_API_KEY` ou `EMBEDDINGS_AZURE_API_KEY`: `api_key`
+    - `AZURE_OPENAI_ENDPOINT` ou `EMBEDDINGS_AZURE_API_BASE`: `api_base`
+    - `EMBEDDINGS_AZURE_DEPLOYMENT_ID`: `deployment_id`
+    - `EMBEDDINGS_AZURE_API_VERSION`: `api_version`
+    - `EMBEDDINGS_AZURE_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_AZURE_API_TYPE`: `api_type`
+    - `EMBEDDINGS_AZURE_DIMENSIONS`: `dimensions`
+  </Accordion>
+
+  <Accordion title="Google Generative AI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.google.types import GenerativeAiProviderSpec
+
+    embedding_model: GenerativeAiProviderSpec = {
+        "provider": "google-generativeai",
+        "config": {
+            "api_key": "your-api-key",
+            "model_name": "gemini-embedding-001",
+            "task_type": "RETRIEVAL_DOCUMENT"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `api_key` (str): Chave da API Google AI
+    - `model_name` (str): Nome do modelo. Padrão: `gemini-embedding-001`. Opções: `gemini-embedding-001`, `text-embedding-005`, `text-multilingual-embedding-002`
+    - `task_type` (str): Tipo de tarefa para embeddings. Padrão: `RETRIEVAL_DOCUMENT`. Opções: `RETRIEVAL_DOCUMENT`, `RETRIEVAL_QUERY`
+
+    **Variáveis de Ambiente:**
+    - `GOOGLE_API_KEY`, `GEMINI_API_KEY` ou `EMBEDDINGS_GOOGLE_API_KEY`: `api_key`
+    - `EMBEDDINGS_GOOGLE_GENERATIVE_AI_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_GOOGLE_GENERATIVE_AI_TASK_TYPE`: `task_type`
+  </Accordion>
+
+  <Accordion title="Google Vertex AI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.google.types import VertexAIProviderSpec
+
+    embedding_model: VertexAIProviderSpec = {
+        "provider": "google-vertex",
+        "config": {
+            "model_name": "text-embedding-004",
+            "project_id": "your-project-id",
+            "region": "us-central1",
+            "api_key": "your-api-key"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `model_name` (str): Nome do modelo. Padrão: `textembedding-gecko`. Opções: `text-embedding-004`, `textembedding-gecko`, `textembedding-gecko-multilingual`
+    - `project_id` (str): ID do projeto Google Cloud. Padrão: `cloud-large-language-models`
+    - `region` (str): Região do Google Cloud. Padrão: `us-central1`
+    - `api_key` (str): Chave de API para autenticação
+
+    **Variáveis de Ambiente:**
+    - `GOOGLE_APPLICATION_CREDENTIALS`: Caminho para o arquivo JSON da conta de serviço
+    - `GOOGLE_CLOUD_PROJECT` ou `EMBEDDINGS_GOOGLE_VERTEX_PROJECT_ID`: `project_id`
+    - `EMBEDDINGS_GOOGLE_VERTEX_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_GOOGLE_VERTEX_REGION`: `region`
+    - `EMBEDDINGS_GOOGLE_VERTEX_API_KEY`: `api_key`
+  </Accordion>
+
+  <Accordion title="Jina AI">
+    ```python main.py
+    from crewai.rag.embeddings.providers.jina.types import JinaProviderSpec
+
+    embedding_model: JinaProviderSpec = {
+        "provider": "jina",
+        "config": {
+            "api_key": "your-api-key",
+            "model_name": "jina-embeddings-v3"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `api_key` (str): Chave da API Jina AI
+    - `model_name` (str): Nome do modelo. Padrão: `jina-embeddings-v2-base-en`. Opções: `jina-embeddings-v3`, `jina-embeddings-v2-base-en`, `jina-embeddings-v2-small-en`
+
+    **Variáveis de Ambiente:**
+    - `JINA_API_KEY` ou `EMBEDDINGS_JINA_API_KEY`: `api_key`
+    - `EMBEDDINGS_JINA_MODEL_NAME`: `model_name`
+  </Accordion>
+
+  <Accordion title="HuggingFace">
+    ```python main.py
+    from crewai.rag.embeddings.providers.huggingface.types import HuggingFaceProviderSpec
+
+    embedding_model: HuggingFaceProviderSpec = {
+        "provider": "huggingface",
+        "config": {
+            "url": "https://api-inference.huggingface.co/models/sentence-transformers/all-MiniLM-L6-v2"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `url` (str): URL completa do endpoint da API de inferência do HuggingFace
+
+    **Variáveis de Ambiente:**
+    - `HUGGINGFACE_URL` ou `EMBEDDINGS_HUGGINGFACE_URL`: `url`
+  </Accordion>
+
+  <Accordion title="Instructor">
+    ```python main.py
+    from crewai.rag.embeddings.providers.instructor.types import InstructorProviderSpec
+
+    embedding_model: InstructorProviderSpec = {
+        "provider": "instructor",
+        "config": {
+            "model_name": "hkunlp/instructor-xl",
+            "device": "cuda",
+            "instruction": "Represent the document"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `model_name` (str): ID do modelo HuggingFace. Padrão: `hkunlp/instructor-base`. Opções: `hkunlp/instructor-xl`, `hkunlp/instructor-large`, `hkunlp/instructor-base`
+    - `device` (str): Dispositivo no qual executar. Padrão: `cpu`. Opções: `cpu`, `cuda`, `mps`, `xpu`
+    - `instruction` (str): Prefixo de instrução para embeddings
+
+    **Variáveis de Ambiente:**
+    - `EMBEDDINGS_INSTRUCTOR_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_INSTRUCTOR_DEVICE`: `device`
+    - `EMBEDDINGS_INSTRUCTOR_INSTRUCTION`: `instruction`
+  </Accordion>
+
+  <Accordion title="Sentence Transformer">
+    ```python main.py
+    from crewai.rag.embeddings.providers.sentence_transformer.types import SentenceTransformerProviderSpec
+
+    embedding_model: SentenceTransformerProviderSpec = {
+        "provider": "sentence-transformer",
+        "config": {
+            "model_name": "all-mpnet-base-v2",
+            "device": "cuda",
+            "normalize_embeddings": True
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `model_name` (str): Nome do modelo Sentence Transformers. Padrão: `all-MiniLM-L6-v2`. Opções: `all-mpnet-base-v2`, `all-MiniLM-L6-v2`, `paraphrase-multilingual-MiniLM-L12-v2`
+    - `device` (str): Dispositivo no qual executar. Padrão: `cpu`. Opções: `cpu`, `cuda`, `mps`, `xpu`
+    - `normalize_embeddings` (bool): Indica se os embeddings devem ser normalizados. Padrão: `False`
+
+    **Variáveis de Ambiente:**
+    - `EMBEDDINGS_SENTENCE_TRANSFORMER_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_SENTENCE_TRANSFORMER_DEVICE`: `device`
+    - `EMBEDDINGS_SENTENCE_TRANSFORMER_NORMALIZE_EMBEDDINGS`: `normalize_embeddings`
+  </Accordion>
+
+  <Accordion title="ONNX">
+    ```python main.py
+    from crewai.rag.embeddings.providers.onnx.types import ONNXProviderSpec
+
+    embedding_model: ONNXProviderSpec = {
+        "provider": "onnx",
+        "config": {
+            "preferred_providers": ["CUDAExecutionProvider", "CPUExecutionProvider"]
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `preferred_providers` (list[str]): Lista de provedores de execução ONNX em ordem de preferência
+
+    **Variáveis de Ambiente:**
+    - `EMBEDDINGS_ONNX_PREFERRED_PROVIDERS`: `preferred_providers` (lista separada por vírgulas)
+  </Accordion>
+
+  <Accordion title="OpenCLIP">
+    ```python main.py
+    from crewai.rag.embeddings.providers.openclip.types import OpenCLIPProviderSpec
+
+    embedding_model: OpenCLIPProviderSpec = {
+        "provider": "openclip",
+        "config": {
+            "model_name": "ViT-B-32",
+            "checkpoint": "laion2b_s34b_b79k",
+            "device": "cuda"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `model_name` (str): Arquitetura do modelo OpenCLIP. Padrão: `ViT-B-32`. Opções: `ViT-B-32`, `ViT-B-16`, `ViT-L-14`
+    - `checkpoint` (str): Nome do checkpoint pré-treinado. Padrão: `laion2b_s34b_b79k`. Opções: `laion2b_s34b_b79k`, `laion400m_e32`, `openai`
+    - `device` (str): Dispositivo no qual executar. Padrão: `cpu`. Opções: `cpu`, `cuda`
+
+    **Variáveis de Ambiente:**
+    - `EMBEDDINGS_OPENCLIP_MODEL_NAME`: `model_name`
+    - `EMBEDDINGS_OPENCLIP_CHECKPOINT`: `checkpoint`
+    - `EMBEDDINGS_OPENCLIP_DEVICE`: `device`
+  </Accordion>
+
+  <Accordion title="Text2Vec">
+    ```python main.py
+    from crewai.rag.embeddings.providers.text2vec.types import Text2VecProviderSpec
+
+    embedding_model: Text2VecProviderSpec = {
+        "provider": "text2vec",
+        "config": {
+            "model_name": "shibing624/text2vec-base-multilingual"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `model_name` (str): Nome do modelo Text2Vec do HuggingFace. Padrão: `shibing624/text2vec-base-chinese`. Opções: `shibing624/text2vec-base-multilingual`, `shibing624/text2vec-base-chinese`
+
+    **Variáveis de Ambiente:**
+    - `EMBEDDINGS_TEXT2VEC_MODEL_NAME`: `model_name`
+  </Accordion>
+
+  <Accordion title="Roboflow">
+    ```python main.py
+    from crewai.rag.embeddings.providers.roboflow.types import RoboflowProviderSpec
+
+    embedding_model: RoboflowProviderSpec = {
+        "provider": "roboflow",
+        "config": {
+            "api_key": "your-api-key",
+            "api_url": "https://infer.roboflow.com"
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `api_key` (str): Chave da API Roboflow. Padrão: `""` (string vazia)
+    - `api_url` (str): URL da API de inferência do Roboflow. Padrão: `https://infer.roboflow.com`
+
+    **Variáveis de Ambiente:**
+    - `ROBOFLOW_API_KEY` ou `EMBEDDINGS_ROBOFLOW_API_KEY`: `api_key`
+    - `ROBOFLOW_API_URL` ou `EMBEDDINGS_ROBOFLOW_API_URL`: `api_url`
+  </Accordion>
+
+  <Accordion title="WatsonX (IBM)">
+    ```python main.py
+    from crewai.rag.embeddings.providers.ibm.types import WatsonXProviderSpec
+
+    embedding_model: WatsonXProviderSpec = {
+        "provider": "watsonx",
+        "config": {
+            "model_id": "ibm/slate-125m-english-rtrvr",
+            "url": "https://us-south.ml.cloud.ibm.com",
+            "api_key": "your-api-key",
+            "project_id": "your-project-id",
+            "batch_size": 100,
+            "concurrency_limit": 10,
+            "persistent_connection": True
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `model_id` (str): Identificador do modelo WatsonX
+    - `url` (str): Endpoint da API WatsonX
+    - `api_key` (str): Chave da API IBM Cloud
+    - `project_id` (str): ID do projeto WatsonX
+    - `space_id` (str): ID do espaço WatsonX (alternativa ao project_id)
+    - `batch_size` (int): Tamanho do lote para embeddings. Padrão: `100`
+    - `concurrency_limit` (int): Número máximo de solicitações simultâneas. Padrão: `10`
+    - `persistent_connection` (bool): Utilizar conexões persistentes. Padrão: `True`
+    - Mais de 20 opções adicionais de autenticação e configuração
+
+    **Variáveis de Ambiente:**
+    - `WATSONX_API_KEY` ou `EMBEDDINGS_WATSONX_API_KEY`: `api_key`
+    - `WATSONX_URL` ou `EMBEDDINGS_WATSONX_URL`: `url`
+    - `WATSONX_PROJECT_ID` ou `EMBEDDINGS_WATSONX_PROJECT_ID`: `project_id`
+    - `EMBEDDINGS_WATSONX_MODEL_ID`: `model_id`
+    - `EMBEDDINGS_WATSONX_SPACE_ID`: `space_id`
+    - `EMBEDDINGS_WATSONX_BATCH_SIZE`: `batch_size`
+    - `EMBEDDINGS_WATSONX_CONCURRENCY_LIMIT`: `concurrency_limit`
+    - `EMBEDDINGS_WATSONX_PERSISTENT_CONNECTION`: `persistent_connection`
+  </Accordion>
+
+  <Accordion title="Personalizado">
+    ```python main.py
+    from crewai.rag.core.base_embeddings_callable import EmbeddingFunction
+    from crewai.rag.embeddings.providers.custom.types import CustomProviderSpec
+
+    class MyEmbeddingFunction(EmbeddingFunction):
+        def __call__(self, input):
+            # Your custom embedding logic
+            return embeddings
+
+    embedding_model: CustomProviderSpec = {
+        "provider": "custom",
+        "config": {
+            "embedding_callable": MyEmbeddingFunction
+        }
+    }
+    ```
+
+    **Opções de Configuração:**
+    - `embedding_callable` (type[EmbeddingFunction]): Classe da função de embedding personalizada
+
+    **Observação:** As funções de embedding personalizadas devem implementar o protocolo `EmbeddingFunction` definido em `crewai.rag.core.base_embeddings_callable`. O método `__call__` deve aceitar dados de entrada e retornar embeddings como uma lista de arrays numpy (ou um formato compatível que será normalizado). Os embeddings retornados são normalizados e validados automaticamente.
+  </Accordion>
+</AccordionGroup>
+
+### Observações
+- Todos os campos de configuração são opcionais, a menos que estejam marcados como **Obrigatório**
+- Normalmente, as chaves de API podem ser fornecidas por meio de variáveis de ambiente em vez da configuração
+- Os valores padrão são exibidos quando aplicável
+
 
 ## Conclusão
-O `RagTool` oferece uma maneira poderosa de criar e consultar bases de conhecimento a partir de diversas fontes de dados. Ao explorar a Geração Aumentada por Recuperação, ele permite que agentes acessem e recuperem informações relevantes de forma eficiente, ampliando a capacidade de fornecer respostas precisas e contextualmente apropriadas.
+O `RagTool` oferece uma maneira poderosa de criar e consultar bases de conhecimento a partir de diversas fontes de dados. Ao explorar a Geração Aumentada por Recuperação, ele permite que agentes acessem e recuperem informações relevantes de forma eficiente, ampliando a capacidade de fornecer respostas precisas e contextualmente apropriadas.

docs/edge/pt-BR/tools/ai-ml/visiontool.mdx

@@ -12,6 +12,16 @@ mode: "wide"
 Esta ferramenta é utilizada para extrair texto de imagens. Quando passada para o agente, ela extrai o texto da imagem e depois o utiliza para gerar uma resposta, relatório ou qualquer outra saída.
 A URL ou o CAMINHO da imagem deve ser passado para o Agente.
 
+Você também pode fazer uma `query` personalizada sobre a imagem e escolher um `complexity_level` que seleciona automaticamente o modelo mais adequado para a solicitação:
+
+| Nível de complexidade | Modelo         |
+| :--------------- | :------------ |
+| `easy`           | `gpt-5.6-luna`  |
+| `medium` (padrão) | `gpt-5.6-terra` |
+| `hard`           | `gpt-5.6-sol`   |
+
+Quando um `llm` ou `model` explícito é fornecido à ferramenta, ele tem precedência sobre a seleção de modelo baseada na complexidade.
+
 ## Instalação
 
 Instale o pacote crewai_tools
@@ -43,8 +53,10 @@ def researcher(self) -> Agent:
 
 ## Argumentos
 
-O VisionTool requer os seguintes argumentos:
+O VisionTool aceita os seguintes argumentos:
 
 | Argumento           | Tipo     | Descrição                                                                        |
 | :------------------ | :------- | :------------------------------------------------------------------------------- |
-| **image_path_url**  | `string` | **Obrigatório**. O caminho para o arquivo de imagem do qual o texto será extraído. |
+| **image_path_url**  | `string` | **Obrigatório**. O caminho para o arquivo de imagem (ou URL) do qual o texto será extraído. |
+| **query**           | `string` | **Opcional**. A pergunta ou instrução a ser feita ao modelo sobre a imagem. O padrão é `"What's in this image?"`. |
+| **complexity_level** | `string` | **Opcional**. A complexidade da solicitação, que seleciona o modelo: `easy`, `medium` ou `hard`. O padrão é `medium`. |

docs/edge/pt-BR/tools/web-scraping/oxylabsscraperstool.mdx

@@ -4,7 +4,7 @@ description: >
   Os Scrapers da Oxylabs permitem acessar facilmente informações de fontes específicas. Veja abaixo a lista de fontes disponíveis:
     - `Amazon Product`
     - `Amazon Search`
-    - `Google Seach`
+    - `Google Search`
     - `Universal`
 icon: globe
 mode: "wide"
@@ -87,7 +87,7 @@ print(result)
 ### Parâmetros
 
 - `query` - termo de busca da Amazon.
-- `domain` - Domínio de localização para Bestbuy.
+- `domain` - domínio de localização da Amazon.
 - `start_page` - número da página inicial.
 - `pages` - quantidade de páginas a ser recuperada.
 - `geo_location` - local de entrega (_Deliver to_).

docs/v1.15.19/ar/api-reference/inputs.mdx

@@ -0,0 +1,8 @@
+---
+title: "GET /inputs"
+description: "الحصول على المدخلات المطلوبة لطاقمك"
+openapi: "/v1.15.19/enterprise-api.en.yaml GET /inputs"
+mode: "wide"
+---
+
+

docs/v1.15.19/ar/api-reference/introduction.mdx

@@ -0,0 +1,135 @@
+---
+title: "مقدمة"
+description: "المرجع الكامل لواجهة برمجة تطبيقات CrewAI AMP REST"
+icon: "code"
+mode: "wide"
+---
+
+# واجهة برمجة تطبيقات CrewAI AMP
+
+مرحبًا بك في مرجع واجهة برمجة تطبيقات CrewAI AMP. تتيح لك هذه الواجهة التفاعل برمجيًا مع الأطقم المنشورة، مما يمكّنك من دمجها مع تطبيقاتك وسير عملك وخدماتك.
+
+## البدء السريع
+
+<Steps>
+  <Step title="الحصول على بيانات اعتماد API">
+    انتقل إلى صفحة تفاصيل طاقمك في لوحة تحكم CrewAI AMP وانسخ رمز Bearer من علامة تبويب الحالة.
+  </Step>
+
+<Step title="اكتشاف المدخلات المطلوبة">
+  استخدم نقطة النهاية `GET /inputs` لمعرفة المعاملات التي يتوقعها طاقمك.
+</Step>
+
+<Step title="بدء تنفيذ الطاقم">
+  استدعِ `POST /kickoff` مع مدخلاتك لبدء تنفيذ الطاقم واستلام
+  `kickoff_id`.
+</Step>
+
+  <Step title="مراقبة التقدم">
+    استخدم `GET /status/{kickoff_id}` للتحقق من حالة التنفيذ واسترجاع النتائج.
+  </Step>
+</Steps>
+
+## المصادقة
+
+تتطلب جميع طلبات API المصادقة باستخدام رمز Bearer. أدرج رمزك في ترويسة `Authorization`:
+
+```bash
+curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \
+  https://your-crew-url.crewai.com/inputs
+```
+
+### أنواع الرموز
+
+| نوع الرمز            | النطاق                     | حالة الاستخدام                                                     |
+| :-------------------- | :------------------------ | :----------------------------------------------------------- |
+| **Bearer Token**      | وصول على مستوى المؤسسة | عمليات الطاقم الكاملة، مثالي للتكامل بين الخوادم |
+| **User Bearer Token** | وصول محدد بالمستخدم        | صلاحيات محدودة، مناسب للعمليات الخاصة بالمستخدم   |
+
+<Tip>
+  يمكنك العثور على كلا نوعي الرموز في علامة تبويب الحالة من صفحة تفاصيل طاقمك في
+  لوحة تحكم CrewAI AMP.
+</Tip>
+
+## عنوان URL الأساسي
+
+لكل طاقم منشور نقطة نهاية API فريدة خاصة به:
+
+```
+https://your-crew-name.crewai.com
+```
+
+استبدل `your-crew-name` بعنوان URL الفعلي لطاقمك من لوحة التحكم.
+
+## سير العمل النموذجي
+
+1. **الاكتشاف**: استدعِ `GET /inputs` لفهم ما يحتاجه طاقمك
+2. **التنفيذ**: أرسل المدخلات عبر `POST /kickoff` لبدء المعالجة
+3. **المراقبة**: استعلم عن `GET /status/{kickoff_id}` حتى الاكتمال
+4. **النتائج**: استخرج المخرجات النهائية من الاستجابة المكتملة
+
+## معالجة الأخطاء
+
+تستخدم الواجهة أكواد حالة HTTP القياسية:
+
+| الكود  | المعنى                                    |
+| ----- | :----------------------------------------- |
+| `200` | نجاح                                    |
+| `400` | طلب غير صالح - تنسيق مدخلات غير صحيح         |
+| `401` | غير مصرّح - رمز bearer غير صالح        |
+| `404` | غير موجود - المورد غير موجود         |
+| `422` | خطأ في التحقق - مدخلات مطلوبة مفقودة |
+| `500` | خطأ في الخادم - تواصل مع الدعم             |
+
+## الاختبار التفاعلي
+
+<Info>
+  **لماذا لا يوجد زر "إرسال"؟** نظرًا لأن كل مستخدم CrewAI AMP لديه عنوان URL
+  فريد للطاقم، نستخدم **وضع المرجع** بدلاً من بيئة تفاعلية لتجنب
+  الالتباس. يوضح لك هذا بالضبط كيف يجب أن تبدو الطلبات بدون
+  أزرار إرسال غير فعالة.
+</Info>
+
+تعرض لك كل صفحة نقطة نهاية:
+
+- **تنسيق الطلب الدقيق** مع جميع المعاملات
+- **أمثلة الاستجابة** لحالات النجاح والخطأ
+- **عينات الكود** بلغات متعددة (cURL، Python، JavaScript، إلخ)
+- **أمثلة المصادقة** بتنسيق رمز Bearer الصحيح
+
+### **لاختبار واجهتك الفعلية:**
+
+<CardGroup cols={2}>
+  <Card title="نسخ أمثلة cURL" icon="terminal">
+    انسخ أمثلة cURL واستبدل العنوان URL + الرمز بقيمك الحقيقية
+  </Card>
+  <Card title="استخدام Postman/Insomnia" icon="play">
+    استورد الأمثلة في أداة اختبار API المفضلة لديك
+  </Card>
+</CardGroup>
+
+**مثال على سير العمل:**
+
+1. **انسخ مثال cURL هذا** من أي صفحة نقطة نهاية
+2. **استبدل `your-actual-crew-name.crewai.com`** بعنوان URL الحقيقي لطاقمك
+3. **استبدل رمز Bearer** برمزك الحقيقي من لوحة التحكم
+4. **نفّذ الطلب** في طرفيتك أو عميل API
+
+## هل تحتاج مساعدة؟
+
+<CardGroup cols={2}>
+  <Card
+    title="دعم المؤسسات"
+    icon="headset"
+    href="mailto:support@crewai.com"
+  >
+    احصل على مساعدة في تكامل API واستكشاف الأخطاء وإصلاحها
+  </Card>
+  <Card
+    title="لوحة تحكم المؤسسات"
+    icon="chart-line"
+    href="https://app.crewai.com"
+  >
+    إدارة أطقمك وعرض سجلات التنفيذ
+  </Card>
+</CardGroup>

docs/v1.15.19/ar/api-reference/kickoff.mdx

@@ -0,0 +1,8 @@
+---
+title: "POST /kickoff"
+description: "بدء تنفيذ الطاقم"
+openapi: "/v1.15.19/enterprise-api.en.yaml POST /kickoff"
+mode: "wide"
+---
+
+

docs/v1.15.19/ar/api-reference/resume.mdx

@@ -0,0 +1,6 @@
+---
+title: "POST /resume"
+description: "استئناف تنفيذ الطاقم مع التغذية الراجعة البشرية"
+openapi: "/v1.15.19/enterprise-api.en.yaml POST /resume"
+mode: "wide"
+---

docs/v1.15.19/ar/api-reference/status.mdx

@@ -0,0 +1,6 @@
+---
+title: "GET /status/{kickoff_id}"
+description: "الحصول على حالة التنفيذ"
+openapi: "/v1.15.19/enterprise-api.en.yaml GET /status/{kickoff_id}"
+mode: "wide"
+---

docs/v1.15.19/ar/concepts/agent-capabilities.mdx

@@ -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>

docs/v1.15.19/ar/concepts/agents.mdx

@@ -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` المختار يدعم الميزات التي تحتاجها

docs/v1.15.19/ar/concepts/checkpointing.mdx

@@ -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. |

docs/v1.15.19/ar/concepts/cli.mdx

@@ -0,0 +1,312 @@
+---
+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`.
+
+#### أسماء مستعار قديمة للأعلام (مهملة)
+
+لا تزال أعلام snake_case القديمة تعمل، لكنها مخفية من `--help`. يُفضّل استخدام صيغ kebab-case الموثّقة في أقسام الأوامر أدناه.
+
+| مهمل | استخدم بدلاً منه |
+| :--- | :--- |
+| `--skip_provider` (في `crewai create crew`) | `--skip-provider` |
+| `--n_iterations` (في `crewai train`، `crewai test`) | `--n-iterations` |
+| `--task_id` (في `crewai replay`) | `--task-id` |
+
+### 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>

docs/v1.15.19/ar/concepts/collaboration.mdx

@@ -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` لرؤية التعاون في العمل
+- **حسّن أوصاف المهام**: المهام الواضحة تؤدي إلى تعاون أفضل
+- **وسّع النطاق**: جرّب العمليات الهرمية للمشاريع المعقدة
+
+يحوّل التعاون وكلاء الذكاء الاصطناعي الفرديين إلى فرق قوية يمكنها معالجة التحديات المعقدة ومتعددة الأوجه معًا.

docs/v1.15.19/ar/concepts/crews.mdx

@@ -0,0 +1,247 @@
+---
+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) لجميع المهام المنفذة.
+
+`total_tokens` هو الإجمالي المفوتر (`prompt_tokens + completion_tokens`). حقول التفصيل مثل `cached_prompt_tokens` و`cache_creation_tokens` تصف أجزاءً مُدرجة بالفعل ضمن تلك الإجماليات ولا تُضاف مرة أخرى إلى `total_tokens`. راجع قسم **UsageMetrics field semantics** في توثيق مفهوم Flows للحصول على العقد الكامل.
+
+```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>
+```

docs/v1.15.19/ar/concepts/event-listener.mdx

@@ -0,0 +1,237 @@
+---
+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**: يُرسل عند اكتمال تنفيذ تدفق
+- **FlowFailedEvent**: يُرسل عند فشل تنفيذ تدفق. يحتوي على اسم التدفق والاستثناء الذي أنهى التنفيذ.
+- **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، يمكنك توسيع وظائفه ودمجه بسلاسة مع بنيتك التحتية الحالية.

docs/v1.15.19/ar/concepts/files.mdx

@@ -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"),
+    }
+)
+```

docs/v1.15.19/ar/concepts/memory.mdx

@@ -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-3.7-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 أثناء الاسترجاع العميق. |

docs/v1.15.19/ar/concepts/planning.mdx

@@ -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>

docs/v1.15.19/ar/concepts/processes.mdx

@@ -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 ضروري لتمكين العمل الجماعي المنهجي بين الوكلاء.
+تم تحديث هذه الوثائق لتعكس أحدث الميزات والتحسينات، مما يضمن وصول المستخدمين إلى أحدث المعلومات وأكثرها شمولاً.

docs/v1.15.19/ar/concepts/production-architecture.mdx

@@ -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. تتعامل مع البنية التحتية والمصادقة والمراقبة نيابة عنك.
+
+راجع [دليل النشر](https://docs-platform.crewai.com/platform/ar/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 واستمرارية.**

docs/v1.15.19/ar/concepts/reasoning.mdx

@@ -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.
+```
+
+تساعد خطة الاستدلال هذه الوكيل على تنظيم نهجه تجاه المهمة، والنظر في التحديات المحتملة، وضمان تقديم المخرجات المتوقعة.

docs/v1.15.19/ar/concepts/skills.mdx

@@ -0,0 +1,373 @@
+---
+title: المهارات
+description: حزم المهارات المبنية على نظام الملفات التي تحقن خبرة المجال والتعليمات في إرشادات الوكلاء.
+icon: bolt
+mode: "wide"
+---
+
+## نظرة عامة
+
+المهارات هي مجلدات مستقلة توفر للوكلاء **تعليمات وإرشادات ومواد مرجعية خاصة بالمجال**. تُعرّف كل مهارة بملف `SKILL.md` يحتوي على بيانات وصفية YAML ومحتوى Markdown.
+
+عند التفعيل، يتم حقن تعليمات المهارة مباشرة في إرشادات مهمة الوكيل — مما يمنح الوكيل خبرة دون الحاجة لأي تغييرات في الكود.
+
+<Note type="info" title="المهارات مقابل الأدوات — التمييز الأساسي">
+**المهارات ليست أدوات.** هذه هي نقطة الارتباك الأكثر شيوعًا.
+
+- **المهارات** تحقن *تعليمات وسياق* في إرشادات الوكيل. تخبر الوكيل *كيف يفكر* في مشكلة ما.
+- **الأدوات** تمنح الوكيل *دوال قابلة للاستدعاء* لاتخاذ إجراءات (البحث، قراءة الملفات، استدعاء APIs).
+
+غالبًا ما تحتاج **كليهما**: مهارات للخبرة، وأدوات للإجراء. يتم تكوينهما بشكل مستقل ويُكمّلان بعضهما.
+</Note>
+
+---
+
+## البداية السريعة
+
+### 1. إنشاء مهارة باستخدام سطر الأوامر (CLI)
+
+واجهة سطر الأوامر هي الطريقة المدعومة لإنشاء مهارة — فهي تُنشئ لك هيكل المجلد وملف `SKILL.md` صالحًا:
+
+```shell Terminal
+crewai skill create code-review
+```
+
+داخل مشروع طاقم (حيث يوجد `pyproject.toml`) يُنشئ هذا الأمر `./skills/code-review/`؛ وخارج المشروع يُنشئ `./code-review/` في المجلد الحالي (يمكنك فرض هذا السلوك باستخدام `--no-project`):
+
+```
+skills/
+└── code-review/
+    ├── SKILL.md          # Required — instructions (pre-filled template)
+    ├── references/       # Optional — reference docs
+    ├── scripts/          # Optional — executable scripts
+    └── assets/           # Optional — static files
+```
+
+### 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"],             # يمكنه إرسال رسائل بريد وتحديث التذاكر
+)
+```
+
+---
+
+## إنشاء المهارات ونشرها وتثبيتها
+
+للمهارات دورة حياة كاملة تُدار عبر واجهة سطر الأوامر: **أنشئها باستخدام `crewai skill create`، وانشرها باستخدام `crewai skill publish`** — إنشاء المجلدات يدويًا يصلح للتجارب المحلية، لكن واجهة سطر الأوامر هي سير العمل المقصود، وهي تحافظ على صحة هيكل المهارة وبياناتها الوصفية.
+
+### الإنشاء
+
+```shell Terminal
+crewai skill create my-skill
+```
+
+يُنشئ هذا الأمر المجلد (داخل `./skills/` في مشروع الطاقم) مع قالب `SKILL.md`، بالإضافة إلى مجلدات فارغة `scripts/` و `references/` و `assets/`. عدّل `SKILL.md` لتعريف التعليمات.
+
+### النشر
+
+نفّذ الأمر من داخل مجلد المهارة (حيث يوجد `SKILL.md`):
+
+```shell Terminal
+cd skills/my-skill
+crewai skill publish
+```
+
+يقرأ النشر الحقول `name` و `description` و `metadata.version` من البيانات الوصفية في مقدمة `SKILL.md` ويدفع المهارة إلى سجل CrewAI. **المهارات المنشورة تكون دائمًا مقيّدة بنطاق مؤسستك** — مثل الأدوات، لا يستطيع رؤيتها وتثبيتها إلا أعضاء المؤسسة الناشرة؛ ولا توجد رؤية عامة. أعلام مفيدة:
+
+| العلم | التأثير |
+| :--- | :--- |
+| `--org <slug>` | النشر تحت مؤسسة محددة (يتجاوز الإعدادات). |
+| `--force` | تخطي التحقق من حالة git (تغييرات غير مُثبتة، إلخ). |
+
+### التثبيت
+
+ثبّت مهارة منشورة عبر مرجعها `@org/name`:
+
+```shell Terminal
+crewai skill install @acme/code-review
+```
+
+داخل مشروع الطاقم تُثبَّت المهارة في `./skills/{name}/`؛ وخارج المشروع تذهب إلى ذاكرة التخزين المؤقتة المشتركة في `~/.crewai/skills/{org}/{name}/`.
+
+يمكن للوكلاء أيضًا الإشارة إلى مهارات السجل مباشرة — يتم حلّها من ذاكرة التخزين المؤقتة المحلية (أو من مجلد `skills/` في المشروع) وقت التشغيل:
+
+```python
+agent = Agent(
+    role="Senior Code Reviewer",
+    goal="Review pull requests for quality and security issues",
+    backstory="Staff engineer with expertise in secure coding practices.",
+    skills=["@acme/code-review"],  # registry ref, resolved locally
+)
+```
+
+### عرض القائمة
+
+```shell Terminal
+crewai skill list
+```
+
+يعرض المهارات المثبّتة من مجلد المشروع `./skills/` ومن ذاكرة التخزين المؤقتة العامة معًا، مع إصداراتها ومساراتها.
+
+---
+
+## المهارات على مستوى الطاقم
+
+يمكن تعيين المهارات على الطاقم لتُطبّق على **جميع الوكلاء**:
+
+```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>

docs/v1.15.19/ar/concepts/testing.mdx

@@ -0,0 +1,54 @@
+---
+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
+```
+
+<Note>
+  العلم القديم `--n_iterations` لا يزال يعمل، لكنه مهمل ومخفي من `--help`.
+  استخدم `--n-iterations` (أو `-n`) بدلاً من ذلك.
+</Note>
+
+عند تشغيل أمر `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**     |                                |                                  |
+
+يوضح المثال أعلاه نتائج الاختبار لتشغيلين للطاقم مع مهمتين، مع الدرجة الإجمالية المتوسطة لكل مهمة والطاقم ككل.

docs/v1.15.19/ar/concepts/tools.mdx

@@ -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، استفد من كل من الأدوات المخصصة والموجودة لتمكين وكلائك وتعزيز نظام الذكاء الاصطناعي البيئي. فكّر في استخدام معالجة الأخطاء وآليات التخزين المؤقت ومرونة معاملات الأدوات لتحسين أداء وقدرات وكلائك.

docs/v1.15.19/ar/concepts/training.mdx

@@ -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.
+
+من المهم ملاحظة أن عملية التدريب قد تستغرق بعض الوقت، اعتمادًا على تعقيد وكلائك وستتطلب أيضًا ملاحظاتك في كل تكرار.
+
+بمجرد اكتمال التدريب، سيكون وكلاؤك مجهزين بقدرات ومعرفة محسّنة، وجاهزين لمعالجة المهام المعقدة وتقديم رؤى أكثر اتساقًا وقيمة.
+
+تذكر تحديث وإعادة تدريب وكلائك بانتظام لضمان بقائهم على اطلاع بأحدث المعلومات والتطورات في المجال.

docs/v1.15.19/ar/examples/cookbooks.mdx

@@ -0,0 +1,49 @@
+---
+title: كتب وصفات CrewAI
+description: بدايات سريعة ودفاتر ملاحظات مركّزة على الميزات لتعلم الأنماط بسرعة.
+icon: book
+mode: "wide"
+---
+
+## بدايات سريعة وعروض توضيحية
+
+<CardGroup cols={3}>
+  <Card title="التعاون" icon="people-arrows" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Collaboration/crewai_collaboration.ipynb">
+    تنسيق عدة Agents على مهام مشتركة. يتضمن دفتر ملاحظات بنمط تعاون شامل.
+  </Card>
+
+  <Card title="التخطيط" icon="timeline" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Planning/crewai_planning.ipynb">
+    تعليم الـ Agents التفكير في خطط متعددة المراحل قبل التنفيذ باستخدام أدوات التخطيط.
+  </Card>
+
+  <Card title="الاستدلال" icon="lightbulb" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Reasoning/crewai_reasoning.ipynb">
+    استكشاف حلقات التأمل الذاتي، ومطالبات النقد، وأنماط التفكير المنظم.
+  </Card>
+</CardGroup>
+
+<CardGroup cols={3}>
+  <Card title="حواجز الحماية المنظمة" icon="shield-check" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Guardrails/task_guardrails.ipynb">
+    تطبيق حواجز حماية على مستوى المهام مع إعادة المحاولة ودوال التحقق والبدائل الآمنة.
+  </Card>
+
+  <Card title="بحث وتأريض Gemini" icon="magnifying-glass" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Custom%20LLM/gemini_search_grounding_crewai.ipynb">
+    ربط CrewAI بـ Gemini مع تأريض البحث للحصول على مخرجات واقعية غنية بالاستشهادات.
+  </Card>
+
+  <Card title="ملخصات فيديو Gemini" icon="video" href="https://github.com/crewAIInc/crewAI-quickstarts/blob/main/Custom%20LLM/summarize_video_gemini_crewai.ipynb">
+    إنشاء ملخصات فيديو باستخدام نموذج Gemini متعدد الوسائط وتنسيق CrewAI.
+  </Card>
+</CardGroup>
+
+<CardGroup cols={2}>
+  <Card title="تصفح البدايات السريعة" icon="bolt" href="https://github.com/crewAIInc/crewAI-quickstarts">
+    عرض جميع دفاتر الملاحظات والعروض التوضيحية التي تستعرض إمكانيات CrewAI المحددة.
+  </Card>
+  <Card title="اطلب كتاب وصفات" icon="message-plus" href="https://community.crewai.com">
+    هل يفتقد نمط معين؟ أرسل طلبًا في منتدى المجتمع وسنوسّع المكتبة.
+  </Card>
+</CardGroup>
+
+<Tip>
+استخدم كتب الوصفات لتعلم نمط بسرعة، ثم انتقل إلى الأمثلة الكاملة للتطبيقات الجاهزة للإنتاج.
+</Tip>

docs/v1.15.19/ar/examples/example.mdx

@@ -0,0 +1,86 @@
+---
+title: أمثلة CrewAI
+description: استكشف أمثلة منسّقة مرتبة حسب Crews وFlows والتكاملات ودفاتر الملاحظات.
+icon: rocket-launch
+mode: "wide"
+---
+
+## Crews
+
+<CardGroup cols={3}>
+  <Card title="استراتيجية التسويق" icon="bullhorn" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/marketing_strategy">
+    تخطيط حملات تسويقية متعددة الـ Agents.
+  </Card>
+  <Card title="رحلة مفاجئة" icon="plane" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/surprise_trip">
+    تخطيط رحلات مفاجئة مخصصة.
+  </Card>
+  <Card title="مطابقة الملف الشخصي بالوظائف" icon="id-card" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/match_profile_to_positions">
+    مطابقة السيرة الذاتية بالوظائف باستخدام البحث المتجهي.
+  </Card>
+  <Card title="نشر وظيفة" icon="newspaper" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/job-posting">
+    إنشاء أوصاف وظيفية آلية.
+  </Card>
+  <Card title="فريق بناء الألعاب" icon="gamepad" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/game-builder-crew">
+    فريق متعدد الـ Agents يصمم ويبني ألعاب Python.
+  </Card>
+  <Card title="التوظيف" icon="user-group" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews/recruitment">
+    استقطاب المرشحين وتقييمهم.
+  </Card>
+  <Card title="تصفح جميع الـ Crews" icon="users" href="https://github.com/crewAIInc/crewAI-examples/tree/main/crews">
+    عرض القائمة الكاملة لأمثلة الـ Crews.
+  </Card>
+</CardGroup>
+
+## Flows
+
+<CardGroup cols={3}>
+  <Card title="Flow إنشاء المحتوى" icon="pen" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/content_creator_flow">
+    إنشاء محتوى متعدد الـ Crews مع التوجيه.
+  </Card>
+  <Card title="الرد التلقائي على البريد الإلكتروني" icon="envelope" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/email_auto_responder_flow">
+    مراقبة البريد الإلكتروني والرد الآلي.
+  </Card>
+  <Card title="Flow تقييم العملاء المحتملين" icon="chart-line" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/lead_score_flow">
+    تأهيل العملاء المحتملين مع تدخل بشري.
+  </Card>
+  <Card title="Flow مساعد الاجتماعات" icon="calendar" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/meeting_assistant_flow">
+    معالجة الملاحظات مع التكاملات.
+  </Card>
+  <Card title="حلقة التقييم الذاتي" icon="rotate" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/self_evaluation_loop_flow">
+    سير عمل التحسين الذاتي التكراري.
+  </Card>
+  <Card title="كتابة كتاب (Flows)" icon="book" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows/write_a_book_with_flows">
+    إنشاء الفصول بالتوازي.
+  </Card>
+  <Card title="تصفح جميع الـ Flows" icon="diagram-project" href="https://github.com/crewAIInc/crewAI-examples/tree/main/flows">
+    عرض القائمة الكاملة لأمثلة الـ Flows.
+  </Card>
+</CardGroup>
+
+## التكاملات
+
+<CardGroup cols={3}>
+  <Card title="CrewAI ↔ LangGraph" icon="link" href="https://github.com/crewAIInc/crewAI-examples/tree/main/integrations/crewai-langgraph">
+    التكامل مع إطار عمل LangGraph.
+  </Card>
+  <Card title="Azure OpenAI" icon="cloud" href="https://github.com/crewAIInc/crewAI-examples/tree/main/integrations/azure_model">
+    استخدام CrewAI مع Azure OpenAI.
+  </Card>
+  <Card title="نماذج NVIDIA" icon="microchip" href="https://github.com/crewAIInc/crewAI-examples/tree/main/integrations/nvidia_models">
+    تكاملات منظومة NVIDIA.
+  </Card>
+  <Card title="تصفح التكاملات" icon="puzzle-piece" href="https://github.com/crewAIInc/crewAI-examples/tree/main/integrations">
+    عرض جميع أمثلة التكاملات.
+  </Card>
+</CardGroup>
+
+## دفاتر الملاحظات
+
+<CardGroup cols={2}>
+  <Card title="Simple QA Crew + Flow" icon="book" href="https://github.com/crewAIInc/crewAI-examples/tree/main/Notebooks/Simple%20QA%20Crew%20%2B%20Flow">
+    Simple QA Crew + Flow.
+  </Card>
+  <Card title="جميع دفاتر الملاحظات" icon="book" href="https://github.com/crewAIInc/crewAI-examples/tree/main/Notebooks">
+    أمثلة تفاعلية للتعلم والتجريب.
+  </Card>
+</CardGroup>

docs/v1.15.19/ar/guides/advanced/customizing-prompts.mdx

@@ -0,0 +1,331 @@
+---
+title: تخصيص المطالبات
+description: تعمّق في تخصيص المطالبات على المستوى المنخفض في CrewAI، مما يتيح حالات استخدام مخصصة ومعقدة لنماذج ولغات مختلفة.
+icon: message-pen
+mode: "wide"
+---
+
+## لماذا نخصص المطالبات؟
+
+على الرغم من أن مطالبات CrewAI الافتراضية تعمل بشكل جيد في كثير من السيناريوهات، إلا أن التخصيص على المستوى المنخفض يفتح الباب أمام سلوك أكثر مرونة وقوة للـ Agent. إليك لماذا قد ترغب في الاستفادة من هذا التحكم العميق:
+
+1. **التحسين لنماذج LLM محددة** – تزدهر النماذج المختلفة (مثل GPT-4 وClaude وLlama) مع تنسيقات مطالبات مصممة لبنيتها الفريدة.
+2. **تغيير اللغة** – بناء Agents تعمل حصريًا بلغات غير الإنجليزية مع التعامل مع الفروق الدقيقة بدقة.
+3. **التخصص في مجالات معقدة** – تكييف المطالبات لصناعات متخصصة للغاية مثل الرعاية الصحية والمالية والقانون.
+4. **ضبط النبرة والأسلوب** – جعل الـ Agents أكثر رسمية أو عفوية أو إبداعية أو تحليلية.
+5. **دعم حالات استخدام مخصصة للغاية** – استخدام هياكل وتنسيقات مطالبات متقدمة لتلبية متطلبات معقدة خاصة بالمشروع.
+
+يستكشف هذا الدليل كيفية الوصول إلى مطالبات CrewAI على مستوى أعمق، مما يمنحك تحكمًا دقيقًا في كيفية تفكير الـ Agents وتفاعلها.
+
+## فهم نظام المطالبات في CrewAI
+
+تحت الغطاء، يستخدم CrewAI نظام مطالبات معياري يمكنك تخصيصه على نطاق واسع:
+
+- **قوالب الـ Agent** – تحكم في نهج كل Agent تجاه دوره المعيّن.
+- **شرائح المطالبات** – تتحكم في السلوكيات المتخصصة مثل المهام واستخدام الأدوات وهيكل المخرجات.
+- **معالجة الأخطاء** – توجيه كيفية استجابة الـ Agents للإخفاقات والاستثناءات وحالات انتهاء المهلة.
+- **مطالبات خاصة بالأدوات** – تعريف تعليمات مفصلة لكيفية استدعاء الأدوات أو استخدامها.
+
+اطلع على [قوالب المطالبات الأصلية في مستودع CrewAI](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/translations/en.json) لمعرفة كيفية تنظيم هذه العناصر. من هناك، يمكنك تجاوزها أو تكييفها حسب الحاجة لفتح سلوكيات متقدمة.
+
+## فهم تعليمات النظام الافتراضية
+
+<Warning>
+**مشكلة شفافية الإنتاج**: يحقن CrewAI تلقائيًا تعليمات افتراضية في مطالباتك قد لا تكون على علم بها. يشرح هذا القسم ما يحدث تحت الغطاء وكيفية الحصول على تحكم كامل.
+</Warning>
+
+عندما تعرّف Agent بـ `role` و`goal` و`backstory`، يضيف CrewAI تلقائيًا تعليمات نظام إضافية تتحكم في التنسيق والسلوك. فهم هذه الحقن الافتراضية أمر بالغ الأهمية لأنظمة الإنتاج التي تحتاج شفافية كاملة في المطالبات.
+
+### ما يحقنه CrewAI تلقائيًا
+
+بناءً على تهيئة الـ Agent، يضيف CrewAI تعليمات افتراضية مختلفة:
+
+#### للـ Agents بدون أدوات
+```text
+"I MUST use these formats, my job depends on it!"
+```
+
+#### للـ Agents مع أدوات
+```text
+"IMPORTANT: Use the following format in your response:
+
+Thought: you should always think about what to do
+Action: the action to take, only one name of [tool_names]
+Action Input: the input to the action, just a simple JSON object...
+```
+
+#### للمخرجات المنظمة (JSON/Pydantic)
+```text
+"Ensure your final answer contains only the content in the following format: {output_format}
+Ensure the final output does not include any code block markers like ```json or ```python."
+```
+
+### عرض مطالبة النظام الكاملة
+
+لمعرفة المطالبة المرسلة بالضبط إلى LLM، يمكنك فحص المطالبة المولّدة:
+
+```python
+from crewai import Agent, Crew, Task
+from crewai.utilities.prompts import Prompts
+
+# Create your agent
+agent = Agent(
+    role="Data Analyst",
+    goal="Analyze data and provide insights",
+    backstory="You are an expert data analyst with 10 years of experience.",
+    verbose=True
+)
+
+# Create a sample task
+task = Task(
+    description="Analyze the sales data and identify trends",
+    expected_output="A detailed analysis with key insights and trends",
+    agent=agent
+)
+
+# Create the prompt generator
+prompt_generator = Prompts(
+    agent=agent,
+    has_tools=len(agent.tools) > 0,
+    use_system_prompt=agent.use_system_prompt
+)
+
+# Generate and inspect the actual prompt
+generated_prompt = prompt_generator.task_execution()
+
+# Print the complete system prompt that will be sent to the LLM
+if "system" in generated_prompt:
+    print("=== SYSTEM PROMPT ===")
+    print(generated_prompt["system"])
+    print("\n=== USER PROMPT ===")
+    print(generated_prompt["user"])
+else:
+    print("=== COMPLETE PROMPT ===")
+    print(generated_prompt["prompt"])
+
+# You can also see how the task description gets formatted
+print("\n=== TASK CONTEXT ===")
+print(f"Task Description: {task.description}")
+print(f"Expected Output: {task.expected_output}")
+```
+
+### تجاوز التعليمات الافتراضية
+
+لديك عدة خيارات للحصول على تحكم كامل في المطالبات:
+
+#### الخيار 1: القوالب المخصصة (مُوصى به)
+```python
+from crewai import Agent
+
+# Define your own system template without default instructions
+custom_system_template = """You are {role}. {backstory}
+Your goal is: {goal}
+
+Respond naturally and conversationally. Focus on providing helpful, accurate information."""
+
+custom_prompt_template = """Task: {input}
+
+Please complete this task thoughtfully."""
+
+agent = Agent(
+    role="Research Assistant",
+    goal="Help users find accurate information",
+    backstory="You are a helpful research assistant.",
+    system_template=custom_system_template,
+    prompt_template=custom_prompt_template,
+    use_system_prompt=True  # Use separate system/user messages
+)
+```
+
+#### الخيار 2: ملف مطالبات مخصص
+أنشئ ملف `custom_prompts.json` لتجاوز شرائح مطالبات محددة:
+
+```json
+{
+  "slices": {
+    "no_tools": "\nProvide your best answer in a natural, conversational way.",
+    "tools": "\nYou have access to these tools: {tools}\n\nUse them when helpful, but respond naturally.",
+    "formatted_task_instructions": "Format your response as: {output_format}"
+  }
+}
+```
+
+ثم استخدمه في Crew:
+
+```python
+crew = Crew(
+    agents=[agent],
+    tasks=[task],
+    prompt_file="custom_prompts.json",
+    verbose=True
+)
+```
+
+<Note>
+يُحتفظ بـ `agent.i18n` للتوافق مع الإصدارات السابقة فقط، وقد تم إهماله. لتخصيص المطالبات أثناء التشغيل، مرّر `prompt_file` إلى `Crew`. وللوصول البرمجي المباشر إلى شرائح المطالبات، استخدم أداة i18n مباشرة:
+</Note>
+
+```python
+from crewai.utilities.i18n import get_i18n
+
+i18n = get_i18n("custom_prompts.json")
+format_slice = i18n.slice("format")
+tool_prompt = i18n.tools("ask_question")
+```
+
+#### الخيار 3: تعطيل مطالبات النظام لنماذج o1
+```python
+agent = Agent(
+    role="Analyst",
+    goal="Analyze data",
+    backstory="Expert analyst",
+    use_system_prompt=False  # Disables system prompt separation
+)
+```
+
+### التصحيح باستخدام أدوات المراقبة
+
+لشفافية الإنتاج، استخدم منصات المراقبة لمتابعة جميع المطالبات وتفاعلات LLM. يتيح لك ذلك رؤية المطالبات المرسلة بالضبط (بما في ذلك التعليمات الافتراضية) إلى نماذج LLM.
+
+راجع [توثيق المراقبة](/ar/observability/overview) للحصول على أدلة تكامل مفصلة مع منصات متعددة بما في ذلك Langfuse وMLflow وWeights & Biases وحلول التسجيل المخصصة.
+
+### أفضل الممارسات للإنتاج
+
+1. **افحص المطالبات المولّدة دائمًا** قبل النشر في الإنتاج
+2. **استخدم قوالب مخصصة** عندما تحتاج تحكمًا كاملاً في محتوى المطالبات
+3. **دمج أدوات المراقبة** للمتابعة المستمرة للمطالبات (راجع [توثيق المراقبة](/ar/observability/overview))
+4. **اختبر مع نماذج LLM مختلفة** حيث قد تعمل التعليمات الافتراضية بشكل مختلف عبر النماذج
+5. **وثّق تخصيصات المطالبات** لشفافية الفريق
+
+<Tip>
+التعليمات الافتراضية موجودة لضمان سلوك Agent متسق، لكنها قد تتعارض مع المتطلبات الخاصة بالمجال. استخدم خيارات التخصيص أعلاه للحفاظ على تحكم كامل في سلوك Agent في أنظمة الإنتاج.
+</Tip>
+
+## أفضل الممارسات لإدارة ملفات المطالبات
+
+عند الانخراط في تخصيص المطالبات على المستوى المنخفض، اتبع هذه الإرشادات للحفاظ على التنظيم وسهولة الصيانة:
+
+1. **احتفظ بالملفات منفصلة** – خزّن المطالبات المخصصة في ملفات JSON مخصصة خارج قاعدة الكود الرئيسية.
+2. **التحكم في الإصدارات** – تتبع التغييرات داخل المستودع مع ضمان توثيق واضح لتعديلات المطالبات بمرور الوقت.
+3. **التنظيم حسب النموذج أو اللغة** – استخدم تسميات مثل `prompts_llama.json` أو `prompts_es.json` لتحديد التهيئات المتخصصة بسرعة.
+4. **توثيق التغييرات** – قدم تعليقات أو حافظ على ملف يوضح غرض ونطاق تخصيصاتك.
+5. **قلل التعديلات** – تجاوز فقط الشرائح المحددة التي تحتاج حقًا لتعديلها مع الحفاظ على الوظائف الافتراضية لكل شيء آخر.
+
+## أبسط طريقة لتخصيص المطالبات
+
+إحدى الطرق المباشرة هي إنشاء ملف JSON للمطالبات التي تريد تجاوزها ثم توجيه Crew إلى ذلك الملف:
+
+1. أنشئ ملف JSON بشرائح المطالبات المحدّثة.
+2. أشر إلى ذلك الملف عبر معامل `prompt_file` في Crew.
+
+يدمج CrewAI بعد ذلك تخصيصاتك مع الإعدادات الافتراضية، فلا تحتاج لإعادة تعريف كل مطالبة. إليك الطريقة:
+
+بالنسبة للكود الذي يحتاج إلى قراءة شرائح المطالبات مباشرة، استخدم `crewai.utilities.i18n.get_i18n()` مع ملف المطالبات نفسه بدلًا من قراءة `agent.i18n`.
+
+### مثال: تخصيص أساسي للمطالبات
+
+أنشئ ملف `custom_prompts.json` بالمطالبات التي تريد تعديلها. تأكد من إدراج جميع المطالبات عالية المستوى التي يجب أن يحتويها، وليس فقط تغييراتك:
+
+```json
+{
+  "slices": {
+    "format": "When responding, follow this structure:\n\nTHOUGHTS: Your step-by-step thinking\nACTION: Any tool you're using\nRESULT: Your final answer or conclusion"
+  }
+}
+```
+
+ثم ادمجه هكذا:
+
+```python
+from crewai import Agent, Crew, Task, Process
+
+# Create agents and tasks as normal
+researcher = Agent(
+    role="Research Specialist",
+    goal="Find information on quantum computing",
+    backstory="You are a quantum physics expert",
+    verbose=True
+)
+
+research_task = Task(
+    description="Research quantum computing applications",
+    expected_output="A summary of practical applications",
+    agent=researcher
+)
+
+# Create a crew with your custom prompt file
+crew = Crew(
+    agents=[researcher],
+    tasks=[research_task],
+    prompt_file="path/to/custom_prompts.json",
+    verbose=True
+)
+
+# Run the crew
+result = crew.kickoff()
+```
+
+بهذه التعديلات البسيطة، تحصل على تحكم منخفض المستوى في كيفية تواصل الـ Agents وحل المهام.
+
+## التحسين لنماذج محددة
+
+تزدهر النماذج المختلفة مع مطالبات منظمة بطرق مختلفة. إجراء تعديلات أعمق يمكن أن يعزز الأداء بشكل كبير من خلال مواءمة مطالباتك مع خصائص النموذج.
+
+### مثال: قالب مطالبات Llama 3.3
+
+على سبيل المثال، عند التعامل مع Llama 3.3 من Meta، قد يعكس التخصيص على المستوى الأعمق الهيكل الموصى به الموضح في:
+https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/#prompt-template
+
+إليك مثالاً يوضح كيف يمكنك ضبط Agent للاستفادة من Llama 3.3 في الكود:
+
+```python
+from crewai import Agent, Crew, Task, Process
+from crewai_tools import DirectoryReadTool, FileReadTool
+
+# Define templates for system, user (prompt), and assistant (response) messages
+system_template = """<|begin_of_text|><|start_header_id|>system<|end_header_id|>{{ .System }}<|eot_id|>"""
+prompt_template = """<|start_header_id|>user<|end_header_id|>{{ .Prompt }}<|eot_id|>"""
+response_template = """<|start_header_id|>assistant<|end_header_id|>{{ .Response }}<|eot_id|>"""
+
+# Create an Agent using Llama-specific layouts
+principal_engineer = Agent(
+    role="Principal Engineer",
+    goal="Oversee AI architecture and make high-level decisions",
+    backstory="You are the lead engineer responsible for critical AI systems",
+    verbose=True,
+    llm="groq/llama-3.3-70b-versatile",  # Using the Llama 3 model
+    system_template=system_template,
+    prompt_template=prompt_template,
+    response_template=response_template,
+    tools=[DirectoryReadTool(), FileReadTool()]
+)
+
+# Define a sample task
+engineering_task = Task(
+    description="Review AI implementation files for potential improvements",
+    expected_output="A summary of key findings and recommendations",
+    agent=principal_engineer
+)
+
+# Create a Crew for the task
+llama_crew = Crew(
+    agents=[principal_engineer],
+    tasks=[engineering_task],
+    process=Process.sequential,
+    verbose=True
+)
+
+# Execute the crew
+result = llama_crew.kickoff()
+print(result.raw)
+```
+
+من خلال هذه التهيئة العميقة، يمكنك ممارسة تحكم شامل منخفض المستوى في سير العمل القائمة على Llama دون الحاجة إلى ملف JSON منفصل.
+
+## الخلاصة
+
+يفتح تخصيص المطالبات على المستوى المنخفض في CrewAI الباب أمام حالات استخدام مخصصة ومعقدة للغاية. من خلال إنشاء ملفات مطالبات منظمة (أو قوالب مضمّنة مباشرة)، يمكنك استيعاب نماذج ولغات ومجالات متخصصة متنوعة. يضمن هذا المستوى من المرونة أنك تستطيع صياغة سلوك الذكاء الاصطناعي الذي تحتاجه بالضبط، مع العلم أن CrewAI لا يزال يوفر إعدادات افتراضية موثوقة عندما لا تتجاوزها.
+
+<Check>
+لديك الآن الأساس لتخصيصات المطالبات المتقدمة في CrewAI. سواء كنت تتكيف مع هياكل خاصة بالنموذج أو قيود خاصة بالمجال، يتيح لك هذا النهج المنخفض المستوى تشكيل تفاعلات الـ Agent بطرق متخصصة للغاية.
+</Check>

docs/v1.15.19/ar/guides/advanced/fingerprinting.mdx

@@ -0,0 +1,134 @@
+---
+title: البصمات الرقمية
+description: تعلم كيفية استخدام نظام البصمات الرقمية في CrewAI لتحديد وتتبع المكونات بشكل فريد طوال دورة حياتها.
+icon: fingerprint
+mode: "wide"
+---
+
+## نظرة عامة
+
+توفر البصمات الرقمية في CrewAI طريقة لتحديد وتتبع المكونات بشكل فريد طوال دورة حياتها. يتلقى كل `Agent` و`Crew` و`Task` بصمة رقمية فريدة تلقائيًا عند الإنشاء، ولا يمكن تجاوزها يدويًا.
+
+يمكن استخدام هذه البصمات لـ:
+- تدقيق وتتبع استخدام المكونات
+- ضمان سلامة هوية المكونات
+- إرفاق بيانات وصفية بالمكونات
+- إنشاء سلسلة عمليات قابلة للتتبع
+
+## كيف تعمل البصمات الرقمية
+
+البصمة الرقمية هي نسخة من فئة `Fingerprint` من وحدة `crewai.security`. تحتوي كل بصمة على:
+
+- سلسلة UUID: معرّف فريد للمكون يتم إنشاؤه تلقائيًا ولا يمكن تعيينه يدويًا
+- طابع زمني للإنشاء: متى تم إنشاء البصمة، يُعيَّن تلقائيًا ولا يمكن تعديله يدويًا
+- بيانات وصفية: قاموس معلومات إضافية يمكن تخصيصه
+
+تُنشأ البصمات الرقمية وتُعيَّن تلقائيًا عند إنشاء المكون. يكشف كل مكون بصمته من خلال خاصية للقراءة فقط.
+
+## الاستخدام الأساسي
+
+### الوصول إلى البصمات الرقمية
+
+```python
+from crewai import Agent, Crew, Task
+
+# Create components - fingerprints are automatically generated
+agent = Agent(
+    role="Data Scientist",
+    goal="Analyze data",
+    backstory="Expert in data analysis"
+)
+
+crew = Crew(
+    agents=[agent],
+    tasks=[]
+)
+
+task = Task(
+    description="Analyze customer data",
+    expected_output="Insights from data analysis",
+    agent=agent
+)
+
+# Access the fingerprints
+agent_fingerprint = agent.fingerprint
+crew_fingerprint = crew.fingerprint
+task_fingerprint = task.fingerprint
+
+# Print the UUID strings
+print(f"Agent fingerprint: {agent_fingerprint.uuid_str}")
+print(f"Crew fingerprint: {crew_fingerprint.uuid_str}")
+print(f"Task fingerprint: {task_fingerprint.uuid_str}")
+```
+
+### العمل مع البيانات الوصفية للبصمة
+
+يمكنك إضافة بيانات وصفية إلى البصمات لسياق إضافي:
+
+```python
+# Add metadata to the agent's fingerprint
+agent.security_config.fingerprint.metadata = {
+    "version": "1.0",
+    "department": "Data Science",
+    "project": "Customer Analysis"
+}
+
+# Access the metadata
+print(f"Agent metadata: {agent.fingerprint.metadata}")
+```
+
+## استمرارية البصمة
+
+صُممت البصمات لتبقى ثابتة دون تغيير طوال دورة حياة المكون. إذا عدّلت مكونًا، تظل البصمة كما هي:
+
+```python
+original_fingerprint = agent.fingerprint.uuid_str
+
+# Modify the agent
+agent.goal = "New goal for analysis"
+
+# The fingerprint remains unchanged
+assert agent.fingerprint.uuid_str == original_fingerprint
+```
+
+## البصمات الحتمية
+
+بينما لا يمكنك تعيين UUID والطابع الزمني مباشرة، يمكنك إنشاء بصمات حتمية باستخدام طريقة `generate` مع بذرة:
+
+```python
+from crewai.security import Fingerprint
+
+# Create a deterministic fingerprint using a seed string
+deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id")
+
+# The same seed always produces the same fingerprint
+same_fingerprint = Fingerprint.generate(seed="my-agent-id")
+assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str
+
+# You can also set metadata
+custom_fingerprint = Fingerprint.generate(
+    seed="my-agent-id",
+    metadata={"version": "1.0"}
+)
+```
+
+## الاستخدام المتقدم
+
+### هيكل البصمة
+
+لكل بصمة الهيكل التالي:
+
+```python
+from crewai.security import Fingerprint
+
+fingerprint = agent.fingerprint
+
+# UUID string - the unique identifier (auto-generated)
+uuid_str = fingerprint.uuid_str  # e.g., "123e4567-e89b-12d3-a456-426614174000"
+
+# Creation timestamp (auto-generated)
+created_at = fingerprint.created_at  # A datetime object
+
+# Metadata - for additional information (can be customized)
+metadata = fingerprint.metadata  # A dictionary, defaults to {}
+```

docs/v1.15.19/ar/guides/agents/crafting-effective-agents.mdx

@@ -0,0 +1,453 @@
+---
+title: صياغة Agents فعّالة
+description: تعلم أفضل الممارسات لتصميم Agents ذكاء اصطناعي قوية ومتخصصة تتعاون بفعالية لحل المشكلات المعقدة.
+icon: robot
+mode: "wide"
+---
+
+## فن وعلم تصميم الـ Agent
+
+في قلب CrewAI يكمن الـ Agent - كيان ذكاء اصطناعي متخصص مصمم لأداء أدوار محددة ضمن إطار تعاوني. بينما إنشاء Agents أساسية أمر بسيط، فإن صياغة Agents فعّالة حقًا تنتج نتائج استثنائية يتطلب فهم مبادئ التصميم الأساسية وأفضل الممارسات.
+
+سيساعدك هذا الدليل على إتقان فن تصميم الـ Agent، مما يمكّنك من إنشاء شخصيات AI متخصصة تتعاون بفعالية وتفكر بشكل نقدي وتنتج مخرجات عالية الجودة مصممة لاحتياجاتك المحددة.
+
+### لماذا يهم تصميم الـ Agent
+
+الطريقة التي تعرّف بها الـ Agents تؤثر بشكل كبير على:
+
+1. **جودة المخرجات**: الـ Agents المصممة جيدًا تنتج نتائج أكثر صلة وجودة
+2. **فعالية التعاون**: الـ Agents ذات المهارات المكملة تعمل معًا بكفاءة أكبر
+3. **أداء المهام**: الـ Agents ذات الأدوار والأهداف الواضحة تنفذ المهام بفعالية أكبر
+4. **قابلية التوسع**: الـ Agents المصممة بعناية يمكن إعادة استخدامها عبر Crews وسياقات متعددة
+
+لنستكشف أفضل الممارسات لإنشاء Agents تتفوق في هذه الأبعاد.
+
+## قاعدة 80/20: ركّز على المهام أكثر من الـ Agents
+
+عند بناء أنظمة AI فعّالة، تذكر هذا المبدأ الحاسم: **80% من جهدك يجب أن يذهب لتصميم المهام، و20% فقط لتعريف الـ Agents**.
+
+لماذا؟ لأن حتى أفضل Agent معرّف سيفشل مع مهام مصممة بشكل سيئ، لكن المهام المصممة جيدًا يمكنها رفع مستوى حتى Agent بسيط. هذا يعني:
+
+- اقضِ معظم وقتك في كتابة تعليمات مهام واضحة
+- حدد المدخلات والمخرجات المتوقعة بالتفصيل
+- أضف أمثلة وسياقًا لتوجيه التنفيذ
+- خصص الوقت المتبقي لدور Agent وهدفه وخلفيته
+
+هذا لا يعني أن تصميم الـ Agent ليس مهمًا - بل هو مهم بالتأكيد. لكن تصميم المهام هو حيث تحدث معظم إخفاقات التنفيذ، لذا رتّب أولوياتك وفقًا لذلك.
+
+## المبادئ الأساسية لتصميم Agent فعّال
+
+### 1. إطار الدور-الهدف-الخلفية
+
+أقوى الـ Agents في CrewAI مبنية على أساس قوي من ثلاثة عناصر رئيسية:
+
+#### الدور: الوظيفة المتخصصة للـ Agent
+
+يحدد الدور ما يفعله الـ Agent ومجال خبرته. عند صياغة الأدوار:
+
+- **كن محددًا ومتخصصًا**: بدلاً من "كاتب"، استخدم "متخصص في التوثيق التقني" أو "راوي قصص إبداعي"
+- **تماشَ مع المهن الواقعية**: ابنِ الأدوار على نماذج مهنية معروفة
+- **تضمين خبرة المجال**: حدد مجال معرفة الـ Agent (مثل "محلل مالي متخصص في اتجاهات السوق")
+
+**أمثلة على أدوار فعّالة:**
+```yaml
+role: "Senior UX Researcher specializing in user interview analysis"
+role: "Full-Stack Software Architect with expertise in distributed systems"
+role: "Corporate Communications Director specializing in crisis management"
+```
+
+#### الهدف: غرض الـ Agent ودافعه
+
+يوجه الهدف جهود الـ Agent ويشكّل عملية صنع القرار. الأهداف الفعّالة يجب أن:
+
+- **تكون واضحة ومركّزة على النتائج**: حدد ما يحاول الـ Agent تحقيقه
+- **تؤكد على معايير الجودة**: تضمين توقعات حول جودة العمل
+- **تتضمن معايير النجاح**: ساعد الـ Agent على فهم ما يعنيه "الجيد"
+
+**أمثلة على أهداف فعّالة:**
+```yaml
+goal: "Uncover actionable user insights by analyzing interview data and identifying recurring patterns, unmet needs, and improvement opportunities"
+goal: "Design robust, scalable system architectures that balance performance, maintainability, and cost-effectiveness"
+goal: "Craft clear, empathetic crisis communications that address stakeholder concerns while protecting organizational reputation"
+```
+
+#### الخلفية: تجربة الـ Agent ومنظوره
+
+تمنح الخلفية عمقًا لشخصية الـ Agent، مؤثرة في كيفية تعامله مع المشكلات وتفاعله مع الآخرين. الخلفيات الجيدة:
+
+- **تؤسس الخبرة والتجربة**: تشرح كيف اكتسب الـ Agent مهاراته
+- **تحدد أسلوب العمل والقيم**: تصف كيف يتعامل الـ Agent مع عمله
+- **تنشئ شخصية متماسكة**: تضمن أن جميع عناصر الخلفية تتماشى مع الدور والهدف
+
+**أمثلة على خلفيات فعّالة:**
+```yaml
+backstory: "You have spent 15 years conducting and analyzing user research for top tech companies. You have a talent for reading between the lines and identifying patterns that others miss. You believe that good UX is invisible and that the best insights come from listening to what users don't say as much as what they do say."
+
+backstory: "With 20+ years of experience building distributed systems at scale, you've developed a pragmatic approach to software architecture. You've seen both successful and failed systems and have learned valuable lessons from each. You balance theoretical best practices with practical constraints and always consider the maintenance and operational aspects of your designs."
+
+backstory: "As a seasoned communications professional who has guided multiple organizations through high-profile crises, you understand the importance of transparency, speed, and empathy in crisis response. You have a methodical approach to crafting messages that address concerns while maintaining organizational credibility."
+```
+
+### 2. المتخصصون أفضل من العموميين
+
+يؤدي الـ Agents أداءً أفضل بشكل ملحوظ عند منحهم أدوارًا متخصصة بدلاً من عامة. الـ Agent المركّز بشدة ينتج مخرجات أكثر دقة وصلة:
+
+**عام (أقل فعالية):**
+```yaml
+role: "Writer"
+```
+
+**متخصص (أكثر فعالية):**
+```yaml
+role: "Technical Blog Writer specializing in explaining complex AI concepts to non-technical audiences"
+```
+
+**فوائد التخصص:**
+- فهم أوضح للمخرجات المتوقعة
+- أداء أكثر اتساقًا
+- توافق أفضل مع المهام المحددة
+- قدرة محسّنة على إصدار أحكام خاصة بالمجال
+
+### 3. التوازن بين التخصص والمرونة
+
+الـ Agents الفعّالة تحقق التوازن الصحيح بين التخصص (القيام بشيء واحد بشكل ممتاز) والمرونة (التكيف مع مواقف متنوعة):
+
+- **تخصص في الدور، مرونة في التطبيق**: أنشئ Agents بمهارات متخصصة يمكن تطبيقها عبر سياقات متعددة
+- **تجنب التعريفات الضيقة جدًا**: تأكد من أن الـ Agents يمكنها التعامل مع التنوعات ضمن مجال خبرتها
+- **ضع في الاعتبار السياق التعاوني**: صمم Agents تكمّل تخصصاتها الـ Agents الأخرى التي ستعمل معها
+
+### 4. تعيين مستويات الخبرة المناسبة
+
+مستوى الخبرة الذي تعيّنه للـ Agent يشكّل كيفية تعامله مع المهام:
+
+- **Agents مبتدئة**: جيدة للمهام المباشرة والعصف الذهني والمسودات الأولية
+- **Agents متوسطة**: مناسبة لمعظم المهام القياسية مع تنفيذ موثوق
+- **Agents خبيرة**: الأفضل للمهام المعقدة والمتخصصة التي تتطلب عمقًا ودقة
+- **Agents على مستوى عالمي**: محجوزة للمهام الحرجة حيث الجودة الاستثنائية مطلوبة
+
+اختر مستوى الخبرة المناسب بناءً على تعقيد المهمة ومتطلبات الجودة. لمعظم Crews التعاونية، غالبًا ما يعمل مزيج من مستويات الخبرة بشكل أفضل، مع تعيين خبرة أعلى للوظائف المتخصصة الأساسية.
+
+## أمثلة عملية: قبل وبعد
+
+لنلقِ نظرة على بعض أمثلة تعريفات الـ Agent قبل وبعد تطبيق أفضل الممارسات:
+
+### مثال 1: Agent إنشاء المحتوى
+
+**قبل:**
+```yaml
+role: "Writer"
+goal: "Write good content"
+backstory: "You are a writer who creates content for websites."
+```
+
+**بعد:**
+```yaml
+role: "B2B Technology Content Strategist"
+goal: "Create compelling, technically accurate content that explains complex topics in accessible language while driving reader engagement and supporting business objectives"
+backstory: "You have spent a decade creating content for leading technology companies, specializing in translating technical concepts for business audiences. You excel at research, interviewing subject matter experts, and structuring information for maximum clarity and impact. You believe that the best B2B content educates first and sells second, building trust through genuine expertise rather than marketing hype."
+```
+
+### مثال 2: Agent البحث
+
+**قبل:**
+```yaml
+role: "Researcher"
+goal: "Find information"
+backstory: "You are good at finding information online."
+```
+
+**بعد:**
+```yaml
+role: "Academic Research Specialist in Emerging Technologies"
+goal: "Discover and synthesize cutting-edge research, identifying key trends, methodologies, and findings while evaluating the quality and reliability of sources"
+backstory: "With a background in both computer science and library science, you've mastered the art of digital research. You've worked with research teams at prestigious universities and know how to navigate academic databases, evaluate research quality, and synthesize findings across disciplines. You're methodical in your approach, always cross-referencing information and tracing claims to primary sources before drawing conclusions."
+```
+
+## صياغة مهام فعّالة للـ Agents
+
+بينما تصميم الـ Agent مهم، تصميم المهام حاسم للتنفيذ الناجح. إليك أفضل الممارسات لتصميم مهام تهيئ الـ Agents للنجاح:
+
+### تشريح المهمة الفعّالة
+
+المهمة المصممة جيدًا لها مكونان رئيسيان يخدمان أغراضًا مختلفة:
+
+#### وصف المهمة: العملية
+يجب أن يركز الوصف على ماذا تفعل وكيف تفعله، بما في ذلك:
+- تعليمات مفصلة للتنفيذ
+- سياق ومعلومات خلفية
+- النطاق والقيود
+- خطوات العملية المتبعة
+
+#### المخرجات المتوقعة: التسليم
+يجب أن تحدد المخرجات المتوقعة شكل النتيجة النهائية:
+- مواصفات التنسيق (markdown، JSON، إلخ)
+- متطلبات الهيكل
+- معايير الجودة
+- أمثلة على مخرجات جيدة (عند الإمكان)
+
+### أفضل ممارسات تصميم المهام
+
+#### 1. غرض واحد، مخرج واحد
+تؤدي المهام أفضل أداء عند التركيز على هدف واضح واحد:
+
+**مثال سيئ (واسع جدًا):**
+```yaml
+task_description: "Research market trends, analyze the data, and create a visualization."
+```
+
+**مثال جيد (مركّز):**
+```yaml
+# Task 1
+research_task:
+  description: "Research the top 5 market trends in the AI industry for 2024."
+  expected_output: "A markdown list of the 5 trends with supporting evidence."
+
+# Task 2
+analysis_task:
+  description: "Analyze the identified trends to determine potential business impacts."
+  expected_output: "A structured analysis with impact ratings (High/Medium/Low)."
+
+# Task 3
+visualization_task:
+  description: "Create a visual representation of the analyzed trends."
+  expected_output: "A description of a chart showing trends and their impact ratings."
+```
+
+#### 2. كن صريحًا بشأن المدخلات والمخرجات
+حدد دائمًا بوضوح ما المدخلات التي ستستخدمها المهمة وكيف يجب أن تبدو المخرجات:
+
+**مثال:**
+```yaml
+analysis_task:
+  description: >
+    Analyze the customer feedback data from the CSV file.
+    Focus on identifying recurring themes related to product usability.
+    Consider sentiment and frequency when determining importance.
+  expected_output: >
+    A markdown report with the following sections:
+    1. Executive summary (3-5 bullet points)
+    2. Top 3 usability issues with supporting data
+    3. Recommendations for improvement
+```
+
+#### 3. تضمين الغرض والسياق
+اشرح لماذا تهم المهمة وكيف تتناسب مع سير العمل الأكبر:
+
+**مثال:**
+```yaml
+competitor_analysis_task:
+  description: >
+    Analyze our three main competitors' pricing strategies.
+    This analysis will inform our upcoming pricing model revision.
+    Focus on identifying patterns in how they price premium features
+    and how they structure their tiered offerings.
+```
+
+#### 4. استخدام أدوات المخرجات المنظمة
+للمخرجات القابلة للقراءة آليًا، حدد التنسيق بوضوح:
+
+**مثال:**
+```yaml
+data_extraction_task:
+  description: "Extract key metrics from the quarterly report."
+  expected_output: "JSON object with the following keys: revenue, growth_rate, customer_acquisition_cost, and retention_rate."
+```
+
+## أخطاء شائعة يجب تجنبها
+
+بناءً على الدروس المستفادة من التطبيقات الواقعية، إليك أكثر المزالق شيوعًا في تصميم الـ Agent والمهام:
+
+### 1. تعليمات مهام غير واضحة
+
+**المشكلة:** تفتقر المهام لتفاصيل كافية مما يصعّب على الـ Agents تنفيذها بفعالية.
+
+**مثال تصميم سيئ:**
+```yaml
+research_task:
+  description: "Research AI trends."
+  expected_output: "A report on AI trends."
+```
+
+**نسخة محسّنة:**
+```yaml
+research_task:
+  description: >
+    Research the top emerging AI trends for 2024 with a focus on:
+    1. Enterprise adoption patterns
+    2. Technical breakthroughs in the past 6 months
+    3. Regulatory developments affecting implementation
+
+    For each trend, identify key companies, technologies, and potential business impacts.
+  expected_output: >
+    A comprehensive markdown report with:
+    - Executive summary (5 bullet points)
+    - 5-7 major trends with supporting evidence
+    - For each trend: definition, examples, and business implications
+    - References to authoritative sources
+```
+
+### 2. "مهام إلهية" تحاول فعل الكثير
+
+**المشكلة:** مهام تجمع عمليات معقدة متعددة في مجموعة تعليمات واحدة.
+
+**مثال تصميم سيئ:**
+```yaml
+comprehensive_task:
+  description: "Research market trends, analyze competitor strategies, create a marketing plan, and design a launch timeline."
+```
+
+**نسخة محسّنة:**
+قسّمها إلى مهام متسلسلة ومركّزة:
+```yaml
+# Task 1: Research
+market_research_task:
+  description: "Research current market trends in the SaaS project management space."
+  expected_output: "A markdown summary of key market trends."
+
+# Task 2: Competitive Analysis
+competitor_analysis_task:
+  description: "Analyze strategies of the top 3 competitors based on the market research."
+  expected_output: "A comparison table of competitor strategies."
+  context: [market_research_task]
+
+# Continue with additional focused tasks...
+```
+
+### 3. عدم توافق الوصف والمخرجات المتوقعة
+
+**المشكلة:** وصف المهمة يطلب شيئًا بينما المخرجات المتوقعة تحدد شيئًا مختلفًا.
+
+**مثال تصميم سيئ:**
+```yaml
+analysis_task:
+  description: "Analyze customer feedback to find areas of improvement."
+  expected_output: "A marketing plan for the next quarter."
+```
+
+**نسخة محسّنة:**
+```yaml
+analysis_task:
+  description: "Analyze customer feedback to identify the top 3 areas for product improvement."
+  expected_output: "A report listing the 3 priority improvement areas with supporting customer quotes and data points."
+```
+
+### 4. عدم فهم العملية بنفسك
+
+**المشكلة:** مطالبة الـ Agents بتنفيذ مهام لا تفهمها أنت بالكامل.
+
+**الحل:**
+1. حاول تنفيذ المهمة يدويًا أولاً
+2. وثّق عمليتك ونقاط القرار ومصادر المعلومات
+3. استخدم هذا التوثيق كأساس لوصف مهمتك
+
+### 5. الاستخدام المبكر للهياكل الهرمية
+
+**المشكلة:** إنشاء هرميات Agents معقدة بلا داعٍ حيث تعمل العمليات المتسلسلة بشكل أفضل.
+
+**الحل:** ابدأ بالعمليات المتسلسلة وانتقل إلى النماذج الهرمية فقط عندما يتطلب تعقيد سير العمل ذلك حقًا.
+
+### 6. تعريفات Agent غامضة أو عامة
+
+**المشكلة:** تعريفات Agent العامة تؤدي لمخرجات عامة.
+
+**مثال تصميم سيئ:**
+```yaml
+agent:
+  role: "Business Analyst"
+  goal: "Analyze business data"
+  backstory: "You are good at business analysis."
+```
+
+**نسخة محسّنة:**
+```yaml
+agent:
+  role: "SaaS Metrics Specialist focusing on growth-stage startups"
+  goal: "Identify actionable insights from business data that can directly impact customer retention and revenue growth"
+  backstory: "With 10+ years analyzing SaaS business models, you've developed a keen eye for the metrics that truly matter for sustainable growth. You've helped numerous companies identify the leverage points that turned around their business trajectory. You believe in connecting data to specific, actionable recommendations rather than general observations."
+```
+
+## استراتيجيات متقدمة لتصميم الـ Agent
+
+### التصميم للتعاون
+
+عند إنشاء Agents ستعمل معًا في Crew، ضع في اعتبارك:
+
+- **مهارات مكملة**: صمم Agents بقدرات مميزة ومكملة
+- **نقاط التسليم**: حدد واجهات واضحة لكيفية انتقال العمل بين الـ Agents
+- **توتر بنّاء**: أحيانًا، إنشاء Agents بمنظورات مختلفة قليلاً يمكن أن يؤدي لنتائج أفضل من خلال حوار منتج
+
+على سبيل المثال، قد يتضمن Crew إنشاء محتوى:
+
+```yaml
+# Research Agent
+role: "Research Specialist for technical topics"
+goal: "Gather comprehensive, accurate information from authoritative sources"
+backstory: "You are a meticulous researcher with a background in library science..."
+
+# Writer Agent
+role: "Technical Content Writer"
+goal: "Transform research into engaging, clear content that educates and informs"
+backstory: "You are an experienced writer who excels at explaining complex concepts..."
+
+# Editor Agent
+role: "Content Quality Editor"
+goal: "Ensure content is accurate, well-structured, and polished while maintaining consistency"
+backstory: "With years of experience in publishing, you have a keen eye for detail..."
+```
+
+### إنشاء مستخدمي أدوات متخصصين
+
+يمكن تصميم بعض الـ Agents خصيصًا للاستفادة من أدوات معينة بفعالية:
+
+```yaml
+role: "Data Analysis Specialist"
+goal: "Derive meaningful insights from complex datasets through statistical analysis"
+backstory: "With a background in data science, you excel at working with structured and unstructured data..."
+tools: [PythonREPLTool, DataVisualizationTool, CSVAnalysisTool]
+```
+
+### تكييف الـ Agents مع قدرات LLM
+
+للنماذج المختلفة نقاط قوة مختلفة. صمم الـ Agents مع وضع هذه القدرات في الاعتبار:
+
+```yaml
+# For complex reasoning tasks
+analyst:
+  role: "Data Insights Analyst"
+  goal: "..."
+  backstory: "..."
+  llm: openai/gpt-4o
+
+# For creative content
+writer:
+  role: "Creative Content Writer"
+  goal: "..."
+  backstory: "..."
+  llm: anthropic/claude-3-opus
+```
+
+## اختبار تصميم الـ Agent والتكرار عليه
+
+تصميم الـ Agent غالبًا عملية تكرارية. إليك نهجًا عمليًا:
+
+1. **ابدأ بنموذج أولي**: أنشئ تعريف Agent أولي
+2. **اختبر مع مهام نموذجية**: قيّم الأداء على مهام تمثيلية
+3. **حلل المخرجات**: حدد نقاط القوة والضعف
+4. **صقل التعريف**: اضبط الدور والهدف والخلفية بناءً على الملاحظات
+5. **اختبر في بيئة تعاونية**: قيّم كيف يعمل الـ Agent في إعداد Crew
+
+## الخلاصة
+
+صياغة Agents فعّالة هي فن وعلم في آن واحد. من خلال تعريف الأدوار والأهداف والخلفيات بعناية بما يتماشى مع احتياجاتك المحددة، ودمجها مع مهام مصممة جيدًا، يمكنك إنشاء متعاونين AI متخصصين ينتجون نتائج استثنائية.
+
+تذكر أن تصميم الـ Agent والمهام عملية تكرارية. ابدأ بأفضل الممارسات هذه، وراقب الـ Agents أثناء العمل، وصقل نهجك بناءً على ما تتعلمه. وتذكر دائمًا قاعدة 80/20 - ركّز معظم جهدك على إنشاء مهام واضحة ومركّزة للحصول على أفضل النتائج من الـ Agents.
+
+<Check>
+تهانينا! أنت الآن تفهم مبادئ وممارسات تصميم Agent الفعّال. طبّق هذه التقنيات لإنشاء Agents قوية ومتخصصة تعمل معًا بسلاسة لإنجاز مهام معقدة.
+</Check>
+
+## الخطوات التالية
+
+- جرّب تهيئات Agent مختلفة لحالة استخدامك المحددة
+- تعلم عن [بناء أول Crew](/ar/guides/crews/first-crew) لمعرفة كيف تعمل الـ Agents معًا
+- استكشف [CrewAI Flows](/ar/guides/flows/first-flow) لتنسيق أكثر تقدمًا

docs/v1.15.19/ar/guides/coding-tools/agents-md.mdx

@@ -0,0 +1,61 @@
+---
+title: أدوات البرمجة
+description: استخدم AGENTS.md لتوجيه أدوات البرمجة وبيئات التطوير عبر مشاريع CrewAI.
+icon: terminal
+mode: "wide"
+---
+
+## لماذا AGENTS.md
+
+`AGENTS.md` هو ملف تعليمات خفيف محلي للمستودع يمنح أدوات البرمجة توجيهات متسقة خاصة بالمشروع. ضعه في جذر المشروع واعتبره المصدر الموثوق لكيفية عمل المساعدين: الاصطلاحات والأوامر وملاحظات البنية والحدود.
+
+## إنشاء مشروع باستخدام CLI
+
+استخدم CLI الخاص بـ CrewAI لإنشاء هيكل مشروع، وسيُضاف `AGENTS.md` تلقائيًا في الجذر.
+
+```bash
+# Crew
+crewai create crew my_crew
+
+# Flow
+crewai create flow my_flow
+
+# Tool repository
+crewai tool create my_tool
+```
+
+## إعداد الأدوات: توجيه المساعدين إلى AGENTS.md
+
+### Codex
+
+يمكن توجيه Codex بملفات `AGENTS.md` الموضوعة في مستودعك. استخدمها لتوفير سياق مشروع مستمر مثل الاصطلاحات والأوامر وتوقعات سير العمل.
+
+### Claude Code
+
+يخزّن Claude Code ذاكرة المشروع في `CLAUDE.md`. يمكنك تهيئته بـ `/init` وتحريره باستخدام `/memory`. يدعم Claude Code أيضًا الاستيرادات داخل `CLAUDE.md`، فيمكنك إضافة سطر واحد مثل `@AGENTS.md` لسحب التعليمات المشتركة دون تكرارها.
+
+يمكنك ببساطة استخدام:
+
+```bash
+mv AGENTS.md CLAUDE.md
+```
+
+### Gemini CLI وGoogle Antigravity
+
+يقوم Gemini CLI وAntigravity بتحميل ملف سياق المشروع (الافتراضي: `GEMINI.md`) من جذر المستودع والمجلدات الأصلية. يمكنك تهيئته لقراءة `AGENTS.md` بدلاً من ذلك (أو بالإضافة إليه) بتعيين `context.fileName` في إعدادات Gemini CLI. على سبيل المثال، عيّنه إلى `AGENTS.md` فقط، أو أدرج كلاً من `AGENTS.md` و`GEMINI.md` إذا أردت الاحتفاظ بتنسيق كل أداة.
+
+يمكنك ببساطة استخدام:
+
+```bash
+mv AGENTS.md GEMINI.md
+```
+
+### Cursor
+
+يدعم Cursor ملف `AGENTS.md` كملف تعليمات مشروع. ضعه في جذر المشروع لتوفير توجيهات لمساعد البرمجة في Cursor.
+
+### Windsurf
+
+يوفر Claude Code تكاملاً رسميًا مع Windsurf. إذا كنت تستخدم Claude Code داخل Windsurf، اتبع توجيهات Claude Code أعلاه واستورد `AGENTS.md` من `CLAUDE.md`.
+
+إذا كنت تستخدم مساعد Windsurf الأصلي، هيّئ ميزة قواعد أو تعليمات المشروع (إذا كانت متاحة) لقراءة `AGENTS.md` أو الصق المحتويات مباشرة.

docs/v1.15.19/ar/guides/coding-tools/build-with-ai.mdx

@@ -0,0 +1,214 @@
+---
+title: "البناء باستخدام الذكاء الاصطناعي"
+description: "كل ما يحتاجه وكلاء البرمجة بالذكاء الاصطناعي للبناء والنشر والتوسع مع CrewAI — المهارات، وثائق مقروءة آلياً، النشر، وميزات المؤسسات."
+icon: robot
+mode: "wide"
+---
+
+# البناء باستخدام الذكاء الاصطناعي
+
+CrewAI مُصمَّم أصلاً للعمل مع الذكاء الاصطناعي. تجمع هذه الصفحة ما يحتاجه وكيل البرمجة بالذكاء الاصطناعي للبناء مع CrewAI — سواءً كان Claude Code أو Codex أو Cursor أو Gemini CLI أو أي مساعد آخر يساعد المطوّر على إيصال الـ crews والـ flows.
+
+### وكلاء البرمجة المدعومون
+
+<CardGroup cols={5}>
+  <Card title="Claude Code" icon="message-bot" color="#D97706" />
+  <Card title="Cursor" icon="arrow-pointer" color="#3B82F6" />
+  <Card title="Codex" icon="terminal" color="#10B981" />
+  <Card title="Windsurf" icon="wind" color="#06B6D4" />
+  <Card title="Gemini CLI" icon="sparkles" color="#8B5CF6" />
+</CardGroup>
+
+<Note>
+  صُممت هذه الصفحة للبشر وللمساعدين الذكيين على حدٍّ سواء. إذا كنت وكيل برمجة، ابدأ بـ **Skills** للحصول على سياق CrewAI، ثم استخدم **llms.txt** للوصول الكامل إلى الوثائق.
+</Note>
+
+---
+
+## 1. Skills — علِّم وكيلك CrewAI
+
+**Skills** حزم تعليمات تمنح وكلاء البرمجة معرفة عميقة بـ CrewAI — كيفية إنشاء هيكل Flows، وضبط Crews، استخدام الأدوات، واتباع اتفاقيات الإطار.
+
+<Tabs>
+  <Tab title="Claude Code (سوق الإضافات)">
+    <img src="https://cdn.simpleicons.org/anthropic/D97706" alt="Anthropic" width="28" style={{display: "inline", verticalAlign: "middle", marginRight: "8px"}} />
+    مهارات CrewAI متاحة في **سوق إضافات Claude Code** — نفس قناة التوزيع التي تستخدمها شركات رائدة في مجال الذكاء الاصطناعي:
+    ```shell
+    /plugin marketplace add crewAIInc/skills
+    /plugin install crewai-skills@crewai-plugins
+    /reload-plugins
+    ```
+
+    تُفعَّل أربع مهارات تلقائياً عند طرح أسئلة متعلقة بـ CrewAI:
+
+    | المهارة | متى تُستخدم |
+    |---------|-------------|
+    | `getting-started` | مشاريع جديدة، الاختيار بين `LLM.call()` / `Agent` / `Crew` / `Flow`، ربط `crew.jsonc` / `main.py` |
+    | `design-agent` | ضبط الوكلاء — الدور، الهدف، الخلفية، الأدوات، نماذج اللغة، الذاكرة، الحدود الآمنة |
+    | `design-task` | وصف المهام، التبعيات، المخرجات المنظمة (`output_pydantic`، `output_json`)، المراجعة البشرية |
+    | `ask-docs` | الاستعلام من [خادم CrewAI docs MCP](https://docs.crewai.com/mcp) للحصول على تفاصيل واجهة البرمجة الحالية |
+  </Tab>
+  <Tab title="npx (أي وكيل)">
+    يعمل مع Claude Code أو Codex أو Cursor أو Gemini CLI أو أي وكيل برمجة:
+    ```shell
+    npx skills add crewaiinc/skills
+    ```
+    يُجلب من [سجل skills.sh](https://skills.sh/crewaiinc/skills).
+  </Tab>
+</Tabs>
+
+<Steps>
+  <Step title="ثبِّت حزمة المهارات الرسمية">
+    استخدم إحدى الطريقتين أعلاه — سوق إضافات Claude Code أو `npx skills add`. كلاهما يثبّت الحزمة الرسمية [crewAIInc/skills](https://github.com/crewAIInc/skills).
+  </Step>
+  <Step title="يحصل وكيلك فوراً على خبرة CrewAI">
+    تعلّم الحزمة وكيلك:
+    - **Flows** — تطبيقات ذات حالة، خطوات، وتشغيل crews
+    - **Crews والوكلاء** — أنماط JSON-first (`crew.jsonc` و `agents/*.jsonc`)، الأدوار، المهام، التفويض
+    - **الأدوات والتكاملات** — البحث، واجهات API، خوادم MCP، وأدوات CrewAI الشائعة
+    - **هيكل المشروع** — هياكل CLI واتفاقيات المستودع
+    - **أنماط محدثة** — يتماشى مع وثائق CrewAI الحالية وأفضل الممارسات
+  </Step>
+  <Step title="ابدأ البناء">
+    يمكن لوكيلك الآن إنشاء هيكل وبناء مشاريع CrewAI دون أن تعيد شرح الإطار في كل جلسة.
+  </Step>
+</Steps>
+
+<CardGroup cols={2}>
+  <Card title="مفهوم Skills" icon="bolt" href="/ar/concepts/skills">
+    كيف تعمل المهارات في وكلاء CrewAI — الحقن، التفعيل، والأنماط.
+  </Card>
+  <Card title="صفحة Skills" icon="wand-magic-sparkles" href="/ar/skills">
+    نظرة على حزمة crewAIInc/skills وما تتضمنه.
+  </Card>
+  <Card title="AGENTS.md والأدوات" icon="terminal" href="/ar/guides/coding-tools/agents-md">
+    إعداد AGENTS.md لـ Claude Code وCodex وCursor وGemini CLI.
+  </Card>
+  <Card title="سجل skills.sh" icon="globe" href="https://skills.sh/crewaiinc/skills">
+    القائمة الرسمية — المهارات، إحصاءات التثبيت، والتدقيق.
+  </Card>
+</CardGroup>
+
+---
+
+## 2. llms.txt — وثائق مقروءة آلياً
+
+ينشر CrewAI ملف `llms.txt` يمنح المساعدين الذكيين وصولاً مباشراً إلى الوثائق الكاملة بصيغة مقروءة آلياً.
+
+```
+https://docs.crewai.com/llms.txt
+```
+
+<Tabs>
+  <Tab title="ما هو llms.txt؟">
+    [`llms.txt`](https://llmstxt.org/) معيار ناشئ لجعل الوثائق قابلة للاستهلاك من قبل نماذج اللغة الكبيرة. بدلاً من استخراج HTML، يمكن لوكيلك جلب ملف نصي واحد منظم بكل المحتوى المطلوب.
+
+    ملف `llms.txt` الخاص بـ CrewAI **متاح فعلياً** — يمكن لوكيلك استخدامه الآن.
+  </Tab>
+  <Tab title="كيفية الاستخدام">
+    وجِّه وكيل البرمجة إلى عنوان URL عندما يحتاج إلى مرجع CrewAI:
+
+    ```
+    Fetch https://docs.crewai.com/llms.txt for CrewAI documentation.
+    ```
+
+    يمكن للعديد من وكلاء البرمجة (Claude Code، Cursor، وغيرهما) جلب عناوين URL مباشرة. يحتوي الملف على وثائق منظمة تغطي مفاهيم CrewAI وواجهات البرمجة والأدلة.
+  </Tab>
+  <Tab title="لماذا يهم">
+    - **دون استخراج ويب** — محتوى نظيف ومنظم في طلب واحد
+    - **دائماً محدث** — يُقدَّم مباشرة من docs.crewai.com
+    - **محسّن لنماذج اللغة** — مُنسَّق لنوافذ السياق لا للمتصفحات
+    - **يُكمّل Skills** — المهارات تعلّم الأنماط، وllms.txt يوفّر المرجع
+  </Tab>
+</Tabs>
+
+---
+
+## 3. النشر للمؤسسات
+
+انتقل من crew محلي إلى الإنتاج على **CrewAI AMP** (منصة إدارة الوكلاء) في دقائق.
+
+<Steps>
+  <Step title="ابنِ محلياً">
+    أنشئ الهيكل واختبر crew أو flow:
+    ```bash
+    crewai create crew my_crew
+    cd my_crew
+    crewai run
+    ```
+  </Step>
+  <Step title="جهّز للنشر">
+    تأكد أن هيكل مشروعك جاهز:
+    ```bash
+    crewai deploy --prepare
+    ```
+    راجع [دليل التحضير](https://docs-platform.crewai.com/platform/ar/guides/prepare-for-deployment) لتفاصيل الهيكل والمتطلبات.
+  </Step>
+  <Step title="انشر على AMP">
+    ادفع إلى منصة CrewAI AMP:
+    ```bash
+    crewai deploy
+    ```
+    يمكنك أيضاً النشر عبر [تكامل GitHub](https://docs-platform.crewai.com/platform/ar/guides/deploy-to-amp) أو [Crew Studio](https://docs-platform.crewai.com/platform/ar/guides/enable-crew-studio).
+  </Step>
+  <Step title="الوصول عبر API">
+    يحصل الـ crew المنشور على نقطة نهاية REST. دمجه في أي تطبيق:
+    ```bash
+    curl -X POST https://app.crewai.com/api/v1/crews/<crew-id>/kickoff \
+      -H "Authorization: Bearer $CREWAI_API_KEY" \
+      -H "Content-Type: application/json" \
+      -d '{"inputs": {"topic": "AI agents"}}'
+    ```
+  </Step>
+</Steps>
+
+<CardGroup cols={2}>
+  <Card title="النشر على AMP" icon="rocket" href="https://docs-platform.crewai.com/platform/ar/guides/deploy-to-amp">
+    دليل النشر الكامل — CLI وGitHub وCrew Studio.
+  </Card>
+  <Card title="مقدمة عن AMP" icon="globe" href="https://docs-platform.crewai.com/platform/ar/introduction">
+    نظرة على المنصة — ما يوفّره AMP لـ crews في الإنتاج.
+  </Card>
+</CardGroup>
+
+---
+
+## 4. ميزات المؤسسات
+
+CrewAI AMP مُصمَّم لفرق الإنتاج. إليك ما تحصل عليه بعد النشر.
+
+<CardGroup cols={2}>
+  <Card title="المراقبة والرصد" icon="chart-line">
+    مسارات تنفيذ مفصّلة، وسجلات، ومقاييس أداء لكل تشغيل crew. راقب قرارات الوكلاء، استدعاءات الأدوات، وإكمال المهام في الوقت الفعلي.
+  </Card>
+  <Card title="Crew Studio" icon="paintbrush">
+    واجهة منخفضة/بدون كود لإنشاء crews وتخصيصها ونشرها بصرياً — ثم التصدير إلى الشيفرة أو النشر مباشرة.
+  </Card>
+  <Card title="بث الويبهوك" icon="webhook">
+    بث أحداث فورية من تنفيذات الـ crews إلى أنظمتك. تكامل مع Slack أو Zapier أو أي مستهلك ويبهوك.
+  </Card>
+  <Card title="إدارة الفريق" icon="users">
+    SSO وRBAC وضوابط على مستوى المؤسسة. أدر من يمكنه إنشاء crews ونشرها والوصول إليها.
+  </Card>
+  <Card title="مستودع الأدوات" icon="toolbox">
+    انشر وشارك أدواتاً مخصصة عبر مؤسستك. ثبّت أدوات المجتمع من السجل.
+  </Card>
+  <Card title="Factory (استضافة ذاتية)" icon="server">
+    شغّل CrewAI AMP على بنيتك التحتية. قدرات المنصة كاملة مع ضوابط إقامة البيانات والامتثال.
+  </Card>
+</CardGroup>
+
+<AccordionGroup>
+  <Accordion title="لمن مخصص AMP؟">
+    لفرق تحتاج نقل سير عمل وكلاء الذكاء الاصطناعي من النماذج الأولية إلى الإنتاج — مع المراقبة وضوابط الوصول والبنية التحتية القابلة للتوسع. سواءً كنت ناشئاً أو مؤسسة كبيرة، يتولى AMP التعقيد التشغيلي لتتفرغ لبناء الوكلاء.
+  </Accordion>
+  <Accordion title="ما خيارات النشر المتاحة؟">
+    - **السحابة (app.crewai.com)** — تُدار من CrewAI، أسرع طريق إلى الإنتاج
+    - **Factory (استضافة ذاتية)** — على بنيتك التحتية لسيطرة كاملة على البيانات
+    - **هجين** — دمج السحابة والاستضافة الذاتية حسب حساسية البيانات
+  </Accordion>
+</AccordionGroup>
+
+<Card title="استكشف CrewAI AMP →" icon="arrow-right" href="https://app.crewai.com">
+  سجّل وانشر أول crew لك في الإنتاج.
+</Card>

docs/v1.15.19/ar/guides/concepts/evaluating-use-cases.mdx

@@ -0,0 +1,485 @@
+---
+title: تقييم حالات الاستخدام لـ CrewAI
+description: تعلم كيفية تقييم احتياجات تطبيقات الذكاء الاصطناعي واختيار النهج الصحيح بين Crews وFlows بناءً على متطلبات التعقيد والدقة.
+icon: scale-balanced
+mode: "wide"
+---
+
+## فهم إطار القرار
+
+عند بناء تطبيقات ذكاء اصطناعي مع CrewAI، أحد أهم القرارات التي ستتخذها هو اختيار النهج الصحيح لحالة الاستخدام المحددة. هل يجب استخدام Crew؟ أم Flow؟ أم مزيج من كليهما؟ سيساعدك هذا الدليل على تقييم متطلباتك واتخاذ قرارات معمارية مدروسة.
+
+في جوهر هذا القرار فهم العلاقة بين **التعقيد** و**الدقة** في تطبيقك:
+
+<Frame caption="مصفوفة التعقيد مقابل الدقة لتطبيقات CrewAI">
+  <img src="/images/complexity_precision.png" alt="مصفوفة التعقيد مقابل الدقة" />
+</Frame>
+
+تساعد هذه المصفوفة في تصور كيف تتوافق النهج المختلفة مع متطلبات متفاوتة للتعقيد والدقة. لنستكشف ما يعنيه كل ربع وكيف يوجه خياراتك المعمارية.
+
+## شرح مصفوفة التعقيد-الدقة
+
+### ما هو التعقيد؟
+
+في سياق تطبيقات CrewAI، يشير **التعقيد** إلى:
+
+- عدد الخطوات أو العمليات المميزة المطلوبة
+- تنوع المهام التي يجب تنفيذها
+- التبعيات المتبادلة بين المكونات المختلفة
+- الحاجة للمنطق الشرطي والتفرع
+- تطور سير العمل الكلي
+
+### ما هي الدقة؟
+
+**الدقة** في هذا السياق تشير إلى:
+
+- الدقة المطلوبة في المخرجات النهائية
+- الحاجة لنتائج منظمة وقابلة للتنبؤ
+- أهمية إمكانية التكرار
+- مستوى التحكم المطلوب في كل خطوة
+- تحمّل التباين في المخرجات
+
+### الأرباع الأربعة
+
+#### 1. تعقيد منخفض، دقة منخفضة
+
+**الخصائص:**
+- مهام بسيطة ومباشرة
+- تحمّل بعض التباين في المخرجات
+- عدد محدود من الخطوات
+- تطبيقات إبداعية أو استكشافية
+
+**النهج الموصى به:** Crews بسيطة مع عدد قليل من الـ Agents
+
+**أمثلة على حالات الاستخدام:**
+- إنشاء محتوى أساسي
+- العصف الذهني
+- مهام التلخيص البسيطة
+- مساعدة الكتابة الإبداعية
+
+#### 2. تعقيد منخفض، دقة عالية
+
+**الخصائص:**
+- سير عمل بسيطة تتطلب مخرجات دقيقة ومنظمة
+- حاجة لنتائج قابلة للتكرار
+- خطوات محدودة مع متطلبات دقة عالية
+- غالبًا تتضمن معالجة أو تحويل بيانات
+
+**النهج الموصى به:** Flows مع استدعاءات LLM مباشرة أو Crews بسيطة مع مخرجات منظمة
+
+**أمثلة على حالات الاستخدام:**
+- استخراج البيانات وتحويلها
+- ملء النماذج والتحقق منها
+- إنشاء محتوى منظم (JSON، XML)
+- مهام التصنيف البسيطة
+
+#### 3. تعقيد عالٍ، دقة منخفضة
+
+**الخصائص:**
+- عمليات متعددة المراحل بخطوات كثيرة
+- مخرجات إبداعية أو استكشافية
+- تفاعلات معقدة بين المكونات
+- تحمّل التباين في النتائج النهائية
+
+**النهج الموصى به:** Crews معقدة مع عدة Agents متخصصة
+
+**أمثلة على حالات الاستخدام:**
+- البحث والتحليل
+- خطوط إنتاج المحتوى
+- تحليل البيانات الاستكشافي
+- حل المشكلات الإبداعي
+
+#### 4. تعقيد عالٍ، دقة عالية
+
+**الخصائص:**
+- سير عمل معقدة تتطلب مخرجات منظمة
+- خطوات مترابطة متعددة مع متطلبات دقة صارمة
+- حاجة لمعالجة متطورة ونتائج دقيقة معًا
+- غالبًا تطبيقات حرجة المهمة
+
+**النهج الموصى به:** Flows تنسّق عدة Crews مع خطوات تحقق
+
+**أمثلة على حالات الاستخدام:**
+- أنظمة دعم القرار المؤسسية
+- خطوط معالجة بيانات معقدة
+- معالجة مستندات متعددة المراحل
+- تطبيقات الصناعات المنظمة
+
+## الاختيار بين Crews وFlows
+
+### متى تختار Crews
+
+الـ Crews مثالية عندما:
+
+1. **تحتاج ذكاء تعاوني** - عدة Agents بتخصصات مختلفة تحتاج للعمل معًا
+2. **المشكلة تتطلب تفكيرًا ناشئًا** - الحل يستفيد من منظورات ونُهج مختلفة
+3. **المهمة إبداعية أو تحليلية بالأساس** - العمل يتضمن بحثًا أو إنشاء محتوى أو تحليل
+4. **تقدّر القدرة على التكيف على الهيكل الصارم** - سير العمل يمكن أن يستفيد من استقلالية الـ Agent
+5. **تنسيق المخرجات يمكن أن يكون مرنًا نوعًا ما** - بعض التباين في هيكل المخرجات مقبول
+
+```python
+# Example: Research Crew for market analysis
+from crewai import Agent, Crew, Process, Task
+
+# Create specialized agents
+researcher = Agent(
+    role="Market Research Specialist",
+    goal="Find comprehensive market data on emerging technologies",
+    backstory="You are an expert at discovering market trends and gathering data."
+)
+
+analyst = Agent(
+    role="Market Analyst",
+    goal="Analyze market data and identify key opportunities",
+    backstory="You excel at interpreting market data and spotting valuable insights."
+)
+
+# Define their tasks
+research_task = Task(
+    description="Research the current market landscape for AI-powered healthcare solutions",
+    expected_output="Comprehensive market data including key players, market size, and growth trends",
+    agent=researcher
+)
+
+analysis_task = Task(
+    description="Analyze the market data and identify the top 3 investment opportunities",
+    expected_output="Analysis report with 3 recommended investment opportunities and rationale",
+    agent=analyst,
+    context=[research_task]
+)
+
+# Create the crew
+market_analysis_crew = Crew(
+    agents=[researcher, analyst],
+    tasks=[research_task, analysis_task],
+    process=Process.sequential,
+    verbose=True
+)
+
+# Run the crew
+result = market_analysis_crew.kickoff()
+```
+
+### متى تختار Flows
+
+الـ Flows مثالية عندما:
+
+1. **تحتاج تحكمًا دقيقًا في التنفيذ** - سير العمل يتطلب تسلسلًا دقيقًا وإدارة حالة
+2. **التطبيق له متطلبات حالة معقدة** - تحتاج لصيانة وتحويل الحالة عبر خطوات متعددة
+3. **تحتاج مخرجات منظمة وقابلة للتنبؤ** - التطبيق يتطلب نتائج متسقة ومنسّقة
+4. **سير العمل يتضمن منطقًا شرطيًا** - مسارات مختلفة يجب اتخاذها بناءً على نتائج وسيطة
+5. **تحتاج الجمع بين AI وكود إجرائي** - الحل يتطلب قدرات AI وبرمجة تقليدية معًا
+
+```python
+# Example: Customer Support Flow with structured processing
+from crewai.flow.flow import Flow, listen, router, start
+from pydantic import BaseModel
+from typing import List, Dict
+
+# Define structured state
+class SupportTicketState(BaseModel):
+    ticket_id: str = ""
+    customer_name: str = ""
+    issue_description: str = ""
+    category: str = ""
+    priority: str = "medium"
+    resolution: str = ""
+    satisfaction_score: int = 0
+
+class CustomerSupportFlow(Flow[SupportTicketState]):
+    @start()
+    def receive_ticket(self):
+        self.state.ticket_id = "TKT-12345"
+        self.state.customer_name = "Alex Johnson"
+        self.state.issue_description = "Unable to access premium features after payment"
+        return "Ticket received"
+
+    @listen(receive_ticket)
+    def categorize_ticket(self, _):
+        from crewai import LLM
+        llm = LLM(model="openai/gpt-4o-mini")
+
+        prompt = f"""
+        Categorize the following customer support issue into one of these categories:
+        - Billing
+        - Account Access
+        - Technical Issue
+        - Feature Request
+        - Other
+
+        Issue: {self.state.issue_description}
+
+        Return only the category name.
+        """
+
+        self.state.category = llm.call(prompt).strip()
+        return self.state.category
+
+    @router(categorize_ticket)
+    def route_by_category(self, category):
+        return category.lower().replace(" ", "_")
+
+    @listen("billing")
+    def handle_billing_issue(self):
+        self.state.priority = "high"
+        return "Billing issue handled"
+
+    @listen("account_access")
+    def handle_access_issue(self):
+        self.state.priority = "high"
+        return "Access issue handled"
+
+    @listen("billing", "account_access", "technical_issue", "feature_request", "other")
+    def resolve_ticket(self, resolution_info):
+        self.state.resolution = f"Issue resolved: {resolution_info}"
+        return self.state.resolution
+
+# Run the flow
+support_flow = CustomerSupportFlow()
+result = support_flow.kickoff()
+```
+
+### متى تجمع بين Crews وFlows
+
+أكثر التطبيقات تطورًا غالبًا تستفيد من الجمع بين Crews وFlows:
+
+1. **عمليات معقدة متعددة المراحل** - استخدم Flows لتنسيق العملية الكلية وCrews للمهام الفرعية المعقدة
+2. **تطبيقات تتطلب إبداعًا وهيكلاً معًا** - استخدم Crews للمهام الإبداعية وFlows للمعالجة المنظمة
+3. **تطبيقات AI مؤسسية** - استخدم Flows لإدارة الحالة وتدفق العمليات مع الاستفادة من Crews للعمل المتخصص
+
+```python
+# Example: Content Production Pipeline combining Crews and Flows
+from crewai.flow.flow import Flow, listen, start
+from crewai import Agent, Crew, Process, Task
+from pydantic import BaseModel
+from typing import List, Dict
+
+class ContentState(BaseModel):
+    topic: str = ""
+    target_audience: str = ""
+    content_type: str = ""
+    outline: Dict = {}
+    draft_content: str = ""
+    final_content: str = ""
+    seo_score: int = 0
+
+class ContentProductionFlow(Flow[ContentState]):
+    @start()
+    def initialize_project(self):
+        self.state.topic = "Sustainable Investing"
+        self.state.target_audience = "Millennial Investors"
+        self.state.content_type = "Blog Post"
+        return "Project initialized"
+
+    @listen(initialize_project)
+    def create_outline(self, _):
+        researcher = Agent(
+            role="Content Researcher",
+            goal=f"Research {self.state.topic} for {self.state.target_audience}",
+            backstory="You are an expert researcher with deep knowledge of content creation."
+        )
+
+        outliner = Agent(
+            role="Content Strategist",
+            goal=f"Create an engaging outline for a {self.state.content_type}",
+            backstory="You excel at structuring content for maximum engagement."
+        )
+
+        research_task = Task(
+            description=f"Research {self.state.topic} focusing on what would interest {self.state.target_audience}",
+            expected_output="Comprehensive research notes with key points and statistics",
+            agent=researcher
+        )
+
+        outline_task = Task(
+            description=f"Create an outline for a {self.state.content_type} about {self.state.topic}",
+            expected_output="Detailed content outline with sections and key points",
+            agent=outliner,
+            context=[research_task]
+        )
+
+        outline_crew = Crew(
+            agents=[researcher, outliner],
+            tasks=[research_task, outline_task],
+            process=Process.sequential,
+            verbose=True
+        )
+
+        result = outline_crew.kickoff()
+
+        import json
+        try:
+            self.state.outline = json.loads(result.raw)
+        except:
+            self.state.outline = {"sections": result.raw}
+
+        return "Outline created"
+
+    @listen(create_outline)
+    def write_content(self, _):
+        writer = Agent(
+            role="Content Writer",
+            goal=f"Write engaging content for {self.state.target_audience}",
+            backstory="You are a skilled writer who creates compelling content."
+        )
+
+        editor = Agent(
+            role="Content Editor",
+            goal="Ensure content is polished, accurate, and engaging",
+            backstory="You have a keen eye for detail and a talent for improving content."
+        )
+
+        writing_task = Task(
+            description=f"Write a {self.state.content_type} about {self.state.topic} following this outline: {self.state.outline}",
+            expected_output="Complete draft content in markdown format",
+            agent=writer
+        )
+
+        editing_task = Task(
+            description="Edit and improve the draft content for clarity, engagement, and accuracy",
+            expected_output="Polished final content in markdown format",
+            agent=editor,
+            context=[writing_task]
+        )
+
+        writing_crew = Crew(
+            agents=[writer, editor],
+            tasks=[writing_task, editing_task],
+            process=Process.sequential,
+            verbose=True
+        )
+
+        result = writing_crew.kickoff()
+        self.state.final_content = result.raw
+
+        return "Content created"
+
+    @listen(write_content)
+    def optimize_for_seo(self, _):
+        from crewai import LLM
+        llm = LLM(model="openai/gpt-4o-mini")
+
+        prompt = f"""
+        Analyze this content for SEO effectiveness for the keyword "{self.state.topic}".
+        Rate it on a scale of 1-100 and provide 3 specific recommendations for improvement.
+
+        Content: {self.state.final_content[:1000]}... (truncated for brevity)
+
+        Format your response as JSON with the following structure:
+        {{
+            "score": 85,
+            "recommendations": [
+                "Recommendation 1",
+                "Recommendation 2",
+                "Recommendation 3"
+            ]
+        }}
+        """
+
+        seo_analysis = llm.call(prompt)
+
+        import json
+        try:
+            analysis = json.loads(seo_analysis)
+            self.state.seo_score = analysis.get("score", 0)
+            return analysis
+        except:
+            self.state.seo_score = 50
+            return {"score": 50, "recommendations": ["Unable to parse SEO analysis"]}
+
+# Run the flow
+content_flow = ContentProductionFlow()
+result = content_flow.kickoff()
+```
+
+## إطار التقييم العملي
+
+لتحديد النهج الصحيح لحالة استخدامك المحددة، اتبع إطار التقييم التدريجي هذا:
+
+### الخطوة 1: تقييم التعقيد
+
+قيّم تعقيد تطبيقك على مقياس من 1-10 من خلال النظر في:
+
+1. **عدد الخطوات**: كم عدد العمليات المميزة المطلوبة؟
+   - 1-3 خطوات: تعقيد منخفض (1-3)
+   - 4-7 خطوات: تعقيد متوسط (4-7)
+   - 8+ خطوات: تعقيد عالٍ (8-10)
+
+2. **التبعيات المتبادلة**: ما مدى ترابط الأجزاء المختلفة؟
+   - تبعيات قليلة: تعقيد منخفض (1-3)
+   - بعض التبعيات: تعقيد متوسط (4-7)
+   - تبعيات معقدة كثيرة: تعقيد عالٍ (8-10)
+
+3. **المنطق الشرطي**: ما مقدار التفرع وصنع القرار المطلوب؟
+   - عملية خطية: تعقيد منخفض (1-3)
+   - بعض التفرع: تعقيد متوسط (4-7)
+   - أشجار قرار معقدة: تعقيد عالٍ (8-10)
+
+4. **المعرفة التخصصية**: ما مدى تخصص المعرفة المطلوبة؟
+   - معرفة عامة: تعقيد منخفض (1-3)
+   - بعض المعرفة المتخصصة: تعقيد متوسط (4-7)
+   - خبرة عميقة في مجالات متعددة: تعقيد عالٍ (8-10)
+
+احسب متوسط درجتك لتحديد التعقيد الكلي.
+
+### الخطوة 2: تقييم متطلبات الدقة
+
+قيّم متطلبات الدقة على مقياس من 1-10 من خلال النظر في:
+
+1. **هيكل المخرجات**: ما مدى التنظيم المطلوب في المخرجات؟
+   - نص حر: دقة منخفضة (1-3)
+   - شبه منظم: دقة متوسطة (4-7)
+   - منسّق بشكل صارم (JSON، XML): دقة عالية (8-10)
+
+2. **احتياجات الدقة**: ما أهمية الدقة الواقعية؟
+   - محتوى إبداعي: دقة منخفضة (1-3)
+   - محتوى معلوماتي: دقة متوسطة (4-7)
+   - معلومات حرجة: دقة عالية (8-10)
+
+3. **إمكانية التكرار**: ما مدى اتساق النتائج عبر التشغيلات؟
+   - التباين مقبول: دقة منخفضة (1-3)
+   - بعض الاتساق مطلوب: دقة متوسطة (4-7)
+   - تكرار دقيق مطلوب: دقة عالية (8-10)
+
+4. **تحمّل الأخطاء**: ما تأثير الأخطاء؟
+   - تأثير منخفض: دقة منخفضة (1-3)
+   - تأثير معتدل: دقة متوسطة (4-7)
+   - تأثير عالٍ: دقة عالية (8-10)
+
+احسب متوسط درجتك لتحديد متطلبات الدقة الكلية.
+
+### الخطوة 3: التعيين على المصفوفة
+
+ارسم درجات التعقيد والدقة على المصفوفة:
+
+- **تعقيد منخفض (1-4)، دقة منخفضة (1-4)**: Crews بسيطة
+- **تعقيد منخفض (1-4)، دقة عالية (5-10)**: Flows مع استدعاءات LLM مباشرة
+- **تعقيد عالٍ (5-10)، دقة منخفضة (1-4)**: Crews معقدة
+- **تعقيد عالٍ (5-10)، دقة عالية (5-10)**: Flows تنسّق Crews
+
+### الخطوة 4: مراعاة عوامل إضافية
+
+بالإضافة إلى التعقيد والدقة، ضع في اعتبارك:
+
+1. **وقت التطوير**: غالبًا ما تكون Crews أسرع في النماذج الأولية
+2. **احتياجات الصيانة**: توفر Flows قابلية صيانة أفضل على المدى الطويل
+3. **خبرة الفريق**: ضع في اعتبارك ألفة فريقك مع النُهج المختلفة
+4. **متطلبات التوسع**: عادةً ما تتوسع Flows بشكل أفضل للتطبيقات المعقدة
+5. **احتياجات التكامل**: ضع في اعتبارك كيف سيتكامل الحل مع الأنظمة الحالية
+
+## الخلاصة
+
+الاختيار بين Crews وFlows — أو الجمع بينهما — قرار معماري حاسم يؤثر على فعالية وقابلية صيانة وتوسع تطبيق CrewAI. من خلال تقييم حالة الاستخدام على أبعاد التعقيد والدقة، يمكنك اتخاذ قرارات مدروسة تتماشى مع متطلباتك المحددة.
+
+تذكر أن أفضل نهج غالبًا يتطور مع نضج تطبيقك. ابدأ بأبسط حل يلبي احتياجاتك، وكن مستعدًا لصقل بنيتك مع اكتساب الخبرة ووضوح المتطلبات.
+
+<Check>
+لديك الآن إطار لتقييم حالات استخدام CrewAI واختيار النهج الصحيح بناءً على متطلبات التعقيد والدقة. سيساعدك هذا في بناء تطبيقات AI أكثر فعالية وقابلية للصيانة والتوسع.
+</Check>
+
+## الخطوات التالية
+
+- تعلم المزيد عن [صياغة Agents فعّالة](/ar/guides/agents/crafting-effective-agents)
+- استكشف [بناء أول Crew](/ar/guides/crews/first-crew)
+- تعمّق في [إتقان إدارة حالة Flow](/ar/guides/flows/mastering-flow-state)
+- اطلع على [المفاهيم الأساسية](/ar/concepts/agents) لفهم أعمق

docs/v1.15.19/ar/guides/crews/first-crew.mdx

@@ -0,0 +1,140 @@
+---
+title: ابنِ أول Crew
+description: دليل خطوة بخطوة لإنشاء فريق AI تعاوني باستخدام تهيئة JSON-first.
+icon: users-gear
+mode: "wide"
+---
+
+## بناء Crew للبحث
+
+في هذا الدليل ستنشئ crew من Agentين: واحد للبحث وآخر لكتابة تقرير markdown. مشاريع الـ crew الجديدة هي JSON-first: تُعرّف الـ Agents في `agents/*.jsonc`، وتُعرّف المهام وإعدادات الـ crew في `crew.jsonc`، ويحمّل `crewai run` هذا التعريف مباشرة.
+
+### المتطلبات
+
+1. تثبيت CrewAI من [دليل التثبيت](/ar/installation)
+2. إعداد مفتاح LLM من [دليل LLMs](/ar/concepts/llms#setting-up-your-llm)
+3. مفتاح [Serper.dev](https://serper.dev/) إذا أردت استخدام البحث على الويب
+
+## الخطوة 1: إنشاء Crew جديدة
+
+```bash
+crewai create crew research_crew
+cd research_crew
+```
+
+البنية الناتجة:
+
+```text
+research_crew/
+├── .gitignore
+├── .env
+├── agents/
+│   └── researcher.jsonc
+├── crew.jsonc
+├── knowledge/
+├── pyproject.toml
+├── README.md
+├── skills/
+└── tools/
+```
+
+<Tip>
+إذا احتجت إلى البنية القديمة التي تحتوي على `crew.py` و `config/agents.yaml` و `config/tasks.yaml`، استخدم `crewai create crew research_crew --classic`.
+</Tip>
+
+## الخطوة 2: تعريف الـ Agents
+
+عدّل ملف `agents/researcher.jsonc` الذي أنشأه القالب، ثم أضف `agents/analyst.jsonc`. يجب أن تطابق أسماء الملفات الأسماء المشار إليها في `crew.jsonc`.
+
+```jsonc agents/researcher.jsonc
+{
+  "role": "Senior Research Specialist for {topic}",
+  "goal": "Find comprehensive and accurate information about {topic}, with a focus on recent developments and key insights.",
+  "backstory": "You are an experienced research specialist who organizes complex information into clear, useful notes.",
+  // استبدله بالنموذج الذي تستخدمه، مثل "openai/gpt-4o".
+  "llm": "provider/model-id",
+  "tools": ["SerperDevTool"],
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
+```
+
+```jsonc agents/analyst.jsonc
+{
+  "role": "Report Analyst for {topic}",
+  "goal": "Turn research findings into a clear, well-structured report.",
+  "backstory": "You are a careful analyst with strong technical writing skills and a talent for extracting useful insights.",
+  // استبدله بالنموذج الذي تستخدمه، مثل "openai/gpt-4o".
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true,
+    "allow_delegation": false
+  }
+}
+```
+
+استبدل `provider/model-id` بالنموذج الذي تستخدمه، مثل `openai/gpt-4o` أو `anthropic/claude-sonnet-4-6` أو `gemini/gemini-3.7-flash`.
+
+## الخطوة 3: تعريف المهام وإعدادات الـ Crew
+
+استبدل `crew.jsonc` بما يلي:
+
+```jsonc crew.jsonc
+{
+  "name": "Research Crew",
+  "agents": ["researcher", "analyst"],
+  "tasks": [
+    {
+      "name": "research_task",
+      "description": "Conduct thorough research on {topic}. Focus on key concepts, recent developments, major challenges, notable applications, and future outlook.",
+      "expected_output": "A comprehensive research document with organized sections, specific facts, and useful examples about {topic}.",
+      "agent": "researcher"
+    },
+    {
+      "name": "analysis_task",
+      "description": "Analyze the research findings and create a polished report on {topic}. Include an executive summary, key insights, trend analysis, and recommendations.",
+      "expected_output": "A professional markdown report with clear headings, a concise summary, main findings, and recommendations.",
+      "agent": "analyst",
+      "context": ["research_task"],
+      "output_file": "output/report.md",
+      "markdown": true
+    }
+  ],
+  "process": "sequential",
+  "verbose": true,
+  "memory": true,
+  "inputs": {
+    "topic": "Artificial Intelligence in Healthcare"
+  }
+}
+```
+
+يشير `context` إلى أسماء مهام سابقة، لذلك يحصل analyst على مخرجات مهمة البحث. يوفر `inputs` قيمة افتراضية لـ `{topic}`. إذا حذفت القيمة الافتراضية، سيطلبها `crewai run`.
+
+## الخطوة 4: متغيرات البيئة
+
+عدّل `.env`:
+
+```sh
+SERPER_API_KEY=your_serper_api_key
+# أضف مفتاح مزود النموذج أيضًا.
+```
+
+## الخطوة 5: التثبيت والتشغيل
+
+```bash
+crewai install
+crewai run
+```
+
+بعد انتهاء التشغيل، افتح `output/report.md`.
+
+<Warning>
+شغّل مشاريع JSON crew من مصادر تثق بها فقط. أدوات `custom:<name>` ومراجع `{"python": "module.attribute"}` تنفذ Python محليًا عند تحميل الـ crew.
+</Warning>
+
+<Check>
+أصبحت لديك crew تعمل بأسلوب JSON-first تبحث في موضوع وتكتب تقريرًا.
+</Check>

docs/v1.15.19/ar/guides/flows/conversational-flows.mdx

@@ -0,0 +1,618 @@
+---
+title: تدفقات المحادثة
+description: أنشئ تطبيقات دردشة متعددة الجولات باستخدام handle_turn لكل جولة، وسجل الرسائل، وتوجيه النية، والتتبع، والبث المنظّم.
+icon: comments
+mode: "wide"
+---
+
+## نظرة عامة
+
+تعامل التطبيقات المحادثية مع كل سطر من المستخدم كـ **تشغيل flow جديد** بنفس **معرّف الجلسة**. توفر CrewAI مساعدات لسجل الرسائل، وتوجيه النية الاختياري، وتأجيل التتبع، والبث المنظّم للجولات، إضافة إلى REPL محلي عبر `flow.chat()`.
+
+| المفهوم | التنفيذ |
+|---------|---------|
+| معرّف الجلسة | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
+| سطر المستخدم | `handle_turn(message)` يضيف الرسالة إلى `state.messages` قبل تشغيل الرسم |
+| اكتمال الجولة | `conversation_turn_completed`؛ ومع تأجيل التتبع الافتراضي ينتظر `FlowFinished` استدعاء `finalize_session_traces()` |
+| تتبع الجلسة الكامل | `ConversationConfig(defer_trace_finalization=True)` + `finalize_session_traces()` |
+
+## واجهات الجولات
+
+استخدم **`flow.handle_turn(message, session_id=...)`** لكل رسالة مستخدم من REST أو WebSocket أو الاختبارات أو الواجهات المخصصة. استخدم **`flow.chat()`** عندما تريد حلقة دردشة محلية في الطرفية لـ `Flow` محادثي.
+
+لا يقبل `Flow.kickoff()` الوسيطين `user_message=` أو `session_id=`. في التدفقات المحادثية، يخزن `handle_turn()` الرسالة المعلقة ويستدعي داخلياً `kickoff(inputs={"id": session_id})` بعد إعادة ضبط حالة التنفيذ الخاصة بالجولة.
+
+| API | الاستخدام |
+|-----|-----------|
+| `handle_turn(message, session_id=...)` | غلاف مريح لجولة واحدة في `Flow` محادثي |
+| `stream_turn(message, session_id=...)` | بث جولة محادثية واحدة كإطارات runtime مرتبة |
+| `chat()` | REPL محلي في الطرفية لـ `Flow` محادثي |
+| `kickoff(inputs={...})` | تشغيل متقدم للـ flow بدون معالجة جولة محادثية |
+| `ask()` | مطالبة حاجزة **داخل** خطوة واحدة (معالج إرشادي أو طلب توضيح) |
+| `@human_feedback` | الموافقة/الرفض على **مخرجات خطوة** — وليس السطر التالي |
+
+ترفع `handle_turn()` و`stream_turn()` و`chat()` الخطأ `ValueError` ما لم يكن الوضع المحادثاتي مفعّلاً. يؤدي تطبيق `@ConversationConfig(...)` إلى تفعيله تلقائياً؛ وإلا فعيّن `conversational = True`.
+
+## بداية سريعة
+
+```python
+from uuid import uuid4
+
+from crewai import Flow
+from crewai.flow import listen
+from crewai.flow import (
+    ConversationConfig,
+    ConversationState,
+)
+
+
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+    def route_turn(self, context):
+        message = (self.state.current_user_message or "").lower()
+        if "order" in message:
+            return "order"
+        if "bye" in message or "goodbye" in message:
+            return "goodbye"
+        return "help"
+
+    @listen("order")
+    def handle_order(self):
+        reply = "Your order is on the way."
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("help")
+    def handle_help(self):
+        reply = "How can I help?"
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("goodbye")
+    def handle_goodbye(self):
+        reply = "Goodbye!"
+        self.append_assistant_message(reply)
+        return reply
+
+
+session_id = str(uuid4())
+flow = SupportFlow()
+
+try:
+    flow.handle_turn("Where is my order?", session_id=session_id)
+    flow.handle_turn("What about returns?", session_id=session_id)
+finally:
+    flow.finalize_session_traces()  # one trace link for the whole chat
+```
+
+## بث جولة
+
+استخدم `stream_turn()` عندما تحتاج واجهة مستخدم أو بيئة تشغيل إلى أحداث منظّمة لجولة دردشة واحدة. يعيد جلسة بث تحتوي على إطارات مرتبة لتوجيه Flow، وأجزاء LLM، ونشاط الأدوات، ورسائل المحادثة.
+
+```python
+stream = flow.stream_turn("Where is my order?", session_id=session_id)
+
+with stream:
+    for frame in stream.events:
+        if frame.channel == "llm" and frame.type == "llm_stream_chunk":
+            print(frame.content, end="", flush=True)
+
+result = stream.result
+```
+
+راجع [عقد بيئة البث](/edge/ar/learn/streaming-runtime-contract) للاطلاع على عقد الإطارات الكامل وقائمة القنوات.
+
+## دورة حياة الجولة
+
+يشغّل كل `handle_turn` المسار التالي:
+
+1. **إعداد الجولة** — يخزن رسالة المستخدم المعلقة، ويحل معرّف الجلسة، ويعيد ضبط تعقّب التنفيذ الخاص بالجولة، ثم يستدعي `kickoff(inputs={"id": session_id})`.
+2. **استعادة الحالة** — إذا وُجد `inputs["id"]` وكان `@persist` مهيّأً، تُحمّل أحدث لقطة.
+3. **`FlowStarted`** — في أول جولة للجلسة المؤجلة فقط.
+4. **ترطيب الجولة المعلقة** — تُضاف رسالة المستخدم إلى `state.messages`، وتُضبط `current_user_message` / `last_user_message`، ويُجرى التصنيف اختيارياً عند ضبط `intents` / `default_intents` مع `intent_llm`.
+5. **تنفيذ الرسم** — طرق `@start` التي يعرّفها المستخدم (إن وجدت) → `route_conversation` (نقطة البدء/الموجّه المدمجة) → معالج `@listen` المختار. تستدعي `route_conversation` أيضاً المساعد القابل للتجاوز `conversation_start()`.
+6. **نهاية التشغيل** — يُتخطى `flow_finished` لكل جولة وإنهاء التتبع عند تفعيل التأجيل؛ كما لا تغلق استدعاءات `Agent.kickoff()` المتداخلة أو crews دفعة الأب.
+
+استدعِ **`append_assistant_message(reply)`** عندما لا تطابق الرد الظاهر قيمة الإرجاع، أو عند قصّ التاريخ. تُسجَّل أيضاً سلسلة الإرجاع العامة كمساعد وتُضمَّن في لقطة `@persist`، فتستعيدها نسخة Flow جديدة. سطر المستخدم محفوظ عبر `handle_turn` — لا تُضفه مرة أخرى.
+
+## نظرة عامة على الإعداد
+
+يؤدي تزيين صنف فرعي من `Flow` بـ `ConversationConfig` إلى إرفاق افتراضيات الدردشة وتفعيل الوضع المحادثاتي معاً. راجع [مرجع الحقول الكامل](#conversationconfig) أدناه. ويمكنك تجاوز التصنيف المسبق لكل جولة عبر `handle_turn(..., intents=..., intent_llm=...)`.
+
+## مساعدات `ChatState` منخفضة المستوى
+
+تظل `ChatState` و`ConversationalConfig` القديمة ومساعدات `crewai.flow.conversation` قابلة للاستيراد للتنسيق المتقدم أو الاختبارات أو الأغلفة المخصصة. وهي منفصلة عن واجهتي `ConversationState` / `ConversationConfig`، ولا تضيف وسيطي `user_message=` أو `session_id=` إلى `Flow.kickoff()`.
+
+```python
+from crewai.flow import ChatState
+
+
+class MyChatState(ChatState):
+    # Inherited: id, messages, last_user_message, last_intent, session_ready
+    research_turn_count: int = 0
+    custom_flag: bool = False
+```
+
+| الحقل | الدور |
+|-------|------|
+| `id` | UUID الجلسة (نفس `inputs["id"]`) |
+| `messages` | `list` من `{role, content}` لسجل LLM |
+| `last_user_message` | آخر سطر مستخدم في هذه الجولة |
+| `last_intent` | تسمية المسار بعد التصنيف (إن وُجد) |
+| `session_ready` | علم bootstrap لمرة واحدة (الصلاحيات، وذاكرات التخزين المؤقت، وغيرها) |
+
+`ConversationalInputs` هو `TypedDict` لمفاتيح `kickoff(inputs={...})` الاصطلاحية: `id` و`user_message` و`last_intent`.
+
+تخزن `ConversationState` رسائل `messages` ككائنات `ConversationMessage`، وتوفر أيضاً `current_user_message` و`ended` و`events` و`agent_threads`. استخدم `conversation_messages` عند تمرير سجلها القانوني إلى LLM.
+
+## API المحادثة على `Flow`
+
+### معاملات `handle_turn`
+
+| المعامل | الغرض |
+|---------|--------|
+| `message` | نص هذه الجولة |
+| `session_id` | UUID المحادثة → `inputs["id"]` / `state.id` |
+| `intents` | تسميات النتائج لـ `classify_intent` قبل kickoff |
+| `intent_llm` | LLM للتصنيف (مطلوب مع `intents`) |
+| `**kickoff_kwargs` | تُمرر إلى `kickoff()` لخيارات مثل `input_files` و`from_checkpoint` و`restore_from_state_id` |
+
+### معاملات `kickoff`
+
+يقبل `Flow.kickoff()` كلاً من `inputs` و`input_files` و`from_checkpoint` و`restore_from_state_id`. مرر `inputs={"id": session_id}` عندما تحتاج إلى تنفيذ flow خام، لكن استخدم `handle_turn()` عندما يمثل الاستدعاء رسالة دردشة.
+
+### سمات المثيل
+
+| السمة | الغرض |
+|-------|--------|
+| `conversational` | عيّنه على `True` لتفعيل الرسم المحادثاتي و`handle_turn()` |
+| `defer_trace_finalization` | تجاوز اختياري على مستوى المثيل. وإلا تقرأ `_should_defer_trace_finalization()` القيمة `ConversationConfig.defer_trace_finalization`. |
+| `suppress_flow_events` | يخفي لوحات flow في الطرفية ويمنع أحداث تنفيذ الطرق؛ وتظل أحداث بدء/انتهاء flow تصدر |
+| `stream` | علم البث العام لـ Flow. استخدم `stream_turn()` للجولات المحادثية بدلاً من جمع هذا العلم مع `handle_turn()`. |
+
+### طرق وخصائص
+
+| الاسم | الوصف |
+|------|--------|
+| `append_assistant_message(content)` | إضافة رد مساعد مرئي للمستخدم إلى `state.messages` |
+| `append_message(role, content, **extra)` | إضافة إلى `state.messages` |
+| `conversation_messages` | سجل للقراءة فقط لاستدعاءات LLM |
+| `classify_intent(text, outcomes, *, llm, context=None)` | تعيين النص إلى نتيجة واحدة (بنفس منطق الاختزال المستخدم في `@human_feedback`) |
+| `receive_user_message(text, *, outcomes=None, llm=None)` | إضافة رسالة مستخدم، وضبط `last_intent` اختيارياً |
+| `finalize_session_traces()` | إصدار `flow_finished` المؤجل وإنهاء دفعة trace |
+| `_should_defer_trace_finalization()` | hook متقدم/داخلي يحسم ما إذا كان إنهاء trace لكل جولة مؤجلاً |
+| `input_history` | سجل تدقيق مطالبات وردود `ask()` |
+
+### مساعدات الوحدة (`crewai.flow.conversation`)
+
+يمكن استيرادها من `crewai.flow.conversation` للاختبارات أو التنسيق المخصص. تستخدم هذه المساعدات بنية `ConversationalConfig` القديمة؛ كما تمسح `prepare_conversational_turn()` قيمة `last_intent`، بخلاف `handle_turn()` التي تحتفظ بها كسياق للموجّه.
+
+| الدالة | الوصف |
+|--------|--------|
+| `normalize_kickoff_inputs(inputs, user_message=..., session_id=...)` | دمج وسائط المحادثة في `inputs` |
+| `get_conversation_messages(flow)` | قراءة الرسائل من الحالة أو المخزن |
+| `append_message(flow, role, content, **extra)` | مثل طريقة المثيل |
+| `prepare_conversational_turn(flow, user_message=..., intents=..., intent_llm=..., config=...)` | ترطيب الجولة منخفض المستوى للأغلفة المخصصة |
+| `receive_user_message(flow, text, ...)` | مثل طريقة المثيل |
+| `set_state_field(flow, name, value)` | تعيين حقل dict أو Pydantic |
+| `get_conversational_config(flow)` | قراءة `conversational_config` |
+| `input_history_to_messages(entries)` | تحويل `input_history` لصيغة رسائل LLM |
+
+## أنماط توجيه النية
+
+### أ. تصنيف مسبق عبر `ConversationConfig` (الأبسط)
+
+عيّن `default_intents` و`intent_llm`. يصنّف كل `handle_turn()` الرسالة الحالية مسبقاً. تكون الأولوية لنتيجة غير فارغة يعيدها `route_turn()` مخصص؛ وإلا تستخدم `route_conversation` النية المصنّفة للجولة الحالية.
+
+### ب. تصنيف داخل `route_turn` (مطالبات أغنى)
+
+عيّن `default_intents=None` كي يضيف `handle_turn()` رسالة المستخدم فقط. داخل `route_turn()`، استدعِ `classify_intent` بمطالبة أو أوصاف مخصصة:
+
+```python
+def route_turn(self, context):
+    intent = self.classify_intent(
+        self._routing_prompt(self.state.current_user_message),
+        ("GREETING", "ORDER", "RESEARCH", "GOODBYE"),
+        llm="gpt-4o-mini",
+    )
+    self.state.last_intent = intent
+    return intent
+```
+
+للبحث على الويب أو أدوات متعددة الخطوات استخدم **`@listen("RESEARCH")`** مع `Agent.kickoff()` وأدوات — وليس `LLM.call()` فقط.
+
+## عندما ينتهي الـ flow ويستمر المستخدم
+
+يُكمل كل `handle_turn()` تشغيل رسم واحد، وتستمر المحادثة عبر `handle_turn()` آخر يستخدم `session_id` نفسه. مع دورة حياة التتبع المؤجلة افتراضياً، يصدر ذلك التشغيل `conversation_turn_completed`، بينما يصدر `FlowFinished` مرة واحدة عندما تغلق `finalize_session_traces()` الجلسة. ويستعيد `@persist` الرسائل والأعلام والسياق.
+
+**نمط الحفظ:** يُفضّل `@persist` على **خطوة نهائية واحدة** (مثل `finalize`) وليس على صنف `Flow` بالكامل. يحفظ الاستمرار على مستوى الصنف بعد كل طريقة؛ وتستخدم `load_state` أحدث صف، وقد يكون لقطة في منتصف التشغيل (مثلاً بعد `bootstrap` مباشرة) لا تتضمن تحديثات المعالج من الجولة نفسها.
+
+لا تستخدم `@human_feedback` لأسطر المتابعة في الدردشة إلا عند الحاجة لموافقة بشرية على مخرجات خطوة محددة.
+
+## `Flow` المحادثاتي
+
+اشترك في رسم الدردشة المحادثاتي بتعيين `conversational = True` على صنف فرعي من `Flow` أو بتطبيق `@ConversationConfig(...)`. يوفر `Flow` الأساسي عندئذٍ `route_conversation` كنقطة البدء/الموجّه المدمجة، إضافة إلى مستمعي `converse_turn` و`end_conversation`. يظل المستمع المهمل `answer_from_history_turn` متاحاً للتوافق. يدير الإطار `state.messages`، ويمكنه تشغيل LLM للموجّه، ويبقي دفعة trace مفتوحة عبر الجولات. أنت تكتب **المسارات المخصصة**؛ والإطار يتولى الباقي.
+
+استخدمه عندما تريد دردشة متعددة الجولات مع موجّه قائم على LLM ومعالجات لكل مسار دون توصيل دورة الحياة يدوياً. استخدم `Flow[ChatState]` (النمط الأدنى مستوى في الأعلى) عندما تحتاج تحكماً كاملاً.
+
+### مثال سريع
+
+```python
+from crewai import Flow
+from crewai.flow import listen
+from crewai.flow import (
+    ConversationConfig,
+    ConversationState,
+)
+
+
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+    def route_turn(self, context: dict) -> str | None:
+        message = (self.state.current_user_message or "").lower()
+        if "search" in message or "news" in message:
+            return "INTERNET_SEARCH"
+        if "docs" in message or "crewai" in message:
+            return "CREWAI_DOCS"
+        return "converse"
+
+    @listen("INTERNET_SEARCH")
+    def handle_internet_search(self) -> str:
+        """Fresh web research, current news, real-time lookups."""
+        reply = "I would run the web research route here."
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("CREWAI_DOCS")
+    def handle_crewai_docs(self) -> str:
+        """Look up the CrewAI documentation for framework/API questions."""
+        reply = "I would look up the CrewAI docs here."
+        self.append_assistant_message(reply)
+        return reply
+
+
+flow = SupportFlow()
+try:
+    flow.handle_turn("What can you do?")              # routes to converse
+    flow.handle_turn("Search the web for AI news.")   # routes to INTERNET_SEARCH
+    flow.handle_turn("Check the CrewAI docs.")         # routes to CREWAI_DOCS
+finally:
+    flow.finalize_session_traces()
+```
+
+للدردشة المحلية في الطرفية، استخدم `chat()`:
+
+```python
+def kickoff() -> None:
+    SupportFlow().chat()
+```
+
+يلف `chat()` استدعاءات `handle_turn()` داخل REPL، ويخرج عند `exit` / `quit`، ويتجاهل الأسطر الفارغة افتراضياً، ويستدعي `finalize_session_traces()` عند انتهاء الجلسة.
+
+### `ConversationConfig`
+
+مزخرف صنف يُلحق افتراضيات الدردشة على مستوى الصنف.
+
+| الحقل | الافتراضي | الغرض |
+|-------|-----------|-------|
+| `system_prompt` | `slices.conversational_system_prompt` من i18n | رسالة system يستخدمها `converse_turn` المدمج. مرر `""` للتعطيل التام. |
+| `llm` | `None` | LLM المحادثة (يستخدمه `converse_turn` وكاحتياطي للموجّه). |
+| `router` | `None` | تجاوزات `RouterConfig` اختيارية. مع وجود مستمعين مخصصين وLLM قابل للحل، يُفعّل التوجيه تلقائياً حتى عند إغفال هذا الحقل. |
+| `answer_from_history_prompt` | افتراضي الإطار | **مهمل.** استخدم system prompt الخاص بـ `converse` أو تجاوز `converse_turn()`. |
+| `answer_from_history_llm` | `None` | **مهمل.** استخدم `llm`؛ إذ يتلقى `converse` السجل القانوني بالفعل. |
+| `intent_llm` | `None` | LLM لمسار التصنيف المسبق القديم `intents=`/`default_intents`. |
+| `default_intents` | `None` | تسميات النتائج للتصنيف المسبق القديم. |
+| `visible_agent_outputs` | `None` | `"all"` أو قائمة بأسماء الـ agents الذين تُرفع مخرجاتهم من `append_agent_result()` إلى رسائل عامة. |
+| `defer_trace_finalization` | `True` | يبقي دفعة trace واحدة مفتوحة عبر استدعاءات `handle_turn()`. |
+
+<Warning>
+  تم إهمال `answer_from_history_prompt` و`answer_from_history_llm` ومسار
+  `answer_from_history`، وستُزال في إصدار مستقبلي. فهي تكرر `converse`، الذي
+  يتولى بالفعل السجل القانوني، وتضيف استدعاء LLM للتحقق من أهلية الإجابة،
+  ويجري تجاوزها عندما يعيد الموجّه التلقائي المعتاد مساراً. تظل الإعدادات
+  الحالية تعمل وتُصدر `DeprecationWarning`.
+</Warning>
+
+عند عدم وجود مسارات مخصصة، تسقط الجولات إلى `converse`. ومع وجود مسارات مخصصة وLLM للمحادثة/الموجّه، ينشئ الإطار `RouterConfig` افتراضية؛ لا توفر واحدة صراحةً إلا لتخصيص المطالبة أو قائمة المسارات أو الأوصاف أو سلوك fallback. أما ضبط `default_intents` فيستخدم مسار التصنيف المسبق القديم.
+
+إذا لم يُهيأ LLM للمحادثة، يعيد `converse_turn` المدمج عنصراً نائباً للإعداد بدلاً من توليد إجابة.
+
+### `RouterConfig` وفهرس المسارات المُولَّد تلقائياً
+
+```python
+from typing import Literal
+
+from pydantic import BaseModel
+
+from crewai import LLM
+from crewai.flow import RouterConfig
+
+
+class MyRoute(BaseModel):
+    intent: Literal["INTERNET_SEARCH", "CREWAI_DOCS", "converse"]
+
+
+ROUTER_LLM = LLM(model="gpt-4o-mini")
+
+
+router_config = RouterConfig(
+    prompt="Optional domain framing (policy, voice, persona).",
+    response_format=MyRoute,        # optional; auto-generated otherwise
+    llm=ROUTER_LLM,                  # falls back to ConversationConfig.llm
+    routes=["INTERNET_SEARCH", "CREWAI_DOCS"],   # optional; inferred from listeners
+    route_descriptions={
+        "INTERNET_SEARCH": "Override the docstring for this one route.",
+    },
+    default_intent="converse",       # used when LLM call fails or no LLM available
+    fallback_intent="converse",      # used when LLM returns an invalid route
+    intent_field="intent",
+)
+```
+
+تُبنى رسالة الموجّه إلى LLM تلقائياً. لكل مسار يختار الإطار وصفاً بهذا الترتيب من الأولوية:
+
+1. `RouterConfig.route_descriptions[label]` — تجاوز صريح.
+2. `Flow.builtin_route_descriptions[label]` — نص جاهز من الإطار لـ `converse` و`end` ولمسار التوافق المهمل `answer_from_history` (مصاغ لـ LLM التوجيه).
+3. قيمة `description` المعلنة للطريقة (تستخدمها التدفقات التعريفية وإسقاطات DSL).
+4. أول سطر غير فارغ من docstring معالج `@listen(label)`.
+5. فارغ (المسار يظهر في الفهرس بلا وصف).
+
+عملياً، **إضافة مسار جديد = `@listen("X")` + docstring من سطر واحد**:
+
+```python
+from crewai.flow import listen
+
+
+@listen("INTERNET_SEARCH")
+def handle_internet_search(self) -> str:
+    """Fresh web research, current news, real-time lookups."""
+    ...
+```
+
+…وسيرى LLM التوجيه:
+
+```
+Routes:
+- CREWAI_DOCS: Look up the CrewAI documentation for framework/API questions.
+- INTERNET_SEARCH: Fresh web research, current news, real-time lookups.
+- converse: Ordinary chat, follow-ups, summaries, clarifications…
+- end: User signals the conversation is finished (goodbye, exit, done).
+```
+
+`RouterConfig.prompt` مخصص لـ **تأطير النطاق** (شخصية المساعد، قواعد العمل، النبرة). فهرس المسارات يُبنى تلقائياً — لا تُدرج المسارات في `prompt`؛ سيختل التزامن لحظة إضافة معالج جديد.
+
+### تسمية المعالجات
+
+السلسلة النصية في `@listen("…")` هي **تسمية مسار للموجّه** (اسم حدث)، وليست اسم طريقة Python. تتشارك تسميات المسارات وأحداث اكتمال الطرق مساحة مشغلات واحدة، ولذلك تؤدي تسمية المعالج باسم مساره نفسه إلى إعادة تشغيل المعالج في حلقة.
+
+استخدم اسماً مختلفاً للطريقة — تستخدم أمثلة التوثيق بادئة `handle_*`:
+
+```python
+@listen("create_video")
+def handle_create_video(self) -> str:
+    """User wants a new video."""
+    ...
+```
+
+لا تكرر تسمية المسار في اسم الطريقة:
+
+```python
+@listen("create_video")
+def create_video(self) -> str:  # rejected at flow instantiation
+    ...
+```
+
+### المسارات المدمجة
+
+| المسار | المعالج | الغرض |
+|--------|---------|-------|
+| `converse` | `converse_turn` | معالج الدردشة الافتراضي. يستدعي `ConversationConfig.llm` بـ system prompt + التاريخ القانوني للرسائل. |
+| `end` | `end_conversation` | يضبط `state.ended = True` ويُصدر رد إنهاء. |
+| `answer_from_history` | `answer_from_history_turn` | **مسار توافق مهمل.** استخدم `converse`، الذي يتلقى السجل القانوني بالفعل. |
+
+يمكنك تجاوز أي من هذه بتعريف معالج بنفس الاسم في الصنف الفرعي.
+
+### دلالات `handle_turn()`
+
+`flow.handle_turn(message)` يُشغّل جولة واحدة:
+
+1. يعيد ضبط تعقّب التنفيذ لكل جولة (`_completed_methods`, `_method_outputs`) ليُعاد تشغيل الرسم — بدون ذلك، استدعاءات `kickoff` المتكررة على نفس النسخة ستُحدث دائرة قصر من الجولة الثانية لأن `Flow.kickoff_async` يعتبر `inputs={"id": ...}` استعادة من نقطة تفتيش.
+2. يُلحق رسالة المستخدم بـ `state.messages` ويضبط `current_user_message` / `last_user_message`. يُحافَظ على `last_intent` **من الجولة السابقة** كي يستخدمها LLM التوجيه كإشارة.
+3. يُشغّل طرق `@start` التي يعرّفها المستخدم (إن وجدت)، ثم `route_conversation` كنقطة البدء/الموجّه المدمجة، ثم معالج `@listen` المختار. وتستدعي `route_conversation` المساعد القابل للتجاوز `conversation_start()`.
+4. يخزّن الموجّه قراره في `state.last_intent` (يكون مرئياً لسياق التوجيه في الجولة التالية).
+5. إذا أعاد معالجك سلسلة نصية ولم يستدعِ `append_assistant_message`، فإن `handle_turn` يُلحقها نيابةً عنك ويحفظ `state.messages` المحدَّث حتى تشمل استعادة `@persist` جولة المساعد.
+
+استدعِ `handle_turn()` لرسائل الدردشة. استدعاء `kickoff(inputs={"id": ...})` مباشرةً يشغل الرسم بدون غلاف الجولة المحادثية.
+
+### `chat()` للـ REPL المحلي
+
+`flow.chat()` هو غلاف الطرفية الجاهز فوق `handle_turn()`:
+
+```python
+flow = SupportFlow()
+flow.chat()
+```
+
+يتولى الحلقة المحلية الشائعة:
+
+1. يطلب رسالة من المستخدم.
+2. يتوقف عند `exit` / `quit` أو `EOFError` أو `KeyboardInterrupt`.
+3. يستدعي `handle_turn(message, session_id=...)`.
+4. يطبع نتيجة المساعد.
+5. ينهي traces الجلسة المؤجلة داخل كتلة `finally`.
+
+يُفعّل `chat(defer_trace_finalization=True)` مؤقتاً علم التأجيل على مستوى المثيل للـ REPL، ثم يعيد قيمته السابقة عند الخروج.
+
+خصص سلوك الطرفية عبر I/O قابل للحقن:
+
+```python
+flow.chat(
+    session_id="demo-session",
+    prompt="You: ",
+    assistant_prefix="Assistant: ",
+    exit_commands=("exit", "quit", "bye"),
+)
+```
+
+لتطبيقات الويب والـ workers الخلفية والاختبارات ووسائط النقل المخصصة، استمر في استخدام `handle_turn()` مباشرةً.
+
+### سلوك موجّه مخصص
+
+لتشغيل آثار جانبية (إعداد ناقل أحداث، قياس عن بُعد) في كل قرار توجيه، تجاوز `route_turn`:
+
+```python
+from typing import Any
+
+from crewai import Flow
+from crewai.flow import ConversationState
+
+
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    def route_turn(self, context: dict[str, Any]) -> str | None:
+        self.event_bus = MyBus(self)
+        return super().route_turn(context)
+```
+
+لتجاوز موجّه LLM بالكامل واختيار مسار برمجياً، أعد سلسلة نصية غير فارغة من `route_turn`. لا يؤدي إرجاع قيمة falsy من التجاوز إلى استدعاء `_route_with_config()`؛ بل يسقط التوجيه إلى النية المصنّفة مسبقاً لهذه الجولة، ثم إلى مسار التوافق المهمل `answer_from_history` عند إعداده، وأخيراً إلى `converse`. تكون `last_intent` من الجولة السابقة متاحة في سياق الموجّه، لكنها لا تُعاد أبداً كـ fallback.
+
+### `append_assistant_message` و`append_agent_result`
+
+داخل معالج `@listen(label)`، اختر:
+
+- `self.append_assistant_message(text)` — يضيف جولة مساعد مرئية للمستخدم إلى `state.messages`. سيراها `converse_turn` في الجولة التالية.
+- `self.append_agent_result(agent_name, result, visibility="private")` — يسجّل حدثاً منظماً في `state.events` وموضوعاً في `state.agent_threads[agent_name]`. الرؤية العامة تستدعي `append_assistant_message` أيضاً. استخدم النتائج الخاصة للعمل الجانبي الذي يجب ألا يلوث التاريخ القانوني.
+
+يمكن لـ `ConversationConfig.visible_agent_outputs` رفع النتائج الخاصة لـ agents محددين إلى عامة عالمياً (`"all"` أو قائمة بالأسماء).
+
+## تعريف تدفق محادثاتي بصيغة JSON/YAML
+
+يمكن لـ [التدفق التعريفي](/edge/ar/concepts/cli) أن يكون محادثاتيًا أيضًا. أضف كتلة `conversational` في المستوى الأعلى وعرّف مساراتك الخاصة كطرق تستمع (`listen`) إلى تسمية مسار:
+
+```yaml
+schema: crewai.flow/v1
+name: SupportFlow
+
+conversational:
+  system_prompt: You are a terse support assistant.
+  llm: gpt-4o-mini
+  router:
+    llm: gpt-4o-mini
+
+methods:
+  handle_order:
+    description: Order status, shipping and delivery questions.
+    listen: order
+    do:
+      call: agent
+      with:
+        role: Support specialist
+        goal: Answer order questions accurately
+        backstory: Knows the fulfilment pipeline.
+        input: "${state.current_user_message}"
+```
+
+تعريف الكتلة هو الاشتراك نفسه — القيمة الافتراضية لـ `enabled` هي `true`. اضبطها على `enabled: false` للاحتفاظ بالإعدادات مع إيقاف المحادثة. يؤدي ذلك أيضاً إلى تعطيل إنشاء الطرق المدمجة، ولذلك يجب أن توفر التعريفة رسماً عادياً غير محادثاتي.
+
+تُوفَّر لك ثلاثة أشياء:
+
+| المُوفَّر | التفاصيل |
+|----------|--------|
+| الرسم البياني المدمج | تُضاف `route_conversation` و`converse_turn` و`end_conversation` تلقائيًا. يُحتفظ بـ `answer_from_history_turn` المهملة للتوافق. عرّف طريقة بأحد هذه الأسماء لتجاوزها. |
+| حالة المحادثة | تُستخدم `ConversationState` عند عدم وجود كتلة `state`. وتُركّب حالة Pydantic ذات `ref` أو `json_schema` تلقائياً مع الحقول المحادثية؛ ولا يلزم أن ترث من `ConversationState`. |
+| كتالوج المسارات | يُستنتج من الطرق غير الموجّهة التي تحمل تسميات `listen`، مع استبعاد المسارات الداخلية. تتبع الأوصاف ترتيب الأولوية أعلاه، ويمكن لـ `router.routes` الصريحة تقييد الخيارات. |
+
+تقبل حقول `llm` و`router.llm` و`intent_llm` التعريفية إما معرّف نموذج أو خريطة إعدادات مثل `{model: openai/gpt-4o-mini, max_tokens: 512}`. وتدعم كتلة `conversational` أيضاً `default_intents` و`visible_agent_outputs` و`defer_trace_finalization` وحقول `RouterConfig` الموضحة أعلاه. تظل تعريفات `answer_from_history_prompt` / `answer_from_history_llm` المهملة مقبولة للتوافق.
+
+شغّله من Python بنفس واجهات الجولة المستخدمة مع تدفق محادثاتي معرّف بصنف:
+
+```python
+from crewai.flow import Flow
+
+flow = Flow.from_declaration(path="flow.yaml")
+
+try:
+    flow.handle_turn("Where is my order?", session_id="session-1")
+finally:
+    flow.finalize_session_traces()
+```
+
+### تسمية المسارات
+
+تتشارك تسميات المسارات وأسماء الطرق مساحة اسم واحدة للمشغّلات، لذا يجب ألا يحمل المعالج اسم المسار الذي يستمع إليه — يُرفض `create_video` الذي يستمع إلى `create_video` عند بناء التدفق. استخدم بادئة `handle_*`.
+
+### ما لا يمكن للتعريفة التعبير عنه
+
+| غير قابل للتعبير | استخدم بدلًا منه |
+|-----------------|-------------|
+| مثيل `LLM` حي أو `BaseLLM` مخصص | سلسلة معرّف نموذج أو خريطة إعدادات ثابتة |
+| `router.response_format` كصنف نموذج حيّ | سمِّ الصنف بمرجع python: `response_format: {python: my_project.schemas.ConversationRoute}`. احذفه ويولّد الإطار واحدًا |
+| تجاوز `route_turn()` | اكتب Flow بلغة Python، أو استبدل طريقة `route_conversation` التعريفية بإجراء `call: code` / expression |
+| تجاوز `can_answer_from_history()` | مهمل. استخدم `converse` أو تجاوز `converse_turn()` في Python. |
+
+يفتح `crewai run` واجهة المحادثة النصية للتدفق المحادثاتي التعريفي — نفس الواجهة التي يحصل عليها Flow محادثاتي مكتوب بلغة Python. تحتاج حلقة المحادثة إلى طرفية، ولذلك يخرج التشغيل بدون طرفية برمز غير صفري مع إرشادات بدلاً من تنفيذ جولة واحدة؛ شغّله من Python هناك عبر `handle_turn()` أو `stream_turn()`. وتعمل الطريقة التعريفية ذات كتلة `human_feedback:` (وفي Python: ‏`@human_feedback`) على REPL طرفي، لأن runtime يجمع الملاحظات بمطالبة حاجزة لا تستطيع TUI خدمتها. لا يُقبل `--inputs` مع Flow محادثاتي — فمدخل كل جولة هو الرسالة التي تكتبها — واستئناف جلسة حسب المعرّف غير موصول بواجهة CLI بعد؛ استخدم `flow.handle_turn(message, session_id=...)` من Python لذلك.
+
+## التتبع عبر الجولات
+
+مع `defer_trace_finalization=True` (افتراضي في `ConversationConfig`):
+
+- **دفعة trace واحدة** لجلسة الدردشة.
+- **`flow_started`** في الجولة الأولى فقط؛ **`flow_finished`** مرة في `finalize_session_traces()`.
+- **`kickoff` لكل جولة** لا يطبع "Trace batch finalized".
+- **العمل المتداخل** (`Agent.kickoff()`, crews, Exa) يُلحق بدفعة **الأب**؛ flow داخلي من `AgentExecutor` لا يغلق دفعة الجلسة مبكراً.
+
+```python
+flow.chat(session_id=session_id)
+```
+
+`flow.chat()` يستدعي `finalize_session_traces()` نيابةً عنك. عندما تملك الحلقة عبر `handle_turn()`، استدعِ `finalize_session_traces()` عند انتهاء الجلسة.
+
+يخفي `suppress_flow_events=True` لوحات Rich ويمنع أحداث تنفيذ الطرق. وتظل أحداث بدء/انتهاء Flow تصدر، فيبقى بالإمكان تتبع دورة حياة Flow الخارجية، بينما تُحذف spans الطرق الفردية.
+
+### دورة حياة trace لـ `Flow` المحادثاتي
+
+يستخدم [`Flow` المحادثاتي](#flow-المحادثاتي) دورة حياة التتبع نفسها: القيمة الافتراضية لـ `defer_trace_finalization` هي `True`، ولذلك يبقي كل `handle_turn()` trace الجلسة مفتوحاً. تمنع الجولات المؤجلة أيضاً إصدار `flow_failed` لكل جولة؛ وعند حدوث خطأ في جولة أو إلغاء الجلسة، أنهِ الجلسة صراحةً. يغلق ذلك الدفعة بحدث `FlowFinished` على مستوى الجلسة بدلاً من حدث `FlowFailed` لكل جولة. لُف REPL/الحلقة دائماً بـ `try/finally` واستدعِ `flow.finalize_session_traces()` عند الخروج. بدون ذلك، تبقى دفعة trace مفتوحة وقد لا تُصدَّر المحادثة النهائية أبداً.
+
+## البث
+
+استخدم `stream_turn()` للواجهات المحادثية، وكرّر عبر كائنات `StreamFrame` المرتبة التي يعيدها:
+
+```python
+stream = flow.stream_turn("Where is my order?", session_id=session_id)
+
+with stream:
+    for frame in stream.events:
+        if frame.channel == "llm" and frame.type == "llm_stream_chunk":
+            print(frame.content, end="", flush=True)
+
+reply = stream.result
+```
+
+بالنسبة إلى Flow غير محادثاتي، يؤدي ضبط `stream = True` إلى جعل `kickoff()` يعيد `StreamSession`. لا تضبط `flow.stream = True` عند استخدام `handle_turn()`؛ إذ تملك `stream_turn()` دورة حياة البث المحادثاتي.
+
+## الاستيراد
+
+```python
+from crewai.flow import (
+    ChatState,
+    ConversationalConfig,
+    ConversationalInputs,
+    Flow,
+    listen,
+    persist,
+    router,
+    start,
+)
+from crewai.flow.conversation import prepare_conversational_turn
+from crewai.flow import (
+    ConversationConfig,
+    ConversationState,
+    RouterConfig,
+)
+```
+
+## مراجع
+
+- [إتقان إدارة حالة Flow](/ar/guides/flows/mastering-flow-state)
+- [أنشئ أول Flow](/ar/guides/flows/first-flow)

docs/v1.15.19/ar/guides/flows/first-flow.mdx

@@ -0,0 +1,222 @@
+---
+title: ابنِ أول Flow لك
+description: تعلم كيفية إنشاء سير عمل منظمة قائمة على الأحداث مع تحكم دقيق في التنفيذ.
+icon: diagram-project
+mode: "wide"
+---
+
+## التحكم في سير عمل AI مع Flows
+
+تمثل CrewAI Flows المستوى التالي في تنسيق AI - الجمع بين القوة التعاونية لفرق Agents AI مع دقة ومرونة البرمجة الإجرائية. بينما تتفوق Crews في تعاون الـ Agents، تمنحك Flows تحكمًا دقيقًا في كيفية ووقت تفاعل المكونات المختلفة لنظام AI.
+
+في هذا الدليل، سنمشي عبر إنشاء CrewAI Flow قوي ينشئ دليلًا تعليميًا شاملاً حول أي موضوع.
+
+### ما يجعل Flows قوية
+
+تمكّنك Flows من:
+
+1. **الجمع بين أنماط تفاعل AI مختلفة** - استخدام Crews للمهام التعاونية المعقدة واستدعاءات LLM المباشرة للعمليات الأبسط والكود العادي للمنطق الإجرائي
+2. **بناء أنظمة قائمة على الأحداث** - تحديد كيفية استجابة المكونات لأحداث وتغييرات بيانات محددة
+3. **الحفاظ على الحالة عبر المكونات** - مشاركة وتحويل البيانات بين أجزاء مختلفة من تطبيقك
+4. **التكامل مع الأنظمة الخارجية** - ربط سير عمل AI بسلاسة مع قواعد البيانات وواجهات API وواجهات المستخدم
+5. **إنشاء مسارات تنفيذ معقدة** - تصميم فروع شرطية ومعالجة متوازية وسير عمل ديناميكية
+
+### المتطلبات المسبقة
+
+قبل البدء، تأكد من:
+
+1. تثبيت CrewAI باتباع [دليل التثبيت](/ar/installation)
+2. إعداد مفتاح API لنموذج LLM في بيئتك، باتباع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm)
+3. فهم أساسي لـ Python
+
+## الخطوة 1: إنشاء مشروع CrewAI Flow جديد
+
+```bash
+crewai create flow guide_creator_flow
+cd guide_creator_flow
+```
+
+<Frame caption="نظرة عامة على إطار عمل CrewAI">
+  <img src="/images/flows.png" alt="نظرة عامة على إطار عمل CrewAI" />
+</Frame>
+
+## الخطوة 2: فهم هيكل المشروع
+
+يستخدم الـ crew المبدئي المضمّن في مشروع Flow بنية Python/YAML الكلاسيكية. لاستخدام crew بنمط JSON-first داخل Flow، أنشئ `crew.jsonc` و `agents/*.jsonc` داخل مجلد الـ crew وحمّله عبر `crewai.project.load_crew` كما في [Flows](/ar/concepts/flows#building-your-crews).
+
+```
+guide_creator_flow/
+├── .gitignore
+├── pyproject.toml
+├── README.md
+├── .env
+└── src/
+    └── guide_creator_flow/
+        ├── __init__.py
+        ├── main.py
+        ├── crews/
+        │   └── poem_crew/
+        │       ├── config/
+        │       │   ├── agents.yaml
+        │       │   └── tasks.yaml
+        │       └── poem_crew.py
+        └── tools/
+            └── custom_tool.py
+```
+
+يوفر هذا الهيكل فصلاً واضحًا بين مكونات Flow المختلفة. سنعدّل هذا الهيكل لإنشاء Flow منشئ الدليل.
+
+## الخطوة 3: إضافة Crew كتابة المحتوى
+
+```bash
+crewai flow add-crew content-crew
+```
+
+## الخطوة 4: تهيئة Crew كتابة المحتوى
+
+سنهيئ crew كتابة المحتوى باستخدام JSONC. سنعرّف Agent للكتابة وAgent للمراجعة، ثم نحمّل `crew.jsonc` من خطوة Flow.
+
+1. أنشئ `src/guide_creator_flow/crews/content_crew/agents/content_writer.jsonc`:
+
+```jsonc
+{
+  "role": "Educational Content Writer",
+  "goal": "Create engaging, informative content that thoroughly explains the assigned topic and provides valuable insights to the reader.",
+  "backstory": "You are a talented educational writer who explains complex concepts in accessible language and organizes information clearly.",
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true
+  }
+}
+```
+
+2. أنشئ `src/guide_creator_flow/crews/content_crew/agents/content_reviewer.jsonc`:
+
+```jsonc
+{
+  "role": "Educational Content Reviewer and Editor",
+  "goal": "Ensure content is accurate, comprehensive, well-structured, and consistent with previously written sections.",
+  "backstory": "You are a meticulous editor with an eye for detail, clarity, and coherence.",
+  "llm": "provider/model-id",
+  "settings": {
+    "verbose": true
+  }
+}
+```
+
+استبدل `provider/model-id` بالنموذج الذي تستخدمه، مثل `openai/gpt-4o` أو `gemini/gemini-3.7-flash` أو `anthropic/claude-sonnet-4-6`.
+
+3. أنشئ `src/guide_creator_flow/crews/content_crew/crew.jsonc`:
+
+```jsonc
+{
+  "name": "Content Crew",
+  "agents": ["content_writer", "content_reviewer"],
+  "tasks": [
+    {
+      "name": "write_section_task",
+      "description": "Write a comprehensive section on the topic: \"{section_title}\".\n\nSection description: {section_description}\nTarget audience: {audience_level} level learners\n\nYour content should begin with a brief introduction, explain key concepts clearly with examples, include practical applications where appropriate, end with a summary, and be approximately 500-800 words.\n\nPreviously written sections:\n{previous_sections}",
+      "expected_output": "A well-structured, comprehensive section in Markdown format that thoroughly explains the topic and is appropriate for the target audience.",
+      "agent": "content_writer",
+      "markdown": true
+    },
+    {
+      "name": "review_section_task",
+      "description": "Review and improve this section on \"{section_title}\":\n\n{draft_content}\n\nTarget audience: {audience_level} level learners\nPreviously written sections:\n{previous_sections}\n\nFix errors, improve clarity, verify consistency, enhance structure, and add missing key information.",
+      "expected_output": "An improved, polished version of the section that maintains the original structure but enhances clarity, accuracy, and consistency.",
+      "agent": "content_reviewer",
+      "context": ["write_section_task"],
+      "markdown": true
+    }
+  ],
+  "process": "sequential",
+  "verbose": true
+}
+```
+
+4. استبدل `src/guide_creator_flow/crews/content_crew/content_crew.py` بمحمل صغير:
+
+```python
+from pathlib import Path
+
+from crewai.project import load_crew
+
+
+def kickoff_content_crew(inputs: dict):
+    crew, default_inputs = load_crew(Path(__file__).with_name("crew.jsonc"))
+    return crew.kickoff(inputs={**default_inputs, **inputs})
+```
+
+## الخطوة 5: إنشاء Flow
+
+الآن الجزء المثير - إنشاء Flow الذي سينسّق عملية إنشاء الدليل بالكامل. راجع الملف الإنجليزي الأصلي للكود الكامل لـ `main.py` حيث أن الكود يبقى كما هو.
+
+## الخطوة 6: إعداد متغيرات البيئة
+
+أنشئ ملف `.env` في جذر مشروعك بمفاتيح API. راجع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm) لتفاصيل تهيئة المزود.
+
+```sh .env
+OPENAI_API_KEY=your_openai_api_key
+# or
+GEMINI_API_KEY=your_gemini_api_key
+# or
+ANTHROPIC_API_KEY=your_anthropic_api_key
+```
+
+## الخطوة 7: تثبيت التبعيات
+
+```bash
+crewai install
+```
+
+## الخطوة 8: تشغيل Flow
+
+```bash
+crewai run
+```
+
+عند تشغيل هذا الأمر، ستشاهد Flow يعمل:
+1. سيطلب منك موضوعًا ومستوى الجمهور
+2. سينشئ مخططًا منظمًا لدليلك
+3. سيعالج كل قسم مع تعاون الكاتب والمراجع
+4. أخيرًا سيجمع كل شيء في دليل شامل
+
+## الخطوة 9: تصوير Flow
+
+```bash
+crewai flow plot
+```
+
+سينشئ ملف HTML يوضح هيكل Flow بما في ذلك العلاقات بين الخطوات المختلفة.
+
+## الخطوة 10: مراجعة المخرجات
+
+بمجرد اكتمال Flow، ستجد ملفين في مجلد `output`:
+
+1. `guide_outline.json`: يحتوي على المخطط المنظم للدليل
+2. `complete_guide.md`: الدليل الشامل بجميع الأقسام
+
+## الميزات الرئيسية الموضّحة
+
+يوضح Flow منشئ الدليل عدة ميزات قوية لـ CrewAI:
+
+1. **تفاعل المستخدم**: يجمع Flow مدخلات مباشرة من المستخدم
+2. **استدعاءات LLM المباشرة**: يستخدم فئة LLM لتفاعلات AI فعّالة وأحادية الغرض
+3. **بيانات منظمة مع Pydantic**: يستخدم نماذج Pydantic لضمان سلامة الأنواع
+4. **معالجة تسلسلية مع سياق**: يكتب الأقسام بالترتيب ويوفر الأقسام السابقة كسياق
+5. **Crews متعددة الـ Agents**: يستفيد من Agents متخصصة (كاتب ومراجع) لإنشاء المحتوى
+6. **إدارة الحالة**: يحافظ على الحالة عبر خطوات العملية المختلفة
+7. **بنية قائمة على الأحداث**: يستخدم مزخرف `@listen` للاستجابة للأحداث
+
+## الخطوات التالية
+
+1. جرّب هياكل Flow أكثر تعقيدًا وأنماطًا
+2. جرّب استخدام `@router()` لإنشاء فروع شرطية
+3. استكشف دوال `and_` و`or_` لتنفيذ متوازٍ أكثر تعقيدًا
+4. اربط Flow بواجهات API خارجية وقواعد بيانات وواجهات مستخدم
+5. ادمج عدة Crews متخصصة في Flow واحد
+6. أنشئ تطبيقات دردشة متعددة الجولات مع [تدفقات المحادثة](/ar/guides/flows/conversational-flows) (`kickoff` لكل رسالة، `ChatSession`، تأجيل التتبع)
+
+<Check>
+تهانينا! لقد بنيت بنجاح أول CrewAI Flow يجمع بين الكود العادي واستدعاءات LLM المباشرة ومعالجة Crew لإنشاء دليل شامل. هذه المهارات الأساسية تمكّنك من إنشاء تطبيقات AI متطورة بشكل متزايد.
+</Check>

docs/v1.15.19/ar/guides/flows/inputs-id-deprecation.mdx

@@ -0,0 +1,102 @@
+---
+title: "الانتقال من inputs.id إلى restore_from_state_id"
+description: "نقل تدفقات @persist من ترطيب inputs.id المهجور إلى حقل restore_from_state_id المدعوم"
+icon: "arrow-right-arrow-left"
+---
+
+<Warning>
+  تمرير `id` داخل `inputs` لترطيب تدفق `@persist` هو **مهجور** ومقرر إزالته في إصدار مستقبلي. البديل، `restore_from_state_id`، متاح في CrewAI **v1.14.5 وما بعده** — الخطوات أدناه تنطبق بمجرد أن تقوم بالتحديث.
+</Warning>
+
+## نظرة عامة
+
+الطريقة الموثقة لترطيب تدفق `@persist` من تنفيذ سابق هي تمرير UUID لذلك التنفيذ كـ `inputs.id`. الآن، تكشف CrewAI عن حقل مخصص، `restore_from_state_id`، الذي يقوم بنفس الترطيب دون تحميل حمولة `inputs` — ودون ربط مفتاح الترطيب بهوية التنفيذ الجديد.
+
+## الانتقال
+
+إذا كنت حالياً تبدأ تدفق `@persist` باستخدام `inputs={"id": ...}`:
+
+```python
+# مهجور
+flow = CounterFlow()
+flow.kickoff(inputs={"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv"})
+```
+
+انتقل إلى `restore_from_state_id`:
+
+```python
+# مدعوم
+flow = CounterFlow()
+flow.kickoff(restore_from_state_id="abcd1234-5678-90ef-ghij-klmnopqrstuv")
+```
+
+تتمتع الوضعيتان بمعاني سلالة مختلفة:
+
+- `inputs={"id": <uuid>}` (مهجور) — **استئناف**: تكتب الكتابات تحت المعرف المقدم، مما يمدد نفس تاريخ `flow_uuid`.
+- `restore_from_state_id=<uuid>` — **تفرع**: يترطب الحالة من اللقطة، ثم يكتب تحت `state.id` جديدة. يتم الحفاظ على تاريخ التدفق المصدر.
+
+لأغلب سيناريوهات الإنتاج — إعادة تشغيل تدفق تم تهيئته من حالة سابقة — فإن التفرع هو ما تريده. راجع [إتقان حالة التدفق](/ar/guides/flows/mastering-flow-state) للحصول على النموذج الذهني الكامل.
+
+إذا كنت تبدأ تدفقك عبر واجهة برمجة تطبيقات CrewAI AMP REST، راجع [AMP](#amp) أدناه لهجرة الحمولة المعادلة.
+
+## لماذا نقوم بإهمال `inputs.id` لـ `@persist`
+
+`inputs.id` هو حالياً الطريقة الموثقة لاستئناف تدفق `@persist` من تنفيذ سابق. المشكلة هي أن نفس UUID يقوم بوظيفتين في وقت واحد:
+
+1. **يحدد أي لقطة يترطب منها `@persist`** — تحميل الحالة المحفوظة تحت ذلك UUID.
+2. **يصبح معرف تنفيذ التدفق الجديد** (`state.id` في SDK؛ يظهر كـ `flow_id` في بعض السياقات) — كل كتابة `@persist` من هذه البداية أيضاً تقع تحت نفس UUID.
+
+هذه الوظيفة المزدوجة هي السبب الجذري للمشاكل التي يصفها هذا الدليل. لأن UUID المقدم هو أيضاً معرف التنفيذ الجديد، فإن بدايتين تمرران نفس `inputs.id` ليست تنفيذين متميزين — إنهما تشتركان في معرف، وتشاركان في سجل الاستمرارية، و(على AMP) تشتركان في صف في قائمة التنفيذات. لا توجد طريقة للقول "ترطب من هذه اللقطة، ولكن سجل هذا التشغيل بشكل منفصل" دون تقسيم المسؤوليتين.
+
+`restore_from_state_id` هو هذا الانقسام. إنه يخبر `@persist` من أي لقطة يترطب، بينما يترك التنفيذ الجديد حراً لاستلام `state.id` جديدة. لم يعد مصدر الترطيب والتشغيل المسجل نفس UUID — وهو ما تريده معظم سيناريوهات الإنتاج فعلياً.
+
+## جدول إزالة
+
+من المقرر إزالة `inputs.id` لترطيب `@persist` في إصدار مستقبلي من CrewAI. لا يوجد قطع صارم فوري — تظل التدفقات الحالية تعمل — ولكن بمجرد أن تقوم بالتحديث إلى v1.14.5 أو ما بعده، يجب أن يستخدم الكود الجديد `restore_from_state_id`، ويجب أن تهاجر التدفقات الحالية في الفرصة المناسبة التالية.
+
+## AMP
+
+إذا كنت تنشر تدفقك إلى CrewAI AMP، فإن الهجرة تمتد إلى الحمولة التي تبدأ بها المرسلة إلى طاقمك المنشور، وتظهر الأعراض المرئية لإعادة استخدام `inputs.id` على لوحة معلومات النشر. تغطي القسمان الفرعيان أدناه كلاهما.
+
+### هجرة حمولة البداية
+
+إذا كنت حالياً تبدأ تدفقاً منشوراً عن طريق تضمين `id` في `inputs`:
+
+```bash
+# مهجور
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
+  -d '{"inputs": {"id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", "topic": "AI Agent Frameworks"}}' \
+  https://your-crew-url.crewai.com/kickoff
+```
+
+نقل UUID إلى حقل `restoreFromStateId` في المستوى الأعلى:
+
+```bash
+# مدعوم
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
+  -d '{
+        "inputs": {"topic": "AI Agent Frameworks"},
+        "restoreFromStateId": "abcd1234-5678-90ef-ghij-klmnopqrstuv"
+      }' \
+  https://your-crew-url.crewai.com/kickoff
+```
+
+يجلس `restoreFromStateId` بجانب `inputs` في حمولة البداية، وليس داخلها. الآن، يحمل كائن `inputs` فقط القيم التي تستهلكها تدفقك فعلياً.
+
+### ماذا يحدث عند إعادة استخدام `inputs.id`
+
+عندما تتلقى AMP بداية لتدفق يتطابق `inputs.id` الخاص به مع تنفيذ موجود، فإنه يحل إلى السجل الموجود بدلاً من إنشاء سجل جديد. من لوحة معلومات النشر سترى:
+
+- **حالة التنفيذ** — حالة التشغيل الجديد تحل محل حالة التشغيل السابق. يمكن أن تعود تنفيذات مكتملة إلى `جارية`، أو يمكن أن تتحول تشغيلات `مكتملة` إلى `خطأ` إذا فشلت البداية الجديدة — في كلتا الحالتين، لم تعد لوحة المعلومات تعكس التشغيل الأصلي.
+- **التتبع** — تتراكم تتبعات OTel عبر البدايات لأنها تشترك في نفس معرف التنفيذ؛ تتبعات التشغيل السابق إما تُستبدل بـ، أو تُخلط مع، تشغيل الجديد. لم يعد إعادة التشغيل خطوة بخطوة يتوافق مع تنفيذ واحد.
+- **قائمة التنفيذات** — البدايات التي يجب أن تظهر كصفوف منفصلة تتقلص إلى إدخال واحد، مما يخفي التاريخ.
+
+تساعد الهجرة إلى `restoreFromStateId` في الحفاظ على كل بداية كتنفيذ خاص بها — مع حالتها الخاصة، وتتبعها، وصفها في القائمة — بينما لا تزال ترطب الحالة من تشغيل سابق.
+
+<Card title="هل تحتاج مساعدة؟" icon="headset" href="mailto:support@crewai.com">
+  اتصل بفريق الدعم لدينا إذا لم تكن متأكداً من أي وضع يحتاجه تدفقك أو واجهت مشاكل أثناء الهجرة.
+</Card>

docs/v1.15.19/ar/guides/flows/mastering-flow-state.mdx

@@ -0,0 +1,228 @@
+---
+title: إتقان إدارة حالة Flow
+description: دليل شامل لإدارة الحالة وحفظها والاستفادة منها في CrewAI Flows لبناء تطبيقات AI قوية.
+icon: diagram-project
+mode: "wide"
+---
+
+## فهم قوة الحالة في Flows
+
+إدارة الحالة هي العمود الفقري لأي سير عمل AI متطور. في CrewAI Flows، يتيح لك نظام الحالة الحفاظ على السياق ومشاركة البيانات بين الخطوات وبناء منطق تطبيق معقد. إتقان إدارة الحالة ضروري لإنشاء تطبيقات AI موثوقة وقابلة للصيانة وقوية.
+
+### لماذا تهم إدارة الحالة
+
+تمكّنك إدارة الحالة الفعّالة من:
+
+1. **الحفاظ على السياق عبر خطوات التنفيذ** - تمرير المعلومات بسلاسة بين مراحل سير العمل المختلفة
+2. **بناء منطق شرطي معقد** - اتخاذ قرارات بناءً على البيانات المتراكمة
+3. **إنشاء تطبيقات مستمرة** - حفظ واستعادة تقدم سير العمل
+4. **معالجة الأخطاء بلطف** - تنفيذ أنماط استرداد لتطبيقات أكثر قوة
+5. **توسيع تطبيقاتك** - دعم سير العمل المعقدة بتنظيم بيانات مناسب
+6. **تمكين التطبيقات الحوارية** - تخزين والوصول إلى سجل المحادثات للتفاعلات الواعية بالسياق
+
+للدردشة متعددة الجولات (`kickoff` لكل سطر مستخدم، `ChatState`، توجيه النية، تأجيل التتبع، و`ChatSession`)، راجع [تدفقات المحادثة](/ar/guides/flows/conversational-flows).
+
+## أساسيات إدارة الحالة
+
+### نهجان لإدارة الحالة
+
+يوفر CrewAI طريقتين لإدارة الحالة في Flows:
+
+1. **الحالة غير المنظمة** - استخدام كائنات شبيهة بالقاموس للمرونة
+2. **الحالة المنظمة** - استخدام نماذج Pydantic لسلامة الأنواع والتحقق
+
+### مثال الحالة غير المنظمة
+
+```python
+from crewai.flow.flow import Flow, listen, start
+
+class UnstructuredStateFlow(Flow):
+    @start()
+    def initialize_data(self):
+        self.state["user_name"] = "Alex"
+        self.state["preferences"] = {"theme": "dark", "language": "English"}
+        self.state["items"] = []
+        return "Initialized"
+
+    @listen(initialize_data)
+    def process_data(self, previous_result):
+        user = self.state["user_name"]
+        self.state["items"].append("item1")
+        self.state["processed"] = True
+        return "Processed"
+
+flow = UnstructuredStateFlow()
+result = flow.kickoff()
+```
+
+### مثال الحالة المنظمة
+
+```python
+from crewai.flow.flow import Flow, listen, start
+from pydantic import BaseModel, Field
+from typing import List, Dict, Optional
+
+class AppState(BaseModel):
+    user_name: str = ""
+    items: List[str] = []
+    processed: bool = False
+    completion_percentage: float = 0.0
+
+class StructuredStateFlow(Flow[AppState]):
+    @start()
+    def initialize_data(self):
+        self.state.user_name = "Taylor"
+        return "Initialized"
+
+    @listen(initialize_data)
+    def process_data(self, previous_result):
+        self.state.items.append("item1")
+        self.state.processed = True
+        self.state.completion_percentage = 50.0
+        return "Processed"
+
+flow = StructuredStateFlow()
+result = flow.kickoff()
+```
+
+### فوائد الحالة المنظمة
+
+1. **سلامة الأنواع** - اكتشاف أخطاء الأنواع في وقت التطوير
+2. **توثيق ذاتي** - نموذج الحالة يوثّق بوضوح البيانات المتاحة
+3. **التحقق** - التحقق التلقائي من أنواع البيانات والقيود
+4. **دعم IDE** - إكمال تلقائي وتوثيق مضمّن
+5. **قيم افتراضية** - تعريف بدائل سهلة للبيانات المفقودة
+
+## حفظ حالة Flow
+
+يوفر مزخرف `@persist()` حفظ حالة تلقائي عند نقاط رئيسية في التنفيذ.
+
+```python
+from crewai.flow.flow import Flow, listen, start
+from crewai.flow.persistence import persist
+from pydantic import BaseModel
+
+class CounterState(BaseModel):
+    value: int = 0
+
+@persist()
+class PersistentCounterFlow(Flow[CounterState]):
+    @start()
+    def increment(self):
+        self.state.value += 1
+        return self.state.value
+
+    @listen(increment)
+    def double(self, value):
+        self.state.value = value * 2
+        return self.state.value
+```
+
+#### تفرع الحالة المستمرة
+
+يدعم `@persist` نمطين متميزين للترطيب في `kickoff` / `kickoff_async`. استخدم **استئناف** (`inputs["id"]`) لمواصلة نفس النسب؛ استخدم **تفرع** (`restore_from_state_id`) لبدء نسبٍ جديد من لقطة:
+
+| | `state.id` بعد kickoff | كتابات `@persist` تذهب إلى |
+|---|---|---|
+| `inputs["id"]` (استئناف) | المعرّف المقدم | المعرّف المقدم (يمد التاريخ) |
+| `restore_from_state_id` (تفرع) | معرّف جديد، أو `inputs["id"]` إذا ثُبّت | المعرّف الجديد (المصدر محفوظ) |
+
+```python
+from crewai.flow.flow import Flow, start
+from crewai.flow.persistence import persist
+from pydantic import BaseModel
+
+class CounterState(BaseModel):
+    id: str = ""
+    counter: int = 0
+
+@persist
+class CounterFlow(Flow[CounterState]):
+    @start()
+    def step(self):
+        self.state.counter += 1
+
+# التشغيل 1: حالة جديدة، العداد 0 -> 1
+flow_1 = CounterFlow()
+flow_1.kickoff()
+
+# التفرع: الترطيب من أحدث لقطة لـ flow_1، لكن الكتابة تحت state.id جديد
+flow_2 = CounterFlow()
+flow_2.kickoff(restore_from_state_id=flow_1.state.id)
+# يبدأ flow_2 بـ counter=1 (مرطّب)، ثم تزيده step() إلى 2.
+# تاريخ flow_uuid لـ flow_1 لم يتغيّر.
+```
+
+ملاحظات السلوك:
+
+- `restore_from_state_id` غير موجود في الاستمرارية → يعود kickoff بصمت إلى السلوك الافتراضي (يعكس سلوك `inputs["id"]` عند عدم العثور عليه). لا يُطلق أي استثناء.
+- الجمع بين `restore_from_state_id` و `from_checkpoint` يطلق `ValueError` — يستهدفان نظامي حالة مختلفين (`@persist` مقابل Checkpointing) ولا يمكن الجمع بينهما.
+- `restore_from_state_id=None` (افتراضي) متطابق بايت ببايت مع kickoff بدون المعامل.
+- تثبيت `inputs["id"]` أثناء التفرع يعني أن التشغيل الجديد يشارك مفتاح الاستمرارية مع تدفق آخر — عادةً ما تريد فقط `restore_from_state_id`.
+
+## أنماط حالة متقدمة
+
+### المنطق الشرطي المبني على الحالة
+
+```python
+from crewai.flow.flow import Flow, listen, router, start
+from pydantic import BaseModel
+
+class PaymentState(BaseModel):
+    amount: float = 0.0
+    is_approved: bool = False
+    retry_count: int = 0
+
+class PaymentFlow(Flow[PaymentState]):
+    @start()
+    def process_payment(self):
+        self.state.amount = 100.0
+        self.state.is_approved = self.state.amount < 1000
+        return "Payment processed"
+
+    @router(process_payment)
+    def check_approval(self, previous_result):
+        if self.state.is_approved:
+            return "approved"
+        elif self.state.retry_count < 3:
+            return "retry"
+        else:
+            return "rejected"
+
+    @listen("approved")
+    def handle_approval(self):
+        return f"Payment of ${self.state.amount} approved!"
+
+    @listen("retry")
+    def handle_retry(self):
+        self.state.retry_count += 1
+        return "Retry initiated"
+
+    @listen("rejected")
+    def handle_rejection(self):
+        return f"Payment of ${self.state.amount} rejected after {self.state.retry_count} retries."
+```
+
+## أفضل الممارسات لإدارة الحالة
+
+1. **اجعل الحالة مركّزة** - صمم الحالة لتحتوي فقط على ما هو ضروري
+2. **استخدم الحالة المنظمة للـ Flows المعقدة** - مع نمو التعقيد تصبح الحالة المنظمة أكثر قيمة
+3. **وثّق انتقالات الحالة** - للـ Flows المعقدة، وثّق كيف تتغير الحالة عبر التنفيذ
+4. **عالج أخطاء الحالة بلطف** - طبّق معالجة أخطاء للوصول إلى الحالة
+5. **استخدم الحالة لتتبع التقدم** - استفد من الحالة لتتبع التقدم في Flows طويلة التشغيل
+6. **استخدم العمليات غير المتغيرة عند الإمكان** - خاصة مع الحالة المنظمة
+
+## الخلاصة
+
+إتقان إدارة الحالة في CrewAI Flows يمنحك القدرة على بناء تطبيقات AI متطورة وقوية تحافظ على السياق وتتخذ قرارات معقدة وتقدم نتائج متسقة.
+
+<Check>
+لقد أتقنت الآن مفاهيم وممارسات إدارة الحالة في CrewAI Flows! بهذه المعرفة، يمكنك إنشاء سير عمل AI قوية تحافظ على السياق بفعالية وتشارك البيانات بين الخطوات وتبني منطق تطبيق متطور.
+</Check>
+
+## الخطوات التالية
+
+- جرّب الحالة المنظمة وغير المنظمة في Flows
+- جرّب تطبيق حفظ الحالة لسير العمل طويلة التشغيل
+- استكشف [بناء أول Crew](/ar/guides/crews/first-crew) لمعرفة كيف تعمل Crews وFlows معًا
+- اطلع على [توثيق مرجع Flow](/ar/concepts/flows) لمزيد من الميزات المتقدمة

docs/v1.15.19/ar/guides/frontend/channels.mdx

@@ -0,0 +1,156 @@
+---
+title: القنوات
+description: شغّل نفس وكيل CrewAI كروبوت على Slack أو Teams باستخدام CopilotKit Channels SDK ومنصة Intelligence المُدارة.
+icon: messages
+mode: "wide"
+---
+
+## قابل مستخدميك حيث هم بالفعل
+
+وكيل CrewAI الذي بنيته في [النظرة العامة](/edge/ar/guides/frontend/overview) لا يجب أن يعيش خلف تطبيق ويب فقط. يمكن لنفس الـ Crew أو الـ Flow أن يعمل كروبوت داخل منصة مراسلة. لا حاجة لإعادة البناء ولا لنسخة ثانية من منطق وكيلك: يبقى الوكيل مكشوفًا عبر [بروتوكول AG-UI](https://docs.ag-ui.com)، وتقوم **قناة** بتشغيله من Slack أو Microsoft Teams.
+
+يوفّر [Channels SDK](https://docs.copilotkit.ai/slack) من CopilotKit تلك القناة. تُعرّف `createChannel` في وقت تشغيل صغير، وتوجّهه إلى وكيل CrewAI الخاص بك، وتتولى منصة **Intelligence** المُدارة من CopilotKit التوسّط في الاتصال مع مزوّد المراسلة.
+
+<Note>
+على خلاف بقية هذا القسم، فإن Channels **ليست ذاتية الاستضافة**. تعمل من خلال **CopilotKit Intelligence** — وهي سطح مطلوب لـ Channels، بحكم التصميم (تتوفر طبقة مجانية). تحتفظ Intelligence باتصال المنصة وبيانات الاعتماد، وتستقبل كل حدث من المنصة، وتسلّم الدور إلى عملية قناتك؛ تشغّل عمليتك الوكيل وتبثّ الرد مرة أخرى. تقوم بإعداد Slack مرة واحدة في لوحة تحكم Intelligence، ولا تدخل بيانات اعتماد المنصة عمليتك أبدًا. يبقى وكيلك وأدواتك وحالتك ملكًا لك.
+</Note>
+
+## كيف تتكامل الأجزاء معًا
+
+لا يتغير أي شيء بخصوص خادم وكيل CrewAI الخاص بك. يستمر في تقديم الـ Crew أو الـ Flow عبر AG-UI تمامًا كما في النظرة العامة. ما تضيفه هو عملية Node منفصلة طويلة الأمد مبنية باستخدام `@copilotkit/channels`: تسجّل قناة على `CopilotRuntime`، وتتصل بـ Intelligence، وتشغّل وكيلك كلما وصلت رسالة.
+
+```
+Slack / Teams  ──►  CopilotKit Intelligence  ──►  channel process (Node)  ──►  CrewAI server (AG-UI)  ──►  Crew / Flow
+```
+
+تحتفظ عملية القناة باتصال دائم مع بوابة Intelligence، لذا فهي تحتاج إلى مضيف طويل الأمد — لا يمكن لمعالج طلبات بلا خادم (serverless) أن يملك ذلك الاتصال. يمكن لخادم CrewAI الخاص بك أن يستمر في تقديم واجهة الويب الأمامية من النظرة العامة في الوقت نفسه: تطبيق الويب والقناة ما هما إلا عميلان لنقطة نهاية AG-UI واحدة.
+
+## دليل التكامل
+
+<Steps>
+
+<Step title="ثبّت حزم Channels">
+
+يأتي Channels SDK مكتمل العناصر — كل منصة تُشحن في الحزمة الواحدة، بلا محوّل خاص بكل منصة لتثبيته. أضفه إلى جانب وقت التشغيل الذي يستضيف القناة وعميل CrewAI AG-UI:
+
+```bash
+npm install @copilotkit/channels @copilotkit/runtime @ag-ui/crewai
+```
+
+</Step>
+
+<Step title="أنشئ قناة في Intelligence">
+
+في [لوحة تحكم CopilotKit](https://docs.copilotkit.ai/slack)، أنشئ قناة واربط Slack — ترشدك Intelligence خلال إنشاء تطبيق Slack وتحتفظ ببيانات اعتماده. يترك ذلك متغيّري بيئة لعمليتك، كلاهما من لوحة التحكم:
+
+```bash
+export INTELLIGENCE_API_KEY=...      # authenticates the runtime with Intelligence (free tier available)
+export INTELLIGENCE_CHANNEL_ID=...   # the Channel ID, matched by createChannel({ name })
+```
+
+</Step>
+
+<Step title="عرّف القناة">
+
+تُعرّف `createChannel` القناة وتربط وكيلك بها. ابنِ الوكيل كمصنع لكل خيط (thread) بحيث تحصل كل محادثة على جلستها الخاصة، مستخدمًا نفس `CrewAIAgent` الذي تستخدمه النظرة العامة في وقت تشغيل الويب، موجّهًا إلى نقطة نهاية AG-UI الخاصة بك. تتيح `identifyUser: "platform"` لـ Intelligence ربط كل مستخدم من المنصة بهوية ثابتة.
+
+```ts
+// channel.ts
+import { createChannel } from "@copilotkit/channels";
+import { CrewAIAgent } from "@ag-ui/crewai";
+
+const channel = createChannel({
+  name: process.env.INTELLIGENCE_CHANNEL_ID!, // must match the Channel ID in Intelligence
+  identifyUser: "platform",
+  // A fresh agent per conversation, pointed at your CrewAI AG-UI endpoint.
+  agent: (threadId) => {
+    const agent = new CrewAIAgent({ url: "http://localhost:8000/recipe" });
+    agent.threadId = threadId;
+    return agent;
+  },
+});
+
+// A mention subscribes the thread and runs the agent; afterwards every message
+// in a subscribed thread runs it without needing another mention.
+channel.onMention(async ({ thread }) => {
+  await thread.subscribe();
+  await thread.runAgent();
+});
+
+channel.onMessage(async ({ thread }) => {
+  if (await thread.isSubscribed()) await thread.runAgent();
+});
+
+export { channel };
+```
+
+</Step>
+
+<Step title="سجّل القناة على وقت التشغيل">
+
+أنشئ `CopilotRuntime` مع بوابة Intelligence وقناتك، ثم قدّمه باستخدام `createCopilotNodeListener`. تبقى خريطة `agents` فارغة — القناة توفّر وكيلها الخاص. انتظر حتى تكون القناة جاهزة كي يفشل بدء التشغيل بصوت عالٍ عند وجود إعداد معطوب.
+
+```ts
+// server.ts
+import { createServer } from "node:http";
+import { CopilotRuntime, CopilotKitIntelligence } from "@copilotkit/runtime/v2";
+import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";
+import { channel } from "./channel";
+
+const runtime = new CopilotRuntime({
+  agents: {}, // the channel supplies its own agent; no web-facing agents needed
+  intelligence: new CopilotKitIntelligence({
+    apiKey: process.env.INTELLIGENCE_API_KEY!, // free tier available
+  }),
+  channels: [channel],
+});
+
+const listener = createCopilotNodeListener({ runtime });
+await listener.channels?.ready({ timeoutMs: 15_000 });
+
+createServer(listener).listen(3123, () => {
+  console.log("Channels runtime listening on port 3123");
+});
+```
+
+</Step>
+
+<Step title="شغّل وقت تشغيل القناة">
+
+ابدأه إلى جانب خادم وكيل CrewAI الخاص بك:
+
+```bash
+uvicorn server:app --port 8000   # terminal 1 — CrewAI agent server
+npx tsx server.ts                 # terminal 2 — Channels runtime
+```
+
+اذكر الروبوت في Slack أو Teams فيشغّل الـ Crew أو الـ Flow الخاص بك، ويبثّ الرد مرة أخرى داخل الخيط. يبقى الخيط مشتركًا، لذا تعمل رسائل المتابعة دون الحاجة إلى ذكر آخر.
+
+</Step>
+
+</Steps>
+
+## نموذج الأحداث
+
+تتفاعل القناة مع أحداث المنصة عبر معالِجات، ويستقبل كل معالِج خيطًا (`thread`) تديره بعدد قليل من الدوال:
+
+- **`channel.onMention`** يُطلَق عندما يذكر مستخدم الروبوت بـ @. استدعِ `thread.subscribe()` للانضمام إلى الخيط، ثم `thread.runAgent()` لتشغيل وكيل CrewAI الخاص بك عند الذكر.
+- **`channel.onMessage`** يُطلَق عند كل رسالة في خيط يمكن للروبوت رؤيته. قيّده بـ `thread.isSubscribed()` كي لا يستجيب الوكيل إلا حيث انضمّ، ثم `thread.runAgent()`.
+- **`thread.runAgent()`** يشغّل وكيل CrewAI المرفق للدور الحالي ويبثّ مخرجاته مرة أخرى داخل القناة. مرّر `{ prompt }` لتجاوز النص الذي يعمل عليه الوكيل.
+
+يستقبل وكيلك `RunAgentInput` عاديًا من AG-UI ويصدر أحداث AG-UI عادية؛ تبقى آليات المنصة خلف القناة، لذا يعمل نفس الـ Crew أو الـ Flow دون تغيير عبر كل منصة. تكشف القناة أيضًا معالِجات للترحيبات والمقاطعات والأوامر والتفاعلات والنوافذ (modals) — راجع [مرجع `Channel`](https://docs.copilotkit.ai/reference/channels/classes/Channel) للاطلاع على السطح الكامل.
+
+## دعم المنصات
+
+يغطي مسار Intelligence المُدار **Slack** و**Microsoft Teams** اليوم — يعمل نفس كود القناة على أيٍّ منهما، وتفيد `message.platform` / `thread.platform` بالأصل الأصلي. تُبلَغ المنصات الأخرى (Discord وTelegram وWhatsApp) عبر **محوّلات مباشرة** يشغّلها المطوّر بدلًا من المسار المُدار — تملك عمليتك الخاصة بيانات اعتماد المنصة والنقل. راجع [توثيق CopilotKit Channels](https://docs.copilotkit.ai/slack) للاطلاع على قائمة المنصات الحالية والإعداد الخاص بكل منصة.
+
+## ذات صلة
+
+<CardGroup cols={2}>
+  <Card title="النظرة العامة على الواجهة الأمامية" icon="browser" href="/edge/ar/guides/frontend/overview">
+    قدّم الـ Crew أو الـ Flow الخاص بك عبر AG-UI — الأساس الذي تُبنى عليه كل قناة.
+  </Card>
+  <Card title="التدخل البشري (Human-in-the-Loop)" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    أوقف الوكيل مؤقتًا لجمع موافقة المستخدم أو مدخلاته في منتصف التشغيل.
+  </Card>
+</CardGroup>

docs/v1.15.19/ar/guides/frontend/overview.mdx

@@ -0,0 +1,238 @@
+---
+title: النظرة العامة على الواجهة الأمامية
+description: ابنِ واجهات مستخدم تفاعلية لوكلاء CrewAI الخاصين بك باستخدام CopilotKit وبروتوكول AG-UI.
+icon: browser
+mode: "wide"
+---
+
+## امنح وكلاءك واجهة مستخدم
+
+يشغّل CrewAI وكلاءك. ويمنحهم [CopilotKit](https://copilotkit.ai) واجهة أمامية. معًا يتيحان لك بناء تطبيقات يحادث فيها المستخدمون Crew أو Flow، ويشاهدونه يعمل في الوقت الفعلي، ويوافقون على قراراته، ويرون مخرجاته معروضة كواجهة حيّة بدلًا من جدران من النص.
+
+يتصل الاثنان عبر [بروتوكول AG-UI](https://docs.ag-ui.com). تكشف حزمة `ag-ui-crewai` أي Crew أو Flow كنقطة نهاية AG-UI. وتستهلك خطافات (hooks) ومكوّنات React من CopilotKit تلك النقطة. يفتح ذلك تجارب تتجاوز بكثير صندوق المحادثة:
+
+<CardGroup cols={2}>
+  <Card title="واجهة المستخدم التوليدية (Generative UI)" icon="wand-magic-sparkles" href="/edge/en/guides/frontend/generative-ui">
+    اعرض استدعاءات أدوات الوكيل وحالته كمكوّنات React خاصة بك.
+  </Card>
+  <Card title="التدخل البشري (Human-in-the-Loop)" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    أوقف الوكيل مؤقتًا لجمع موافقة المستخدم أو مدخلاته في منتصف التشغيل.
+  </Card>
+  <Card title="الحالة المشتركة (Shared State)" icon="arrows-rotate" href="/edge/en/guides/frontend/shared-state">
+    أبقِ حالة الوكيل وواجهة تطبيقك متزامنتين في الاتجاهين.
+  </Card>
+  <Card title="القنوات (Channels)" icon="messages" href="/edge/ar/guides/frontend/channels">
+    شغّل نفس الوكيل كروبوت على Slack أو Discord أو Teams.
+  </Card>
+</CardGroup>
+
+يجعل هذا الدليل Crew أو Flow يتحدث مع واجهة أمامية بـ Next.js من البداية إلى النهاية. تبني بقية القسم على التطبيق الذي تعدّه هنا.
+
+## البنية
+
+هناك ثلاثة أجزاء:
+
+1. **خادم وكيل CrewAI** — عملية Python تقدّم الـ Crew أو الـ Flow الخاص بك عبر AG-UI (FastAPI + `ag-ui-crewai`).
+2. **وقت تشغيل CopilotKit** — مسار Next.js يسجّل وكيلك ويوكّل الطلبات إليه.
+3. **الواجهة الأمامية بـ React** — مزوّد `<CopilotKit>` إلى جانب مكوّنات المحادثة والواجهة التوليدية.
+
+```
+React app  ──►  CopilotKit runtime (/api/copilotkit)  ──►  CrewAI server (AG-UI)  ──►  Crew / Flow
+```
+
+<Note>
+يغطي هذا الدليل المسار **الذاتي الاستضافة**: تشغّل خادم وكيل CrewAI بنفسك باستخدام `ag-ui-crewai`، ويعمل محليًا دون أي خدمة مُدارة. يقدّم CopilotKit أيضًا مسارًا **مُدارًا** (CopilotKit Cloud / Enterprise Intelligence) بخيوط مستضافة وأداة فحص — راجع [دليل البدء السريع لـ CopilotKit مع CrewAI](https://docs.copilotkit.ai/crewai-crews/quickstart) إن أردت ذلك بدلًا منه. كود الواجهة الأمامية في هذا القسم هو نفسه في الحالتين؛ الاختلاف فقط في كيفية استضافة الوكيل وتسجيله.
+</Note>
+
+<Note>
+يعمل CrewAI خلف AG-UI بثلاثة أشكال: الـ **Flows** العادية (المستخدمة في هذه الأدلة)، و**[الـ Flows المحادثية (Conversational Flows)](/edge/en/guides/frontend/conversational-flows)** (أصلية، مدركة للجلسة، قائمة على الأدوار، بتكافؤ كامل في الميزات)، والـ **Crews** (محادثة أساسية). الواجهة الأمامية في هذا القسم متطابقة عبرها جميعًا — الاختلاف فقط في تأليف الخلفية وتسجيلها.
+</Note>
+
+## دليل التكامل
+
+<Steps>
+
+<Step title="قدّم وكيلك عبر AG-UI">
+
+ثبّت حزمة التكامل في مشروع CrewAI الخاص بك:
+
+```bash
+pip install ag-ui-crewai
+```
+
+اكشف وكيلك من تطبيق FastAPI. تستخدم الـ Flows دالة `add_crewai_flow_fastapi_endpoint`؛ وتستخدم الـ Crews دالة `add_crewai_crew_fastapi_endpoint`. يمكنك تسجيل ما تشاء منها، كلٌّ على مساره الخاص.
+
+<CodeGroup>
+
+```python Flow
+# server.py
+from fastapi import FastAPI
+from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
+from my_agents.recipe_flow import RecipeFlow
+
+app = FastAPI(title="CrewAI Agent Server")
+
+add_crewai_flow_fastapi_endpoint(
+    app=app,
+    flow=RecipeFlow(),
+    path="/recipe",
+)
+```
+
+```python Crew
+# server.py
+from fastapi import FastAPI
+from ag_ui_crewai.endpoint import add_crewai_crew_fastapi_endpoint
+from my_agents.research_crew import ResearchCrew
+
+app = FastAPI(title="CrewAI Agent Server")
+
+add_crewai_crew_fastapi_endpoint(
+    app=app,
+    crew=ResearchCrew().crew(),
+    path="/research",
+)
+```
+
+</CodeGroup>
+
+شغّله:
+
+```bash
+uvicorn server:app --port 8000
+```
+
+<Note>
+اضبط متغيّرات البيئة الخاصة بمزوّد الـ LLM الخاص بك (على سبيل المثال `OPENAI_API_KEY`) قبل بدء الخادم.
+</Note>
+
+</Step>
+
+<Step title="أنشئ تطبيق Next.js">
+
+إن لم تكن لديك واجهة أمامية بعد، أنشئ هيكلًا:
+
+```bash
+npx create-next-app@latest my-app
+cd my-app
+```
+
+ثبّت CopilotKit وعميل CrewAI AG-UI:
+
+```bash
+npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/crewai
+```
+
+</Step>
+
+<Step title="أضف وقت تشغيل CopilotKit">
+
+أنشئ مسارًا يسجّل وكيل (أو وكلاء) CrewAI مع وقت تشغيل CopilotKit. يشير كل وكيل إلى مسار على خادم Python الخاص بك عبر `CrewAIAgent`.
+
+```ts
+// app/api/copilotkit/route.ts
+import {
+  CopilotRuntime,
+  InMemoryAgentRunner,
+  createCopilotEndpoint,
+} from "@copilotkit/runtime/v2";
+import { CrewAIAgent } from "@ag-ui/crewai";
+import { handle } from "hono/vercel";
+
+const runtime = new CopilotRuntime({
+  agents: {
+    recipe: new CrewAIAgent({ url: "http://localhost:8000/recipe" }),
+  },
+  runner: new InMemoryAgentRunner(),
+});
+
+const app = createCopilotEndpoint({
+  runtime,
+  basePath: "/api/copilotkit",
+});
+
+const handler = handle(app);
+export const GET = handler;
+export const POST = handler;
+```
+
+</Step>
+
+<Step title="غلّف تطبيقك بالمزوّد">
+
+وجّه `<CopilotKit>` إلى مسار وقت التشغيل واذكر اسم الوكيل الذي سجّلته.
+
+```tsx
+// app/page.tsx
+"use client";
+import { CopilotKit } from "@copilotkit/react-core";
+import { CopilotSidebar } from "@copilotkit/react-core/v2";
+import "@copilotkit/react-core/v2/styles.css";
+
+export default function Page() {
+  return (
+    <CopilotKit runtimeUrl="/api/copilotkit" agent="recipe">
+      <YourApp />
+      <CopilotSidebar agentId="recipe" labels={{ modalHeaderTitle: "Assistant" }} />
+    </CopilotKit>
+  );
+}
+```
+
+</Step>
+
+<Step title="شغّله">
+
+ابدأ العمليتين وافتح التطبيق. تشغّل المحادثة في الشريط الجانبي الآن الـ Crew أو الـ Flow الخاص بك.
+
+```bash
+uvicorn server:app --port 8000   # terminal 1
+npm run dev                       # terminal 2
+```
+
+</Step>
+
+</Steps>
+
+## خيارات واجهة المحادثة
+
+يشحن CopilotKit ثلاثة أسطح محادثة قابلة للتبديل. بدّل المكوّن؛ يبقى التوصيل متطابقًا.
+
+<CodeGroup>
+
+```tsx Sidebar
+import { CopilotSidebar } from "@copilotkit/react-core/v2";
+
+<CopilotSidebar agentId="recipe" />
+```
+
+```tsx Popup
+import { CopilotPopup } from "@copilotkit/react-core/v2";
+
+<CopilotPopup agentId="recipe" />
+```
+
+```tsx Inline
+import { CopilotChat } from "@copilotkit/react-core/v2";
+
+<CopilotChat agentId="recipe" />
+```
+
+</CodeGroup>
+
+## إلى أين تذهب بعد ذلك
+
+<CardGroup cols={2}>
+  <Card title="واجهة المستخدم التوليدية (Generative UI)" icon="wand-magic-sparkles" href="/edge/en/guides/frontend/generative-ui">
+    اعرض استدعاءات الأدوات وحالة الوكيل كمكوّنات مخصّصة.
+  </Card>
+  <Card title="إجراءات الواجهة الأمامية (Frontend Actions)" icon="bolt" href="/edge/en/guides/frontend/frontend-actions">
+    دع الوكيل يستدعي دوالًا تعمل في المتصفح.
+  </Card>
+  <Card title="التدخل البشري (Human-in-the-Loop)" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    قيّد إجراءات الوكيل خلف موافقة المستخدم.
+  </Card>
+  <Card title="الحالة التنبؤية (Predictive State)" icon="gauge-high" href="/edge/en/guides/frontend/predictive-state-updates">
+    ابثّ الحالة قيد التنفيذ إلى الواجهة أثناء عمل الوكيل.
+  </Card>
+</CardGroup>

docs/v1.15.19/ar/guides/migration/migrating-from-langgraph.mdx

@@ -0,0 +1,103 @@
+---
+title: "الانتقال من LangGraph إلى CrewAI: دليل عملي للمهندسين"
+description: إذا كنت قد بنيت بالفعل مع LangGraph، تعلم كيفية نقل مشاريعك بسرعة إلى CrewAI
+icon: switch
+mode: "wide"
+---
+
+لقد بنيت Agents مع LangGraph. لقد تعاملت مع `StateGraph`، وربطت الحواف الشرطية، وصححت أخطاء قواميس الحالة في الثانية صباحًا. إنه يعمل — لكن في مرحلة ما، بدأت تتساءل عما إذا كان هناك مسار أفضل نحو الإنتاج.
+
+هناك بالفعل. **CrewAI Flows** يمنحك نفس القوة — تنسيق قائم على الأحداث، توجيه شرطي، حالة مشتركة — مع نموذج كود أبسط بشكل كبير ونموذج ذهني يتماشى مع طريقة تفكيرك الفعلية في سير عمل AI متعدد الخطوات.
+
+تمشي هذه المقالة عبر المفاهيم الأساسية جنبًا إلى جنب، وتعرض مقارنات كود حقيقية، وتوضح لماذا CrewAI Flows هو إطار العمل الذي ستريد الوصول إليه بعد ذلك.
+
+---
+
+## تحول النموذج الذهني
+
+LangGraph يطلب منك التفكير في **رسوم بيانية**: عقد وحواف وقواميس حالة. كل سير عمل هو رسم بياني موجّه تربط فيه الانتقالات صراحةً بين خطوات الحساب.
+
+CrewAI Flows يطلب منك التفكير في **أحداث**: طرق تبدأ الأشياء، وطرق تستمع للنتائج، وطرق توجّه التنفيذ. طوبولوجيا سير العمل تنبثق من تعليقات المزخرفات بدلاً من بناء رسم بياني صريح.
+
+إليك الخريطة الأساسية:
+
+| مفهوم LangGraph | المكافئ في CrewAI Flows |
+| --- | --- |
+| `StateGraph` class | `Flow` class |
+| `add_node()` | طرق مزخرفة بـ `@start`، `@listen` |
+| `add_edge()` / `add_conditional_edges()` | مزخرفات `@listen()` / `@router()` |
+| `TypedDict` state | حالة Pydantic `BaseModel` |
+| `START` / `END` constants | مزخرف `@start()` / إرجاع طبيعي للطريقة |
+| `graph.compile()` | `flow.kickoff()` |
+| Checkpointer / persistence | ذاكرة مدمجة (مدعومة بـ LanceDB) |
+
+---
+
+## العرض 1: خط أنابيب تسلسلي بسيط
+
+تخيل أنك تبني خط أنابيب يأخذ موضوعًا، ويبحث فيه، ويكتب ملخصًا، وينسّق المخرجات. راجع الملف الإنجليزي الأصلي لأمثلة الكود الكاملة لكلا النهجين.
+
+الفرق الرئيسي: لا بناء رسم بياني، لا ربط حواف، لا خطوة ترجمة. ترتيب التنفيذ مُعلَن مباشرة حيث يوجد المنطق. `@start()` يحدد نقطة الدخول، و`@listen(method_name)` يربط الخطوات.
+
+---
+
+## العرض 2: التوجيه الشرطي
+
+مزخرف `@router()` يحوّل طريقة إلى نقطة قرار. يعيد سلسلة تطابق مستمعًا — بلا قواميس تعيين، بلا دوال توجيه منفصلة. منطق التفرع يُقرأ كتعبير `if` في Python لأنه كذلك فعلاً.
+
+---
+
+## العرض 3: دمج فرق Agents AI في Flows
+
+هنا تتجلى القوة الحقيقية لـ CrewAI. الـ Flows لا تقتصر على ربط استدعاءات LLM — بل تنسّق **Crews** كاملة من Agents مستقلة.
+
+الفكرة الرئيسية: **الـ Flows توفر طبقة التنسيق، والـ Crews توفر طبقة الذكاء.** كل خطوة في Flow يمكنها تشغيل فريق كامل من Agents متعاونة.
+
+---
+
+## العرض 4: التنفيذ المتوازي والمزامنة
+
+المشغّل `and_()` على مزخرف `@listen` يضمن أن الطريقة تُنفَّذ فقط بعد اكتمال *جميع* الطرق السابقة. هناك أيضًا `or_()` للمتابعة بمجرد اكتمال *أي* مهمة سابقة.
+
+---
+
+## لماذا CrewAI Flows للإنتاج
+
+- **حفظ حالة مدمج.** حالة Flow مدعومة بـ LanceDB.
+- **إدارة حالة آمنة الأنواع.** نماذج Pydantic توفر التحقق والتسلسل ودعم IDE.
+- **تنسيق Agents أصلي.** الـ Crews بنية أساسية أصلية.
+- **نموذج ذهني أبسط.** المزخرفات تعلن عن النية.
+- **تكامل CLI.** شغّل Flows بـ `crewai run`.
+
+---
+
+## ورقة الغش للترحيل
+
+1. **عيّن حالتك.** حوّل `TypedDict` إلى Pydantic `BaseModel`.
+2. **حوّل العقد إلى طرق.** كل دالة `add_node` تصبح طريقة على فئة `Flow` الفرعية.
+3. **استبدل الحواف بمزخرفات.** `add_edge(START, "first_node")` يصبح `@start()`. `add_edge("a", "b")` يصبح `@listen(a)`.
+4. **استبدل الحواف الشرطية بـ `@router`.** دالة التوجيه و`add_conditional_edges()` تصبح طريقة `@router()` واحدة.
+5. **استبدل compile + invoke بـ kickoff.** احذف `graph.compile()`. استدعِ `flow.kickoff()` بدلاً منه.
+6. **فكّر أين تناسب الـ Crews.** أي عقدة بها منطق Agent معقد متعدد الخطوات هي مرشحة لاستخراجها في Crew.
+
+---
+
+## البدء
+
+```bash
+pip install crewai
+crewai create flow my_first_flow
+cd my_first_flow
+```
+
+```bash
+crewai run
+```
+
+---
+
+## أفكار أخيرة
+
+LangGraph علّم المنظومة أن سير عمل AI تحتاج هيكلاً. كان ذلك درسًا مهمًا. لكن CrewAI Flows يأخذ ذلك الدرس ويقدمه في شكل أسرع في الكتابة وأسهل في القراءة وأقوى في الإنتاج — خاصة عندما تتضمن سير عملك عدة Agents متعاونة.
+
+ابدأ بـ `crewai create flow`. لن تنظر للخلف.

docs/v1.15.19/ar/guides/migration/upgrading-crewai.mdx

@@ -0,0 +1,190 @@
+---
+title: "ترقية CrewAI"
+description: "كيفية ترقية CrewAI في مشروعك والتكيّف مع التغييرات الجذرية بين الإصدارات."
+icon: "arrow-up-circle"
+---
+
+## نظرة عامة
+
+تجلب إصدارات CrewAI قدرات جديدة بانتظام. يرشدك هذا الدليل خلال الخطوات العملية للحفاظ على تثبيتك محدّثًا — سواء أداة سطر الأوامر أو البيئة الافتراضية لمشروعك.
+
+إذا كنت تبدأ من الصفر، راجع [التثبيت](/ar/installation). إذا كنت قادمًا من إطار عمل آخر، راجع [الترحيل من LangGraph](/ar/guides/migration/migrating-from-langgraph).
+
+---
+
+## الشيئان اللذان قد ترغب في ترقيتهما
+
+يوجد CrewAI في مكانين على جهازك، ويتم ترقيتهما بشكل مستقل:
+
+| ماذا | كيف يُثبَّت | كيف تتم الترقية |
+|---|---|---|
+| **أداة سطر الأوامر العامة `crewai`** | `uv tool install crewai` | `uv tool install crewai --upgrade` |
+| **بيئة venv للمشروع** (حيث يعمل الكود) | `crewai install` / `uv sync` | `uv add "crewai[...]>=X.Y.Z"` ثم `crewai install` |
+
+يمكن لهما — وغالبًا ما يحدث — أن يخرجا عن التزامن. تشغيل `crewai --version` يُظهر إصدار سطر الأوامر. تشغيل `uv pip show crewai` داخل مشروعك يُظهر إصدار venv. إذا اختلفا، فهذا طبيعي؛ ما يهم بالنسبة للكود قيد التشغيل هو إصدار venv.
+
+## لماذا لا يقوم `crewai install` وحده بالترقية
+
+`crewai install` هو غلاف رفيع حول `uv sync`. يُثبّت بالضبط ما يقوله ملف `uv.lock` الحالي — وهو **لا** يرفع أي قيود إصدار.
+
+إذا كان `pyproject.toml` يقول `crewai>=1.11.1` وقد قام ملف القفل بحلّه إلى `1.11.1`، فإن تشغيل `crewai install` سيُبقيك على `1.11.1` للأبد، حتى وإن كان الإصدار `1.14.4` متاحًا.
+
+للترقية فعلًا، عليك:
+
+1. تحديث قيد الإصدار في `pyproject.toml`
+2. إعادة حلّ ملف القفل
+3. مزامنة venv
+
+`uv add` يقوم بالثلاثة في خطوة واحدة.
+
+## كيفية ترقية مشروعك
+
+```bash
+# يرفع القيد ويعيد القفل في أمر واحد
+uv add "crewai[tools]>=1.14.4"
+
+# يزامن venv (crewai install يستدعي uv sync تحت الغطاء)
+crewai install
+
+# تحقّق
+uv pip show crewai
+# → Version: 1.14.4
+```
+
+استبدل `[tools]` بأي إضافات يستخدمها مشروعك (مثلًا `[tools,anthropic]`). تحقّق من قائمة `dependencies` في `pyproject.toml` إن لم تكن متأكدًا.
+
+<Note>
+  يحدّث `uv add` كلا من `pyproject.toml` **و** `uv.lock` بشكل ذرّي. إذا قمت بتحرير `pyproject.toml` يدويًا، فإنك لا تزال بحاجة إلى تشغيل `uv lock --upgrade-package crewai` لإعادة حلّ ملف القفل قبل أن يلتقط `crewai install` الإصدار الجديد.
+</Note>
+
+## ترقية أداة سطر الأوامر العامة
+
+أداة سطر الأوامر العامة منفصلة عن مشروعك. قم بترقيتها عبر:
+
+```bash
+uv tool install crewai --upgrade
+```
+
+إذا حذّرك الـ shell بشأن `PATH` بعد الترقية، قم بتحديثه:
+
+```bash
+uv tool update-shell
+```
+
+هذا **لا** يمسّ بيئة venv الخاصة بمشروعك — لا تزال بحاجة إلى `uv add` + `crewai install` داخل المشروع.
+
+## التحقق من تزامن الاثنين
+
+```bash
+# إصدار سطر الأوامر العام
+crewai --version
+
+# إصدار venv للمشروع
+uv pip show crewai | grep Version
+```
+
+ليس من الضروري أن يتطابقا — لكن إصدار venv للمشروع هو ما يهم لسلوك التشغيل.
+
+<Note>
+  يتطلب CrewAI `Python >=3.10, <3.14`. إذا كان `uv` مثبَّتًا مقابل مفسّر أقدم، فأعد إنشاء venv للمشروع باستخدام إصدار Python مدعوم قبل تشغيل `crewai install`.
+</Note>
+
+---
+
+## التغييرات الجذرية وملاحظات الترحيل
+
+تتطلب معظم الترقيات تعديلات صغيرة فقط. المناطق أدناه هي تلك التي تنكسر بصمت أو بتتبعات مكدّس مربكة.
+
+### مسارات الاستيراد: tools و`BaseTool`
+
+الموقع الرسمي لاستيراد الـ tools هو `crewai.tools`. لا تزال المسارات القديمة تظهر في الدروس لكن يجب تحديثها.
+
+```python
+# قبل
+from crewai_tools import BaseTool
+from crewai.agents.tools import tool
+
+# بعد
+from crewai.tools import BaseTool, tool
+```
+
+كلٌ من المُزخرف `@tool` والفئة الفرعية `BaseTool` يقعان في `crewai.tools`. `AgentFinish` والرموز الأخرى الداخلية للوكيل لم تعد جزءًا من السطح العام — إذا كنت تستوردها، فانتقل إلى event listeners أو callbacks الـ `Task` بدلًا منها.
+
+### تغييرات معاملات `Agent`
+
+```python
+from crewai import Agent
+
+agent = Agent(
+    role="Researcher",
+    goal="Find authoritative sources on {topic}",
+    backstory="You are a careful, source-driven researcher.",
+    llm="gpt-4o-mini",   # اسم نموذج كسلسلة نصية أو كائن LLM
+    verbose=True,        # bool وليس مستوى عددي صحيح
+    max_iter=15,         # تغيّر الافتراضي بين الإصدارات — حدّده بشكل صريح
+    allow_delegation=False,
+)
+```
+
+- يقبل `llm` إما اسم نموذج كسلسلة نصية (يُحلَّ عبر المزوّد المهيّأ) أو كائن `LLM` للتحكم الدقيق.
+- `verbose` هو `bool` بسيط. تمرير عدد صحيح لم يعد يبدّل مستويات السجل.
+- تغيّرت افتراضات `max_iter` بين الإصدارات. إذا توقف وكيلك بصمت عن التكرار بعد أول استدعاء tool، فحدّد `max_iter` صراحةً.
+
+### معاملات `Crew`
+
+```python
+from crewai import Crew, Process
+
+crew = Crew(
+    agents=[...],
+    tasks=[...],
+    process=Process.sequential,   # أو Process.hierarchical
+    memory=True,
+    cache=True,
+    embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}},
+)
+```
+
+- يتطلب `process=Process.hierarchical` إما `manager_llm=` أو `manager_agent=`. بدون أحدهما، يرفع kickoff خطأً عند التحقّق.
+- `memory=True` مع مزوّد embedding غير افتراضي يحتاج إلى قاموس `embedder` — راجع [إعداد الذاكرة وembedder](#memory-embedder-config) أدناه.
+
+### الإخراج المُهيكل لـ `Task`
+
+استخدم `output_pydantic` أو `output_json` أو `output_file` لإلزام نتيجة المهمة بشكل مكتوب الأنواع:
+
+```python
+from pydantic import BaseModel
+from crewai import Task
+
+class Article(BaseModel):
+    title: str
+    body: str
+
+write = Task(
+    description="Write an article about {topic}",
+    expected_output="A short article with a title and body",
+    agent=writer,
+    output_pydantic=Article,        # الفئة، وليس مثيلًا منها
+    output_file="output/article.md",
+)
+```
+
+`output_pydantic` يأخذ **الفئة** نفسها. تمرير `Article(title="", body="")` خطأ شائع ويفشل بخطأ تحقّق مربك.
+
+### إعداد الذاكرة وembedder {#memory-embedder-config}
+
+إذا كان `memory=True` وأنت لا تستخدم embeddings الافتراضية الخاصة بـ OpenAI، فيجب أن تمرّر `embedder`:
+
+```python
+crew = Crew(
+    agents=[...],
+    tasks=[...],
+    memory=True,
+    embedder={
+        "provider": "ollama",
+        "config": {"model": "nomic-embed-text"},
+    },
+)
+```
+
+ضع بيانات اعتماد المزوّد المعنيّة (`OPENAI_API_KEY`, `OLLAMA_HOST`, إلخ) في ملف `.env`. مسارات تخزين الذاكرة محلية بالنسبة للمشروع افتراضيًا — احذف مجلد ذاكرة المشروع إذا غيّرت embedders، لأن الأبعاد لا تختلط.

docs/v1.15.19/ar/guides/tools/publish-custom-tools.mdx

@@ -0,0 +1,96 @@
+---
+title: نشر أدوات مخصصة
+description: كيفية بناء وتعبئة ونشر أدواتك الخاصة المتوافقة مع CrewAI على PyPI ليتمكن أي مستخدم CrewAI من تثبيتها واستخدامها.
+icon: box-open
+mode: "wide"
+---
+
+## نظرة عامة
+
+نظام الأدوات في CrewAI مصمم للتوسيع. إذا بنيت أداة يمكن أن تفيد الآخرين، يمكنك تعبئتها كمكتبة Python مستقلة ونشرها على PyPI وإتاحتها لأي مستخدم CrewAI — دون الحاجة لطلب سحب إلى مستودع CrewAI.
+
+يمشي هذا الدليل عبر العملية الكاملة: تنفيذ عقد الأدوات، وهيكلة حزمتك، والنشر على PyPI.
+
+<Note type="info" title="لا تبحث عن النشر؟">
+إذا كنت تحتاج فقط أداة مخصصة لمشروعك، راجع دليل [إنشاء أدوات مخصصة](/ar/learn/create-custom-tools) بدلاً من ذلك.
+</Note>
+
+## عقد الأدوات
+
+كل أداة CrewAI يجب أن تستوفي إحدى الواجهتين:
+
+### الخيار 1: وراثة `BaseTool`
+
+ورث من `crewai.tools.BaseTool` وطبّق طريقة `_run`. عرّف `name` و`description` واختياريًا `args_schema` للتحقق من المدخلات.
+
+```python
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field
+
+
+class GeolocateInput(BaseModel):
+    """Input schema for GeolocateTool."""
+    address: str = Field(..., description="The street address to geolocate.")
+
+
+class GeolocateTool(BaseTool):
+    name: str = "Geolocate"
+    description: str = "Converts a street address into latitude/longitude coordinates."
+    args_schema: type[BaseModel] = GeolocateInput
+
+    def _run(self, address: str) -> str:
+        return f"40.7128, -74.0060"
+```
+
+### الخيار 2: استخدام مزخرف `@tool`
+
+للأدوات الأبسط، يحوّل مزخرف `@tool` دالة إلى أداة CrewAI. يجب أن تحتوي الدالة على سلسلة توثيق (تُستخدم كوصف الأداة) وتعليقات أنواع.
+
+```python
+from crewai.tools import tool
+
+
+@tool("Geolocate")
+def geolocate(address: str) -> str:
+    """Converts a street address into latitude/longitude coordinates."""
+    return "40.7128, -74.0060"
+```
+
+### المتطلبات الأساسية
+
+بغض النظر عن النهج الذي تستخدمه، يجب أن تحتوي أداتك على:
+
+- **`name`** — معرّف قصير ووصفي.
+- **`description`** — يخبر الـ Agent متى وكيف يستخدم الأداة.
+- **`_run`** (BaseTool) أو **جسم الدالة** (@tool) — منطق التنفيذ المتزامن.
+- **تعليقات أنواع** على جميع المعاملات وقيم الإرجاع.
+- إرجاع نتيجة **نصية** (أو شيء يمكن تحويله لنص).
+
+## هيكل الحزمة
+
+```
+crewai-geolocate/
+├── pyproject.toml
+├── LICENSE
+├── README.md
+└── src/
+    └── crewai_geolocate/
+        ├── __init__.py
+        └── tools.py
+```
+
+## النشر على PyPI
+
+```bash
+# Build the package
+uv build
+
+# Publish to PyPI
+uv publish
+```
+
+بعد النشر، يمكن للمستخدمين تثبيت أداتك بـ:
+
+```bash
+uv add crewai-geolocate
+```

docs/v1.15.19/ar/index.mdx

@@ -0,0 +1,105 @@
+---
+title: "توثيق CrewAI"
+description: "ابنِ Agents ذكاء اصطناعي تعاونية وCrews وFlows — جاهزة للإنتاج من اليوم الأول."
+icon: "house"
+mode: "wide"
+---
+
+<div
+  style={{
+    display: 'flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    gap: 20,
+    textAlign: 'center',
+    padding: '48px 24px',
+    borderRadius: 16,
+    background: 'linear-gradient(180deg, rgba(235,102,88,0.12) 0%, rgba(201,76,60,0.08) 100%)',
+    border: '1px solid rgba(235,102,88,0.18)'
+  }}
+>
+  <img src="/images/crew_only_logo.png" alt="CrewAI" width="250" height="100" />
+  <div style={{ maxWidth: 720 }}>
+    <h1 style={{ marginBottom: 12 }}>أطلق أنظمة متعددة الـ Agents بثقة</h1>
+    <p style={{ color: 'var(--mint-text-2)' }}>
+      صمم Agents، ونسّق Crews، وأتمت Flows مع حواجز حماية وذاكرة ومعرفة ومراقبة مدمجة.
+    </p>
+  </div>
+
+  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12, justifyContent: 'center' }}>
+    <a className="button button-primary" href="/ar/quickstart">ابدأ الآن</a>
+    <a className="button" href="/ar/changelog">سجل التغييرات</a>
+    <a className="button" href="/ar/api-reference/introduction">مرجع API</a>
+  </div>
+
+</div>
+
+<div style={{ marginTop: 32 }} />
+
+## ابدأ
+
+<CardGroup cols={3}>
+  <Card title="مقدمة" href="/ar/introduction" icon="sparkles">
+    نظرة عامة على مفاهيم CrewAI وبنيته المعمارية وما يمكنك بناؤه باستخدام Agents وCrews وFlows.
+  </Card>
+  <Card title="التثبيت" href="/ar/installation" icon="wrench">
+    التثبيت عبر `uv`، وإعداد مفاتيح API، وتهيئة CLI للتطوير المحلي.
+  </Card>
+  <Card title="البداية السريعة" href="/ar/quickstart" icon="rocket">
+    أنشئ أول Crew لك في دقائق. تعلم بيئة التشغيل الأساسية وهيكل المشروع ودورة التطوير.
+  </Card>
+</CardGroup>
+
+## ابنِ الأساسيات
+
+<CardGroup cols={3}>
+  <Card title="Agents" href="/ar/concepts/agents" icon="users">
+    أنشئ Agents بأدوات وذاكرة ومعرفة ومخرجات منظمة باستخدام Pydantic. يتضمن قوالب وأفضل الممارسات.
+  </Card>
+  <Card title="Flows" href="/ar/concepts/flows" icon="arrow-progress">
+    نسّق خطوات start/listen/router، وأدر الحالة، واحفظ التنفيذ، واستأنف سير العمل الطويل.
+  </Card>
+  <Card title="المهام والعمليات" href="/ar/concepts/tasks" icon="check">
+    حدد عمليات متسلسلة أو هرمية أو مختلطة مع حواجز حماية واستدعاءات راجعة ومحفزات تدخل بشري.
+  </Card>
+</CardGroup>
+
+## رحلة المؤسسات
+
+<CardGroup cols={3}>
+  <Card title="نشر الأتمتة" href="https://docs-platform.crewai.com/platform/ar/features/automations" icon="server">
+    إدارة البيئات وإعادة النشر بأمان ومراقبة التشغيل المباشر من لوحة تحكم المؤسسات.
+  </Card>
+  <Card title="المحفزات والـ Flows" href="https://docs-platform.crewai.com/platform/ar/guides/automation-triggers" icon="bolt">
+    ربط Gmail وSlack وSalesforce والمزيد. تمرير بيانات المحفزات إلى Crews وFlows تلقائيًا.
+  </Card>
+  <Card title="إدارة الفريق" href="https://docs-platform.crewai.com/platform/ar/guides/team-management" icon="users-gear">
+    دعوة أعضاء الفريق وتهيئة التحكم في الوصول المبني على الأدوار وإدارة الوصول إلى أتمتة الإنتاج.
+  </Card>
+</CardGroup>
+
+## ما الجديد
+
+<CardGroup cols={2}>
+  <Card title="نظرة عامة على المحفزات" href="https://docs-platform.crewai.com/platform/ar/guides/automation-triggers" icon="sparkles">
+    نظرة شاملة موحدة على Gmail وDrive وOutlook وTeams وOneDrive وHubSpot والمزيد — الآن مع نماذج بيانات وCrews.
+  </Card>
+  <Card title="أدوات التكامل" href="/ar/tools/integration/overview" icon="plug">
+    استدعاء أتمتة CrewAI الحالية أو Amazon Bedrock Agents مباشرة من Crews باستخدام مجموعة أدوات التكامل المحدّثة.
+  </Card>
+</CardGroup>
+
+<Callout title="استكشف الأنماط الواقعية" icon="github">
+  تصفح <a href="/ar/examples/cookbooks">الأمثلة وكتب الوصفات</a> للحصول على تطبيقات مرجعية شاملة عبر Agents وFlows وأتمتة المؤسسات.
+</Callout>
+
+## ابقَ على تواصل
+
+<CardGroup cols={2}>
+  <Card title="امنحنا نجمة على GitHub" href="https://github.com/crewAIInc/crewAI" icon="star">
+    إذا ساعدك CrewAI في الإطلاق بشكل أسرع، امنحنا نجمة وشارك مشاريعك مع المجتمع.
+  </Card>
+  <Card title="انضم إلى المجتمع" href="https://community.crewai.com" icon="comments">
+    اطرح أسئلة واعرض سير العمل واطلب ميزات جديدة جنبًا إلى جنب مع المطورين الآخرين.
+  </Card>
+</CardGroup>

docs/v1.15.19/ar/installation.mdx

@@ -0,0 +1,216 @@
+---
+title: التثبيت
+description: ابدأ مع CrewAI - التثبيت والتهيئة وبناء أول فريق AI
+icon: wrench
+mode: "wide"
+---
+
+### شاهد: بناء Agents و Flows في CrewAI باستخدام Coding Agent Skills
+
+قم بتثبيت مهارات وكيل البرمجة الخاصة بنا (Claude Code، Codex، ...) لتشغيل وكلاء البرمجة بسرعة مع CrewAI.
+
+يمكنك تثبيتها باستخدام `npx skills add crewaiinc/skills`
+
+<iframe src="https://www.loom.com/embed/befb9f68b81f42ad8112bfdd95a780af" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style={{width: "100%", height: "400px"}}></iframe>
+
+## فيديو تعليمي
+
+شاهد هذا الفيديو التعليمي لعرض تفصيلي لعملية التثبيت:
+
+<iframe
+  className="w-full aspect-video rounded-xl"
+  src="https://www.youtube.com/embed/-kSOTtYzgEw"
+  title="CrewAI Installation Guide"
+  frameBorder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowFullScreen
+></iframe>
+
+## دليل نصي
+
+<Note>
+  **متطلبات إصدار Python**
+
+يتطلب CrewAI إصدار `Python >=3.10 and <3.14`. إليك كيفية التحقق من إصدارك:
+
+```bash
+python3 --version
+```
+
+إذا كنت بحاجة لتحديث Python، قم بزيارة [python.org/downloads](https://python.org/downloads)
+
+</Note>
+
+<Note>
+  **متطلبات OpenAI SDK**
+
+يتطلب CrewAI 0.175.0 إصدار `openai >= 1.13.3`. إذا كنت تدير التبعيات بنفسك، تأكد من أن بيئتك تستوفي هذا الشرط لتجنب مشاكل الاستيراد/التشغيل.
+
+</Note>
+
+يستخدم CrewAI أداة `uv` لإدارة التبعيات والحزم. وهي تبسّط إعداد المشروع وتنفيذه وتوفر تجربة سلسة.
+
+إذا لم تكن قد ثبّتت `uv` بعد، اتبع **الخطوة 1** لإعدادها بسرعة على نظامك، وإلا يمكنك الانتقال إلى **الخطوة 2**.
+
+<Steps>
+    <Step title="تثبيت uv">
+      - **على macOS/Linux:**
+
+        استخدم `curl` لتحميل السكريبت وتنفيذه عبر `sh`:
+
+        ```shell
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        ```
+        إذا لم يكن `curl` متاحًا على نظامك، يمكنك استخدام `wget`:
+
+        ```shell
+        wget -qO- https://astral.sh/uv/install.sh | sh
+        ```
+
+      - **على Windows:**
+
+        استخدم `irm` لتحميل السكريبت و`iex` لتنفيذه:
+
+        ```shell
+        powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+        ```
+        إذا واجهت أي مشاكل، راجع [دليل تثبيت UV](https://docs.astral.sh/uv/getting-started/installation/) لمزيد من المعلومات.
+    </Step>
+
+    <Step title="تثبيت CrewAI">
+      - شغّل الأمر التالي لتثبيت واجهة سطر أوامر `crewai`:
+        ```shell
+        uv tool install crewai
+        ```
+          <Warning>
+            إذا ظهر تحذير بشأن `PATH`، شغّل هذا الأمر لتحديث الصدفة:
+            ```shell
+            uv tool update-shell
+            ```
+          </Warning>
+
+          <Warning>
+            إذا واجهت خطأ بناء `chroma-hnswlib==0.7.6` (`fatal error C1083: Cannot open include file: 'float.h'`) على Windows، ثبّت [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) مع خيار *Desktop development with C++*.
+          </Warning>
+
+      - للتحقق من تثبيت `crewai`، شغّل:
+        ```shell
+        uv tool list
+        ```
+      - يجب أن ترى شيئًا مثل:
+        ```shell
+        crewai v0.102.0
+        - crewai
+        ```
+      - إذا كنت بحاجة لتحديث `crewai`، شغّل:
+        ```shell
+        uv tool install crewai --upgrade
+        ```
+      <Check>تم التثبيت بنجاح! أنت جاهز لإنشاء أول Crew!</Check>
+    </Step>
+
+</Steps>
+
+# إنشاء مشروع CrewAI
+
+يقوم `crewai create crew` الآن بإنشاء مشروع crew بأسلوب JSON-first. توضع الـ Agents في `agents/*.jsonc`، وتوضع المهام وإعدادات الـ crew في `crew.jsonc`، ويحمّل `crewai run` هذا التعريف مباشرة.
+
+<Steps>
+  <Step title="إنشاء هيكل المشروع">
+    - شغّل أمر `crewai` عبر CLI:
+      ```shell
+      crewai create crew <your_project_name>
+      ```
+
+    - سينشئ هذا مشروعًا جديدًا بالهيكل التالي:
+      ```
+      my_project/
+      ├── .gitignore
+      ├── .env
+      ├── agents/
+      │   └── researcher.jsonc
+      ├── crew.jsonc
+      ├── knowledge/
+      ├── pyproject.toml
+      ├── README.md
+      ├── skills/
+      └── tools/
+      ```
+
+    - إذا احتجت إلى البنية القديمة Python/YAML التي تحتوي على `crew.py` و `config/agents.yaml` و `config/tasks.yaml`، شغّل:
+      ```shell
+      crewai create crew <your_project_name> --classic
+      ```
+
+  </Step>
+
+  <Step title="تخصيص مشروعك">
+    - سيحتوي مشروعك على هذه الملفات الأساسية:
+      | الملف | الغرض |
+      | --- | --- |
+      | `crew.jsonc` | إعداد الـ crew وترتيب المهام والعملية وقيم الإدخال الافتراضية |
+      | `agents/*.jsonc` | تعريف دور كل Agent وهدفه و backstory والـ LLM والأدوات والسلوك |
+      | `.env` | تخزين مفاتيح API ومتغيرات البيئة |
+      | `tools/` | ملفات Python اختيارية لأدوات `custom:<name>` |
+      | `knowledge/` | ملفات معرفة اختيارية للـ Agents |
+      | `skills/` | ملفات skills اختيارية تطبق على الـ crew |
+
+    - ابدأ بتحرير `crew.jsonc` والملفات داخل `agents/` لتعريف سلوك الـ crew.
+    - استخدم قيم `{placeholder}` في نصوص الـ Agents والمهام، ثم ضع القيم الافتراضية في `inputs` داخل `crew.jsonc`. عند تشغيل `crewai run` ستطلب CLI أي قيم ناقصة.
+    - احتفظ بالمعلومات الحساسة مثل مفاتيح API في `.env`.
+
+  </Step>
+
+  <Step title="تشغيل الـ Crew">
+    - قبل تشغيل الـ Crew، تأكد من تنفيذ:
+      ```bash
+      crewai install
+      ```
+    - إذا كنت بحاجة لتثبيت حزم إضافية، استخدم:
+      ```shell
+      uv add <package-name>
+      ```
+    - لتشغيل الـ Crew، نفّذ الأمر التالي في جذر مشروعك:
+      ```bash
+      crewai run
+      ```
+  </Step>
+</Steps>
+
+## خيارات التثبيت للمؤسسات
+
+<Note type="info">
+للفرق والمؤسسات، يوفر CrewAI خيارات نشر مؤسسية تزيل تعقيد الإعداد:
+
+### CrewAI AMP (SaaS)
+
+- لا يتطلب أي تثبيت - فقط سجّل مجانًا على [app.crewai.com](https://app.crewai.com)
+- تحديثات وصيانة تلقائية
+- بنية تحتية مُدارة وقابلة للتوسع
+- بناء Crews بدون كتابة كود
+
+### CrewAI Factory (استضافة ذاتية)
+
+- نشر بالحاويات على بنيتك التحتية
+- يدعم أي مزود سحابي بما في ذلك النشر المحلي
+- تكامل مع أنظمة الأمان الحالية
+
+<Card title="استكشف خيارات المؤسسات" icon="building" href="https://share.hsforms.com/1Ooo2UViKQ22UOzdr7i77iwr87kg">
+  تعرّف على عروض CrewAI للمؤسسات وجدول عرضًا توضيحيًا
+</Card>
+</Note>
+
+## الخطوات التالية
+
+<CardGroup cols={2}>
+  <Card title="بدء سريع: Flow + وكيل" icon="code" href="/ar/quickstart">
+    اتبع البداية السريعة لإنشاء Flow وتشغيل طاقم بوكيل واحد وإنتاج تقرير.
+  </Card>
+  <Card
+    title="انضم إلى المجتمع"
+    icon="comments"
+    href="https://community.crewai.com"
+  >
+    تواصل مع مطورين آخرين واحصل على المساعدة وشارك تجاربك مع CrewAI.
+  </Card>
+</CardGroup>

docs/v1.15.19/ar/introduction.mdx

@@ -0,0 +1,152 @@
+---
+title: مقدمة
+description: ابنِ فرق Agents ذكاء اصطناعي تعمل معًا لمعالجة المهام المعقدة
+icon: handshake
+mode: "wide"
+---
+
+# ما هو CrewAI؟
+
+**CrewAI هو إطار العمل مفتوح المصدر الرائد لتنسيق Agents الذكاء الاصطناعي المستقلة وبناء سير العمل المعقدة.**
+
+يمكّن المطورين من بناء أنظمة متعددة الـ Agents جاهزة للإنتاج من خلال الجمع بين الذكاء التعاوني لـ **Crews** والتحكم الدقيق لـ **Flows**.
+
+- **[CrewAI Flows](/ar/guides/flows/first-flow)**: العمود الفقري لتطبيق الذكاء الاصطناعي. تتيح لك Flows إنشاء سير عمل منظمة قائمة على الأحداث تدير الحالة وتتحكم في التنفيذ. وهي توفر البنية الأساسية التي تعمل ضمنها Agents الذكاء الاصطناعي.
+- **[CrewAI Crews](/ar/guides/crews/first-crew)**: وحدات العمل ضمن Flow. الـ Crews هي فرق من Agents مستقلة تتعاون لحل مهام محددة يفوضها إليها Flow.
+
+مع أكثر من 100,000 مطور معتمد عبر دوراتنا المجتمعية، يُعد CrewAI المعيار لأتمتة الذكاء الاصطناعي الجاهزة للمؤسسات.
+
+### شاهد: بناء Agents و Flows في CrewAI باستخدام Coding Agent Skills
+
+قم بتثبيت مهارات وكيل البرمجة الخاصة بنا (Claude Code، Codex، ...) لتشغيل وكلاء البرمجة بسرعة مع CrewAI.
+
+يمكنك تثبيتها باستخدام `npx skills add crewaiinc/skills`
+
+<iframe src="https://www.loom.com/embed/befb9f68b81f42ad8112bfdd95a780af" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen style={{width: "100%", height: "400px"}}></iframe>
+
+## بنية CrewAI المعمارية
+
+صُممت بنية CrewAI لتحقيق التوازن بين الاستقلالية والتحكم.
+
+### 1. Flows: العمود الفقري
+
+<Note>
+  فكّر في Flow كـ "المدير" أو "تعريف العملية" لتطبيقك. يحدد الخطوات والمنطق وكيفية تدفق البيانات عبر نظامك.
+</Note>
+
+<Frame caption="نظرة عامة على إطار عمل CrewAI">
+  <img src="/images/flows.png" alt="نظرة عامة على إطار عمل CrewAI" />
+</Frame>
+
+توفر Flows:
+- **إدارة الحالة**: حفظ البيانات عبر الخطوات والتنفيذات.
+- **تنفيذ قائم على الأحداث**: تشغيل إجراءات بناءً على أحداث أو مدخلات خارجية.
+- **التحكم في التدفق**: استخدام المنطق الشرطي والحلقات والتفرع.
+
+### 2. Crews: الذكاء
+
+<Note>
+  الـ Crews هي "الفرق" التي تقوم بالعمل الثقيل. ضمن Flow، يمكنك تشغيل Crew لمعالجة مشكلة معقدة تتطلب إبداعًا وتعاونًا.
+</Note>
+
+<Frame caption="نظرة عامة على إطار عمل CrewAI">
+  <img src="/images/crews.png" alt="نظرة عامة على إطار عمل CrewAI" />
+</Frame>
+
+توفر Crews:
+- **Agents بأدوار محددة**: Agents متخصصة بأهداف وأدوات محددة.
+- **تعاون مستقل**: تعمل الـ Agents معًا لحل المهام.
+- **تفويض المهام**: يتم تعيين المهام وتنفيذها بناءً على قدرات الـ Agent.
+
+## كيف يعمل الكل معًا
+
+1.  يبدأ **Flow** حدثًا أو يشغّل عملية.
+2.  يدير **Flow** الحالة ويقرر ما يجب فعله بعد ذلك.
+3.  يفوّض **Flow** مهمة معقدة إلى **Crew**.
+4.  تتعاون Agents الـ **Crew** لإكمال المهمة.
+5.  يعيد **Crew** النتيجة إلى **Flow**.
+6.  يستمر **Flow** في التنفيذ بناءً على النتيجة.
+
+## الميزات الرئيسية
+
+<CardGroup cols={2}>
+  <Card title="Flows بمستوى الإنتاج" icon="arrow-progress">
+    ابنِ سير عمل موثوقة وذات حالة يمكنها التعامل مع العمليات طويلة التشغيل والمنطق المعقد.
+  </Card>
+  <Card title="Crews مستقلة" icon="users">
+    انشر فرقًا من الـ Agents يمكنها التخطيط والتنفيذ والتعاون لتحقيق أهداف عالية المستوى.
+  </Card>
+  <Card title="أدوات مرنة" icon="screwdriver-wrench">
+    اربط Agents بأي API أو قاعدة بيانات أو أداة محلية.
+  </Card>
+  <Card title="أمان المؤسسات" icon="lock">
+    مصمم مع مراعاة الأمان والامتثال لعمليات نشر المؤسسات.
+  </Card>
+</CardGroup>
+
+## متى تستخدم Crews مقابل Flows
+
+**الإجابة المختصرة: استخدم كليهما.**
+
+لأي تطبيق جاهز للإنتاج، **ابدأ بـ Flow**.
+
+- **استخدم Flow** لتعريف الهيكل العام والحالة والمنطق لتطبيقك.
+- **استخدم Crew** ضمن خطوة Flow عندما تحتاج فريقًا من الـ Agents لأداء مهمة معقدة محددة تتطلب استقلالية.
+
+| حالة الاستخدام | البنية المعمارية |
+| :--- | :--- |
+| **أتمتة بسيطة** | Flow واحد مع مهام Python |
+| **بحث معقد** | Flow يدير الحالة -> Crew يجري البحث |
+| **واجهة تطبيق خلفية** | Flow يعالج طلبات API -> Crew ينشئ المحتوى -> Flow يحفظ في قاعدة البيانات |
+
+## لماذا تختار CrewAI؟
+
+- **تشغيل مستقل**: تتخذ الـ Agents قرارات ذكية بناءً على أدوارها وأدواتها المتاحة
+- **تفاعل طبيعي**: تتواصل الـ Agents وتتعاون كأعضاء فريق بشري
+- **تصميم قابل للتوسيع**: سهولة إضافة أدوات وأدوار وقدرات جديدة
+- **جاهز للإنتاج**: مبني للموثوقية والتوسع في التطبيقات الواقعية
+- **موجّه نحو الأمان**: مصمم مع مراعاة متطلبات أمان المؤسسات
+- **كفاءة التكلفة**: محسّن لتقليل استخدام الرموز المميزة واستدعاءات API
+
+## هل أنت مستعد للبدء في البناء؟
+
+<CardGroup cols={2}>
+  <Card
+    title="ابنِ أول Flow لك"
+    icon="diagram-project"
+    href="/ar/guides/flows/first-flow"
+  >
+    تعلم كيفية إنشاء سير عمل منظمة قائمة على الأحداث مع تحكم دقيق في التنفيذ.
+  </Card>
+  <Card
+    title="ابنِ أول Crew لك"
+    icon="users-gear"
+    href="/ar/guides/crews/first-crew"
+  >
+    دليل تفصيلي لإنشاء فريق AI تعاوني يعمل معًا لحل المشكلات المعقدة.
+  </Card>
+</CardGroup>
+
+<CardGroup cols={3}>
+  <Card
+    title="تثبيت CrewAI"
+    icon="wrench"
+    href="/ar/installation"
+  >
+    ابدأ مع CrewAI في بيئة التطوير الخاصة بك.
+  </Card>
+  <Card
+    title="البداية السريعة"
+    icon="bolt"
+    href="/ar/quickstart"
+  >
+    أنشئ Flow وشغّل طاقمًا بوكيل واحد وأنشئ تقريرًا من البداية للنهاية.
+  </Card>
+  <Card
+    title="انضم إلى المجتمع"
+    icon="comments"
+    href="https://community.crewai.com"
+  >
+    تواصل مع مطورين آخرين واحصل على المساعدة وشارك تجاربك مع CrewAI.
+  </Card>
+</CardGroup>

docs/v1.15.19/ar/learn/a2a-agent-delegation.mdx

@@ -0,0 +1,87 @@
+---
+title: بروتوكول Agent-to-Agent (A2A)
+description: الـ Agents تفوّض المهام إلى Agents A2A بعيدة و/أو تعمل كـ Agents خادم متوافقة مع A2A.
+icon: network-wired
+mode: "wide"
+---
+
+## تفويض Agent A2A
+
+يعامل CrewAI [بروتوكول A2A](https://a2a-protocol.org/latest/) كبنية تفويض أساسية، مما يمكّن الـ Agents من تفويض المهام وطلب المعلومات والتعاون مع Agents بعيدة، وكذلك العمل كـ Agents خادم متوافقة مع A2A. في وضع العميل، تختار الـ Agents تلقائيًا بين التنفيذ المحلي والتفويض البعيد بناءً على متطلبات المهمة.
+
+## كيف يعمل
+
+عندما يُهيَّأ Agent بقدرات A2A:
+
+1. يحلل الـ Agent كل مهمة
+2. يقرر إما:
+   - معالجة المهمة مباشرة باستخدام قدراته الخاصة
+   - التفويض إلى Agent A2A بعيد للمعالجة المتخصصة
+3. إذا فوّض، يتواصل الـ Agent مع Agent A2A البعيد عبر البروتوكول
+4. تُعاد النتائج إلى سير عمل CrewAI
+
+<Note>
+  تفويض A2A يتطلب حزمة `a2a-sdk`. ثبّتها بـ: `uv add 'crewai[a2a]'` أو `pip install 'crewai[a2a]'`
+</Note>
+
+## التهيئة الأساسية
+
+<Warning>
+  `crewai.a2a.config.A2AConfig` مهمل وسيُزال في v2.0.0. استخدم `A2AClientConfig` للاتصال بـ Agents بعيدة و/أو `A2AServerConfig` لعرض الـ Agents كخوادم.
+</Warning>
+
+```python Code
+from crewai import Agent, Crew, Task
+from crewai.a2a import A2AClientConfig
+
+agent = Agent(
+    role="Research Coordinator",
+    goal="Coordinate research tasks efficiently",
+    backstory="Expert at delegating to specialized research agents",
+    llm="gpt-4o",
+    a2a=A2AClientConfig(
+        endpoint="https://example.com/.well-known/agent-card.json",
+        timeout=120,
+        max_turns=10
+    )
+)
+
+task = Task(
+    description="Research the latest developments in quantum computing",
+    expected_output="A comprehensive research report",
+    agent=agent
+)
+
+crew = Crew(agents=[agent], tasks=[task], verbose=True)
+result = crew.kickoff()
+```
+
+## خيارات تهيئة العميل
+
+راجع الملف الإنجليزي الأصلي للحصول على القائمة الكاملة لمعاملات `A2AClientConfig` وخيارات المصادقة وآليات التحديث وتهيئة الخادم.
+
+## أفضل الممارسات
+
+<CardGroup cols={2}>
+  <Card title="عيّن مهلات مناسبة" icon="clock">
+    هيّئ المهلات بناءً على أوقات استجابة Agent A2A المتوقعة.
+  </Card>
+
+  <Card title="حدّ جولات المحادثة" icon="comments">
+    استخدم `max_turns` لمنع التبادل المفرط.
+  </Card>
+
+  <Card title="استخدم معالجة أخطاء مرنة" icon="shield-check">
+    عيّن `fail_fast=False` لبيئات الإنتاج مع عدة Agents.
+  </Card>
+
+  <Card title="أمّن بيانات الاعتماد" icon="lock">
+    خزّن رموز المصادقة وبيانات الاعتماد كمتغيرات بيئة، ليس في الكود.
+  </Card>
+</CardGroup>
+
+## تعلم المزيد
+
+- [توثيق بروتوكول A2A](https://a2a-protocol.org)
+- [تطبيقات A2A النموذجية](https://github.com/a2aproject/a2a-samples)
+- [A2A Python SDK](https://github.com/a2aproject/a2a-python)

docs/v1.15.19/ar/learn/before-and-after-kickoff-hooks.mdx

@@ -0,0 +1,47 @@
+---
+title: خطافات قبل وبعد الانطلاق
+description: تعلم كيفية استخدام خطافات قبل وبعد الانطلاق في CrewAI
+mode: "wide"
+---
+
+يوفر CrewAI خطافات تتيح لك تنفيذ كود قبل وبعد انطلاق Crew. هذه الخطافات مفيدة لمعالجة المدخلات مسبقًا أو معالجة النتائج لاحقًا.
+
+## خطاف قبل الانطلاق
+
+يُنفَّذ خطاف قبل الانطلاق قبل أن يبدأ Crew مهامه. يتلقى قاموس المدخلات ويمكنه تعديله قبل تمريره إلى Crew. يمكنك استخدام هذا الخطاف لإعداد بيئتك أو تحميل البيانات اللازمة أو معالجة المدخلات مسبقًا.
+
+```python
+from crewai import CrewBase
+from crewai.project import before_kickoff
+
+@CrewBase
+class MyCrew:
+    @before_kickoff
+    def prepare_data(self, inputs):
+        inputs['processed'] = True
+        return inputs
+```
+
+## خطاف بعد الانطلاق
+
+يُنفَّذ خطاف بعد الانطلاق بعد إتمام Crew مهامه. يتلقى كائن النتيجة الذي يحتوي على مخرجات تنفيذ Crew. هذا الخطاف مثالي لمعالجة النتائج لاحقًا مثل التسجيل أو تحويل البيانات أو التحليل الإضافي.
+
+```python
+from crewai import CrewBase
+from crewai.project import after_kickoff
+
+@CrewBase
+class MyCrew:
+    @after_kickoff
+    def log_results(self, result):
+        print("Crew execution completed with result:", result)
+        return result
+```
+
+## استخدام كلا الخطافين
+
+يمكن استخدام كلا الخطافين معًا لتوفير عملية إعداد وتفكيك شاملة لتنفيذ Crew. وهما مفيدان بشكل خاص في الحفاظ على بنية كود نظيفة من خلال فصل المسؤوليات وتعزيز نمطية تنفيذات CrewAI.
+
+## الخلاصة
+
+توفر خطافات قبل وبعد الانطلاق في CrewAI طرقًا قوية للتفاعل مع دورة حياة تنفيذ Crew. من خلال فهم واستخدام هذه الخطافات، يمكنك تعزيز متانة ومرونة Agents الذكاء الاصطناعي بشكل كبير.

docs/v1.15.19/ar/learn/bring-your-own-agent.mdx

@@ -0,0 +1,41 @@
+---
+title: أحضر Agent الخاص بك
+description: تعلم كيفية إحضار Agents خاصة بك تعمل ضمن Crew.
+icon: robots
+mode: "wide"
+---
+
+قابلية التشغيل البيني مفهوم أساسي في CrewAI. يوضح هذا الدليل كيفية إحضار Agents خاصة بك تعمل ضمن Crew.
+
+## دليل المحوّلات لإحضار Agents الخاصة (Agents من LangGraph وOpenAI وغيرها...)
+
+نتطلب 3 محوّلات لتحويل أي Agent من أطر عمل مختلفة للعمل ضمن Crew.
+
+1. BaseAgentAdapter
+2. BaseToolAdapter
+3. BaseConverter
+
+## BaseAgentAdapter
+
+تعرّف هذه الفئة المجردة الواجهة المشتركة والوظائف التي يجب أن تنفذها جميع محوّلات الـ Agent. تمتد BaseAgent للحفاظ على التوافق مع إطار عمل CrewAI مع إضافة متطلبات خاصة بالمحوّل.
+
+الطرق المطلوبة:
+
+1. `def configure_tools`
+2. `def configure_structured_output`
+
+## إنشاء محوّل خاص بك
+
+لدمج Agent من إطار عمل مختلف في CrewAI، تحتاج لإنشاء محوّل مخصص بوراثة `BaseAgentAdapter`. يعمل هذا المحوّل كطبقة توافق تترجم بين واجهات CrewAI والمتطلبات المحددة للـ Agent الخارجي.
+
+راجع الملف الإنجليزي الأصلي لأمثلة الكود التفصيلية لتنفيذ BaseAgentAdapter وBaseToolAdapter وBaseConverter.
+
+## محوّلات جاهزة للاستخدام
+
+نوفر محوّلات جاهزة للأطر التالية:
+1. LangGraph
+2. OpenAI Agents
+
+## تشغيل Crew مع Agents محوّلة:
+
+راجع الملف الإنجليزي الأصلي للحصول على مثال الكود الكامل الذي يوضح استخدام CrewAI Agent وOpenAI Agent Adapter وLangGraph Agent Adapter معًا في Crew واحد.