chore(env): inline self-contained install in environment.json

Co-authored-by: Rip&Tear <theCyberTech@users.noreply.github.com>

.cursor/environment.json

@@ -0,0 +1,4 @@
+{
+  "name": "CrewAI",
+  "install": "export PATH=\"$HOME/.local/bin:$PATH\"\ncommand -v uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh\nexport PATH=\"$HOME/.local/bin:$PATH\"\nuv sync --all-groups --all-extras"
+}

.github/workflows/vulnerability-scan.yml

@@ -86,8 +86,11 @@ jobs:
             --skip-editable
             --format json
             --output pip-audit-report.json
-            --ignore-vuln GHSA-rrmf-rvhw-rf47 # torch 2.12.0 (CVE-2025-3000): local-only memory corruption in torch.jit.script; no fix available.
-            --ignore-vuln GHSA-f4j7-r4q5-qw2c # chromadb 1.1.1 (CVE-2026-45829): pre-auth RCE in the HTTP server; no fix available.
+            # chromadb <=1.5.9 (CVE-2026-45829 / GHSA-f4j7-r4q5-qw2c): pre-auth RCE in
+            # the Python HTTP server. Fix merged upstream in chroma-core/chroma#7237
+            # but no PyPI release beyond 1.5.9 yet. CrewAI only uses PersistentClient
+            # (embedded), not the HTTP server.
+            --ignore-vuln GHSA-f4j7-r4q5-qw2c
           )
           uv run pip-audit "${pip_audit_args[@]}"
         continue-on-error: true

.pre-commit-config.yaml

@@ -48,7 +48,6 @@ repos:
           --ignore-vuln PYSEC-2025-197
           --ignore-vuln PYSEC-2025-210
           --ignore-vuln PYSEC-2026-139
-          --ignore-vuln GHSA-rrmf-rvhw-rf47
           --ignore-vuln PYSEC-2025-211
           --ignore-vuln PYSEC-2025-212
           --ignore-vuln PYSEC-2025-213

AGENTS.md

@@ -24,3 +24,5 @@ Follow these guidelines when contributing:
    may reference them.
 4. If you want to preview your changes locally, use `cd docs && mintlify dev`.
    To check for broken links, run `cd docs && mintlify broken-links`.
+5. After editing English docs, sync translations to `ar`, `ko`, and `pt-BR`
+   before finishing the task. Follow [DOCS_TRANSLATIONS.md](DOCS_TRANSLATIONS.md).

DOCS_TRANSLATIONS.md

@@ -0,0 +1,81 @@
+# Sync Docs Translations
+
+After English documentation changes, sync the same updates to Arabic (`ar`),
+Korean (`ko`), and Brazilian Portuguese (`pt-BR`).
+
+Supported locales: `ar`, `ko`, `pt-BR`.
+
+## Step 1 — Find changed English files with git
+
+From the repo root:
+
+```bash
+# Uncommitted changes (staged or unstaged)
+git diff --name-only HEAD -- docs/edge/en/
+
+# All changes on this branch vs main
+git diff --name-only main...HEAD -- docs/edge/en/
+
+# Newly added files
+git status --porcelain docs/edge/en/
+```
+
+Only process `*.mdx` under `docs/edge/en/`. Do not edit `docs/v*/` snapshots.
+
+## Step 2 — Map each file to locale targets
+
+For `docs/edge/en/<path>.mdx`, update or create:
+
+- `docs/edge/ar/<path>.mdx`
+- `docs/edge/ko/<path>.mdx`
+- `docs/edge/pt-BR/<path>.mdx`
+
+If English is a **new page**, also add matching entries in `docs/docs.json`
+navigation for each locale.
+
+## Step 3 — Translate
+
+Use the updated English file as source of truth. When locale files already
+exist, apply the same semantic change — do not rewrite unrelated sections.
+
+Rules:
+
+- Translate prose and frontmatter values (`title`, `description`, `sidebarTitle`)
+- Keep MDX/JSX tags, code blocks, URLs, and identifiers unchanged
+- Keep terms like Agent, Crew, Task, Flow, LLM, API, CLI, MCP in English where
+  appropriate
+- Rewrite internal links: `/en/` → `/{lang}/` (`/ar/`, `/ko/`, `/pt-BR/`)
+- Do not add translator notes
+
+## Step 4 — Verify (optional)
+
+```bash
+cd docs && mintlify broken-links
+```
+
+Commit English and locale files together.
+
+## Checklist
+
+```markdown
+- [ ] Git: listed changed docs/edge/en/*.mdx files
+- [ ] ar: updated/created matching files
+- [ ] ko: updated/created matching files
+- [ ] pt-BR: updated/created matching files
+- [ ] Links use /{lang}/ prefix; code blocks unchanged
+- [ ] docs/docs.json updated if new English page added
+```
+
+## Example
+
+`git diff --name-only HEAD -- docs/edge/en/` returns:
+
+```text
+docs/edge/en/concepts/llms.mdx
+```
+
+Update:
+
+- `docs/edge/ar/concepts/llms.mdx`
+- `docs/edge/ko/concepts/llms.mdx`
+- `docs/edge/pt-BR/concepts/llms.mdx`

README.md

@@ -66,7 +66,7 @@ standard for production-ready agentic automation.
 
 # CrewAI AMP Suite
 
-For organizations that need a commercial control plane around CrewAI, [CrewAI AMP Suite](https://www.crewai.com/enterprise) adds managed deployment, observability, governance, security, and enterprise support.
+For organizations that need a commercial control plane around CrewAI, [CrewAI AMP Suite](https://crewai.com/amp) adds managed deployment, observability, governance, security, and enterprise support.
 
 You can try one part of the suite, the [Crew Control Plane, for free](https://app.crewai.com).
 
@@ -88,8 +88,12 @@ intelligent automations.
 - [Build with AI](#build-with-ai)
 - [Why CrewAI?](#why-crewai)
 - [Getting Started](#getting-started)
+  - [Learning Resources](#learning-resources)
+  - [Understanding Flows and Crews](#understanding-flows-and-crews)
+  - [Installation](#1-installation)
+  - [Setting Up Your Crew](#2-setting-up-your-crew-with-the-yaml-configuration)
+  - [Running Your Crew](#3-running-your-crew)
 - [Key Features](#key-features)
-- [Understanding Flows and Crews](#understanding-flows-and-crews)
 - [Examples](#examples)
   - [Quick Tutorial](#quick-tutorial)
   - [Write Job Descriptions](#write-job-descriptions)
@@ -151,9 +155,7 @@ Setup and run your first CrewAI agents by following this tutorial.
 
 [![CrewAI Getting Started Tutorial](https://img.youtube.com/vi/-kSOTtYzgEw/hqdefault.jpg)](https://www.youtube.com/watch?v=-kSOTtYzgEw "CrewAI Getting Started Tutorial")
 
-###
-
-Learning Resources
+### Learning Resources
 
 Learn CrewAI through our comprehensive courses:
 
@@ -307,7 +309,7 @@ research_task:
   description: >
     Conduct a thorough research about {topic}
     Make sure you find any interesting and relevant information given
-    the current year is 2025.
+    the current year is 2026.
   expected_output: >
     A list with 10 bullet points of the most relevant information about {topic}
   agent: researcher
@@ -317,7 +319,7 @@ reporting_task:
     Review the context you got and expand each topic into a full section for a report.
     Make sure the report is detailed and contains any and all relevant information.
   expected_output: >
-    A fully fledge reports with the mains topics, each with a full section of information.
+    A fully fledged report with the main topics, each with a full section of information.
     Formatted as markdown without '```'
   agent: reporting_analyst
   output_file: report.md
@@ -430,7 +432,7 @@ crewai update
 
 You should see the output in the console and the `report.md` file should be created in the root of your project with the full final report.
 
-In addition to the sequential process, you can use the hierarchical process, which automatically assigns a manager to the defined crew to properly coordinate the planning and execution of tasks through delegation and validation of results. [See more about the processes here](https://docs.crewai.com/core-concepts/Processes/).
+In addition to the sequential process, you can use the hierarchical process, which automatically assigns a manager to the defined crew to properly coordinate the planning and execution of tasks through delegation and validation of results. [See more about the processes here](https://docs.crewai.com/en/concepts/processes).
 
 ## Key Features
 
@@ -451,7 +453,7 @@ Choose CrewAI to build powerful, adaptable, and production-ready AI automations.
 You can test different real life examples of AI crews in the [CrewAI-examples repo](https://github.com/crewAIInc/crewAI-examples?tab=readme-ov-file):
 
 - [Landing Page Generator](https://github.com/crewAIInc/crewAI-examples/tree/main/crews/landing_page_generator)
-- [Having Human input on the execution](https://docs.crewai.com/how-to/Human-Input-on-Execution)
+- [Having Human input on the execution](https://docs.crewai.com/en/learn/human-input-on-execution)
 - [Trip Planner](https://github.com/crewAIInc/crewAI-examples/tree/main/crews/trip_planner)
 - [Stock Analysis](https://github.com/crewAIInc/crewAI-examples/tree/main/crews/stock_analysis)
 
@@ -483,7 +485,7 @@ CrewAI's power truly shines when combining Crews with Flows to create sophistica
 CrewAI flows support logical operators like `or_` and `and_` to combine multiple conditions. This can be used with `@start`, `@listen`, or `@router` decorators to create complex triggering conditions.
 
 - `or_`: Triggers when any of the specified conditions are met.
-- `and_`Triggers when all of the specified conditions are met.
+- `and_`: Triggers when all of the specified conditions are met.
 
 Here's how you can orchestrate multiple Crews within a Flow:
 
@@ -580,7 +582,7 @@ This example demonstrates how to:
 
 CrewAI supports using various LLMs through a variety of connection options. By default your agents will use the OpenAI API when querying the model. However, there are several other ways to allow your agents to connect to models. For example, you can configure your agents to use a local model via the Ollama tool.
 
-Please refer to the [Connect CrewAI to LLMs](https://docs.crewai.com/how-to/LLM-Connections/) page for details on configuring your agents' connections to models.
+Please refer to the [Connect CrewAI to LLMs](https://docs.crewai.com/en/learn/llm-connections) page for details on configuring your agents' connections to models.
 
 ## When to Use CrewAI
 
@@ -596,13 +598,26 @@ CrewAI is especially useful when you want to:
 
 ## Contribution
 
-CrewAI is open-source and we welcome contributions. If you're looking to contribute, please:
+CrewAI is open-source and we welcome contributions. See
+[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md) for the full setup guide,
+branching conventions, and PR checklist.
 
-- Fork the repository.
-- Create a new branch for your feature.
-- Add your feature or improvement.
-- Send a pull request.
-- We appreciate your input!
+Quick start:
+
+```bash
+git clone https://github.com/crewAIInc/crewAI.git
+cd crewAI
+uv sync --all-groups --all-extras
+uv run pre-commit install
+```
+
+```bash
+# Tests
+uv run pytest lib/crewai/tests/ -x -q
+
+# Type checks
+uv run mypy lib/
+```
 
 ### Contributing to the docs
 
@@ -614,51 +629,8 @@ immediately and are frozen into a new versioned snapshot under
 `docs/v<X.Y.Z>/` at the next release cut. Frozen snapshots are immutable — CI
 rejects PRs that modify them without a `[docs-freeze]` title prefix. The
 release CLI (`devtools release`) handles the freeze automatically; see
-[`AGENTS.md`](AGENTS.md) for the full contributor guide and
-[`RELEASING.md`](RELEASING.md) for the release-cut runbook.
-
-### Installing Dependencies
-
-```bash
-uv lock
-uv sync
-```
-
-### Virtual Env
-
-```bash
-uv venv
-```
-
-### Pre-commit hooks
-
-```bash
-pre-commit install
-```
-
-### Running Tests
-
-```bash
-uv run pytest .
-```
-
-### Running static type checks
-
-```bash
-uvx mypy src
-```
-
-### Packaging
-
-```bash
-uv build
-```
-
-### Installing Locally
-
-```bash
-uv pip install dist/*.tar.gz
-```
+[`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md) for contributor guidance and
+[`lib/devtools/README.md`](lib/devtools/README.md) for release tooling.
 
 ## Telemetry
 
@@ -729,7 +701,7 @@ A: CrewAI is a lean, fast Python framework built specifically for orchestrating
 
 ### Q: How do I install CrewAI?
 
-A: Install CrewAI using pip:
+A: Install CrewAI with [UV](https://docs.astral.sh/uv/):
 
 ```shell
 uv pip install crewai
@@ -751,7 +723,7 @@ A: Yes. CrewAI excels at both simple and highly complex real-world scenarios, of
 
 ### Q: Can I use CrewAI with local AI models?
 
-A: Absolutely! CrewAI supports various language models, including local ones. Tools like Ollama and LM Studio allow seamless integration. Check the [LLM Connections documentation](https://docs.crewai.com/how-to/LLM-Connections/) for more details.
+A: Absolutely! CrewAI supports various language models, including local ones. Tools like Ollama and LM Studio allow seamless integration. Check the [LLM Connections documentation](https://docs.crewai.com/en/learn/llm-connections) for more details.
 
 ### Q: What makes Crews different from Flows?
 
@@ -771,7 +743,7 @@ A: Check out practical examples in the [CrewAI-examples repository](https://gith
 
 ### Q: How can I contribute to CrewAI?
 
-A: Contributions are warmly welcomed! Fork the repository, create your branch, implement your changes, and submit a pull request. See the Contribution section of the README for detailed guidelines.
+A: Contributions are warmly welcomed! Fork the repository, create your branch, implement your changes, and submit a pull request. See [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md) for detailed guidelines.
 
 ### Q: What additional features does CrewAI AMP offer?
 

docs/edge/ar/changelog.mdx

@@ -4,6 +4,133 @@ description: "تحديثات المنتج والتحسينات وإصلاحات
 icon: "clock"
 mode: "wide"
 ---
+<Update label="13 أغسطس 2026">
+  ## v1.15.16
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.16)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - تقديم إدارة سياق التنفيذ مع دعم UUID
+  - تسجيل نوع الاستثناء الذي أنهى تدفق العمل
+  - تسجيل متى تم مشاركة دفعة تتبع مع AMP
+  - عد عمليات النشر من أي مصدر وتسجيل مكان بدايتها
+
+  ### إصلاحات الأخطاء
+  - تسجيل الإصدار الجاري على كل نطاق تم إصداره
+  - إصلاح التحقق من صحة اسم جدول البحث في MySQL
+  - منع فشل دورة من تحديد الدورة التالية على أنها فاشلة
+
+  ### الوثائق
+  - إضافة أدلة الواجهة الأمامية لـ CopilotKit و AG-UI
+
+  ## المساهمون
+
+  @joaomdmoura, @lorenzejay, @ranst91, @theCyberTech
+
+</Update>
+
+<Update label="11 أغسطس 2026">
+  ## v1.15.15
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.15)
+
+  ## ما الذي تغيّر
+
+  ### الميزات
+  - الإبلاغ عن نتيجة التدفق، والمدة، وإشارات الإنسان في الحلقة.
+
+  ### إصلاحات الأخطاء
+  - إصدار FlowStartedEvent عندما يقوم خطاف الحدود بإلغاء التدفق.
+  - تحديد نطاق تصدير النطاق لمزود المتعقب الخاص بنا.
+  - ترقية torch إلى الإصدار 2.13.0 لمعالجة ثغرة أمنية.
+  - ترقية gitpython إلى الإصدار 3.1.58 في crewai-tools[github].
+
+  ### إعادة الهيكلة
+  - تحديث وظيفة حقن التاريخ في الوكلاء.
+  - توحيد علامات CLI إلى صيغة kebab-case.
+
+  ### الوثائق
+  - لقطة وتغيير السجل للإصدار v1.15.14.
+
+  ## المساهمون
+
+  @Vidit-Ostwal, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech
+
+</Update>
+
+<Update label="8 أغسطس 2026">
+  ## v1.15.14
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.14)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - فصل سياق وقت التشغيل عن وكيل الترميز وإضافة معرف المشروع
+
+  ### الوثائق
+  - تحديث اللقطة وسجل التغييرات للإصدار v1.15.13
+
+  ## المساهمون
+
+  @joaomdmoura
+
+</Update>
+
+<Update label="7 أغسطس 2026">
+  ## v1.15.13
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.13)
+
+  ## ما الذي تغير
+
+  ### إصلاحات الأخطاء
+  - إصلاح الحفاظ على مزود النماذج الموجهة بواسطة LiteLLM.
+  - تعزيز نماذج حدث LLM الهشة.
+  - إصلاح التقارير الناقصة لاستخدام رموز التخزين المؤقت من Anthropic.
+  - ترقية h2 إلى الإصدار 4.4.1 لمعالجة ثغرة الأمان GHSA-6hr6-w5qg-qmwg.
+
+  ### الوثائق
+  - إضافة سير العمل DOCS_TRANSLATIONS لمزامنة المواقع.
+  - إصلاح الروابط المعطلة في README، وفهرس المحتويات، وإرشادات المساهمة.
+  - لقطة وتغيير سجل الإصدار 1.15.12.
+
+  ## المساهمون
+
+  @Vidit-Ostwal, @joaomdmoura, @lucasgomide, @theCyberTech
+
+</Update>
+
+<Update label="5 أغسطس 2026">
+  ## v1.15.12
+
+  [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.12)
+
+  ## ما الذي تغير
+
+  ### الميزات
+  - زيادة إصدار Flow canary عند الإصدار
+  - إضافة URLReadTool لقراءة عناوين URL العشوائية
+  - إضافة بيانات التعريف الخاصة بالتطبيق إلى أدوات إجراءات المنصة
+  - توحيد الهيكل تحت `crewai create <resource>`
+
+  ### إصلاحات الأخطاء
+  - توضيح أخطاء تصادم أسماء المسارات/المعالجين في المحادثات
+
+  ### الوثائق
+  - تحديث ملف AGENTS.md للهيكل الموحد لأداة سطر الأوامر لإنشاء
+
+  ### تغييرات كبيرة
+  - لا شيء
+
+  ## المساهمون
+
+  @Vidit-Ostwal, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech
+
+</Update>
+
 <Update label="4 أغسطس 2026">
   ## v1.15.11
 

docs/edge/ar/concepts/agents.mdx

@@ -60,7 +60,7 @@ mode: "wide"
 | **احترام نافذة السياق** _(اختياري)_ | `respect_context_window` | `bool`                                | إبقاء الرسائل تحت حجم نافذة السياق عبر التلخيص. الافتراضي True.                                 |
 | **وضع تنفيذ الكود** _(اختياري)_    | `code_execution_mode`    | `Literal["safe", "unsafe"]`           | وضع تنفيذ الكود: 'safe' (باستخدام Docker) أو 'unsafe' (مباشر). الافتراضي 'safe'.                  |
 | **متعدد الوسائط** _(اختياري)_             | `multimodal`             | `bool`                                | ما إذا كان الوكيل يدعم القدرات متعددة الوسائط. الافتراضي False.                                    |
-| **حقن التاريخ** _(اختياري)_            | `inject_date`            | `bool`                                | ما إذا كان يتم حقن التاريخ الحالي تلقائيًا في المهام. الافتراضي False.                           |
+| **حقن التاريخ** _(اختياري)_            | `inject_date`            | `bool`                                | ما إذا كان يتم حقن التاريخ الحالي تلقائيًا في أمر الوكيل. الافتراضي False.                        |
 | **تنسيق التاريخ** _(اختياري)_            | `date_format`            | `str`                                 | سلسلة تنسيق التاريخ عند تفعيل inject_date. الافتراضي "%Y-%m-%d" (تنسيق ISO).                  |
 | **الاستدلال** _(اختياري)_              | `reasoning`              | `bool`                                | ما إذا كان يجب على الوكيل التأمل وإنشاء خطة قبل تنفيذ المهمة. الافتراضي False.            |
 | **الحد الأقصى لمحاولات الاستدلال** _(اختياري)_ | `max_reasoning_attempts` | `Optional[int]`                       | الحد الأقصى لمحاولات الاستدلال قبل تنفيذ المهمة. إذا None، سيحاول حتى الاستعداد.           |
@@ -287,7 +287,7 @@ analysis_agent = Agent(
 
 - `multimodal`: تفعيل القدرات متعددة الوسائط لمعالجة النص والمحتوى المرئي
 - `reasoning`: تمكين الوكيل من التأمل وإنشاء خطط قبل تنفيذ المهام
-- `inject_date`: حقن التاريخ الحالي تلقائيًا في أوصاف المهام
+- `inject_date`: حقن التاريخ الحالي تلقائيًا في أمر الوكيل
 
 #### القوالب
 

docs/edge/ar/concepts/cli.mdx

@@ -54,6 +54,16 @@ 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.
@@ -72,7 +82,7 @@ crewai version [OPTIONS]
 crewai train [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: عدد تكرارات التدريب (افتراضي: 5)
+- `-n, --n-iterations INTEGER`: عدد تكرارات التدريب (افتراضي: 5)
 - `-f, --filename TEXT`: مسار ملف مخصص للتدريب (افتراضي: "trained_agents_data.pkl")
 
 ### 4. الإعادة
@@ -83,7 +93,7 @@ crewai train [OPTIONS]
 crewai replay [OPTIONS]
 ```
 
-- `-t, --task_id TEXT`: إعادة تنفيذ الطاقم من معرّف المهمة هذا، بما في ذلك جميع المهام اللاحقة
+- `-t, --task-id TEXT`: إعادة تنفيذ الطاقم من معرّف المهمة هذا، بما في ذلك جميع المهام اللاحقة
 
 ### 5. سجل مخرجات المهام
 
@@ -117,7 +127,7 @@ crewai reset-memories [OPTIONS]
 crewai test [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: عدد تكرارات الاختبار (افتراضي: 3)
+- `-n, --n-iterations INTEGER`: عدد تكرارات الاختبار (افتراضي: 3)
 - `-m, --model TEXT`: نموذج LLM لتشغيل الاختبارات (افتراضي: "gpt-4o-mini")
 
 ### 8. التشغيل

docs/edge/ar/concepts/crews.mdx

@@ -172,6 +172,8 @@ class YourCrewName:
 
 بعد تنفيذ الطاقم، يمكنك الوصول إلى خاصية `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()

docs/edge/ar/concepts/flows.mdx

@@ -266,6 +266,24 @@ print(flow.usage_metrics)
   كلما احتجت إلى الإجمالي **الكامل** للتوكنات لتنفيذ التدفق.
 </Note>
 
+### دلالات حقول UsageMetrics
+
+يستخدم كائن [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) المُعاد عقدًا محايدًا للمزود:
+
+| الحقل | المعنى |
+| --- | --- |
+| `total_tokens` | الإجمالي المفوتر: `prompt_tokens + completion_tokens` |
+| `prompt_tokens` | إجمالي رموز الإدخال/المطالبة المفوترة للطلب |
+| `completion_tokens` | رموز الإخراج/الإكمال المفوترة للطلب |
+| `cached_prompt_tokens` | جزء قراءة الذاكرة المؤقتة من رموز المطالبة (تفصيل فقط) |
+| `cache_creation_tokens` | جزء كتابة الذاكرة المؤقتة من رموز المطالبة (تفصيل فقط، Anthropic) |
+| `reasoning_tokens` | جزء التفكير/الاستدلال حيث يبلّغ المزود عنه بشكل منفصل (تفصيل فقط) |
+| `successful_requests` | عدد استدعاءات LLM المُجمّعة |
+
+حقول التفصيل مثل `cached_prompt_tokens` و`cache_creation_tokens` و`reasoning_tokens` **لا تُضاف** فوق `total_tokens` — بل تصف أجزاءً مُدرجة بالفعل ضمن `prompt_tokens` أو `completion_tokens`.
+
+بالنسبة إلى Anthropic، تُدمج عدادات قراءة وكتابة الذاكرة المؤقتة ضمن `prompt_tokens`، لذا تنعكس أعباء العمل المخزنة مؤقتًا بالكامل في `total_tokens`. يُدرج مزودو OpenAI الرموز المخزنة مؤقتًا بالفعل داخل `prompt_tokens`؛ يعرض CrewAI الجزء المخزن مؤقتًا بشكل منفصل للوضوح.
+
 كل حقل في [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) المُعاد هو مجموع جميع استدعاءات نموذج اللغة التي حدثت خلال استدعاء واحد لـ `flow.kickoff()`. تتم إعادة تعيين العدادات عند الاستدعاء التالي لـ `kickoff()` (وفي كل تكرار من `kickoff_for_each`)، لذلك لن تتكرر العدّات عبر التشغيلات المتتالية. يمكن قراءة هذه الخاصية بأمان في أي وقت بعد اكتمال `kickoff()`؛ قراءتها أثناء التنفيذ تُرجع المجموع الجزئي المتراكم حتى تلك اللحظة.
 
 ## إدارة حالة التدفق

docs/edge/ar/concepts/llms.mdx

@@ -392,6 +392,22 @@ mode: "wide"
     - تتبع استخدام الرموز
     - محادثات استخدام أدوات متعددة الأدوار
 
+    **استخدام الرموز والتخزين المؤقت للمطالبة:**
+
+    يُبلّغ Anthropic عن الإدخال المفوتر في عدادات منفصلة — `input_tokens` (غير المخزن مؤقتًا)، و`cache_read_input_tokens`، و`cache_creation_input_tokens`. يدمج CrewAI الثلاثة ضمن `prompt_tokens` (و`input_tokens` الأصلي في استجابات المزود) بحيث يعكس `total_tokens` الاستخدام المفوتر الكامل على أعباء العمل المخزنة مؤقتًا.
+
+    يسجّل `cached_prompt_tokens` جزء قراءة الذاكرة المؤقتة كتفصيل فقط؛ وهو مُدرج بالفعل ضمن `prompt_tokens` ولا يجب إضافته مرة أخرى إلى `total_tokens`. يسجّل `cache_creation_tokens` عمليات الكتابة في الذاكرة المؤقتة بنفس الطريقة.
+
+    ```python Code
+    usage = llm.get_token_usage_summary()
+    # total_tokens == prompt_tokens + completion_tokens
+    # prompt_tokens includes cache read + cache write for Anthropic
+    ```
+
+    راجع قسم **UsageMetrics field semantics** في توثيق مفهوم Flows
+    للحصول على العقد المحايد للمزود المستخدم في `crew.usage_metrics`
+    و`flow.usage_metrics`.
+
     **ملاحظات مهمة:**
     - `max_tokens` معامل **مطلوب** لجميع نماذج Anthropic
     - يستخدم Claude `stop_sequences` بدلاً من `stop`

docs/edge/ar/concepts/testing.mdx

@@ -20,7 +20,7 @@ crewai test
 إذا أردت تشغيل المزيد من التكرارات أو استخدام نموذج مختلف، يمكنك تحديد المعاملات هكذا:
 
 ```bash
-crewai test --n_iterations 5 --model gpt-4o
+crewai test --n-iterations 5 --model gpt-4o
 ```
 
 أو باستخدام الصيغة المختصرة:
@@ -29,6 +29,11 @@ crewai test --n_iterations 5 --model gpt-4o
 crewai test -n 5 -m gpt-4o
 ```
 
+<Note>
+  العلم القديم `--n_iterations` لا يزال يعمل، لكنه مهمل ومخفي من `--help`.
+  استخدم `--n-iterations` (أو `-n`) بدلاً من ذلك.
+</Note>
+
 عند تشغيل أمر `crewai test`، سيتم تنفيذ الطاقم للعدد المحدد من التكرارات، وستُعرض مقاييس الأداء في نهاية التشغيل.
 
 سيظهر جدول الدرجات في النهاية لعرض أداء الطاقم من حيث المقاييس التالية:

docs/edge/ar/learn/execution-boundary-hooks.mdx

@@ -0,0 +1,200 @@
+---
+title: خطافات حدود التنفيذ
+description: اعتراض بداية تنفيذ الـ Crew والـ Flow ومدخلاته ومخرجاته ونهايته باستخدام المزخرف @on
+mode: "wide"
+---
+
+تعترض خطافات حدود التنفيذ الأطراف الخارجية للتشغيل — قبل بدء أي عمل، وعند
+حسم المدخلات، وعند جاهزية النتيجة النهائية، وعند انتهاء التنفيذ. وهي تعمل مع
+الـ Crew والـ Flow على حد سواء، وتُعد المكان المناسب لفحوصات السياسة على
+مستوى التشغيل وإعادة كتابة المدخلات وتنقية المخرجات.
+
+## نظرة عامة
+
+أربع نقاط اعتراض تغطي الحدود:
+
+| النقطة | التوقيت | `ctx.payload` |
+|--------|---------|---------------|
+| `EXECUTION_START` | Crew أو Flow على وشك البدء | `dict` المدخلات |
+| `INPUT` | المدخلات المحسومة للتنفيذ | `dict` المدخلات |
+| `OUTPUT` | النتيجة النهائية جاهزة | كائن المخرجات |
+| `EXECUTION_END` | انتهى التنفيذ (نجاحًا أو فشلًا) | كائن المخرجات، أو `None` عند الفشل |
+
+بالنسبة إلى الـ Crew، يكون payload المخرجات `CrewOutput`. أما في الـ Flow فهو
+النتيجة النهائية لدالة الـ Flow.
+
+## توقيع الخطاف
+
+```python
+from crewai.hooks import on, HookAborted, InterceptionPoint
+
+@on(InterceptionPoint.EXECUTION_START)
+def boundary_hook(ctx) -> Any | None:
+    # Mutate ctx.payload in place, or
+    # return a non-None value to replace it, or
+    # raise HookAborted(reason, source) to stop the run
+    return None
+```
+
+تتبع خطافات الحدود العقد القياسي: المتابعة (`return None`)، أو التعديل في
+المكان، أو الاستبدال بإرجاع قيمة، أو الإجهاض برفع `HookAborted`. أي إجهاض
+عند أي حد ينتشر خارج `kickoff()` مع سببه.
+
+## مخطط السياق
+
+تتلقى كل نقطة سياقًا منمّطًا. تشترك جميع السياقات في الحقول الأساسية:
+
+```python
+class InterceptionContext:
+    payload: Any            # The interceptable value (see table above)
+    agent: Any = None       # Not populated at execution boundaries
+    agent_role: str | None  # Not populated at execution boundaries
+    task: Any = None        # Not populated at execution boundaries
+    crew: Any = None        # The Crew instance (crew runs only)
+    flow: Any = None        # The Flow instance (flow runs only)
+```
+
+تضيف سياقات كل نقطة اسمًا بديلًا للـ payload:
+
+```python
+class ExecutionStartContext(InterceptionContext):
+    inputs: dict            # Same dict as payload
+
+class InputContext(InterceptionContext):
+    inputs: dict            # Same dict as payload
+
+class OutputContext(InterceptionContext):
+    output: Any             # The output object
+
+class ExecutionEndContext(InterceptionContext):
+    output: Any                    # The output object (None when status == "failed")
+    status: str                    # "completed" or "failed"
+    error: BaseException | None    # The exception when status == "failed"
+```
+
+<Note>
+`ctx.inputs` هو اسم بديل لقاموس المدخلات **الأصلي**، لذا فإن التعديلات في
+المكان عبر أي من الاسمين متكافئة. إذا *استبدل* خطاف سابق الـ payload بإرجاع
+dict جديد، فإن `ctx.payload` وحده يُعاد ربطه — اقرأ واكتب دائمًا عبر
+`ctx.payload` عندما يمكن أن تتسلسل الخطافات.
+</Note>
+
+## تشغيلات الـ Crew مقابل تشغيلات الـ Flow
+
+تعمل خطافات الحدود على كلا وقتي التشغيل، وتنفيذ الـ Crew يجري داخليًا فوق وقت
+تشغيل Flow. لذلك أثناء `crew.kickoff()` يُطلق الخطاف الحدودي العام لحدّ الـ
+Crew (‏`ctx.crew` مضبوط و`ctx.flow` يساوي `None`) **و** للـ Flow الداخلي
+(‏`ctx.flow` مضبوط و`ctx.crew` يساوي `None`). ميّز حسب وقت التشغيل:
+
+```python
+@on(InterceptionPoint.OUTPUT)
+def crew_output_only(ctx):
+    if ctx.crew is None:
+        return None  # Skip the internal flow (or a bare flow)
+    ctx.payload.raw = ctx.payload.raw.strip()
+```
+
+## حالات استخدام شائعة
+
+### فحص السياسة عند البدء
+
+```python
+@on(InterceptionPoint.EXECUTION_START)
+def enforce_policy(ctx):
+    if ctx.crew is not None and not ctx.payload.get("authorized"):
+        raise HookAborted(reason="unauthorized execution", source="access-control")
+```
+
+### إعادة كتابة المدخلات
+
+```python
+@on(InterceptionPoint.INPUT)
+def add_defaults(ctx):
+    if ctx.crew is None:
+        return None
+    ctx.payload.setdefault("locale", "en-US")
+    ctx.payload["topic"] = ctx.payload["topic"].strip().lower()
+```
+
+تتدفق المدخلات المعاد كتابتها إلى استيفاء الـ Task، فيتصرف التشغيل كما لو
+بدأ بالقاموس المعدل.
+
+فضّل `INPUT` لإعادة الكتابة وعامل `EXECUTION_START` كبوابة سماح/منع. إعادة
+الكتابة عند `EXECUTION_START` تظل مُحترمة — في الـ Crew تغذي أيضًا استدعاءات
+`before_kickoff`؛ وفي الـ Flow تُطبق تمامًا كإعادة كتابة `INPUT`.
+
+### تنقية المخرجات
+
+```python
+import re
+
+@on(InterceptionPoint.OUTPUT)
+def redact_emails(ctx):
+    if ctx.crew is None:
+        return None
+    ctx.payload.raw = re.sub(
+        r"\b[\w.+-]+@[\w-]+\.[\w.]+\b", "[EMAIL-REDACTED]", ctx.payload.raw
+    )
+```
+
+يعمل `OUTPUT` قبل `EXECUTION_END`، وكلاهما يرى الـ payload (الذي ربما
+استُبدل) من الخطافات السابقة؛ والقيمة النهائية المعاد كتابتها هي ما يعيده
+`kickoff()`.
+
+### مراقبة الإخفاقات
+
+يُطلق `EXECUTION_END` مرة واحدة بالضبط لكل تنفيذ، عند النجاح والفشل على حد
+سواء. عندما يرفع التشغيل استثناءً — خطأ في Task، أو استثناء في دالة Flow، أو
+`HookAborted` من نقطة سابقة — يتلقى الخطاف `status="failed"` مع الاستثناء في
+`ctx.error`، ويظل الاستثناء الأصلي ينتشر خارج `kickoff()` دون تغيير:
+
+```python
+@on(InterceptionPoint.EXECUTION_END)
+def report_outcome(ctx):
+    if ctx.status == "failed":
+        notify_policy_engine(status="failed", error=repr(ctx.error))
+    else:
+        notify_policy_engine(status="completed")
+```
+
+تنبيهان: لا يُطلق `EXECUTION_END` عندما لا يكون `EXECUTION_START` قد أُرسل
+أصلًا (الإجهاض عند البدء يعني أن الحد لم يُفتح قط، فلا توجد نهاية تقابله)،
+ورفع `HookAborted` من إرسال `EXECUTION_END` في مسار الفشل يُتجاهل — لم يعد
+هناك ما يُجهض، والخطأ الأصلي هو الغالب.
+
+## الترتيب
+
+لتشغيل Crew يكون ترتيب الحدود:
+
+```
+EXECUTION_START → before_kickoff callbacks → INPUT → tasks execute → OUTPUT → EXECUTION_END
+```
+
+لتشغيل Flow، تحسم خطافات الحدود المدخلات قبل أن تبدأ أحداث دورة الحياة:
+
+```
+EXECUTION_START → INPUT → FlowStartedEvent → flow methods execute → OUTPUT → EXECUTION_END → FlowFinishedEvent
+```
+
+يحمل `FlowStartedEvent` المدخلات كما حسمتها الخطافات، وإعادة كتابة
+`inputs["id"]` داخل خطاف حدودي تعيد توجيه استعادة الحالة. يظهر الإجهاض عند
+`EXECUTION_START` مع ذلك كحدث `FlowStartedEvent` يتبعه `FlowFailedEvent`،
+ويُبثان عند الإجهاض مع الحمولة كما حسمتها الخطافات التي عملت قبله.
+
+تعمل الخطافات في النقطة نفسها حسب ترتيب التسجيل، الخطافات العامة أولًا ثم
+الخطافات المحدودة بالـ Crew. تُبث القياسات (`HookDispatchedEvent`) مع كل
+إرسال.
+
+## إدارة الخطافات في الاختبارات
+
+```python
+from crewai.hooks import clear_all_hooks
+
+clear_all_hooks()  # Clears every point, including boundaries
+```
+
+## وثائق ذات صلة
+
+- [نظرة عامة على خطافات التنفيذ →](/edge/ar/learn/execution-hooks)
+- [خطافات استدعاء LLM →](/edge/ar/learn/llm-hooks)
+- [خطافات استدعاء الأدوات →](/edge/ar/learn/tool-hooks)

docs/edge/ar/telemetry.mdx

@@ -34,6 +34,20 @@ os.environ['CREWAI_DISABLE_TELEMETRY'] = 'true'
 os.environ['OTEL_SDK_DISABLED'] = 'true'
 ```
 
+### العزل عن إعداد OpenTelemetry الخاص بك
+
+يعمل القياس عن بُعد الخاص بـ CrewAI على `TracerProvider` خاص به ولا يسجل نفسه
+أبدًا كمزوّد عام. هذا يفصل الاتجاهين:
+
+- لا تُرسَل أبدًا إلى CrewAI الامتدادات (spans) الصادرة عن المكتبات الأخرى
+  المزوّدة بأدوات القياس في عمليتك — أطر الويب، وعملاء قواعد البيانات،
+  وعملاء HTTP.
+- لا تُرسَل امتدادات القياس عن بُعد الخاصة بـ CrewAI إلى نظام المراقبة لديك، لذا
+  لن تظهر في Langfuse أو Braintrust أو Phoenix أو أي مُجمِّع آخر تقوم بإعداده.
+
+لا تتأثر تكاملات المراقبة: فهي تقيس CrewAI عبر مزوّد التتبع الخاص بها، وهو
+مستقل عن المزوّد الموصوف هنا.
+
 ### شرح البيانات:
 | افتراضي | البيانات                                      | السبب والتفاصيل                                                                                                       |
 |:----------|:------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------|
@@ -45,7 +59,10 @@ os.environ['OTEL_SDK_DISABLED'] = 'true'
 | نعم       | بيانات تنفيذ الاختبار | تشمل: مفتاح ومعرّف الطاقم المُولّد عشوائياً، عدد التكرارات، اسم النموذج المستخدم، درجة الجودة (عدد عشري)، وقت التنفيذ (بالثواني). كلها غير شخصية. |
 | نعم       | بيانات دورة حياة المهمة | تشمل: أوقات الإنشاء وبدء/انتهاء التنفيذ، معرّفات الطاقم والمهمة. مخزنة كنطاقات مع طوابع زمنية. لا بيانات شخصية. |
 | نعم       | سمات LLM | تشمل: الاسم، model_name، model، top_k، temperature، واسم فئة LLM. كلها بيانات تقنية غير شخصية. |
-| نعم       | محاولة نشر الطاقم باستخدام CLI الخاص بـ CrewAI | تشمل: حقيقة إجراء النشر ومعرّف الطاقم، وما إذا كان يحاول سحب السجلات، لا بيانات أخرى. |
+| نعم       | محاولة نشر الطاقم باستخدام CLI الخاص بـ CrewAI | تشمل: حقيقة إجراء النشر ومعرّف الطاقم، وما إذا كان يحاول سحب السجلات، وما إذا بدأ النشر من أمر CLI أو من واجهة التشغيل TUI. لا تُسجَّل محتويات المشروع أو الطاقم. لا توجد بيانات شخصية. |
+| نعم       | بيئة التنفيذ | تشمل: مساعد البرمجة بالذكاء الاصطناعي الذي يشغّل العملية إن وُجد (واحد من قائمة ثابتة مثل `claude_code` أو `codex` أو `cursor` أو `unknown`)، ومكان تشغيل العملية (واحد من قائمة ثابتة مثل `ci` أو `container` أو `serverless` أو `interactive`)، و`project_id` من ملف `pyproject.toml` عند ضبطه. يتحقق الاكتشاف فقط مما إذا كانت متغيرات البيئة المعروفة مضبوطة، ولا يقرأ قيمها أبدًا. لا بيانات شخصية. |
+| نعم       | إشارات دورة حياة التدفق | تشمل: بدء التدفق، وما إذا اكتمل أو فشل، وما إذا فشلت إحدى طرقه، وما إذا توقف مؤقتًا لانتظار إدخال أو ملاحظات بشرية، وما إذا كان البدء تشغيلًا مستأنفًا، وما إذا فشل دور محادثة، ومدة تشغيل التدفق، وما إذا كان التدفق مما تشغّله CrewAI داخليًا أو مما كتبته أنت. ويُسجَّل اسم التدفق، كما هو الحال بالفعل لإنشاء التدفق وتنفيذه. وعند فشل تدفق أو إحدى طرقه، يُسجَّل **اسم فئة** الاستثناء (مثل `TimeoutError`) لتشخيص الأعطال — ولا تُسجَّل أبدًا رسالة الخطأ، التي قد تحتوي على مطالبات أو مخرجات النموذج أو مسارات ملفات أو بيانات اعتماد. ولا تُسجَّل أبدًا أسماء الطرق أو حالة التدفق. لا توجد بيانات شخصية. |
+| نعم       | إشارة مشاركة التتبع | تشمل: نجاح مشاركة دفعة من عمليات التتبع مع CrewAI AMP، وما إذا تمت المشاركة بشكل مجهول (قبل إنشاء حساب) أو مرتبطة بحسابك. ومثل كل span، تحمل أيضًا سمات بيئة التنفيذ الموضحة أعلاه (`project_id` عند تكوينه، ومساعد البرمجة، وبيئة التشغيل). يصف هذا الصف بيانات القياس عن بُعد الخاصة بالمشاركة فقط — وليس محتويات التتبع أو الوصول الذي تمنحه روابط التتبع المشتركة. لا تُسجَّل محتويات التتبع أو المدخلات أو المخرجات في هذه الإشارة. قبل مشاركة التتبعات، راجع الأسرار والبيانات الشخصية وإعدادات التنقيح والاحتفاظ في AMP. |
 | لا        | بيانات الوكيل الموسّعة | تشمل: وصف الهدف، نص الخلفية، معرّف ملف موجهات i18n. يجب على المستخدمين التأكد من عدم تضمين معلومات شخصية في حقول النص. |
 | لا        | معلومات المهمة التفصيلية | تشمل: وصف المهمة، وصف المخرجات المتوقعة، مراجع السياق. يجب على المستخدمين التأكد من عدم تضمين معلومات شخصية في هذه الحقول. |
 | لا        | معلومات البيئة | تشمل: المنصة، الإصدار، النظام، الإصدار، وعدد وحدات المعالجة المركزية. مثال: 'Windows 10'، 'x86_64'. لا بيانات شخصية. |

docs/edge/en/changelog.mdx

@@ -4,6 +4,133 @@ description: "Product updates, improvements, and bug fixes for CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="Aug 13, 2026">
+  ## v1.15.16
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.16)
+
+  ## What's Changed
+
+  ### Features
+  - Introduce execution context management with UUID support
+  - Record what kind of exception ended a flow
+  - Record when a trace batch is shared with AMP
+  - Count deployments from any origin and record where they started
+
+  ### Bug Fixes
+  - Record the running release on every emitted span
+  - Fix MySQL search table name validation
+  - Stop a failed turn from marking the next one as failed
+
+  ### Documentation
+  - Add Frontend guides for CopilotKit and AG-UI
+
+  ## Contributors
+
+  @joaomdmoura, @lorenzejay, @ranst91, @theCyberTech
+
+</Update>
+
+<Update label="Aug 11, 2026">
+  ## v1.15.15
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.15)
+
+  ## What's Changed
+
+  ### Features
+  - Report flow outcome, duration, and human-in-the-loop signals.
+
+  ### Bug Fixes
+  - Emit FlowStartedEvent when a boundary hook aborts the flow.
+  - Scope span export to our own tracer provider.
+  - Bump torch to version 2.13.0 to address security vulnerability.
+  - Bump gitpython to version 3.1.58 in crewai-tools[github].
+
+  ### Refactoring
+  - Update date injection functionality in agents.
+  - Standardize CLI flags to kebab-case.
+
+  ### Documentation
+  - Snapshot and changelog for v1.15.14.
+
+  ## Contributors
+
+  @Vidit-Ostwal, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech
+
+</Update>
+
+<Update label="Aug 08, 2026">
+  ## v1.15.14
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.14)
+
+  ## What's Changed
+
+  ### Features
+  - Split runtime context from coding agent and add project ID
+
+  ### Documentation
+  - Update snapshot and changelog for v1.15.13
+
+  ## Contributors
+
+  @joaomdmoura
+
+</Update>
+
+<Update label="Aug 07, 2026">
+  ## v1.15.13
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.13)
+
+  ## What's Changed
+
+  ### Bug Fixes
+  - Fix preservation of provider on LiteLLM-routed models.
+  - Harden brittle LLM event-bus mocks.
+  - Fix underreporting of Anthropic cache token usage.
+  - Bump h2 to version 4.4.1 to address security vulnerability GHSA-6hr6-w5qg-qmwg.
+
+  ### Documentation
+  - Add DOCS_TRANSLATIONS workflow for locale synchronization.
+  - Fix broken README links, table of contents, and contribution guidance.
+  - Snapshot and changelog for version 1.15.12.
+
+  ## Contributors
+
+  @Vidit-Ostwal, @joaomdmoura, @lucasgomide, @theCyberTech
+
+</Update>
+
+<Update label="Aug 05, 2026">
+  ## v1.15.12
+
+  [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.12)
+
+  ## What's Changed
+
+  ### Features
+  - Bump Flow canary on release
+  - Add URLReadTool for reading arbitrary URLs
+  - Add app metadata to platform action tools
+  - Unify scaffolding under `crewai create <resource>`
+
+  ### Bug Fixes
+  - Clarify conversational route/handler name collision errors
+
+  ### Documentation
+  - Update scaffold AGENTS.md for unified create CLI
+
+  ### Breaking Changes
+  - None
+
+  ## Contributors
+
+  @Vidit-Ostwal, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech
+
+</Update>
+
 <Update label="Aug 04, 2026">
   ## v1.15.11
 

docs/edge/en/concepts/agents.mdx

@@ -61,7 +61,7 @@ The Visual Agent Builder enables:
 | **Respect Context Window** _(optional)_ | `respect_context_window` | `bool`                                | Keep messages under context window size by summarizing. Default is True.                                 |
 | **Code Execution Mode** _(optional)_    | `code_execution_mode`    | `Literal["safe", "unsafe"]`           | Mode for code execution: 'safe' (using Docker) or 'unsafe' (direct). Default is 'safe'.                  |
 | **Multimodal** _(optional)_             | `multimodal`             | `bool`                                | Whether the agent supports multimodal capabilities. Default is False.                                    |
-| **Inject Date** _(optional)_            | `inject_date`            | `bool`                                | Whether to automatically inject the current date into tasks. Default is False.                           |
+| **Inject Date** _(optional)_            | `inject_date`            | `bool`                                | Whether to automatically inject the current date into the agent's prompt. Default is False.              |
 | **Date Format** _(optional)_            | `date_format`            | `str`                                 | Format string for date when inject_date is enabled. Default is "%Y-%m-%d" (ISO format).                  |
 | **Reasoning** _(optional)_              | `reasoning`              | `bool`                                | Whether the agent should reflect and create a plan before executing a task. Default is False.            |
 | **Max Reasoning Attempts** _(optional)_ | `max_reasoning_attempts` | `Optional[int]`                       | Maximum number of reasoning attempts before executing the task. If None, will try until ready.           |
@@ -236,7 +236,7 @@ strategic_agent = Agent(
     role="Market Analyst",
     goal="Track market movements with precise date references and strategic planning",
     backstory="Expert in time-sensitive financial analysis and strategic reporting",
-    inject_date=True,  # Automatically inject current date into tasks
+    inject_date=True,  # Automatically inject current date into the prompt
     date_format="%B %d, %Y",  # Format as "May 21, 2025"
     reasoning=True,  # Enable strategic planning
     max_reasoning_attempts=2,  # Limit planning iterations
@@ -303,7 +303,7 @@ multimodal_agent = Agent(
 
 - `multimodal`: Enable multimodal capabilities for processing text and visual content
 - `reasoning`: Enable agent to reflect and create plans before executing tasks
-- `inject_date`: Automatically inject current date into task descriptions
+- `inject_date`: Automatically inject current date into the agents prompt
 
 #### Templates
 

docs/edge/en/concepts/cli.mdx

@@ -103,6 +103,16 @@ These older commands still work but print a yellow deprecation warning. Prefer t
 
 Lifecycle commands are unchanged — for example `crewai tool install`, `crewai skill publish`, and `crewai template list` stay under their resource groups.
 
+#### Deprecated flag aliases
+
+These older snake_case flags still work but are hidden from `--help`. Prefer the kebab-case forms documented in each command section below.
+
+| Deprecated | Use instead |
+| :--- | :--- |
+| `--skip_provider` (on `crewai create crew`) | `--skip-provider` |
+| `--n_iterations` (on `crewai train`, `crewai test`) | `--n-iterations` |
+| `--task_id` (on `crewai replay`) | `--task-id` |
+
 ### 2. Version
 
 Show the installed version of CrewAI.
@@ -128,7 +138,7 @@ Train the crew for a specified number of iterations.
 crewai train [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: Number of iterations to train the crew (default: 5)
+- `-n, --n-iterations INTEGER`: Number of iterations to train the crew (default: 5)
 - `-f, --filename TEXT`: Path to a custom file for training (default: "trained_agents_data.pkl")
 
 Example:
@@ -145,7 +155,7 @@ Replay the crew execution from a specific task.
 crewai replay [OPTIONS]
 ```
 
-- `-t, --task_id TEXT`: Replay the crew from this task ID, including all subsequent tasks
+- `-t, --task-id TEXT`: Replay the crew from this task ID, including all subsequent tasks
 
 Example:
 
@@ -192,7 +202,7 @@ Test the crew and evaluate the results.
 crewai test [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: Number of iterations to test the crew (default: 3)
+- `-n, --n-iterations INTEGER`: Number of iterations to test the crew (default: 3)
 - `-m, --model TEXT`: LLM Model to run the tests on the Crew (default: "gpt-4o-mini")
 
 Example:

docs/edge/en/concepts/crews.mdx

@@ -322,6 +322,8 @@ Caches can be employed to store the results of tools' execution, making the proc
 
 After the crew execution, you can access the `usage_metrics` attribute to view the language model (LLM) usage metrics for all tasks executed by the crew. This provides insights into operational efficiency and areas for improvement.
 
+`total_tokens` is the billed total (`prompt_tokens + completion_tokens`). Breakdown fields such as `cached_prompt_tokens` and `cache_creation_tokens` describe subsets already included in those totals and are not added on top of `total_tokens`. See the **UsageMetrics field semantics** section in the Flows concept documentation for the full contract.
+
 ```python Code
 # Access the crew's usage metrics
 crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])

docs/edge/en/concepts/flows.mdx

@@ -267,7 +267,27 @@ print(flow.usage_metrics)
   execution.
 </Note>
 
-Each entry in the returned [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) is the sum across all LLM calls made within a single `flow.kickoff()` invocation. Counters reset on the next `kickoff()` call (or on each iteration of `kickoff_for_each`), so successive runs don't double-count. The property is safe to read at any point after `kickoff()` completes; reading it during execution returns the partial total accumulated so far.
+### UsageMetrics field semantics
+
+The returned [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) object uses a provider-neutral contract:
+
+| Field | Meaning |
+| --- | --- |
+| `total_tokens` | Billed total: `prompt_tokens + completion_tokens` |
+| `prompt_tokens` | Full input/prompt tokens billed for the request |
+| `completion_tokens` | Output/completion tokens billed for the request |
+| `cached_prompt_tokens` | Cache-read subset of prompt tokens (breakdown only) |
+| `cache_creation_tokens` | Cache-write subset of prompt tokens (breakdown only, Anthropic) |
+| `reasoning_tokens` | Reasoning/thinking subset where the provider reports it separately (breakdown only) |
+| `successful_requests` | Number of LLM calls aggregated |
+
+Breakdown fields such as `cached_prompt_tokens`, `cache_creation_tokens`, and
+`reasoning_tokens` are **not** added on top of `total_tokens` — they describe
+portions already included in `prompt_tokens` or `completion_tokens`.
+
+For Anthropic, cache read and cache write counters are folded into `prompt_tokens`, so cached workloads are fully reflected in `total_tokens`. OpenAI-style providers already include cached input inside `prompt_tokens`; CrewAI surfaces the cached portion separately for visibility.
+
+Each entry in the returned `UsageMetrics` is the sum across all LLM calls made within a single `flow.kickoff()` invocation. Counters reset on the next `kickoff()` call (or on each iteration of `kickoff_for_each`), so successive runs don't double-count. The property is safe to read at any point after `kickoff()` completes; reading it during execution returns the partial total accumulated so far.
 
 ## Flow State Management
 

docs/edge/en/concepts/llms.mdx

@@ -418,6 +418,27 @@ In this section, you'll find detailed examples that help you select, configure,
     - Token usage tracking
     - Multi-turn tool use conversations
 
+    **Token usage and prompt caching:**
+
+    Anthropic reports billed input in separate counters — `input_tokens` (uncached),
+    `cache_read_input_tokens`, and `cache_creation_input_tokens`. CrewAI folds all
+    three into `prompt_tokens` (and native `input_tokens` in provider responses) so
+    `total_tokens` reflects full billed usage on cached workloads.
+
+    `cached_prompt_tokens` records the cache-read portion as a breakdown only; it is
+    already included in `prompt_tokens` and must not be added again to
+    `total_tokens`. `cache_creation_tokens` records cache writes the same way.
+
+    ```python Code
+    usage = llm.get_token_usage_summary()
+    # total_tokens == prompt_tokens + completion_tokens
+    # prompt_tokens includes cache read + cache write for Anthropic
+    ```
+
+    See the **UsageMetrics field semantics** section in the Flows concept
+    documentation for the provider-neutral contract used by `crew.usage_metrics`
+    and `flow.usage_metrics`.
+
     **Important Notes:**
     - `max_tokens` is a **required** parameter for all Anthropic models
     - Claude uses `stop_sequences` instead of `stop`

docs/edge/en/concepts/testing.mdx

@@ -20,7 +20,7 @@ crewai test
 If you want to run more iterations or use a different model, you can specify the parameters like this:
 
 ```bash
-crewai test --n_iterations 5 --model gpt-4o
+crewai test --n-iterations 5 --model gpt-4o
 ```
 
 or using the short forms:
@@ -29,6 +29,11 @@ or using the short forms:
 crewai test -n 5 -m gpt-4o
 ```
 
+<Note>
+  The older `--n_iterations` flag still works but is deprecated and hidden from
+  `--help`. Use `--n-iterations` (or `-n`) instead.
+</Note>
+
 When you run the `crewai test` command, the crew will be executed for the specified number of iterations, and the performance metrics will be displayed at the end of the run.
 
 A table of scores at the end will show the performance of the crew in terms of the following metrics:

docs/edge/en/guides/flows/conversational-flows.mdx

@@ -376,6 +376,27 @@ def handle_internet_search(self) -> str:
     ...
 ```
 
+### Naming handlers
+
+The string in `@listen("…")` is a **router route label** (an event name), not the Python method name. Route labels and method completion events share one trigger namespace, so naming a handler the same as its route causes the handler to re-trigger itself in a loop.
+
+Use a different method name — the docs examples use a `handle_*` prefix:
+
+```python
+@listen("create_video")
+def handle_create_video(self) -> str:
+    """User wants a new video."""
+    ...
+```
+
+Do **not** mirror the route label on the method:
+
+```python
+@listen("create_video")
+def create_video(self) -> str:  # rejected at flow instantiation
+    ...
+```
+
 …and the router LLM sees:
 
 ```

docs/edge/en/guides/frontend/a2ui.mdx

@@ -0,0 +1,127 @@
+---
+title: A2UI
+description: The declarative tier of generative UI — the agent assembles a surface from a catalog of components you own.
+icon: table-cells
+mode: "wide"
+---
+
+## The agent assembles the UI
+
+[Tool-based rendering](/edge/en/guides/frontend/tool-based-generative-ui) maps one tool to one component: the agent picks a component, you draw it. A2UI is the **declarative** tier of the [generative-UI spectrum](/edge/en/guides/frontend/generative-ui#declarative) — instead of picking a single component, the agent **assembles a surface** by combining building blocks from a catalog you define.
+
+You still own the components. The agent can only use what is in your catalog, so it can never render something you did not ship. What the agent decides is the **layout and the data** — how those building blocks come together into a panel, and what goes in them.
+
+<Note>
+A2UI works with [Flows](/en/concepts/flows). Both modes below — dynamic and fixed-schema — run as Flows served over AG-UI, exactly like the rest of this section.
+</Note>
+
+## The catalog (same for every mode)
+
+The frontend wiring is identical no matter which backend mode you use: you register a **catalog** on the `<CopilotKit>` provider with the `a2ui` prop.
+
+```tsx
+import { CopilotKit } from "@copilotkit/react-core";
+import { catalog } from "@/a2ui-catalog";
+
+<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}>
+  {/* ... */}
+</CopilotKit>
+```
+
+The catalog is your set of React components keyed by a catalog id — a `FlightCard`, a `HotelCard`, a `Chart`, whatever your app needs. The agent references catalog ids; CopilotKit paints your components with the data the agent supplies.
+
+<Note>
+Authoring the catalog itself — the id schema, prop mapping, and composition rules — is deeper than this page covers. See the [CopilotKit A2UI docs](https://docs.copilotkit.ai) for the full authoring reference. Here we focus on the two backend modes and when to reach for each.
+</Note>
+
+## Two backend modes
+
+A2UI backends come in two shapes. In **dynamic** mode the agent designs the surface; in **fixed-schema** mode you pre-author the layout and the agent only fills in data.
+
+| Mode | Who designs the layout | Backend | Predictability |
+| --- | --- | --- | --- |
+| **[Dynamic](#dynamic)** | The agent, from the conversation | No A2UI tool — auto-injected | Novel layouts, LLM layout step |
+| **[Fixed-schema](#fixed-schema)** | You, up front | Backend tools return an envelope | Deterministic, no layout step |
+
+### Dynamic
+
+The Flow wires **no** A2UI tool. Enable A2UI on the runtime for this agent and it gains a `generate_a2ui` tool automatically. A sub-agent designs a surface from the conversation against your catalog, streams it to the frontend progressively, and self-heals invalid output through a validate-then-retry recovery pass. You write a normal agentic-chat Flow; the tool is injected for you.
+
+<Steps>
+
+<Step title="Register the catalog on the provider">
+
+Same as above — pass your catalog through the `a2ui` prop:
+
+```tsx
+<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}>
+  {/* ... */}
+</CopilotKit>
+```
+
+</Step>
+
+<Step title="Serve a normal Flow">
+
+Your backend is a plain agentic-chat Flow. You do not define an A2UI tool — the runtime injects `generate_a2ui` when A2UI is enabled for the agent, and the sub-agent invents the layout from the conversation.
+
+</Step>
+
+<Step title="Let the agent compose">
+
+When a turn calls for UI, the agent assembles a surface from your catalog, streams the components in as it designs them, and repairs any invalid output before it reaches the screen. Your registered components render in the layout the agent chose.
+
+</Step>
+
+</Steps>
+
+### Fixed-schema
+
+When you already know the layout and only the data changes per call, pre-author the surface and let the agent fill it. The Flow wires backend tools (for example `search_flights`, `search_hotels`). Each tool returns an **A2UI operations envelope** as its result — `createSurface` -> `updateComponents` -> `updateDataModel` — which the frontend paints. There is no sub-agent, no generation, and no recovery pass: the layout JSON is authored by you, and only the data varies.
+
+Install the toolkit that provides the envelope helpers:
+
+```bash
+pip install ag-ui-a2ui-toolkit
+```
+
+Build the envelope with the toolkit helpers and emit it as the tool result:
+
+```python
+from ag_ui_a2ui_toolkit import (
+    A2UI_OPERATIONS_KEY,
+    create_surface,
+    update_components,
+    update_data_model,
+)
+from ag_ui_crewai.sdk import copilotkit_emit_tool_result, copilotkit_stream
+```
+
+The tool assembles the `createSurface` -> `updateComponents` -> `updateDataModel` operations into an envelope keyed by `A2UI_OPERATIONS_KEY`, then hands it back with `copilotkit_emit_tool_result(...)`. Because the layout is fixed, the same tool always produces the same shape — only the values differ from call to call.
+
+## When to use which
+
+<CardGroup cols={2}>
+  <Card title="Dynamic" icon="wand-magic-sparkles">
+    The layout is not known ahead of time and you want the agent to compose novel surfaces from your primitives. You gain flexibility and pay for an LLM layout step.
+  </Card>
+  <Card title="Fixed-schema" icon="table-cells">
+    The layout is known and only the data varies. More predictable and deterministic — no generation, no recovery, no LLM in the layout path.
+  </Card>
+</CardGroup>
+
+Both modes share the same frontend: one catalog, registered once on the provider. Start with fixed-schema when your surfaces are stable, and reach for dynamic when you want the agent to design layouts you did not anticipate.
+
+## Related
+
+<CardGroup cols={3}>
+  <Card title="Generative UI" icon="wand-magic-sparkles" href="/edge/en/guides/frontend/generative-ui">
+    The full spectrum — A2UI is its declarative tier.
+  </Card>
+  <Card title="Tool-Based Generative UI" icon="puzzle-piece" href="/edge/en/guides/frontend/tool-based-generative-ui">
+    Map one tool to one component (controlled).
+  </Card>
+  <Card title="Agentic Generative UI" icon="list-check" href="/edge/en/guides/frontend/agentic-generative-ui">
+    Render live agent state (controlled).
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/agentic-generative-ui.mdx

@@ -0,0 +1,208 @@
+---
+title: Agentic Generative UI
+description: Render your CrewAI Flow's live state as UI that updates as the agent works through multi-step tasks.
+icon: list-check
+mode: "wide"
+---
+
+## Render the agent's live state
+
+Some work does not fit into a single tool call. A research task, a multi-step plan, a long-running job: the interesting thing to show the user is not one result, but *progress*. Agentic generative UI renders the agent's **state** and re-renders it every time that state changes.
+
+The pattern has two halves:
+
+1. Your Flow writes progress into its own state as it works.
+2. Your frontend reads that state with `useAgent` and paints it, re-rendering as the state streams in.
+
+The Flow's state reaches the frontend over AG-UI without you wiring up any transport. A state snapshot is emitted automatically at each step (method) boundary of the Flow, and you can push intermediate updates during a long-running step by calling `copilotkit_emit_state` explicitly. You subclass the state to add your own fields, update them in the Flow, and read them in React.
+
+<Note>
+State-driven rendering requires a **Flow** with custom state (`Flow[AgentState]`). Crews are chat-oriented and do not expose custom state this way, so with a Crew use [tool rendering](/edge/en/guides/frontend/tool-based-generative-ui) instead.
+</Note>
+
+## Build a live task planner
+
+This example builds a planner that breaks a request into about ten steps and streams them to the UI as a checklist. It assumes you already have a CrewAI server and a CopilotKit frontend wired up. If you do not, start with the [Frontend Overview](/edge/en/guides/frontend/overview).
+
+<Steps>
+
+<Step title="Add your own fields to the agent state">
+
+Subclass `CopilotKitState` to declare the state your UI needs. `CopilotKitState` already carries the conversation (`messages`); you add whatever else you want to render, here a list of task steps.
+
+```python
+from typing import List, Literal
+from pydantic import BaseModel, Field
+from ag_ui_crewai.sdk import CopilotKitState
+
+
+class TaskStep(BaseModel):
+    description: str
+    status: Literal["enabled", "disabled"]
+
+
+class AgentState(CopilotKitState):
+    steps: List[TaskStep] = Field(default_factory=list)
+```
+
+Everything on `AgentState` is included in the state snapshot the frontend receives. A snapshot is emitted automatically at each step boundary, so writing to `self.state` is enough for the UI to pick it up between steps. To update the UI *during* a long step, emit explicitly (shown below).
+
+</Step>
+
+<Step title="Write progress into state from the Flow">
+
+Type your Flow with the custom state (`Flow[AgentState]`) and let the model fill it in. Here the LLM calls a `generate_task_steps` tool; the streamed tool call lands in the conversation and the steps become visible in state.
+
+```python
+from crewai.flow.flow import Flow, start
+from litellm import acompletion
+from ag_ui_crewai.sdk import copilotkit_stream
+
+GENERATE_TASK_STEPS_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "generate_task_steps",
+        "description": "Break a task into about 10 short imperative steps.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "steps": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "description": {"type": "string"},
+                            "status": {"type": "string", "enum": ["enabled"]},
+                        },
+                        "required": ["description", "status"],
+                    },
+                },
+            },
+            "required": ["steps"],
+        },
+    },
+}
+
+
+class TaskPlannerFlow(Flow[AgentState]):
+    @start()
+    async def chat(self):
+        response = await copilotkit_stream(
+            await acompletion(
+                model="openai/gpt-4o",
+                messages=[
+                    {"role": "system", "content": "Plan the task the user asks for."},
+                    *self.state.messages,
+                ],
+                tools=[GENERATE_TASK_STEPS_TOOL],
+                parallel_tool_calls=False,
+                stream=True,
+            )
+        )
+        message = response.choices[0].message
+        self.state.messages.append(message)
+```
+
+Wrapping the LLM call in `copilotkit_stream` streams the assistant's tokens and tool call to the frontend as they are produced. The `steps` you write to `self.state` are sent in the state snapshot emitted at the end of this step.
+
+</Step>
+
+<Step title="Stream progress during a long step (optional)">
+
+The automatic snapshot fires at step boundaries. If a single step does substantial work and you want the checklist to fill in *as it happens*, emit intermediate state yourself with `copilotkit_emit_state`. Each call pushes the current state to the frontend immediately.
+
+```python
+from ag_ui_crewai.sdk import copilotkit_emit_state
+
+class TaskPlannerFlow(Flow[AgentState]):
+    @start()
+    async def execute(self):
+        for step in self.state.steps:
+            step.status = "disabled"          # mark done as you go
+            await copilotkit_emit_state(self.state)   # push update now
+            await do_work(step)
+```
+
+Import `copilotkit_emit_state` from `ag_ui_crewai.sdk`. It requires the CopilotKit SDK (`pip install "copilotkit[crewai]"`). Reach for it only when a step is long enough that waiting for its boundary snapshot would feel unresponsive.
+
+</Step>
+
+<Step title="Serve the Flow over AG-UI">
+
+Register the Flow exactly as any other, on its own path:
+
+```python
+# server.py
+from fastapi import FastAPI
+from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
+from my_agents.task_planner import TaskPlannerFlow
+
+app = FastAPI(title="CrewAI Agent Server")
+
+add_crewai_flow_fastapi_endpoint(
+    app=app,
+    flow=TaskPlannerFlow(),
+    path="/task_planner",
+)
+```
+
+See the [Frontend Overview](/edge/en/guides/frontend/overview) for the full server, runtime, and provider setup, and remember to register the agent (here `task_planner`) in your CopilotKit runtime route.
+
+</Step>
+
+<Step title="Read the live state in React">
+
+On the frontend, `useAgent` gives you the agent's live state. Subscribe to state changes so your component re-renders every time the Flow writes an update.
+
+```tsx
+"use client";
+import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2";
+
+function TaskPlan() {
+  const { agent } = useAgent({
+    agentId: "task_planner",
+    updates: [UseAgentUpdate.OnStateChanged],
+  });
+
+  const steps = agent?.state?.steps ?? [];
+
+  return (
+    <ul>
+      {steps.map((s, i) => (
+        <li key={i}>{s.description}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+`useAgent` returns `{ agent }`. A few things to know:
+
+- `agent.state` is the live Flow state. Its shape matches the fields you added to `AgentState`, so `agent.state.steps` is your list of task steps.
+- `agent.isRunning` tells you when the agent is actively working, useful for showing a spinner or disabling input.
+- `updates: [UseAgentUpdate.OnStateChanged]` re-renders the component whenever state changes, so the checklist fills in as the Flow streams its steps.
+
+</Step>
+
+</Steps>
+
+## Where this goes next
+
+Reading state is the foundation. Two guides build directly on it:
+
+- [Shared State](/edge/en/guides/frontend/shared-state) adds the other direction: editing the agent's state from the UI and having the Flow pick up the change.
+- [Predictive State](/edge/en/guides/frontend/predictive-state-updates) streams a tool's in-progress arguments into state so the UI reflects work before it is committed.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Shared State" icon="arrows-rotate" href="/edge/en/guides/frontend/shared-state">
+    Sync agent state and app UI in both directions.
+  </Card>
+  <Card title="Predictive State" icon="gauge-high" href="/edge/en/guides/frontend/predictive-state-updates">
+    Stream in-progress tool arguments into state.
+  </Card>
+  <Card title="Tool-Based Generative UI" icon="puzzle-piece" href="/edge/en/guides/frontend/tool-based-generative-ui">
+    Map agent tool calls to components.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/channels.mdx

@@ -0,0 +1,125 @@
+---
+title: Channels
+description: Run the same CrewAI agent as a chat bot on Slack and Discord with the CopilotKit Channels SDK.
+icon: slack
+mode: "wide"
+---
+
+## Meet your users where they already are
+
+The CrewAI agent you built in the [Overview](/edge/en/guides/frontend/overview) does not have to live behind a web app. The same Crew or Flow can run as a bot inside a messaging platform. No rebuild, no second copy of your agent logic: the agent stays exposed over the [AG-UI protocol](https://docs.ag-ui.com), and a bot process drives it.
+
+CopilotKit's [Channels SDK](https://docs.copilotkit.ai/reference/channels) provides that bot process. It ships a platform-agnostic engine plus per-platform adapters.
+
+## How it fits together
+
+Nothing about your agent server changes. It keeps serving your Crew or Flow over AG-UI exactly as in the Overview. What you add is a separate **bot process**: it connects to a platform adapter, listens for messages, and runs your agent when it is messaged. The reply streams back into the channel.
+
+```
+Slack / Discord  ──►  Channels bot process  ──►  CrewAI server (AG-UI)  ──►  Crew / Flow
+```
+
+Your agent server can keep serving the web frontend from the Overview at the same time. The web app and the bot are just two clients of one AG-UI endpoint.
+
+## Slack
+
+<Steps>
+
+<Step title="Install the Channels packages">
+
+```bash
+npm install @copilotkit/channels @copilotkit/channels-slack @ag-ui/crewai
+```
+
+</Step>
+
+<Step title="Create a Slack app and get tokens">
+
+Create an app in the Slack API dashboard for your workspace, enable Socket Mode, and grant it the message and event scopes it needs to read and post in channels. Then expose its tokens to the bot process:
+
+```bash
+export SLACK_BOT_TOKEN=xoxb-...   # bot user token
+export SLACK_APP_TOKEN=xapp-...   # app-level token (Socket Mode)
+```
+
+</Step>
+
+<Step title="Point the bot at your CrewAI agent">
+
+`createBot` wires a Slack adapter to your agent. The `agent` factory returns a `CrewAIAgent` pointed at the AG-UI path your server exposes (the same URL you registered in the runtime in the Overview).
+
+```ts
+// bot.ts
+import { createBot } from "@copilotkit/channels";
+import { slack, defaultSlackTools, defaultSlackContext } from "@copilotkit/channels-slack";
+import { CrewAIAgent } from "@ag-ui/crewai";
+
+const bot = createBot({
+  adapters: [
+    slack({
+      botToken: process.env.SLACK_BOT_TOKEN!, // xoxb-…
+      appToken: process.env.SLACK_APP_TOKEN!, // xapp-… (Socket Mode)
+    }),
+  ],
+  agent: (threadId) => new CrewAIAgent({ url: "http://localhost:8000/recipe" }),
+  tools: [...defaultSlackTools],
+  context: [...defaultSlackContext],
+});
+
+bot.start();
+```
+
+</Step>
+
+<Step title="Run the bot">
+
+Start the bot process alongside your agent server:
+
+```bash
+uvicorn server:app --port 8000   # terminal 1 — CrewAI agent server
+node bot.ts                       # terminal 2 — Slack bot
+```
+
+Message the bot in Slack and it runs your Crew or Flow, streaming the reply back into the thread.
+
+</Step>
+
+</Steps>
+
+<Note>
+Slack app scopes, Socket Mode setup, and the full adapter options are maintained by CopilotKit. Follow the [Slack channel reference](https://docs.copilotkit.ai/reference/channels/slack) together with Slack's own app setup guide for the authoritative steps.
+</Note>
+
+## Discord
+
+Discord uses the same `createBot` engine with the Discord adapter from `@copilotkit/channels-discord`:
+
+```ts
+import { createBot } from "@copilotkit/channels";
+import { discord } from "@copilotkit/channels-discord";
+import { CrewAIAgent } from "@ag-ui/crewai";
+
+const bot = createBot({
+  adapters: [discord({ token: process.env.DISCORD_BOT_TOKEN! })],
+  agent: (threadId) => new CrewAIAgent({ url: "http://localhost:8000/recipe" }),
+});
+
+bot.start();
+```
+
+See the [Discord channel reference](https://docs.copilotkit.ai/reference/channels/discord) for the exact adapter options and bot setup.
+
+## Platform support
+
+Slack and Discord have official Channels adapters (`@copilotkit/channels-slack`, `@copilotkit/channels-discord`). Microsoft Teams is available through CopilotKit's managed offering (currently waitlisted). Check the [Channels reference](https://docs.copilotkit.ai/reference/channels) for the current list before promising a platform.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Frontend Overview" icon="browser" href="/edge/en/guides/frontend/overview">
+    Serve your Crew or Flow over AG-UI — the foundation every channel builds on.
+  </Card>
+  <Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    Pause the agent to collect user approval or input mid-run.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/conversational-flows.mdx

@@ -0,0 +1,106 @@
+---
+title: Conversational Flows
+description: Serve native, session-aware CrewAI Flows over AG-UI with managed conversation state and full frontend parity.
+icon: comments
+mode: "wide"
+---
+
+## Three execution shapes, one bridge
+
+Behind the AG-UI bridge, a CrewAI backend can take one of three shapes. Knowing which one you are serving decides how you author the backend, not how you build the frontend.
+
+| Shape | What it is | How it is entered |
+| --- | --- | --- |
+| **Regular Flows** | Author-controlled `@start`/`@listen`/`@router` graphs. The default used throughout these guides. | `kickoff` / `astream` |
+| **Conversational Flows** | Native, session-aware, turn-based Flows with managed conversation state. | `stream_turn(message, session_id=...)` |
+| **Crews** | Closed autonomous task/agent loops. Basic chat only, a separate compatibility path. | Not the focus here. |
+
+Conversational Flows are a newer CrewAI capability, and an important thing to be clear about up front: **they are Flows, not Crews.** They now run at full regular-Flow feature parity. This page introduces them and shows how they fit the rest of the frontend guides.
+
+<Note>
+Reach for a Conversational Flow when you want native multi-turn conversation with CrewAI managing session state and history for you, rather than wiring turn and state handling into a regular Flow yourself. If you are new here, start with the [Frontend Overview](/edge/en/guides/frontend/overview) for the base server, runtime, and provider setup.
+</Note>
+
+## Register a Conversational Flow
+
+You register a Conversational Flow through the same endpoint helper as any other Flow, with one extra argument: `conversational=True`.
+
+```python
+# server.py
+from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
+
+add_crewai_flow_fastapi_endpoint(
+    app,
+    flow,
+    "/conversation",
+    conversational=True,
+)
+```
+
+Two requirements must hold for this to work:
+
+- The Flow instance declares `conversational = True`.
+- The Flow exposes CrewAI's public, callable `stream_turn(message, session_id=...)`.
+
+Detection is capability-based, not version-gated: the bridge checks that the Flow actually offers turn-based conversation, rather than keying off a version number.
+
+<Warning>
+If those requirements are not met, the request fails loudly with a `RUN_ERROR` (code `AGUI_CREWAI_CONVERSATIONAL_FLOW_UNSUPPORTED`). It never silently falls back to regular kickoff semantics, so you always know exactly which path you are on.
+</Warning>
+
+Authoring the Flow itself, including how you implement `stream_turn`, belongs to CrewAI's Conversational Flows documentation. This page stays at the registration and integration boundary.
+
+## Session and state
+
+Conversational Flows manage session state and history for you across turns. You do not re-thread history manually.
+
+- The AG-UI `threadId` **is** the CrewAI conversation `session_id`. The same thread is the same conversation.
+- Before each turn the bridge hydrates the Flow's state and conversation history, then calls `stream_turn`. CrewAI restores the stored session state, and a per-request overlay reapplies the incoming AG-UI state and history so the browser's latest edits win over stale storage.
+
+The result: from the backend author's side, each turn arrives already carrying the conversation's state, and CrewAI persists what you write for the next turn.
+
+## Frontend parity
+
+This is the point to hold onto: **Conversational Flows run through the same event pipeline as regular Flows, so the frontend code is identical.**
+
+There is no Conversational-Flow-specific frontend API. Every feature in these guides works exactly the same way with a Conversational Flow as it does with a regular Flow, using the same hooks and components:
+
+<CardGroup cols={2}>
+  <Card title="Tool-Based Generative UI" icon="puzzle-piece" href="/edge/en/guides/frontend/tool-based-generative-ui">
+    Map agent tool calls to your React components.
+  </Card>
+  <Card title="Agentic Generative UI" icon="list-check" href="/edge/en/guides/frontend/agentic-generative-ui">
+    Render the Flow's live state as it works.
+  </Card>
+  <Card title="Shared State" icon="arrows-rotate" href="/edge/en/guides/frontend/shared-state">
+    Keep agent state and app UI in two-way sync.
+  </Card>
+  <Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    Pause the agent for user approval or input mid-turn.
+  </Card>
+  <Card title="Predictive State" icon="gauge-high" href="/edge/en/guides/frontend/predictive-state-updates">
+    Stream in-progress tool arguments into state.
+  </Card>
+  <Card title="Reasoning" icon="brain" href="/edge/en/guides/frontend/reasoning">
+    Show the model's thinking in the chat.
+  </Card>
+  <Card title="A2UI" icon="table-cells" href="/edge/en/guides/frontend/a2ui">
+    Render agent-authored UI from a component catalog.
+  </Card>
+</CardGroup>
+
+The only difference is on the backend: how you author the Flow (turn-based `stream_turn` with managed session state) and the `conversational=True` registration. Once the endpoint is up, everything you already know about building the frontend applies unchanged.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Frontend Overview" icon="browser" href="/edge/en/guides/frontend/overview">
+    Wire a Crew or Flow to a Next.js frontend end to end.
+  </Card>
+  <Card title="Generative UI" icon="wand-magic-sparkles" href="/edge/en/guides/frontend/generative-ui">
+    Render tool calls and agent state as custom components.
+  </Card>
+  <Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    Gate agent actions behind user approval.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/frontend-actions.mdx

@@ -0,0 +1,121 @@
+---
+title: Frontend Actions
+description: Let your CrewAI agent call functions that run in the user's browser, from switching themes to navigating your app.
+icon: bolt
+mode: "wide"
+---
+
+## Let the agent act on the app
+
+A frontend action is a tool the agent calls that runs code in the browser instead of on the server. The model decides to invoke it; your handler switches the theme, navigates, highlights an element, or updates your app data; and the result flows back to the agent.
+
+It uses the same hook as tool-based generative UI, `useFrontendTool`. The difference is what you give it: a `handler` that runs code, instead of (or alongside) a `render` that draws UI.
+
+<Note>
+Frontend actions work with both Crews and Flows. Any agent that binds `copilotkit.actions` into its LLM call can invoke them.
+</Note>
+
+## Build a frontend action
+
+The example below lets the agent switch the app into dark mode on request.
+
+<Steps>
+
+<Step title="Register the action on the frontend">
+
+Call `useFrontendTool` with a `handler`. The handler runs in the browser when the agent invokes the tool, and the string it returns is fed back to the agent.
+
+```tsx
+"use client";
+import { useFrontendTool } from "@copilotkit/react-core/v2";
+import { z } from "zod";
+
+useFrontendTool({
+  agentId: "assistant",
+  name: "set_theme",
+  description: "Switch the app between light and dark mode.",
+  parameters: z.object({
+    theme: z.enum(["light", "dark"]),
+  }),
+  followUp: false,
+  handler: async ({ theme }) => {
+    document.documentElement.dataset.theme = theme; // runs in the browser
+    return `Theme set to ${theme}.`;
+  },
+});
+```
+
+The arguments:
+
+- **`name`** — the tool name the model calls (`set_theme`).
+- **`description`** — a short explanation of what the tool does. The model reads it to decide *when* to call the tool, so make it specific. Omitting it leaves the model guessing from the name alone.
+- **`parameters`** — a [zod](https://zod.dev) schema describing the arguments the model must supply. CopilotKit turns this into the tool's JSON schema and validates the incoming call.
+- **`handler(args)`** — runs in the browser with the parsed arguments. Do your side effect here (set the theme, navigate, update state). The string you return is handed back to the agent as the tool result.
+- **`followUp: false`** — stops the agent from taking another turn after the action runs. Leave it out (or set `true`) when you want the agent to respond after acting.
+
+</Step>
+
+<Step title="Bind the frontend tools on the backend">
+
+The agent can only call a tool it has been given. In your Flow, pass the frontend-registered tools into the LLM `tools` list with `*self.state.copilotkit.actions`.
+
+```python
+from crewai.flow.flow import Flow, start
+from litellm import acompletion
+from ag_ui_crewai.sdk import copilotkit_stream, CopilotKitState
+
+class AssistantFlow(Flow[CopilotKitState]):
+    @start()
+    async def chat(self):
+        response = await copilotkit_stream(
+            await acompletion(
+                model="openai/gpt-4o",
+                messages=[
+                    {"role": "system", "content": "Help the user. Use the tools available to control the app."},
+                    *self.state.messages,
+                ],
+                tools=[*self.state.copilotkit.actions],  # tools the frontend registered
+                parallel_tool_calls=False,
+                stream=True,
+            )
+        )
+        message = response.choices[0].message
+        self.state.messages.append(message)
+```
+
+`self.state.copilotkit.actions` holds the tool definitions for every frontend action registered with `useFrontendTool`. Spreading them into the LLM `tools` list is what makes the agent able to invoke browser-side actions. `copilotkit_stream` streams the response, including the tool call, back to the frontend, where CopilotKit runs the matching handler.
+
+</Step>
+
+<Step title="Serve the Flow">
+
+Expose the Flow over AG-UI with `add_crewai_flow_fastapi_endpoint(...)` and register it in the CopilotKit runtime, exactly as in the [Frontend Overview](/edge/en/guides/frontend/overview). Once both are running, asking the assistant to "switch to dark mode" triggers `set_theme`, and the page flips.
+
+</Step>
+
+</Steps>
+
+## Actions vs. generative UI
+
+`useFrontendTool` covers both ends of a spectrum, and you pick per tool:
+
+| You provide | What it does |
+| --- | --- |
+| **`handler`** | Runs code in the browser (a frontend action) |
+| **`render`** | Draws UI for the tool call (generative UI) |
+
+You can supply either one, or both. A `handler` with a `render` alongside it performs the action and draws UI while it runs. For render-only tools that just display the result of an agent action, see [Tool-Based Generative UI](/edge/en/guides/frontend/tool-based-generative-ui).
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Tool-Based Generative UI" icon="puzzle-piece" href="/edge/en/guides/frontend/tool-based-generative-ui">
+    Map agent tool calls to React components.
+  </Card>
+  <Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    Gate agent actions behind user approval.
+  </Card>
+  <Card title="Shared State" icon="arrows-rotate" href="/edge/en/guides/frontend/shared-state">
+    Keep agent state and your app UI in two-way sync.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/generative-ui.mdx

@@ -0,0 +1,107 @@
+---
+title: Generative UI
+description: Render your CrewAI agent's work as live React components, across the full spectrum from author-controlled to agent-invented UI.
+icon: wand-magic-sparkles
+mode: "wide"
+---
+
+## Beyond the chat bubble
+
+Generative UI means the agent's work shows up as real interface, not just text. When your Crew or Flow calls a tool, updates its state, or reasons about a problem, you decide what the user sees: a progress checklist, a recipe card, a chart, a whole assembled panel.
+
+CopilotKit renders generative UI along a **spectrum**, from fully author-controlled (you decide every pixel) to agent-invented (the agent assembles the surface):
+
+| Tier | Who decides the UI | CrewAI mechanism |
+| --- | --- | --- |
+| **[Controlled](#controlled)** | You — a fixed set of components the agent picks from | `useRenderTool`, `useAgent`, reasoning |
+| **[Declarative](#declarative)** | The agent — assembles a surface from *your* component catalog | [A2UI](/edge/en/guides/frontend/a2ui) |
+| **[Open-ended](#open-ended)** | An external tool/server invents the surface | MCP tools |
+
+The tiers compose freely; a single app usually mixes them.
+
+## Controlled
+
+You own the components. The agent chooses which to show and with what data. This is the most predictable tier and where most apps start.
+
+### Tool rendering
+
+The agent calls a tool on the backend. You register a matching component on the frontend with `useRenderTool`, and CopilotKit renders it, streaming the arguments in as they arrive.
+
+```tsx
+"use client";
+import { useRenderTool } from "@copilotkit/react-core/v2";
+import { z } from "zod";
+
+useRenderTool({
+  name: "generate_recipe",
+  parameters: z.object({
+    title: z.string(),
+    ingredients: z.array(z.string()),
+  }),
+  render: ({ args }) => <RecipeCard title={args.title} ingredients={args.ingredients} />,
+});
+```
+
+<Note>
+`useRenderTool` renders a tool call. When a tool also needs to *run* code in the browser, use [`useFrontendTool`](/edge/en/guides/frontend/frontend-actions) (a `handler`, with optional `render`).
+</Note>
+
+See [Tool-Based Generative UI](/edge/en/guides/frontend/tool-based-generative-ui) for the full walkthrough, including progressive rendering as arguments stream, and [Backend Tool Rendering](/edge/en/guides/frontend/tool-based-generative-ui#backend-tools) for tools your Crew or Flow executes server-side.
+
+### State rendering
+
+Instead of reacting to a single tool call, render the agent's **state** as it changes. This is the right pattern for multi-step work: read the agent's working state with `useAgent` and paint it however you like.
+
+```tsx
+"use client";
+import { useAgent } from "@copilotkit/react-core/v2";
+
+function TaskProgress() {
+  const { agent } = useAgent({ agentId: "task_runner" });
+  const steps = agent?.state?.steps ?? [];
+  return <StepList steps={steps} />;
+}
+```
+
+See [Agentic Generative UI](/edge/en/guides/frontend/agentic-generative-ui) for streaming state from a Flow, and [Shared State](/edge/en/guides/frontend/shared-state) for editing that state from the UI.
+
+### Reasoning
+
+When the model reasons before answering, that thinking renders in the chat automatically. No component to write. See [Reasoning](/edge/en/guides/frontend/reasoning).
+
+## Declarative
+
+The agent goes beyond picking a component: it **assembles a surface** by combining building blocks from a catalog *you* define. You still own the components (the agent can only use what is in your catalog), but the layout is the agent's.
+
+This is [A2UI](/edge/en/guides/frontend/a2ui). You register a catalog on the provider:
+
+```tsx
+<CopilotKit runtimeUrl="/api/copilotkit" agent="assistant" a2ui={{ catalog }}>
+  {/* ... */}
+</CopilotKit>
+```
+
+The agent then builds surfaces from that catalog — either dynamically (it designs the layout from the conversation) or from a fixed schema your backend fills with data. See [A2UI](/edge/en/guides/frontend/a2ui) for both modes and error recovery.
+
+## Open-ended
+
+At the far end, the surface is invented outside your app entirely. For CrewAI this comes through **MCP**: tools served by an MCP server the agent connects to render as tool calls in the chat, the same way backend tools do. This is the least constrained and the least predictable tier.
+
+MCP tool calls surface as standard tool-call UI — render them with `useRenderTool` like any other tool. Full agent-invented "MCP App" surfaces are an emerging capability; see the [CopilotKit docs](https://docs.copilotkit.ai) for the current state.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Tool-Based Generative UI" icon="puzzle-piece" href="/edge/en/guides/frontend/tool-based-generative-ui">
+    Map agent tool calls to components (controlled).
+  </Card>
+  <Card title="Agentic Generative UI" icon="list-check" href="/edge/en/guides/frontend/agentic-generative-ui">
+    Render live agent state (controlled).
+  </Card>
+  <Card title="A2UI" icon="table-cells" href="/edge/en/guides/frontend/a2ui">
+    Let the agent assemble surfaces from your catalog (declarative).
+  </Card>
+  <Card title="Reasoning" icon="brain" href="/edge/en/guides/frontend/reasoning">
+    Render the agent's thinking.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/human-in-the-loop.mdx

@@ -0,0 +1,191 @@
+---
+title: Human-in-the-Loop
+description: Pause your CrewAI agent mid-run to collect a user decision, then resume the agent with their answer.
+icon: user-check
+mode: "wide"
+---
+
+## Put the user in the loop
+
+Some steps should not happen without a human saying yes. Human-in-the-loop pauses the agent mid-run, renders an interactive component in the frontend, and waits. The user makes a choice; the agent resumes with that choice and continues.
+
+The mechanism is a tool the frontend registers. When the model calls it, the run halts at that tool call until the user responds. Nothing happens automatically: the agent stays parked until `respond()` hands control back.
+
+In the example below, the agent proposes a list of task steps. The user enables or disables each step and confirms. The agent then continues, respecting exactly what the user approved.
+
+<Note>
+This pattern works with Flows. It relies on the Flow's chat loop re-entering after `respond()`: the returned value comes back as a tool result, and the agent's next turn acts on it.
+</Note>
+
+## Build it
+
+<Steps>
+
+<Step title="Bind the frontend actions into the model's tools">
+
+In your Flow, add the frontend-registered actions to the model's tool list with `*self.state.copilotkit.actions`. Those actions are the tools your frontend registered (via `useHumanInTheLoop`). Binding them lets the model call them; the run pauses at that tool call until the user responds.
+
+```python
+# human_in_the_loop_flow.py
+from crewai.flow.flow import Flow, start, router, listen
+from litellm import acompletion
+from ag_ui_crewai.sdk import copilotkit_stream, CopilotKitState
+
+
+class HumanInTheLoopFlow(Flow[CopilotKitState]):
+    @start()
+    @listen("route_follow_up")
+    async def start_flow(self):
+        pass
+
+    @router(start_flow)
+    async def chat(self):
+        system_prompt = (
+            "You perform tasks for the user. When asked to do a task, call the "
+            "tool the frontend provides so the user can approve or adjust the steps "
+            "before you continue."
+        )
+
+        response = await copilotkit_stream(
+            await acompletion(
+                model="openai/gpt-4o",
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    *self.state.messages,
+                ],
+                tools=[*self.state.copilotkit.actions],  # tools registered by the frontend
+                parallel_tool_calls=False,
+                stream=True,
+            )
+        )
+
+        message = response.choices[0].message
+        self.state.messages.append(message)
+        return "route_end"
+
+    @listen("route_end")
+    async def end(self):
+        pass
+```
+
+`CopilotKitState` carries the frontend-registered actions on `self.state.copilotkit.actions`. When the model calls one, the run pauses there. After the user responds, the returned value lands in `self.state.messages` as the tool result, and the Flow loops back through `chat` so the model can act on the decision.
+
+</Step>
+
+<Step title="Serve the Flow over AG-UI">
+
+Expose the Flow from your FastAPI server with `add_crewai_flow_fastapi_endpoint`, the same way as every other agent. See [Frontend Overview](/edge/en/guides/frontend/overview) for the full server, runtime, and provider setup.
+
+```python
+# server.py
+from fastapi import FastAPI
+from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
+from my_agents.human_in_the_loop_flow import HumanInTheLoopFlow
+
+app = FastAPI(title="CrewAI Agent Server")
+
+add_crewai_flow_fastapi_endpoint(
+    app=app,
+    flow=HumanInTheLoopFlow(),
+    path="/human_in_the_loop",
+)
+```
+
+</Step>
+
+<Step title="Register the interactive tool on the frontend">
+
+`useHumanInTheLoop` registers the tool the agent pauses on and gives you a `render` function to draw the interactive UI. When the agent calls the tool, your component appears; when the user acts, you call `respond()` to resume the agent.
+
+```tsx
+"use client";
+import { useHumanInTheLoop } from "@copilotkit/react-core/v2";
+import { z } from "zod";
+
+useHumanInTheLoop({
+  agentId: "human_in_the_loop",
+  name: "generate_task_steps",
+  parameters: z.object({
+    steps: z.array(
+      z.object({
+        description: z.string(),
+        status: z.enum(["enabled", "disabled", "executing"]),
+      })
+    ),
+  }),
+  render: ({ args, respond, status }) => (
+    <StepReview
+      steps={args.steps ?? []}
+      // `status === "executing"` means the agent is waiting for the user
+      waiting={status === "executing"}
+      onConfirm={(chosen) => respond?.(chosen)}
+    />
+  ),
+});
+```
+
+The `render` function receives:
+
+- **`args`** — the tool arguments the model produced (here, the proposed `steps`). These stream in as the model generates them.
+- **`status`** — the tool call's lifecycle. While it is `"executing"`, the agent is paused and waiting on the human.
+- **`respond(value)`** — resumes the agent with the user's decision. The agent's next turn sees the returned value and acts on it.
+
+</Step>
+
+<Step title="Let the user decide, then respond">
+
+Your component reads `args.steps`, lets the user toggle each one, and calls `respond()` with the final selection. That value is what the agent continues with.
+
+```tsx
+function StepReview({ steps, waiting, onConfirm }) {
+  const [choices, setChoices] = useState(steps);
+
+  const toggle = (i) =>
+    setChoices((prev) =>
+      prev.map((s, idx) =>
+        idx === i
+          ? { ...s, status: s.status === "enabled" ? "disabled" : "enabled" }
+          : s
+      )
+    );
+
+  return (
+    <div>
+      {choices.map((step, i) => (
+        <label key={i}>
+          <input
+            type="checkbox"
+            checked={step.status === "enabled"}
+            disabled={!waiting}
+            onChange={() => toggle(i)}
+          />
+          {step.description}
+        </label>
+      ))}
+      <button disabled={!waiting} onClick={() => onConfirm(choices)}>
+        Confirm
+      </button>
+    </div>
+  );
+}
+```
+
+Once the user clicks Confirm, `respond()` fires, the run resumes, and the Flow's `chat` step runs again with the user's choices in the message history.
+
+</Step>
+
+</Steps>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Frontend Actions" icon="bolt" href="/edge/en/guides/frontend/frontend-actions">
+    Let the agent call functions that run in the browser.
+  </Card>
+  <Card title="Shared State" icon="arrows-rotate" href="/edge/en/guides/frontend/shared-state">
+    Keep agent state and your app UI in two-way sync.
+  </Card>
+  <Card title="Agentic Generative UI" icon="list-check" href="/edge/en/guides/frontend/agentic-generative-ui">
+    Render live agent state as custom components.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/overview.mdx

@@ -0,0 +1,238 @@
+---
+title: Frontend Overview
+description: Build interactive user interfaces for your CrewAI agents with CopilotKit and the AG-UI protocol.
+icon: browser
+mode: "wide"
+---
+
+## Give your agents a user interface
+
+CrewAI runs your agents. [CopilotKit](https://copilotkit.ai) gives them a frontend. Together they let you build applications where users chat with a Crew or Flow, watch it work in real time, approve its decisions, and see its output rendered as live UI instead of walls of text.
+
+The two connect through the [AG-UI protocol](https://docs.ag-ui.com). The `ag-ui-crewai` package exposes any Crew or Flow as an AG-UI endpoint. CopilotKit's React hooks and components consume that endpoint. This unlocks experiences that go well beyond a chat box:
+
+<CardGroup cols={2}>
+  <Card title="Generative UI" icon="wand-magic-sparkles" href="/edge/en/guides/frontend/generative-ui">
+    Render agent tool calls and state as your own React components.
+  </Card>
+  <Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    Pause the agent to collect user approval or input mid-run.
+  </Card>
+  <Card title="Shared State" icon="arrows-rotate" href="/edge/en/guides/frontend/shared-state">
+    Keep agent state and your app UI in two-way sync.
+  </Card>
+  <Card title="Channels" icon="slack" href="/edge/en/guides/frontend/channels">
+    Run the same agent as a Slack, Discord, or Teams bot.
+  </Card>
+</CardGroup>
+
+This guide gets a Crew or Flow talking to a Next.js frontend end to end. The rest of the section builds on the app you set up here.
+
+## Architecture
+
+There are three pieces:
+
+1. **CrewAI agent server** — a Python process that serves your Crew or Flow over AG-UI (FastAPI + `ag-ui-crewai`).
+2. **CopilotKit runtime** — a Next.js route that registers your agent and proxies requests to it.
+3. **React frontend** — the `<CopilotKit>` provider plus chat and generative-UI components.
+
+```
+React app  ──►  CopilotKit runtime (/api/copilotkit)  ──►  CrewAI server (AG-UI)  ──►  Crew / Flow
+```
+
+<Note>
+This guide covers the **self-hosted** path: you run the CrewAI agent server yourself with `ag-ui-crewai`, and it works locally with no managed service. CopilotKit also offers a **managed** path (CopilotKit Cloud / Enterprise Intelligence) with hosted threads and an inspector — see the [CopilotKit CrewAI quickstart](https://docs.copilotkit.ai/crewai-crews/quickstart) if you want that instead. The frontend code in this section is the same either way; only how the agent is hosted and registered differs.
+</Note>
+
+<Note>
+CrewAI runs behind AG-UI in three shapes: regular **Flows** (used throughout these guides), **[Conversational Flows](/edge/en/guides/frontend/conversational-flows)** (native, session-aware, turn-based, at full feature parity), and **Crews** (basic chat). The frontend in this section is identical across them — only the backend authoring and registration differ.
+</Note>
+
+## Integration guide
+
+<Steps>
+
+<Step title="Serve your agent over AG-UI">
+
+Install the integration package into your CrewAI project:
+
+```bash
+pip install ag-ui-crewai
+```
+
+Expose your agent from a FastAPI app. Flows use `add_crewai_flow_fastapi_endpoint`; Crews use `add_crewai_crew_fastapi_endpoint`. You can register as many as you want, each on its own path.
+
+<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>
+
+Run it:
+
+```bash
+uvicorn server:app --port 8000
+```
+
+<Note>
+Set the environment variables for your LLM provider (for example `OPENAI_API_KEY`) before starting the server.
+</Note>
+
+</Step>
+
+<Step title="Create a Next.js app">
+
+If you do not have a frontend yet, scaffold one:
+
+```bash
+npx create-next-app@latest my-app
+cd my-app
+```
+
+Install CopilotKit and the CrewAI AG-UI client:
+
+```bash
+npm install @copilotkit/react-core @copilotkit/react-ui @copilotkit/runtime @ag-ui/crewai
+```
+
+</Step>
+
+<Step title="Add the CopilotKit runtime">
+
+Create a route that registers your CrewAI agent(s) with the CopilotKit runtime. Each agent points at a path on your Python server via `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="Wrap your app with the provider">
+
+Point `<CopilotKit>` at the runtime route and name the agent you registered.
+
+```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="Run it">
+
+Start both processes and open the app. Chatting in the sidebar now runs your Crew or Flow.
+
+```bash
+uvicorn server:app --port 8000   # terminal 1
+npm run dev                       # terminal 2
+```
+
+</Step>
+
+</Steps>
+
+## Chat UI options
+
+CopilotKit ships three interchangeable chat surfaces. Swap the component; the wiring is identical.
+
+<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>
+
+## Where to go next
+
+<CardGroup cols={2}>
+  <Card title="Generative UI" icon="wand-magic-sparkles" href="/edge/en/guides/frontend/generative-ui">
+    Render tool calls and agent state as custom components.
+  </Card>
+  <Card title="Frontend Actions" icon="bolt" href="/edge/en/guides/frontend/frontend-actions">
+    Let the agent call functions that run in the browser.
+  </Card>
+  <Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    Gate agent actions behind user approval.
+  </Card>
+  <Card title="Predictive State" icon="gauge-high" href="/edge/en/guides/frontend/predictive-state-updates">
+    Stream in-progress state to the UI as the agent works.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/predictive-state-updates.mdx

@@ -0,0 +1,142 @@
+---
+title: Predictive State Updates
+description: Stream an in-progress tool call's arguments into agent state so the UI updates optimistically while the agent is still generating.
+icon: gauge-high
+mode: "wide"
+---
+
+## Show the work as it happens
+
+Normally a tool call is atomic from the UI's point of view: the agent decides what to write, and your interface only sees the result once the call finishes. For a tool that produces a large document that means a long pause followed by everything snapping into place at once.
+
+Predictive state updates remove the wait. You project a streaming tool argument onto a field of the agent's state, so as the model generates the argument token by token, that state field fills in live. A document the agent is writing appears in the editor as it is typed, not after.
+
+<Note>
+Predictive state relies on a Flow with custom state (`Flow[AgentState]`). It projects a streaming tool argument onto a state field, so there is no equivalent for a bare Crew.
+</Note>
+
+## How it compares to Shared State
+
+Both patterns read the agent's state from the frontend, but they solve different problems:
+
+| Pattern | What it does |
+| --- | --- |
+| **Predictive state** | One-way. Streams an in-progress tool argument into a state field so the UI updates *during* generation, before the call completes. |
+| **[Shared State](/edge/en/guides/frontend/shared-state)** | Two-way. The UI reads *and writes* the agent's committed state, keeping app and agent in sync across turns. |
+
+Reach for predictive state when you want an optimistic, in-flight preview of what the agent is producing. Reach for [Shared State](/edge/en/guides/frontend/shared-state) when the user needs to edit that state back.
+
+## Walkthrough
+
+This assumes you already have a Crew or Flow served over AG-UI and a CopilotKit frontend wired up. If not, start with the [Frontend Overview](/edge/en/guides/frontend/overview).
+
+<Steps>
+
+<Step title="Define a Flow with custom state">
+
+Predictive state projects a tool argument onto a state field, so your Flow needs a typed state field to receive it. Add the field you want to stream into to your `CopilotKitState` subclass.
+
+```python
+from typing import Optional
+from crewai.flow.flow import Flow, start, router, listen
+from litellm import acompletion
+from ag_ui_crewai.sdk import copilotkit_stream, copilotkit_predict_state, CopilotKitState
+
+WRITE_DOCUMENT_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "write_document",
+        "description": "Write the full document in markdown.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "document": {"type": "string", "description": "The document to write"},
+            },
+        },
+    },
+}
+
+class AgentState(CopilotKitState):
+    document: Optional[str] = None
+
+class DocumentFlow(Flow[AgentState]):
+    @start()
+    @listen("route_follow_up")
+    async def start_flow(self):
+        pass
+```
+
+</Step>
+
+<Step title="Map a state field to a tool argument">
+
+Call `copilotkit_predict_state` **before** you start streaming the completion. It tells the runtime to project the named tool argument onto the named state field: as the `write_document` call streams its `document` argument, the `document` state field updates live.
+
+```python
+    @router(start_flow)
+    async def chat(self):
+        # Map the `document` state field to the `document` argument of write_document.
+        # As the tool call streams, the state field updates live.
+        await copilotkit_predict_state({
+            "document": {"tool_name": "write_document", "tool_argument": "document"},
+        })
+
+        response = await copilotkit_stream(
+            await acompletion(
+                model="openai/gpt-4o",
+                messages=[
+                    {"role": "system", "content": "Write and edit the document with write_document."},
+                    *self.state.messages,
+                ],
+                tools=[*self.state.copilotkit.actions, WRITE_DOCUMENT_TOOL],
+                parallel_tool_calls=False,
+                stream=True,
+            )
+        )
+        message = response.choices[0].message
+        self.state.messages.append(message)
+```
+
+The key is `copilotkit_predict_state({ "<state_field>": {"tool_name": ..., "tool_argument": ...} })`. Without it, the frontend would only see `document` once the tool call completed. With it, the partial argument streams onto the field while the agent is still generating.
+
+Serve the Flow with `add_crewai_flow_fastapi_endpoint(...)` as shown in the [Frontend Overview](/edge/en/guides/frontend/overview).
+
+</Step>
+
+<Step title="Read the predicted state on the frontend">
+
+On the frontend, read the field with `useAgent` and subscribe to state changes. Because the backend is projecting the streaming argument onto `document`, this component re-renders as the agent types.
+
+```tsx
+"use client";
+import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2";
+
+function DocumentView() {
+  const { agent } = useAgent({
+    agentId: "document",
+    updates: [UseAgentUpdate.OnStateChanged],
+  });
+  const document = (agent?.state as { document?: string })?.document ?? "";
+  return <article>{document}</article>; // updates as the agent types
+}
+```
+
+The `document` field fills in progressively as the agent generates the `write_document` call, so the editor updates in real time rather than snapping in at the end.
+
+</Step>
+
+</Steps>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Shared State" icon="arrows-rotate" href="/edge/en/guides/frontend/shared-state">
+    Read and write the agent's state two-way.
+  </Card>
+  <Card title="Agentic Generative UI" icon="list-check" href="/edge/en/guides/frontend/agentic-generative-ui">
+    Render live agent state as it changes.
+  </Card>
+  <Card title="Tool-Based Generative UI" icon="puzzle-piece" href="/edge/en/guides/frontend/tool-based-generative-ui">
+    Map agent tool calls to components.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/reasoning.mdx

@@ -0,0 +1,68 @@
+---
+title: Reasoning
+description: Show the model's thinking in the chat automatically, with no component to build.
+icon: brain
+mode: "wide"
+---
+
+## Thinking, rendered for free
+
+When a reasoning-capable model thinks before it answers, CopilotKit renders that thinking right in the chat. This is the simplest generative-UI pattern in the whole section: there is nothing to build. No hook, no component, no props. Use a reasoning-capable model, keep the streaming wrapper your Flows already have, and the chat surface from the [Overview](/edge/en/guides/frontend/overview) does the rest.
+
+## Use a reasoning-capable model
+
+Reasoning is surfaced automatically by `copilotkit_stream`, which every Flow example already wraps the model call in. The bridge reads the model's reasoning deltas and emits them to the frontend. It is provider-agnostic and works over both of CrewAI's streaming transports, so the only thing you change is the model.
+
+```python
+# recipe_flow.py
+from crewai.flow.flow import Flow, start
+from ag_ui_crewai.sdk import copilotkit_stream, CopilotKitState
+from litellm import acompletion
+
+
+class RecipeFlow(Flow[CopilotKitState]):
+    @start()
+    async def chat(self):
+        response = await copilotkit_stream(
+            acompletion(
+                # any reasoning-capable model, e.g. deepseek-reasoner
+                model="deepseek/deepseek-reasoner",
+                messages=self.state.messages,
+                stream=True,
+            )
+        )
+        message = response.choices[0].message
+        self.state.messages.append(message)
+```
+
+Models that emit reasoning over the standard channel include DeepSeek `deepseek-reasoner`, Anthropic extended thinking (Claude), and Gemini thinking, among others. Swap the `model` for one of these and its thinking starts streaming through.
+
+This works the same for both Crews and Flows, since both run their model calls through `copilotkit_stream`.
+
+## Render it
+
+There is no frontend step. The `CopilotChat`, `CopilotSidebar`, or `CopilotPopup` surface you already mounted shows the reasoning as it streams, above the answer it produced.
+
+```tsx
+import { CopilotChat } from "@copilotkit/react-core/v2";
+
+<CopilotChat agentId="recipe" />
+```
+
+<Note>
+There is no `useReasoning` hook and no reasoning component to write. Reasoning is not something you wire up on the frontend; it renders automatically as long as the model emits it.
+</Note>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Generative UI" icon="wand-magic-sparkles" href="/edge/en/guides/frontend/generative-ui">
+    The full spectrum, from author-controlled to agent-invented UI.
+  </Card>
+  <Card title="Agentic Generative UI" icon="list-check" href="/edge/en/guides/frontend/agentic-generative-ui">
+    Render live agent state as the Flow works.
+  </Card>
+  <Card title="Frontend Overview" icon="browser" href="/edge/en/guides/frontend/overview">
+    Set up the chat surface and runtime.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/shared-state.mdx

@@ -0,0 +1,210 @@
+---
+title: Shared State
+description: Keep your CrewAI agent's state and your app's UI in two-way sync, so edits on either side flow to the other.
+icon: arrows-rotate
+mode: "wide"
+---
+
+## One state, both directions
+
+Shared state is a single state object that the agent and the UI both read and write. The agent updates it as it works and your React components render it live. When the user edits that same state in the UI, the change flows back so the agent sees it on its next turn.
+
+The classic example is a recipe: the agent drafts it, the user tweaks an ingredient or an instruction, and the agent picks up from the edited version. Neither side owns the state; they share it.
+
+<Note>
+Shared state relies on a Flow with custom state. Define an `AgentState` that subclasses `CopilotKitState` and type your Flow as `Flow[AgentState]`. Crews do not carry custom state, so this pattern is Flow-only.
+</Note>
+
+## How it works
+
+<Steps>
+
+<Step title="Define the shared state on your Flow">
+
+Subclass `CopilotKitState` so the agent keeps CopilotKit's message plumbing, then add your own fields. Here the shared field is `recipe`.
+
+```python
+# recipe_flow.py
+import json
+from typing import List, Optional
+from pydantic import BaseModel, Field
+from crewai.flow.flow import Flow, start, router, listen
+from litellm import acompletion
+from ag_ui_crewai.sdk import copilotkit_stream, CopilotKitState
+
+
+class Ingredient(BaseModel):
+    name: str
+    amount: str
+
+
+class Recipe(BaseModel):
+    title: str
+    ingredients: List[Ingredient] = Field(default_factory=list)
+    instructions: List[str] = Field(default_factory=list)
+
+
+class AgentState(CopilotKitState):
+    recipe: Optional[Recipe] = None
+```
+
+</Step>
+
+<Step title="Read and write the state from the agent">
+
+The agent reads the current state by dumping it into the system prompt, and writes it back by assigning to `self.state.recipe`. A `generate_recipe` tool lets the model return the updated recipe as structured arguments.
+
+```python
+GENERATE_RECIPE_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "generate_recipe",
+        "description": "Generate or modify the recipe.",
+        "parameters": {
+            "type": "object",
+            "properties": {"recipe": {"type": "object"}},
+            "required": ["recipe"],
+        },
+    },
+}
+
+
+class SharedStateFlow(Flow[AgentState]):
+    @start()
+    @listen("route_follow_up")
+    async def start_flow(self):
+        pass
+
+    @router(start_flow)
+    async def chat(self):
+        # The current shared state is visible to the model.
+        system_prompt = f"""You help the user build a recipe.
+        Current recipe: {self.state.model_dump_json(indent=2)}
+        Modify it by calling generate_recipe."""
+
+        response = await copilotkit_stream(
+            await acompletion(
+                model="openai/gpt-4o",
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    *self.state.messages,
+                ],
+                tools=[*self.state.copilotkit.actions, GENERATE_RECIPE_TOOL],
+                parallel_tool_calls=False,
+                stream=True,
+            )
+        )
+        message = response.choices[0].message
+        self.state.messages.append(message)
+
+        if message.tool_calls:
+            call = message.tool_calls[0]
+            if call.function.name == "generate_recipe":
+                args = json.loads(call.function.arguments)
+                self.state.recipe = Recipe(**args["recipe"])  # write to shared state
+                self.state.messages.append({
+                    "role": "tool",
+                    "content": "Recipe updated.",
+                    "tool_call_id": call.id,
+                })
+                return "route_follow_up"
+        return "route_end"
+
+    @listen("route_end")
+    async def end(self):
+        pass
+```
+
+Two things make this shared rather than one-way: dumping `self.state` into the prompt means the agent always works from the latest recipe (including edits the user made in the UI), and assigning `self.state.recipe` puts the new value into the state snapshot sent to connected clients at the end of the step. For updates during a long step, emit explicitly with `copilotkit_emit_state` (see [Agentic Generative UI](/edge/en/guides/frontend/agentic-generative-ui)).
+
+</Step>
+
+<Step title="Serve the Flow over AG-UI">
+
+Expose the Flow from your FastAPI app with `add_crewai_flow_fastapi_endpoint`, then register it in the CopilotKit runtime. See the [Frontend Overview](/edge/en/guides/frontend/overview) for the full server and runtime setup.
+
+```python
+# server.py
+from fastapi import FastAPI
+from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
+from recipe_flow import SharedStateFlow
+
+app = FastAPI(title="CrewAI Agent Server")
+
+add_crewai_flow_fastapi_endpoint(
+    app=app,
+    flow=SharedStateFlow(),
+    path="/shared_state",
+)
+```
+
+</Step>
+
+<Step title="Read and write the state from the UI">
+
+`useAgent` gives you both directions in one hook. Read the shared state off `agent.state`, and write it back with `agent.setState(...)`. Subscribe to `OnStateChanged` so your component re-renders whenever the agent updates the state.
+
+```tsx
+"use client";
+import { useAgent, UseAgentUpdate } from "@copilotkit/react-core/v2";
+
+function RecipeEditor() {
+  const { agent } = useAgent({
+    agentId: "shared_state",
+    updates: [UseAgentUpdate.OnStateChanged],
+  });
+
+  const state = agent?.state as { recipe?: Recipe } | undefined;
+  const isLoading = agent?.isRunning;
+
+  const recipe = state?.recipe;
+
+  // setState replaces the whole state object, so spread the current
+  // state and override only the field you changed. Passing just
+  // `{ recipe }` would drop messages and other runtime fields.
+  const updateRecipe = (patch: Partial<Recipe>) =>
+    agent?.setState({ ...(agent.state ?? {}), recipe: { ...(recipe ?? {}), ...patch } });
+
+  return (
+    <div>
+      <input
+        value={recipe?.title ?? ""}
+        disabled={isLoading}
+        onChange={(e) => updateRecipe({ title: e.target.value })}
+      />
+      {/* render inputs for ingredients and instructions the same way */}
+    </div>
+  );
+}
+```
+
+`agent.state` reads the shared state, `agent.setState(...)` writes it back so the agent sees the change on its next turn, and `agent.isRunning` reflects whether the agent is currently working.
+
+<Note>
+`setState` **replaces** the entire state object rather than merging. Always spread the current state (`{ ...agent.state, ... }`) and override only the fields you are changing, or you will drop the conversation and other runtime fields the agent depends on.
+</Note>
+
+</Step>
+
+</Steps>
+
+## The two-way loop
+
+Putting the pieces together, a single recipe object is kept in sync in both directions:
+
+- **Agent edits, UI updates.** The Flow assigns `self.state.recipe`, the new value ships in the step's state snapshot, and `OnStateChanged` re-renders your inputs.
+- **User edits, agent sees it.** A change in the UI calls `agent.setState(...)`, and because the Flow dumps `self.state` into its prompt, the agent works from the edited recipe on its next turn.
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Agentic Generative UI" icon="list-check" href="/edge/en/guides/frontend/agentic-generative-ui">
+    Render live agent state as it changes.
+  </Card>
+  <Card title="Predictive State" icon="gauge-high" href="/edge/en/guides/frontend/predictive-state-updates">
+    Stream in-progress state to the UI as the agent works.
+  </Card>
+  <Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    Pause the agent to collect user approval or input mid-run.
+  </Card>
+</CardGroup>

docs/edge/en/guides/frontend/tool-based-generative-ui.mdx

@@ -0,0 +1,235 @@
+---
+title: Tool-Based Generative UI
+description: Map a CrewAI agent's tool calls to React components and stream the arguments in as they arrive.
+icon: puzzle-piece
+mode: "wide"
+---
+
+## Render tool calls as components
+
+When your Crew or Flow calls a tool, you rarely want the raw arguments dumped into the chat. Tool-based generative UI maps each tool the agent calls to a React component you own. The agent decides *when* to call the tool; you decide what the user sees.
+
+Because CopilotKit streams the tool call to the frontend as the model generates it, the arguments fill in progressively. Your component can paint the moment the first field arrives and update as the rest stream in.
+
+This guide builds a haiku generator: the agent calls a `generate_haiku` tool, and the frontend renders each haiku as a card. It assumes you already have a Crew or Flow talking to a Next.js app. If not, start with the [Frontend Overview](/edge/en/guides/frontend/overview) for the full server, runtime, and provider setup.
+
+<Note>
+Tool rendering works with both Crews and Flows. The example below uses a Flow, but the frontend wiring is identical either way.
+</Note>
+
+## Walkthrough
+
+<Steps>
+
+<Step title="Define the tool on the backend">
+
+Declare the tool with a JSON schema and pass it to the model. The `copilotkit_stream` wrapper together with `stream=True` is what streams the tool call to the frontend as it is generated, one argument chunk at a time.
+
+```python
+# haiku_flow.py
+from crewai.flow.flow import Flow, start
+from litellm import acompletion
+from ag_ui_crewai.sdk import copilotkit_stream, CopilotKitState
+
+GENERATE_HAIKU_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "generate_haiku",
+        "description": "Generate a haiku in Japanese and its English translation",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "japanese": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Three lines in Japanese",
+                },
+                "english": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Three lines in English",
+                },
+            },
+            "required": ["japanese", "english"],
+        },
+    },
+}
+
+
+class HaikuFlow(Flow[CopilotKitState]):
+    @start()
+    async def chat(self):
+        system_prompt = "You help the user write haikus. Use the generate_haiku tool."
+
+        response = await copilotkit_stream(
+            await acompletion(
+                model="openai/gpt-4o",
+                messages=[
+                    {"role": "system", "content": system_prompt},
+                    *self.state.messages,
+                ],
+                tools=[GENERATE_HAIKU_TOOL],
+                parallel_tool_calls=False,
+                stream=True,
+            )
+        )
+
+        message = response.choices[0].message
+        self.state.messages.append(message)
+
+        if message.tool_calls:
+            self.state.messages.append({
+                "tool_call_id": message.tool_calls[0].id,
+                "role": "tool",
+                "content": "Haiku generated.",
+            })
+```
+
+The tool has no Python implementation. It exists only so the model emits a structured call the frontend can render. After the call, append a short tool result so the conversation stays well-formed for the next turn.
+
+</Step>
+
+<Step title="Serve the Flow over AG-UI">
+
+Expose the Flow from your FastAPI app on its own path:
+
+```python
+# server.py
+from fastapi import FastAPI
+from ag_ui_crewai.endpoint import add_crewai_flow_fastapi_endpoint
+from haiku_flow import HaikuFlow
+
+app = FastAPI(title="CrewAI Agent Server")
+
+add_crewai_flow_fastapi_endpoint(
+    app=app,
+    flow=HaikuFlow(),
+    path="/haiku",
+)
+```
+
+Register the agent with the CopilotKit runtime and point `<CopilotKit>` at it exactly as shown in the [Frontend Overview](/edge/en/guides/frontend/overview). The rest of this guide assumes the agent is registered under the id `haiku`.
+
+</Step>
+
+<Step title="Register the rendering component">
+
+On the frontend, call `useRenderTool` with the same `name` the backend declared. `useRenderTool` is the hook for *rendering* a tool call: it takes a `render` function and nothing to execute, because this tool is pure display.
+
+<Note>
+Use `useRenderTool` when the tool only draws UI. If the tool also needs to *run* something in the browser, use [`useFrontendTool`](/edge/en/guides/frontend/frontend-actions) instead, which pairs a `handler` with an optional `render`.
+</Note>
+
+```tsx
+"use client";
+import { useRenderTool } from "@copilotkit/react-core/v2";
+import { z } from "zod";
+
+useRenderTool({
+  name: "generate_haiku",
+  parameters: z.object({
+    japanese: z.array(z.string()),
+    english: z.array(z.string()),
+  }),
+  render: ({ args, status }) => {
+    if (!args.japanese) return <></>; // still streaming
+    return <HaikuCard japanese={args.japanese} english={args.english} />;
+  },
+});
+```
+
+The tool is scoped to the active agent by the `<CopilotKit agent="haiku">` provider, so no `agentId` is needed here. A few things to note:
+
+- **`name` must match the backend tool name** exactly (`generate_haiku`). That match is how CopilotKit routes the call to this component.
+- **`render` receives `{ args, status }`.** `args` fills in progressively as the model streams the call; early on it may be empty or partial. `status` moves through `"inProgress"` / `"executing"` to `"complete"` if you want to show a loading state while arguments stream.
+- **Guard against partial args.** Return an empty fragment until the fields you need exist. Here we wait for `args.japanese` before rendering the card.
+
+</Step>
+
+<Step title="Render the haiku">
+
+The `render` function delegates to an ordinary React component. Nothing about it is CopilotKit-specific: it takes props and returns markup.
+
+```tsx
+function HaikuCard({
+  japanese,
+  english,
+}: {
+  japanese: string[];
+  english: string[];
+}) {
+  return (
+    <div className="haiku-card">
+      {japanese.map((line, i) => (
+        <div key={i} className="haiku-line">
+          <span className="jp">{line}</span>
+          <span className="en">{english?.[i]}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+Because `english` streams in alongside `japanese`, use optional access (`english?.[i]`) so the card renders cleanly while the translation is still arriving.
+
+</Step>
+
+<Step title="Run it">
+
+Start both processes and ask the assistant for a haiku. The card renders as the arguments stream in, filling out line by line.
+
+```bash
+uvicorn server:app --port 8000   # terminal 1
+npm run dev                       # terminal 2
+```
+
+</Step>
+
+</Steps>
+
+## How progressive rendering works
+
+The model does not emit the tool call all at once. It streams tokens, and CopilotKit re-invokes your `render` function every time a new chunk of arguments arrives:
+
+1. The call begins. `args` is empty, so your guard returns an empty fragment.
+2. `args.japanese` fills in line by line. The card appears and grows.
+3. `args.english` fills in. Translations slot into place.
+4. The call completes. `args` holds the final, fully-validated object.
+
+This is why the partial-args guard matters: `render` runs against incomplete data by design. Read only the fields you have, and let the rest paint as they arrive.
+
+## Backend tools
+
+The `generate_haiku` tool above has no Python implementation — it exists only so the model emits a structured call the frontend renders. But a **real tool your Crew or Flow runs server-side** renders the same way.
+
+When an Agent or Crew executes a tool during its run, the bridge surfaces that tool call along with its **result**. Register a `useRenderTool` for the tool's name and read `result` in the render:
+
+```tsx
+useRenderTool({
+  name: "get_weather",
+  parameters: z.object({ location: z.string() }),
+  render: ({ args, result, status }) => {
+    if (status !== "complete") return <WeatherSkeleton location={args.location} />;
+    return <WeatherCard data={JSON.parse(result)} />;
+  },
+});
+```
+
+<Note>
+A backend tool must return a **JSON string**, not a Python dict. The bridge stringifies tool output, so a raw dict arrives as a Python repr the browser cannot `JSON.parse`. Return `json.dumps(...)` from the tool.
+</Note>
+
+## Related
+
+<CardGroup cols={2}>
+  <Card title="Agentic Generative UI" icon="list-check" href="/edge/en/guides/frontend/agentic-generative-ui">
+    Render live agent state as it changes across a multi-step run.
+  </Card>
+  <Card title="Human-in-the-Loop" icon="user-check" href="/edge/en/guides/frontend/human-in-the-loop">
+    Pause the agent to collect user approval or input mid-run.
+  </Card>
+  <Card title="Frontend Actions" icon="bolt" href="/edge/en/guides/frontend/frontend-actions">
+    Let the agent call functions that run in the browser.
+  </Card>
+</CardGroup>

docs/edge/en/learn/execution-boundary-hooks.mdx

@@ -120,6 +120,11 @@ def add_defaults(ctx):
 Rewritten inputs flow into task interpolation, so the run behaves as if it was
 kicked off with the modified dict.
 
+Prefer `INPUT` for rewriting and treat `EXECUTION_START` as the allow/deny
+gate. Rewrites at `EXECUTION_START` are still honored — on crews they also
+feed the `before_kickoff` callbacks; on flows they land exactly like an
+`INPUT` rewrite.
+
 ### Output Sanitization
 
 ```python
@@ -156,9 +161,10 @@ def report_outcome(ctx):
 ```
 
 Two caveats: `EXECUTION_END` does not fire when `EXECUTION_START` never
-dispatched (an abort at start counts as the execution never beginning), and
-raising `HookAborted` from a failure-path `EXECUTION_END` dispatch is ignored —
-there is nothing left to abort, and the original error wins.
+dispatched (an abort at start means the boundary never opened, so there is no
+end to pair), and raising `HookAborted` from a failure-path `EXECUTION_END`
+dispatch is ignored — there is nothing left to abort, and the original error
+wins.
 
 ## Ordering
 
@@ -168,6 +174,19 @@ For a crew run the boundary order is:
 EXECUTION_START → before_kickoff callbacks → INPUT → tasks execute → OUTPUT → EXECUTION_END
 ```
 
+For a flow run, the boundary hooks resolve the inputs before the lifecycle
+events begin:
+
+```
+EXECUTION_START → INPUT → FlowStartedEvent → flow methods execute → OUTPUT → EXECUTION_END → FlowFinishedEvent
+```
+
+`FlowStartedEvent` carries the hook-resolved inputs, and rewriting
+`inputs["id"]` in a boundary hook redirects state restoration. An abort at
+`EXECUTION_START` still surfaces as `FlowStartedEvent` followed by
+`FlowFailedEvent`, emitted at the abort with the payload as resolved by the
+hooks that ran before it.
+
 Hooks at the same point run in registration order, global hooks first, then
 crew-scoped hooks. Telemetry (`HookDispatchedEvent`) is emitted per dispatch.
 

docs/edge/en/telemetry.mdx

@@ -34,6 +34,20 @@ os.environ['CREWAI_DISABLE_TELEMETRY'] = 'true'
 os.environ['OTEL_SDK_DISABLED'] = 'true'
 ```
 
+### Isolation from your own OpenTelemetry setup
+
+CrewAI's telemetry runs on its own private `TracerProvider` and never registers
+itself as the global one. This keeps the two directions separate:
+
+- Spans from other instrumented libraries in your process — web frameworks,
+  database clients, HTTP clients — are never sent to CrewAI.
+- CrewAI's telemetry spans are never sent to your observability backend, so they
+  will not appear in Langfuse, Braintrust, Phoenix, or any other collector you
+  configure.
+
+Observability integrations are unaffected: they instrument CrewAI through their
+own tracer provider, which is independent of the one described here.
+
 ### Data Explanation:
 | Defaulted | Data                                      | Reason and Specifics                                                                                                       |
 |:----------|:------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------|
@@ -45,7 +59,10 @@ os.environ['OTEL_SDK_DISABLED'] = 'true'
 | Yes       | Test Execution Data | Includes: crew's randomly generated key and ID, number of iterations, model name used, quality score (float), execution time (in seconds). All non-personal. |
 | Yes       | Task Lifecycle Data | Includes: creation and execution start/end times, crew and task identifiers. 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       | Crew Deployment attempt using crewAI CLI | Includes: The fact a deploy is being made and crew id, and if it's trying to pull logs, no other 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       | 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`), and the `project_id` from your `pyproject.toml` when one is configured. 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. |
 | No        | Agent's Expanded Data | Includes: goal description, backstory text, i18n prompt file identifier. Users should ensure no personal info is included in text fields. |
 | No        | Detailed Task Information | Includes: task description, expected output description, context references. Users should ensure no personal info is included in these fields. |
 | No        | Environment Information | Includes: platform, release, system, version, and CPU count. Example: 'Windows 10', 'x86_64'. No personal data. |

docs/edge/ko/changelog.mdx

@@ -4,6 +4,133 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="2026년 8월 13일">
+  ## v1.15.16
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.16)
+
+  ## 변경 사항
+
+  ### 기능
+  - UUID 지원을 통한 실행 컨텍스트 관리 도입
+  - 흐름을 종료한 예외의 종류 기록
+  - 트레이스 배치가 AMP와 공유된 시점 기록
+  - 모든 출처에서 배포를 카운트하고 시작 위치 기록
+
+  ### 버그 수정
+  - 모든 생성된 스팬에서 실행 중인 릴리스를 기록
+  - MySQL 검색 테이블 이름 유효성 검사 수정
+  - 실패한 턴이 다음 턴을 실패로 표시하지 않도록 중지
+
+  ### 문서
+  - CopilotKit 및 AG-UI에 대한 프론트엔드 가이드 추가
+
+  ## 기여자
+
+  @joaomdmoura, @lorenzejay, @ranst91, @theCyberTech
+
+</Update>
+
+<Update label="2026년 8월 11일">
+  ## v1.15.15
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.15)
+
+  ## 변경 사항
+
+  ### 기능
+  - 보고서 흐름 결과, 지속 시간 및 인간 개입 신호를 보고합니다.
+
+  ### 버그 수정
+  - 경계 후크가 흐름을 중단할 때 FlowStartedEvent를 발생시킵니다.
+  - 범위 스팬 내보내기를 우리 고유의 트레이서 제공자로 제한합니다.
+  - 보안 취약점을 해결하기 위해 torch를 2.13.0 버전으로 업데이트합니다.
+  - crewai-tools[github]에서 gitpython을 3.1.58 버전으로 업데이트합니다.
+
+  ### 리팩토링
+  - 에이전트의 날짜 주입 기능을 업데이트합니다.
+  - CLI 플래그를 케밥 케이스로 표준화합니다.
+
+  ### 문서
+  - v1.15.14에 대한 스냅샷 및 변경 로그.
+
+  ## 기여자
+
+  @Vidit-Ostwal, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech
+
+</Update>
+
+<Update label="2026년 8월 8일">
+  ## v1.15.14
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.14)
+
+  ## 변경 사항
+
+  ### 기능
+  - 코딩 에이전트와 런타임 컨텍스트 분리 및 프로젝트 ID 추가
+
+  ### 문서
+  - v1.15.13에 대한 스냅샷 및 변경 로그 업데이트
+
+  ## 기여자
+
+  @joaomdmoura
+
+</Update>
+
+<Update label="2026년 8월 7일">
+  ## v1.15.13
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.13)
+
+  ## 변경 사항
+
+  ### 버그 수정
+  - LiteLLM 라우팅 모델에서 제공자의 보존 문제 수정.
+  - 취약한 LLM 이벤트 버스 모의 객체 강화.
+  - Anthropic 캐시 토큰 사용량의 과소 보고 문제 수정.
+  - 보안 취약점 GHSA-6hr6-w5qg-qmwg를 해결하기 위해 h2를 버전 4.4.1로 업데이트.
+
+  ### 문서
+  - 로케일 동기화를 위한 DOCS_TRANSLATIONS 워크플로 추가.
+  - 깨진 README 링크, 목차 및 기여 가이드 수정.
+  - 버전 1.15.12에 대한 스냅샷 및 변경 로그.
+
+  ## 기여자
+
+  @Vidit-Ostwal, @joaomdmoura, @lucasgomide, @theCyberTech
+
+</Update>
+
+<Update label="2026년 8월 5일">
+  ## v1.15.12
+
+  [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.15.12)
+
+  ## 변경 사항
+
+  ### 기능
+  - 릴리스 시 Flow 카나리 버전 증가
+  - 임의의 URL을 읽기 위한 URLReadTool 추가
+  - 플랫폼 액션 도구에 앱 메타데이터 추가
+  - `crewai create <resource>` 아래에서 스캐폴딩 통합
+
+  ### 버그 수정
+  - 대화형 경로/핸들러 이름 충돌 오류 명확화
+
+  ### 문서
+  - 통합된 생성 CLI를 위한 AGENTS.md 스캐폴드 업데이트
+
+  ### 주요 변경 사항
+  - 없음
+
+  ## 기여자
+
+  @Vidit-Ostwal, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech
+
+</Update>
+
 <Update label="2026년 8월 4일">
   ## v1.15.11
 

docs/edge/ko/concepts/agents.mdx

@@ -56,7 +56,7 @@ CrewAI AOP에는 코드를 작성하지 않고도 에이전트 생성 및 구성
 | **컨텍스트 윈도우 준수** _(옵션)_         | `respect_context_window` | `bool`                        | 메시지를 컨텍스트 윈도우 크기 내로 유지하기 위하여 요약 기능을 사용합니다. 기본값은 True입니다.                         |
 | **코드 실행 모드** _(옵션)_              | `code_execution_mode`    | `Literal["safe", "unsafe"]`   | 코드 실행 모드: 'safe'(Docker 사용) 또는 'unsafe'(직접 실행). 기본값은 'safe'입니다.                                   |
 | **멀티모달** _(옵션)_                    | `multimodal`             | `bool`                        | 에이전트가 멀티모달 기능을 지원하는지 여부입니다. 기본값은 False입니다.                                                |
-| **날짜 자동 삽입** _(옵션)_              | `inject_date`            | `bool`                        | 작업에 현재 날짜를 자동으로 삽입할지 여부입니다. 기본값은 False입니다.                                                 |
+| **날짜 자동 삽입** _(옵션)_              | `inject_date`            | `bool`                        | 에이전트 프롬프트에 현재 날짜를 자동으로 삽입할지 여부입니다. 기본값은 False입니다.                                     |
 | **날짜 형식** _(옵션)_                   | `date_format`            | `str`                         | inject_date 활성화 시 날짜 표시 형식 문자열입니다. 기본값은 "%Y-%m-%d"(ISO 포맷)입니다.                                 |
 | **추론** _(옵션)_                        | `reasoning`              | `bool`                        | 에이전트가 작업을 실행하기 전에 반영 및 플랜을 생성할지 여부입니다. 기본값은 False입니다.                              |
 | **최대 추론 시도 수** _(옵션)_           | `max_reasoning_attempts` | `Optional[int]`               | 작업 실행 전 최대 추론 시도 횟수입니다. 설정하지 않으면 준비될 때까지 시도합니다.                                        |
@@ -267,7 +267,7 @@ strategic_agent = Agent(
     role="Market Analyst",
     goal="Track market movements with precise date references and strategic planning",
     backstory="Expert in time-sensitive financial analysis and strategic reporting",
-    inject_date=True,  # Automatically inject current date into tasks
+    inject_date=True,  # Automatically inject current date into the prompt
     date_format="%B %d, %Y",  # Format as "May 21, 2025"
     reasoning=True,  # Enable strategic planning
     max_reasoning_attempts=2,  # Limit planning iterations
@@ -328,7 +328,7 @@ multimodal_agent = Agent(
 #### 고급 기능
 - `multimodal`: 텍스트와 시각적 콘텐츠 처리를 위한 멀티모달 기능 활성화
 - `reasoning`: 에이전트가 작업을 수행하기 전에 반영하고 계획을 작성할 수 있도록 활성화
-- `inject_date`: 현재 날짜를 작업 설명에 자동으로 삽입
+- `inject_date`: 현재 날짜를 에이전트 프롬프트에 자동으로 삽입
 
 #### 템플릿
 - `system_template`: 에이전트의 핵심 동작을 정의합니다

docs/edge/ko/concepts/cli.mdx

@@ -54,6 +54,16 @@ crewai create flow my_new_flow
 
 기본적으로 `crewai create crew`는 `crew.jsonc`와 `agents/*.jsonc`가 있는 JSON-first 프로젝트를 만듭니다. `crew.py`, `config/agents.yaml`, `config/tasks.yaml`을 사용하는 기존 Python/YAML 스캐폴드가 필요할 때만 `crewai create crew my_new_crew --classic`을 사용하세요.
 
+#### 사용 중단된 플래그 별칭
+
+이전 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의 버전을 표시합니다.
@@ -79,7 +89,7 @@ crewai version --tools
 crewai train [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: crew를 훈련할 반복 횟수 (기본값: 5)
+- `-n, --n-iterations INTEGER`: crew를 훈련할 반복 횟수 (기본값: 5)
 - `-f, --filename TEXT`: 훈련에 사용할 커스텀 파일의 경로 (기본값: "trained_agents_data.pkl")
 
 예시:
@@ -96,7 +106,7 @@ crewai train -n 10 -f my_training_data.pkl
 crewai replay [OPTIONS]
 ```
 
-- `-t, --task_id TEXT`: 이 task ID에서부터 crew를 다시 재생하며, 이후의 모든 task를 포함합니다.
+- `-t, --task-id TEXT`: 이 task ID에서부터 crew를 다시 재생하며, 이후의 모든 task를 포함합니다.
 
 예시:
 
@@ -143,7 +153,7 @@ crew를 테스트하고 결과를 평가합니다.
 crewai test [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: crew를 테스트할 반복 횟수 (기본값: 3)
+- `-n, --n-iterations INTEGER`: crew를 테스트할 반복 횟수 (기본값: 3)
 - `-m, --model TEXT`: Crew에서 테스트를 실행할 LLM 모델 (기본값: "gpt-4o-mini")
 
 예시:

docs/edge/ko/concepts/crews.mdx

@@ -324,6 +324,8 @@ crew는 메모리(단기, 장기 및 엔티티 메모리)를 활용하여 시간
 
 crew 실행 후, `usage_metrics` 속성에 접근하여 crew가 실행한 모든 작업에 대한 언어 모델(LLM) 사용 메트릭을 확인할 수 있습니다. 이를 통해 운영 효율성과 개선이 필요한 영역에 대한 인사이트를 얻을 수 있습니다.
 
+`total_tokens`는 청구된 총합(`prompt_tokens + completion_tokens`)입니다. `cached_prompt_tokens` 및 `cache_creation_tokens`와 같은 breakdown 필드는 이미 해당 총합에 포함된 부분 집합을 설명하며 `total_tokens` 위에 다시 더하지 않습니다. 전체 계약은 Flows 개념 문서의 **UsageMetrics field semantics** 섹션을 참조하세요.
+
 ```python Code
 # Access the crew's usage metrics
 crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])

docs/edge/ko/concepts/flows.mdx

@@ -261,6 +261,24 @@ print(flow.usage_metrics)
   **전체** 토큰 집계가 필요할 때는 항상 `flow.usage_metrics`를 사용하십시오.
 </Note>
 
+### UsageMetrics 필드 의미
+
+반환되는 [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) 객체는 제공자 중립 계약을 사용합니다:
+
+| 필드 | 의미 |
+| --- | --- |
+| `total_tokens` | 청구된 총합: `prompt_tokens + completion_tokens` |
+| `prompt_tokens` | 요청에 대해 청구된 전체 입력/프롬프트 토큰 |
+| `completion_tokens` | 요청에 대해 청구된 출력/완료 토큰 |
+| `cached_prompt_tokens` | 프롬프트 토큰 중 캐시 읽기 부분 집합 (breakdown 전용) |
+| `cache_creation_tokens` | 프롬프트 토큰 중 캐시 쓰기 부분 집합 (breakdown 전용, Anthropic) |
+| `reasoning_tokens` | 제공자가 별도로 보고하는 추론/사고 부분 집합 (breakdown 전용) |
+| `successful_requests` | 집계된 LLM 호출 수 |
+
+`cached_prompt_tokens`, `cache_creation_tokens`, `reasoning_tokens`와 같은 breakdown 필드는 `total_tokens` **위에 추가되지 않습니다** — 이미 `prompt_tokens` 또는 `completion_tokens`에 포함된 부분을 설명합니다.
+
+Anthropic의 경우 캐시 읽기 및 쓰기 카운터가 `prompt_tokens`에 포함되므로, 캐시된 워크로드가 `total_tokens`에 완전히 반영됩니다. OpenAI 스타일 제공자는 캐시된 입력을 이미 `prompt_tokens`에 포함합니다. CrewAI는 가시성을 위해 캐시된 부분을 별도로 표시합니다.
+
 반환되는 [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py)의 각 항목은 단일 `flow.kickoff()` 실행 동안 발생한 모든 LLM 호출의 합계입니다. 다음 `kickoff()` 호출(및 `kickoff_for_each`의 각 반복)에서 카운터가 초기화되므로 연속 실행이 이중으로 집계되지 않습니다. 이 속성은 `kickoff()` 완료 후 언제든지 안전하게 읽을 수 있으며, 실행 중에 읽으면 그 시점까지 누적된 부분 합계를 반환합니다.
 
 ## 플로우 상태 관리

docs/edge/ko/concepts/llms.mdx

@@ -270,6 +270,21 @@ CrewAI는 고유한 기능, 인증 방법, 모델 역량을 제공하는 다양
     )
     ```
 
+    **토큰 사용량 및 프롬프트 캐싱:**
+
+    Anthropic은 청구된 입력을 별도 카운터로 보고합니다 — `input_tokens`(캐시되지 않은 입력), `cache_read_input_tokens`, `cache_creation_input_tokens`. CrewAI는 세 값을 모두 `prompt_tokens`(및 제공자 응답의 네이티브 `input_tokens`)에 포함시켜 캐시된 워크로드에서 `total_tokens`가 전체 청구 사용량을 반영하도록 합니다.
+
+    `cached_prompt_tokens`는 캐시 읽기 부분을 breakdown으로만 기록합니다. 이미 `prompt_tokens`에 포함되어 있으므로 `total_tokens`에 다시 더하면 안 됩니다. `cache_creation_tokens`도 캐시 쓰기를 같은 방식으로 기록합니다.
+
+    ```python Code
+    usage = llm.get_token_usage_summary()
+    # total_tokens == prompt_tokens + completion_tokens
+    # prompt_tokens includes cache read + cache write for Anthropic
+    ```
+
+    `crew.usage_metrics` 및 `flow.usage_metrics`에 사용되는 제공자 중립 계약은
+    Flows 개념 문서의 **UsageMetrics field semantics** 섹션을 참조하세요.
+
     현재 모델 ID와 기능은 Anthropic의 [모델 개요](https://platform.claude.com/docs/en/about-claude/models/overview)를 확인하고, 프로덕션에서 모델을 고정하기 전에 [모델 지원 중단 표](https://platform.claude.com/docs/en/about-claude/model-deprecations)를 검토하세요.
   </Accordion>
 

docs/edge/ko/concepts/testing.mdx

@@ -20,7 +20,7 @@ crewai test
 더 많은 반복 횟수로 실행하거나 다른 모델을 사용하려면 다음과 같이 매개변수를 지정할 수 있습니다:
 
 ```bash
-crewai test --n_iterations 5 --model gpt-4o
+crewai test --n-iterations 5 --model gpt-4o
 ```
 
 또는 축약형을 사용할 수 있습니다:
@@ -29,6 +29,11 @@ crewai test --n_iterations 5 --model gpt-4o
 crewai test -n 5 -m gpt-4o
 ```
 
+<Note>
+  이전 `--n_iterations` 플래그는 여전히 동작하지만 사용 중단되었으며 `--help`에는
+  표시되지 않습니다. 대신 `--n-iterations`(또는 `-n`)를 사용하세요.
+</Note>
+
 `crewai test` 명령어를 실행하면 crew가 지정한 횟수만큼 실행되고, 수행이 끝나면 성능 지표가 표시됩니다.
 
 실행 마지막에 표시되는 점수 표는 다음과 같은 지표로 crew의 성능을 보여줍니다:

docs/edge/ko/learn/execution-boundary-hooks.mdx

@@ -0,0 +1,204 @@
+---
+title: 실행 경계 훅
+description: "@on 데코레이터로 crew와 flow 실행의 시작, 입력, 출력, 종료를 가로채기"
+mode: "wide"
+---
+
+실행 경계 훅은 실행의 가장 바깥쪽 경계를 가로챕니다 — 작업이 시작되기 전,
+입력이 확정될 때, 최종 결과가 준비될 때, 그리고 실행이 끝날 때입니다. 크루와
+플로우 모두에서 발생하며, 실행 수준의 정책 검사, 입력 재작성, 출력 정제에
+적합한 위치입니다.
+
+## 개요
+
+네 가지 인터셉션 포인트가 경계를 담당합니다:
+
+| 포인트 | 시점 | `ctx.payload` |
+|--------|------|---------------|
+| `EXECUTION_START` | 크루 또는 플로우가 막 시작되려는 시점 | 입력 `dict` |
+| `INPUT` | 실행을 위한 입력이 확정된 시점 | 입력 `dict` |
+| `OUTPUT` | 최종 결과가 준비된 시점 | 출력 객체 |
+| `EXECUTION_END` | 실행이 끝난 시점(성공 또는 실패) | 출력 객체, 실패 시 `None` |
+
+크루의 경우 출력 payload는 `CrewOutput`입니다. 플로우의 경우 최종 플로우
+메서드의 결과입니다.
+
+## 훅 시그니처
+
+```python
+from crewai.hooks import on, HookAborted, InterceptionPoint
+
+@on(InterceptionPoint.EXECUTION_START)
+def boundary_hook(ctx) -> Any | None:
+    # Mutate ctx.payload in place, or
+    # return a non-None value to replace it, or
+    # raise HookAborted(reason, source) to stop the run
+    return None
+```
+
+경계 훅은 표준 계약을 따릅니다: 진행(`return None`), 제자리(in-place) 수정,
+값을 반환하여 교체, 또는 `HookAborted`를 발생시켜 중단합니다. 어떤
+경계에서든 중단(abort)은 그 사유와 함께 `kickoff()` 밖으로 전파됩니다.
+
+## 컨텍스트 스키마
+
+각 포인트는 타입이 지정된 컨텍스트를 받습니다. 모든 컨텍스트는 공통 기본
+필드를 공유합니다:
+
+```python
+class InterceptionContext:
+    payload: Any            # The interceptable value (see table above)
+    agent: Any = None       # Not populated at execution boundaries
+    agent_role: str | None  # Not populated at execution boundaries
+    task: Any = None        # Not populated at execution boundaries
+    crew: Any = None        # The Crew instance (crew runs only)
+    flow: Any = None        # The Flow instance (flow runs only)
+```
+
+포인트별 컨텍스트는 payload에 대한 이름 있는 별칭을 추가합니다:
+
+```python
+class ExecutionStartContext(InterceptionContext):
+    inputs: dict            # Same dict as payload
+
+class InputContext(InterceptionContext):
+    inputs: dict            # Same dict as payload
+
+class OutputContext(InterceptionContext):
+    output: Any             # The output object
+
+class ExecutionEndContext(InterceptionContext):
+    output: Any                    # The output object (None when status == "failed")
+    status: str                    # "completed" or "failed"
+    error: BaseException | None    # The exception when status == "failed"
+```
+
+<Note>
+`ctx.inputs`는 **원본** 입력 dict의 별칭이므로, 어느 이름으로든 제자리
+수정은 동일하게 동작합니다. 이전 훅이 새 dict를 반환하여 payload를
+*교체*했다면 `ctx.payload`만 다시 바인딩됩니다 — 훅이 연쇄될 수 있는 경우
+항상 `ctx.payload`를 읽고 쓰세요.
+</Note>
+
+## 크루 실행 vs. 플로우 실행
+
+경계 훅은 두 런타임 모두에서 발생하며, 크루 실행은 내부적으로 플로우 런타임
+위에서 동작합니다. 따라서 `crew.kickoff()` 중에는 전역 경계 훅이 크루
+경계(`ctx.crew` 설정, `ctx.flow`는 `None`)**와** 내부 플로우(`ctx.flow`
+설정, `ctx.crew`는 `None`) 모두에서 발생합니다. 런타임으로 구분하세요:
+
+```python
+@on(InterceptionPoint.OUTPUT)
+def crew_output_only(ctx):
+    if ctx.crew is None:
+        return None  # Skip the internal flow (or a bare flow)
+    ctx.payload.raw = ctx.payload.raw.strip()
+```
+
+## 일반적인 사용 사례
+
+### 시작 시 정책 검사
+
+```python
+@on(InterceptionPoint.EXECUTION_START)
+def enforce_policy(ctx):
+    if ctx.crew is not None and not ctx.payload.get("authorized"):
+        raise HookAborted(reason="unauthorized execution", source="access-control")
+```
+
+### 입력 재작성
+
+```python
+@on(InterceptionPoint.INPUT)
+def add_defaults(ctx):
+    if ctx.crew is None:
+        return None
+    ctx.payload.setdefault("locale", "en-US")
+    ctx.payload["topic"] = ctx.payload["topic"].strip().lower()
+```
+
+재작성된 입력은 태스크 보간(interpolation)으로 흘러가므로, 실행은 수정된
+dict로 시작된 것처럼 동작합니다.
+
+재작성에는 `INPUT`을 사용하고, `EXECUTION_START`는 허용/거부 게이트로
+취급하세요. `EXECUTION_START`에서의 재작성도 여전히 반영됩니다 — 크루에서는
+`before_kickoff` 콜백에도 전달되고, 플로우에서는 `INPUT` 재작성과 동일하게
+적용됩니다.
+
+### 출력 정제
+
+```python
+import re
+
+@on(InterceptionPoint.OUTPUT)
+def redact_emails(ctx):
+    if ctx.crew is None:
+        return None
+    ctx.payload.raw = re.sub(
+        r"\b[\w.+-]+@[\w-]+\.[\w.]+\b", "[EMAIL-REDACTED]", ctx.payload.raw
+    )
+```
+
+`OUTPUT`은 `EXECUTION_END`보다 먼저 실행되며, 둘 다 이전 훅에서 (교체되었을
+수 있는) payload를 봅니다. 최종적으로 재작성된 값이 `kickoff()`가 반환하는
+값입니다.
+
+### 실패 관찰
+
+`EXECUTION_END`는 성공이든 실패든 실행마다 정확히 한 번 발생합니다. 실행이
+예외를 던지면 — 태스크 오류, 플로우 메서드 예외, 또는 이전 포인트의
+`HookAborted` — 훅은 `ctx.error`에 예외가 담긴 `status="failed"`를 받으며,
+원래 예외는 변경 없이 `kickoff()` 밖으로 전파됩니다:
+
+```python
+@on(InterceptionPoint.EXECUTION_END)
+def report_outcome(ctx):
+    if ctx.status == "failed":
+        notify_policy_engine(status="failed", error=repr(ctx.error))
+    else:
+        notify_policy_engine(status="completed")
+```
+
+두 가지 주의 사항: `EXECUTION_START`가 디스패치되지 않았다면
+`EXECUTION_END`는 발생하지 않습니다(시작 시점의 중단은 경계가 열리지
+않았다는 뜻이므로 짝을 이룰 종료가 없습니다). 또한 실패 경로의
+`EXECUTION_END` 디스패치에서 `HookAborted`를 발생시키는 것은 무시됩니다 —
+더 이상 중단할 것이 없고, 원래 오류가 우선합니다.
+
+## 순서
+
+크루 실행의 경계 순서는 다음과 같습니다:
+
+```
+EXECUTION_START → before_kickoff callbacks → INPUT → tasks execute → OUTPUT → EXECUTION_END
+```
+
+플로우 실행에서는 라이프사이클 이벤트가 시작되기 전에 경계 훅이 입력을
+확정합니다:
+
+```
+EXECUTION_START → INPUT → FlowStartedEvent → flow methods execute → OUTPUT → EXECUTION_END → FlowFinishedEvent
+```
+
+`FlowStartedEvent`는 훅이 확정한 입력을 담으며, 경계 훅에서 `inputs["id"]`를
+재작성하면 상태 복원 대상이 바뀝니다. `EXECUTION_START`에서의 중단은 여전히
+`FlowStartedEvent` 다음에 `FlowFailedEvent`가 오는 형태로 나타나며, 중단
+시점에 그때까지 실행된 훅이 확정한 페이로드와 함께 발생합니다.
+
+같은 포인트의 훅은 등록 순서대로 실행되며, 전역 훅이 먼저, 그다음 크루 범위
+훅이 실행됩니다. 텔레메트리(`HookDispatchedEvent`)는 디스패치마다
+발생합니다.
+
+## 테스트에서 훅 관리
+
+```python
+from crewai.hooks import clear_all_hooks
+
+clear_all_hooks()  # Clears every point, including boundaries
+```
+
+## 관련 문서
+
+- [실행 훅 개요 →](/edge/ko/learn/execution-hooks)
+- [LLM 호출 훅 →](/edge/ko/learn/llm-hooks)
+- [도구 호출 훅 →](/edge/ko/learn/tool-hooks)

docs/edge/ko/telemetry.mdx

@@ -33,6 +33,19 @@ os.environ['CREWAI_DISABLE_TELEMETRY'] = 'true'
 os.environ['OTEL_SDK_DISABLED'] = 'true'
 ```
 
+### 사용자 OpenTelemetry 설정과의 격리
+
+CrewAI의 telemetry는 자체 전용 `TracerProvider`에서 실행되며 자신을 전역
+provider로 등록하지 않습니다. 이를 통해 양방향이 분리됩니다:
+
+- 프로세스 내 다른 계측된 라이브러리(웹 프레임워크, 데이터베이스 클라이언트,
+  HTTP 클라이언트)의 span은 CrewAI로 전송되지 않습니다.
+- CrewAI의 telemetry span은 사용자의 관측 가능성 백엔드로 전송되지 않으므로
+  Langfuse, Braintrust, Phoenix 또는 구성한 다른 수집기에 나타나지 않습니다.
+
+관측 가능성 통합은 영향을 받지 않습니다: 해당 통합은 여기서 설명한 provider와
+독립적인 자체 tracer provider를 통해 CrewAI를 계측합니다.
+
 ### 데이터 설명:
 | 기본값 | 데이터                                      | 사유 및 세부 사항                                                                                                       |
 |:--------|:-------------------------------------------|:----------------------------------------------------------------------------------------------------------------------|
@@ -44,7 +57,10 @@ os.environ['OTEL_SDK_DISABLED'] = 'true'
 | 예      | 테스트 실행 데이터                         | crew의 랜덤 생성 키와 ID, 반복 횟수, 사용된 모델명, 품질 점수(실수), 실행 시간(초 단위)이 포함됩니다. 모두 비개인 정보입니다. |
 | 예      | 작업 라이프사이클 데이터                   | 생성 및 실행 시작/종료 시각, crew 및 작업 식별자가 포함됩니다. 타임스탬프를 포함한 span으로 저장됩니다. 개인 정보 없음. |
 | 예      | LLM 속성                                  | LLM의 이름, model_name, 모델, top_k, temperature 및 클래스명이 포함됩니다. 모두 기술적이고 비개인 정보입니다. |
-| 예      | crewAI CLI를 통한 Crew 배포 시도           | 배포가 시도되고 있고 crew id가 포함되며, 로그를 가져오려고 하는 경우에만 해당. 다른 데이터 없음. |
+| 예      | crewAI CLI를 통한 Crew 배포 시도 | 포함 항목: 배포가 시도되고 있다는 사실과 crew id, 로그를 가져오려고 하는지 여부, 그리고 배포가 CLI 명령에서 시작되었는지 실행 TUI에서 시작되었는지 여부. 프로젝트나 crew의 내용은 기록되지 않습니다. 개인 정보 없음. |
+| 예      | 실행 환경                                  | 포함: 프로세스를 실행 중인 AI 코딩 어시스턴트(있는 경우, `claude_code`, `codex`, `cursor`, `unknown` 등 고정 목록 중 하나), 프로세스가 실행되는 위치(`ci`, `container`, `serverless`, `interactive` 등 고정 목록 중 하나), 그리고 `pyproject.toml`에 설정된 경우 `project_id`. 감지는 알려진 환경 변수의 설정 여부만 확인하며 값은 읽지 않음. 개인 데이터 없음. |
+| 예      | Flow 라이프사이클 신호 | 포함 항목: flow의 시작, 완료 또는 실패 여부, 해당 메서드의 실패 여부, 사람의 입력이나 피드백을 위해 일시 중지되었는지 여부, 해당 시작이 재개된 실행이었는지 여부, 대화 턴의 실패 여부, flow 실행 시간, 그리고 해당 flow가 CrewAI가 내부적으로 실행하는 것인지 사용자가 작성한 것인지 여부. flow 이름은 flow 생성 및 실행에서와 마찬가지로 기록됩니다. flow 또는 해당 메서드가 실패하면 장애 진단을 위해 예외의 **클래스 이름**(예: `TimeoutError`)이 기록되며, 프롬프트·모델 출력·파일 경로·자격 증명이 포함될 수 있는 오류 메시지는 절대 기록되지 않습니다. 메서드 이름과 flow 상태는 절대 기록되지 않습니다. 개인 정보 없음. |
+| 예      | 트레이스 공유 신호 | 포함 항목: 트레이스 배치가 CrewAI AMP에 성공적으로 공유되었는지 여부와, 익명으로(계정 생성 전) 공유되었는지 또는 계정에 연결되어 공유되었는지 여부. 모든 span과 마찬가지로 위에서 설명한 실행 환경 속성(구성된 경우 `project_id`, 코딩 어시스턴트, 런타임)도 함께 기록됩니다. 이 행은 공유 텔레메트리만 설명하며 — 트레이스 내용이나 공유된 트레이스 링크로 부여되는 접근 권한은 설명하지 않습니다. 트레이스 내용, 입력, 출력은 이 신호에는 기록되지 않습니다. 트레이스를 공유하기 전에 비밀 정보, 개인 데이터, AMP 편집 및 보존 설정을 검토하세요. |
 | 아니오  | 에이전트 확장 데이터                      | 목표 설명, 배경 이야기 텍스트, i18n 프롬프트 파일 식별자가 포함됩니다. 사용자들은 텍스트 필드에 개인 정보가 포함되지 않도록 해야 합니다. |
 | 아니오  | 상세 작업 정보                            | 작업 설명, 예상 출력 설명, 컨텍스트 참조가 포함됩니다. 사용자들은 이러한 필드에 개인 정보가 포함되지 않도록 해야 합니다. |
 | 아니오  | 환경 정보                                 | 플랫폼, 릴리즈, 시스템, 버전, CPU 개수가 포함됩니다. 예: 'Windows 10', 'x86_64'. 개인 정보 없음. |

docs/edge/pt-BR/changelog.mdx

@@ -4,6 +4,133 @@ description: "Atualizações de produto, melhorias e correções do CrewAI"
 icon: "clock"
 mode: "wide"
 ---
+<Update label="13 ago 2026">
+  ## v1.15.16
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.16)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Introduzir gerenciamento de contexto de execução com suporte a UUID
+  - Registrar que tipo de exceção finalizou um fluxo
+  - Registrar quando um lote de rastreamento é compartilhado com AMP
+  - Contar implantações de qualquer origem e registrar onde elas começaram
+
+  ### Correções de Bugs
+  - Registrar a versão em execução em cada span emitido
+  - Corrigir a validação do nome da tabela de busca do MySQL
+  - Impedir que uma tentativa falhada marque a próxima como falhada
+
+  ### Documentação
+  - Adicionar guias de Frontend para CopilotKit e AG-UI
+
+  ## Contribuidores
+
+  @joaomdmoura, @lorenzejay, @ranst91, @theCyberTech
+
+</Update>
+
+<Update label="11 ago 2026">
+  ## v1.15.15
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.15)
+
+  ## O que Mudou
+
+  ### Funcionalidades
+  - Relatar resultado do fluxo, duração e sinais de interação humana.
+
+  ### Correções de Bugs
+  - Emitir FlowStartedEvent quando um gancho de limite aborta o fluxo.
+  - Escopar a exportação de span para nosso próprio provedor de rastreamento.
+  - Atualizar o torch para a versão 2.13.0 para resolver vulnerabilidade de segurança.
+  - Atualizar o gitpython para a versão 3.1.58 em crewai-tools[github].
+
+  ### Refatoração
+  - Atualizar a funcionalidade de injeção de data em agentes.
+  - Padronizar as flags da CLI para kebab-case.
+
+  ### Documentação
+  - Snapshot e changelog para v1.15.14.
+
+  ## Contributors
+
+  @Vidit-Ostwal, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech
+
+</Update>
+
+<Update label="08 ago 2026">
+  ## v1.15.14
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.14)
+
+  ## O que Mudou
+
+  ### Recursos
+  - Separar o contexto de execução do agente de codificação e adicionar ID do projeto
+
+  ### Documentação
+  - Atualizar snapshot e changelog para v1.15.13
+
+  ## Contribuidores
+
+  @joaomdmoura
+
+</Update>
+
+<Update label="07 ago 2026">
+  ## v1.15.13
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.13)
+
+  ## O que Mudou
+
+  ### Correções de Bugs
+  - Corrigir a preservação do provedor em modelos roteados por LiteLLM.
+  - Fortalecer os mocks do barramento de eventos LLM que são frágeis.
+  - Corrigir a subnotificação do uso de tokens de cache da Anthropic.
+  - Atualizar o h2 para a versão 4.4.1 para resolver a vulnerabilidade de segurança GHSA-6hr6-w5qg-qmwg.
+
+  ### Documentação
+  - Adicionar o fluxo de trabalho DOCS_TRANSLATIONS para sincronização de locais.
+  - Corrigir links quebrados no README, tabela de conteúdos e orientações de contribuição.
+  - Snapshot e changelog para a versão 1.15.12.
+
+  ## Contributors
+
+  @Vidit-Ostwal, @joaomdmoura, @lucasgomide, @theCyberTech
+
+</Update>
+
+<Update label="05 ago 2026">
+  ## v1.15.12
+
+  [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.15.12)
+
+  ## O que Mudou
+
+  ### Funcionalidades
+  - Aumentar o canário do Flow na versão
+  - Adicionar URLReadTool para leitura de URLs arbitrárias
+  - Adicionar metadados do aplicativo às ferramentas de ação da plataforma
+  - Unificar a estrutura sob `crewai create <resource>`
+
+  ### Correções de Bugs
+  - Esclarecer erros de colisão de nomes de rota/manipulador de conversa
+
+  ### Documentação
+  - Atualizar o AGENTS.md da estrutura para CLI de criação unificada
+
+  ### Mudanças Quebradoras
+  - Nenhuma
+
+  ## Contribuidores
+
+  @Vidit-Ostwal, @joaomdmoura, @lorenzejay, @lucasgomide, @theCyberTech
+
+</Update>
+
 <Update label="04 ago 2026">
   ## v1.15.11
 

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

@@ -61,7 +61,7 @@ O Construtor Visual de Agentes permite:
 | **Respect Context Window** _(opcional)_ | `respect_context_window` | `bool`                                | Mantém as mensagens dentro do tamanho da janela de contexto, resumindo quando necessário. Padrão: True.   |
 | **Code Execution Mode** _(opcional)_    | `code_execution_mode`    | `Literal["safe", "unsafe"]`           | Modo de execução de código: 'safe' (usando Docker) ou 'unsafe' (direto). Padrão: 'safe'.                  |
 | **Multimodal** _(opcional)_             | `multimodal`             | `bool`                                | Se o agente suporta capacidades multimodais. Padrão: False.                                               |
-| **Inject Date** _(opcional)_            | `inject_date`            | `bool`                                | Se deve injetar automaticamente a data atual nas tarefas. Padrão: False.                                  |
+| **Inject Date** _(opcional)_            | `inject_date`            | `bool`                                | Se deve injetar automaticamente a data atual no prompt do agente. Padrão: False.                          |
 | **Date Format** _(opcional)_            | `date_format`            | `str`                                 | Formato de data utilizado quando `inject_date` está ativo. Padrão: "%Y-%m-%d" (formato ISO).              |
 | **Reasoning** _(opcional)_              | `reasoning`              | `bool`                                | Se o agente deve refletir e criar um plano antes de executar uma tarefa. Padrão: False.                   |
 | **Max Reasoning Attempts** _(opcional)_ | `max_reasoning_attempts` | `Optional[int]`                       | Número máximo de tentativas de raciocínio antes de executar a tarefa. Se None, tentará até estar pronto.  |
@@ -274,7 +274,7 @@ strategic_agent = Agent(
     role="Analista de Mercado",
     goal="Acompanhar movimentos do mercado com referências de datas precisas e planejamento estratégico",
     backstory="Especialista em análise financeira sensível ao tempo e relatórios estratégicos",
-    inject_date=True,  # Injeta automaticamente a data atual nas tarefas
+    inject_date=True,  # Injeta automaticamente a data atual no prompt
     date_format="%d de %B de %Y",  # Exemplo: "21 de maio de 2025"
     reasoning=True,  # Ativa planejamento estratégico
     max_reasoning_attempts=2,  # Limite de iterações de planejamento
@@ -341,7 +341,7 @@ multimodal_agent = Agent(
 
 - `multimodal`: Habilita capacidades multimodais para processar texto e conteúdo visual
 - `reasoning`: Permite que o agente reflita e crie planos antes de executar tarefas
-- `inject_date`: Injeta a data atual automaticamente nas descrições das tarefas
+- `inject_date`: Injeta a data atual automaticamente no prompt do agente
 
 #### Templates
 

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

@@ -55,6 +55,16 @@ crewai create flow my_new_flow
 
 Por padrão, `crewai create crew` cria um projeto JSON-first com `crew.jsonc` e `agents/*.jsonc`. Use `crewai create crew my_new_crew --classic` somente quando quiser o scaffold antigo em Python/YAML com `crew.py`, `config/agents.yaml` e `config/tasks.yaml`.
 
+#### Aliases de flags obsoletas
+
+As flags antigas em snake_case ainda funcionam, mas ficam ocultas no `--help`. Prefira as formas em kebab-case documentadas em cada seção de comando abaixo.
+
+| Obsoleto | Use em vez disso |
+| :--- | :--- |
+| `--skip_provider` (em `crewai create crew`) | `--skip-provider` |
+| `--n_iterations` (em `crewai train`, `crewai test`) | `--n-iterations` |
+| `--task_id` (em `crewai replay`) | `--task-id` |
+
 ### 2. Version
 
 Mostre a versão instalada do CrewAI.
@@ -80,7 +90,7 @@ Treine o crew por um número específico de iterações.
 crewai train [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: Número de iterações para treinar o crew (padrão: 5)
+- `-n, --n-iterations INTEGER`: Número de iterações para treinar o crew (padrão: 5)
 - `-f, --filename TEXT`: Caminho para um arquivo customizado para treinamento (padrão: "trained_agents_data.pkl")
 
 Exemplo:
@@ -113,7 +123,7 @@ Reexecute a execução do crew a partir de uma tarefa específica.
 crewai replay [OPTIONS]
 ```
 
-- `-t, --task_id TEXT`: Reexecuta o crew a partir deste task ID, incluindo todas as tarefas subsequentes
+- `-t, --task-id TEXT`: Reexecuta o crew a partir deste task ID, incluindo todas as tarefas subsequentes
 
 Exemplo:
 
@@ -160,7 +170,7 @@ Teste o crew e avalie os resultados.
 crewai test [OPTIONS]
 ```
 
-- `-n, --n_iterations INTEGER`: Número de iterações para testar o crew (padrão: 3)
+- `-n, --n-iterations INTEGER`: Número de iterações para testar o crew (padrão: 3)
 - `-m, --model TEXT`: Modelo LLM para executar os testes no Crew (padrão: "gpt-4o-mini")
 
 Exemplo:

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

@@ -322,6 +322,8 @@ Caches podem ser utilizados para armazenar resultados de execuções de ferramen
 
 Após a execução da crew, você pode acessar o atributo `usage_metrics` para visualizar as métricas de uso do modelo de linguagem (LLM) para todas as tasks executadas pela crew. Isso fornece insights sobre eficiência operacional e oportunidades de melhoria.
 
+`total_tokens` é o total faturado (`prompt_tokens + completion_tokens`). Campos de breakdown como `cached_prompt_tokens` e `cache_creation_tokens` descrevem subconjuntos já incluídos nesses totais e não são somados novamente a `total_tokens`. Consulte a seção **UsageMetrics field semantics** na documentação do conceito Flows para o contrato completo.
+
 ```python Code
 # Acessar as métricas de uso da crew
 crew = Crew(agents=[agent1, agent2], tasks=[task1, task2])

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

@@ -260,6 +260,24 @@ print(flow.usage_metrics)
   rollup **completo** de tokens da execução do Flow.
 </Note>
 
+### Semântica dos campos UsageMetrics
+
+O objeto [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) retornado usa um contrato neutro em relação ao provedor:
+
+| Campo | Significado |
+| --- | --- |
+| `total_tokens` | Total faturado: `prompt_tokens + completion_tokens` |
+| `prompt_tokens` | Total de tokens de entrada/prompt faturados para a requisição |
+| `completion_tokens` | Tokens de saída/conclusão faturados para a requisição |
+| `cached_prompt_tokens` | Subconjunto de leitura de cache dos tokens de prompt (apenas breakdown) |
+| `cache_creation_tokens` | Subconjunto de escrita de cache dos tokens de prompt (apenas breakdown, Anthropic) |
+| `reasoning_tokens` | Subconjunto de raciocínio/pensamento quando o provedor reporta separadamente (apenas breakdown) |
+| `successful_requests` | Número de chamadas LLM agregadas |
+
+Campos de breakdown como `cached_prompt_tokens`, `cache_creation_tokens` e `reasoning_tokens` **não** são somados sobre `total_tokens` — eles descrevem porções já incluídas em `prompt_tokens` ou `completion_tokens`.
+
+Para Anthropic, os contadores de leitura e escrita de cache são incorporados em `prompt_tokens`, de modo que workloads em cache são totalmente refletidos em `total_tokens`. Provedores no estilo OpenAI já incluem a entrada em cache dentro de `prompt_tokens`; o CrewAI expõe a porção em cache separadamente para visibilidade.
+
 Cada campo do [`UsageMetrics`](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai/src/crewai/types/usage_metrics.py) retornado representa a soma de todas as chamadas de LLM feitas em uma única invocação de `flow.kickoff()`. Os contadores são resetados a cada novo `kickoff()` (e em cada iteração de `kickoff_for_each`), de modo que execuções sucessivas não duplicam o total. A propriedade é segura para ser lida em qualquer momento após o `kickoff()`; lê-la durante a execução retorna o total parcial acumulado até aquele instante.
 
 ## Gerenciamento de Estado em Flows

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

@@ -270,6 +270,22 @@ Nesta seção, você encontrará exemplos detalhados que ajudam a selecionar, co
     )
     ```
 
+    **Uso de tokens e prompt caching:**
+
+    A Anthropic reporta a entrada faturada em contadores separados — `input_tokens` (não em cache), `cache_read_input_tokens` e `cache_creation_input_tokens`. O CrewAI incorpora os três em `prompt_tokens` (e no `input_tokens` nativo nas respostas do provedor) para que `total_tokens` reflita o uso faturado completo em workloads em cache.
+
+    `cached_prompt_tokens` registra a porção de leitura de cache apenas como breakdown; ela já está incluída em `prompt_tokens` e não deve ser somada novamente a `total_tokens`. `cache_creation_tokens` registra escritas de cache da mesma forma.
+
+    ```python Code
+    usage = llm.get_token_usage_summary()
+    # total_tokens == prompt_tokens + completion_tokens
+    # prompt_tokens includes cache read + cache write for Anthropic
+    ```
+
+    Consulte a seção **UsageMetrics field semantics** na documentação do
+    conceito Flows para o contrato neutro em relação ao provedor usado por
+    `crew.usage_metrics` e `flow.usage_metrics`.
+
     Consulte a [visão geral dos modelos](https://platform.claude.com/docs/en/about-claude/models/overview) da Anthropic para obter IDs e capacidades atuais e revise a [tabela de descontinuação](https://platform.claude.com/docs/en/about-claude/model-deprecations) antes de fixar um modelo em produção.
   </Accordion>
 

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

@@ -20,7 +20,7 @@ crewai test
 Se quiser rodar mais iterações ou utilizar um modelo diferente, você pode especificar os parâmetros assim:
 
 ```bash
-crewai test --n_iterations 5 --model gpt-4o
+crewai test --n-iterations 5 --model gpt-4o
 ```
 
 ou usando as formas abreviadas:
@@ -29,6 +29,11 @@ ou usando as formas abreviadas:
 crewai test -n 5 -m gpt-4o
 ```
 
+<Note>
+  A flag antiga `--n_iterations` ainda funciona, mas está obsoleta e oculta no
+  `--help`. Use `--n-iterations` (ou `-n`) em vez disso.
+</Note>
+
 Ao executar o comando `crewai test`, a crew será executada pelo número especificado de iterações, e as métricas de desempenho serão exibidas ao final da execução.
 
 Uma tabela de pontuações ao final mostrará o desempenho da crew em relação às seguintes métricas:

docs/edge/pt-BR/learn/execution-boundary-hooks.mdx

@@ -0,0 +1,211 @@
+---
+title: Hooks de Fronteira de Execução
+description: Intercepte o início, as entradas, a saída e o fim de execuções de crews e flows com o decorator @on
+mode: "wide"
+---
+
+Os hooks de fronteira de execução interceptam as bordas mais externas de uma
+execução — antes de qualquer trabalho começar, quando as entradas são
+resolvidas, quando o resultado final está pronto e quando a execução termina.
+Eles disparam tanto para crews quanto para flows e são o lugar certo para
+verificações de política no nível da execução, reescrita de entradas e
+sanitização de saídas.
+
+## Visão Geral
+
+Quatro pontos de interceptação cobrem as fronteiras:
+
+| Ponto | Quando | `ctx.payload` |
+|-------|--------|---------------|
+| `EXECUTION_START` | Uma crew ou flow está prestes a começar | `dict` de entradas |
+| `INPUT` | Entradas resolvidas para a execução | `dict` de entradas |
+| `OUTPUT` | O resultado final está pronto | o objeto de saída |
+| `EXECUTION_END` | A execução terminou (sucesso ou falha) | o objeto de saída, ou `None` em caso de falha |
+
+Para uma crew, o payload de saída é um `CrewOutput`. Para um flow, é o
+resultado final do método do flow.
+
+## Assinatura do Hook
+
+```python
+from crewai.hooks import on, HookAborted, InterceptionPoint
+
+@on(InterceptionPoint.EXECUTION_START)
+def boundary_hook(ctx) -> Any | None:
+    # Mutate ctx.payload in place, or
+    # return a non-None value to replace it, or
+    # raise HookAborted(reason, source) to stop the run
+    return None
+```
+
+Hooks de fronteira seguem o contrato padrão: prosseguir (`return None`), mutar
+in place, substituir retornando um valor, ou abortar lançando `HookAborted`.
+Um abort em qualquer fronteira propaga para fora do `kickoff()` com seu
+motivo.
+
+## Esquema de Contexto
+
+Cada ponto recebe um contexto tipado. Todos os contextos compartilham os
+campos base:
+
+```python
+class InterceptionContext:
+    payload: Any            # The interceptable value (see table above)
+    agent: Any = None       # Not populated at execution boundaries
+    agent_role: str | None  # Not populated at execution boundaries
+    task: Any = None        # Not populated at execution boundaries
+    crew: Any = None        # The Crew instance (crew runs only)
+    flow: Any = None        # The Flow instance (flow runs only)
+```
+
+Os contextos de cada ponto adicionam um alias nomeado para o payload:
+
+```python
+class ExecutionStartContext(InterceptionContext):
+    inputs: dict            # Same dict as payload
+
+class InputContext(InterceptionContext):
+    inputs: dict            # Same dict as payload
+
+class OutputContext(InterceptionContext):
+    output: Any             # The output object
+
+class ExecutionEndContext(InterceptionContext):
+    output: Any                    # The output object (None when status == "failed")
+    status: str                    # "completed" or "failed"
+    error: BaseException | None    # The exception when status == "failed"
+```
+
+<Note>
+`ctx.inputs` é um alias para o dict de entradas **original**, então edições in
+place por qualquer um dos nomes são equivalentes. Se um hook anterior
+*substituiu* o payload retornando um novo dict, apenas `ctx.payload` é
+reassociado — sempre leia e escreva `ctx.payload` quando hooks puderem
+encadear.
+</Note>
+
+## Execuções de Crew vs. Execuções de Flow
+
+Hooks de fronteira disparam em ambos os runtimes, e a execução de uma crew
+roda internamente sobre um runtime de flow. Durante um `crew.kickoff()`, um
+hook de fronteira global portanto dispara para a fronteira da crew
+(`ctx.crew` definido, `ctx.flow` `None`) **e** para o flow interno
+(`ctx.flow` definido, `ctx.crew` `None`). Discrimine pelo runtime:
+
+```python
+@on(InterceptionPoint.OUTPUT)
+def crew_output_only(ctx):
+    if ctx.crew is None:
+        return None  # Skip the internal flow (or a bare flow)
+    ctx.payload.raw = ctx.payload.raw.strip()
+```
+
+## Casos de Uso Comuns
+
+### Verificação de Política no Início
+
+```python
+@on(InterceptionPoint.EXECUTION_START)
+def enforce_policy(ctx):
+    if ctx.crew is not None and not ctx.payload.get("authorized"):
+        raise HookAborted(reason="unauthorized execution", source="access-control")
+```
+
+### Reescrita de Entradas
+
+```python
+@on(InterceptionPoint.INPUT)
+def add_defaults(ctx):
+    if ctx.crew is None:
+        return None
+    ctx.payload.setdefault("locale", "en-US")
+    ctx.payload["topic"] = ctx.payload["topic"].strip().lower()
+```
+
+Entradas reescritas fluem para a interpolação de tasks, então a execução se
+comporta como se tivesse sido iniciada com o dict modificado.
+
+Prefira `INPUT` para reescrita e trate `EXECUTION_START` como o gate de
+allow/deny. Reescritas em `EXECUTION_START` continuam sendo honradas — em
+crews elas também alimentam os callbacks de `before_kickoff`; em flows elas
+se aplicam exatamente como uma reescrita de `INPUT`.
+
+### Sanitização de Saída
+
+```python
+import re
+
+@on(InterceptionPoint.OUTPUT)
+def redact_emails(ctx):
+    if ctx.crew is None:
+        return None
+    ctx.payload.raw = re.sub(
+        r"\b[\w.+-]+@[\w-]+\.[\w.]+\b", "[EMAIL-REDACTED]", ctx.payload.raw
+    )
+```
+
+`OUTPUT` roda antes de `EXECUTION_END`, e ambos veem o payload (possivelmente
+substituído) de hooks anteriores; o valor final reescrito é o que `kickoff()`
+retorna.
+
+### Observando Falhas
+
+`EXECUTION_END` dispara exatamente uma vez por execução, tanto em sucesso
+quanto em falha. Quando a execução lança uma exceção — um erro de task, uma
+exceção de método de flow ou um `HookAborted` de um ponto anterior — o hook
+recebe `status="failed"` com a exceção em `ctx.error`, e a exceção original
+ainda propaga para fora do `kickoff()` sem alterações:
+
+```python
+@on(InterceptionPoint.EXECUTION_END)
+def report_outcome(ctx):
+    if ctx.status == "failed":
+        notify_policy_engine(status="failed", error=repr(ctx.error))
+    else:
+        notify_policy_engine(status="completed")
+```
+
+Duas ressalvas: `EXECUTION_END` não dispara quando `EXECUTION_START` nunca foi
+despachado (um abort no início significa que a fronteira nunca abriu, então
+não há fim para parear), e lançar `HookAborted` de um dispatch de
+`EXECUTION_END` no caminho de falha é ignorado — não resta nada para abortar,
+e o erro original prevalece.
+
+## Ordenação
+
+Para uma execução de crew, a ordem de fronteira é:
+
+```
+EXECUTION_START → before_kickoff callbacks → INPUT → tasks execute → OUTPUT → EXECUTION_END
+```
+
+Para uma execução de flow, os hooks de fronteira resolvem as entradas antes
+de os eventos de ciclo de vida começarem:
+
+```
+EXECUTION_START → INPUT → FlowStartedEvent → flow methods execute → OUTPUT → EXECUTION_END → FlowFinishedEvent
+```
+
+`FlowStartedEvent` carrega as entradas resolvidas pelos hooks, e reescrever
+`inputs["id"]` em um hook de fronteira redireciona a restauração de estado.
+Um abort em `EXECUTION_START` ainda aparece como `FlowStartedEvent` seguido
+de `FlowFailedEvent`, emitidos no momento do abort com o payload como
+resolvido pelos hooks que rodaram antes dele.
+
+Hooks no mesmo ponto rodam em ordem de registro, hooks globais primeiro,
+depois hooks com escopo de crew. A telemetria (`HookDispatchedEvent`) é
+emitida por dispatch.
+
+## Gerenciando Hooks em Testes
+
+```python
+from crewai.hooks import clear_all_hooks
+
+clear_all_hooks()  # Clears every point, including boundaries
+```
+
+## Documentação Relacionada
+
+- [Visão Geral dos Hooks de Execução →](/edge/pt-BR/learn/execution-hooks)
+- [Hooks de Chamada LLM →](/edge/pt-BR/learn/llm-hooks)
+- [Hooks de Chamada de Ferramenta →](/edge/pt-BR/learn/tool-hooks)

docs/edge/pt-BR/telemetry.mdx

@@ -34,6 +34,20 @@ os.environ['CREWAI_DISABLE_TELEMETRY'] = 'true'
 os.environ['OTEL_SDK_DISABLED'] = 'true'
 ```
 
+### Isolamento da sua própria configuração do OpenTelemetry
+
+A telemetria do CrewAI roda em seu próprio `TracerProvider` privado e nunca se
+registra como o provider global. Isso mantém as duas direções separadas:
+
+- Spans de outras bibliotecas instrumentadas no seu processo — frameworks web,
+  clientes de banco de dados, clientes HTTP — nunca são enviados ao CrewAI.
+- Os spans de telemetria do CrewAI nunca são enviados ao seu backend de
+  observabilidade, portanto não aparecerão no Langfuse, Braintrust, Phoenix ou
+  em qualquer outro coletor que você configurar.
+
+As integrações de observabilidade não são afetadas: elas instrumentam o CrewAI
+por meio do próprio tracer provider, que é independente do descrito aqui.
+
 ### Explicação dos Dados:
 | Padrão | Dados                                      | Razão e Especificidades                                                                                                                         |
 |--------|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
@@ -45,7 +59,10 @@ os.environ['OTEL_SDK_DISABLED'] = 'true'
 | Sim    | Dados de Execução de Testes                | Inclui: chave e ID aleatórias do crew, número de iterações, nome do modelo usado, score de qualidade (float), tempo de execução (em segundos). Tudo não pessoal.         |
 | 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. 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    | Tentativa de Deploy do Crew pelo CLI do crewAI | Inclui: O fato de um deploy estar sendo realizado e o crew id, e se está tentando buscar logs, sem mais dados.                          |
+| 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    | Ambiente de Execução                       | Inclui: qual assistente de código com IA está executando o processo, se houver (um de uma lista fixa como `claude_code`, `codex`, `cursor` ou `unknown`), onde o processo é executado (um de uma lista fixa como `ci`, `container`, `serverless`, `interactive`) e o `project_id` do seu `pyproject.toml` quando houver um configurado. A detecçã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. |
 | Não    | Dados Expandidos do Agente                 | Inclui: descrição do objetivo, texto da história, identificador de arquivo i18n prompt. Usuários devem garantir que não haja info pessoal nesses campos de texto.            |
 | Não    | Informações Detalhadas da Tarefa           | Inclui: descrição da tarefa, descrição do resultado esperado, referências de contexto. Usuários devem garantir que não haja info pessoal nessas áreas.           |
 | Não    | Informações de Ambiente                    | Inclui: plataforma, release, sistema, versão e quantidade de CPUs. Exemplo: 'Windows 10', 'x86_64'. Sem dados pessoais.                       |

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

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

docs/v1.15.12/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.12/ar/api-reference/kickoff.mdx

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

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

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

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

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

docs/v1.15.12/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.12/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.12/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.12/ar/concepts/cli.mdx

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

docs/v1.15.12/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.12/ar/concepts/crews.mdx

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

docs/v1.15.12/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.12/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.12/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-2.0-flash")
+
+# Pass a pre-configured LLM instance with custom settings
+llm = LLM(model="gpt-4o", temperature=0)
+memory = Memory(llm=llm)
+```
+
+يتم تهيئة LLM **بشكل كسول** -- يتم إنشاؤه فقط عند الحاجة لأول مرة. هذا يعني أن `Memory()` لا يفشل أبدًا في وقت الإنشاء، حتى لو لم تكن مفاتيح API مُعيّنة. تظهر الأخطاء فقط عند استدعاء LLM فعليًا (مثلاً عند الحفظ بدون نطاق/فئات صريحة، أو أثناء الاسترجاع العميق).
+
+للتشغيل المحلي/الخاص بالكامل، استخدم نموذجًا محليًا لكل من LLM والمُضمِّن:
+
+```python
+memory = Memory(
+    llm="ollama/llama3.2",
+    embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}},
+)
+```
+
+
+## واجهة التخزين
+
+- **الافتراضي**: LanceDB، مخزّن تحت `./.crewai/memory` (أو `$CREWAI_STORAGE_DIR/memory` إذا تم تعيين متغير البيئة، أو المسار الذي تمرره كـ `storage="path/to/dir"`).
+- **واجهة مخصصة**: نفّذ بروتوكول `StorageBackend` (انظر `crewai.memory.storage.backend`) ومرّر مثيلًا إلى `Memory(storage=your_backend)`.
+
+
+## الاستكشاف
+
+فحص التسلسل الهرمي للنطاقات والفئات والسجلات:
+
+```python
+memory.tree()                        # Formatted tree of scopes and record counts
+memory.tree("/project", max_depth=2) # Subtree view
+memory.info("/project")              # ScopeInfo: record_count, categories, oldest/newest
+memory.list_scopes("/")              # Immediate child scopes
+memory.list_categories()             # Category names and counts
+memory.list_records(scope="/project/alpha", limit=20)  # Records in a scope, newest first
+```
+
+
+## سلوك الفشل
+
+إذا فشل LLM أثناء التحليل (خطأ شبكة، حد معدل، استجابة غير صالحة)، تتدهور الذاكرة بسلاسة:
+
+- **تحليل الحفظ** -- يتم تسجيل تحذير ولا يزال يتم تخزين الذاكرة مع النطاق الافتراضي `/`، فئات فارغة، وأهمية `0.5`.
+- **استخراج الذكريات** -- يتم تخزين المحتوى الكامل كذاكرة واحدة حتى لا يُفقد شيء.
+- **تحليل الاستعلام** -- يتراجع الاسترجاع إلى اختيار نطاق بسيط وبحث متجهي حتى تستمر في الحصول على نتائج.
+
+لا يتم رفع أي استثناء لفشل التحليل هذه؛ فقط فشل التخزين أو المُضمِّن سيرفع استثناءً.
+
+
+## ملاحظة حول الخصوصية
+
+يتم إرسال محتوى الذاكرة إلى LLM المُعدّ للتحليل (النطاق/الفئات/الأهمية عند الحفظ، تحليل الاستعلام والاسترجاع العميق الاختياري). للبيانات الحساسة، استخدم LLM محليًا (مثل Ollama) أو تأكد من أن مزودك يلبي متطلبات الامتثال الخاصة بك.
+
+
+## أحداث الذاكرة
+
+جميع عمليات الذاكرة تُصدر أحداثًا مع `source_type="unified_memory"`. يمكنك الاستماع للتوقيت والأخطاء والمحتوى.
+
+| الحدث | الوصف | الخصائص الرئيسية |
+| :---- | :---------- | :------------- |
+| **MemoryQueryStartedEvent** | بداية الاستعلام | `query`, `limit` |
+| **MemoryQueryCompletedEvent** | نجاح الاستعلام | `query`, `results`, `query_time_ms` |
+| **MemoryQueryFailedEvent** | فشل الاستعلام | `query`, `error` |
+| **MemorySaveStartedEvent** | بداية الحفظ | `value`, `metadata` |
+| **MemorySaveCompletedEvent** | نجاح الحفظ | `value`, `save_time_ms` |
+| **MemorySaveFailedEvent** | فشل الحفظ | `value`, `error` |
+| **MemoryRetrievalStartedEvent** | بداية استرجاع الوكيل | `task_id` |
+| **MemoryRetrievalCompletedEvent** | اكتمال استرجاع الوكيل | `task_id`, `memory_content`, `retrieval_time_ms` |
+
+مثال: مراقبة وقت الاستعلام:
+
+```python
+from crewai.events import BaseEventListener, MemoryQueryCompletedEvent
+
+class MemoryMonitor(BaseEventListener):
+    def setup_listeners(self, crewai_event_bus):
+        @crewai_event_bus.on(MemoryQueryCompletedEvent)
+        def on_done(source, event):
+            if getattr(event, "source_type", None) == "unified_memory":
+                print(f"Query '{event.query}' completed in {event.query_time_ms:.0f}ms")
+```
+
+
+## استكشاف المشاكل
+
+**الذاكرة لا تستمر؟**
+- تأكد من أن مسار التخزين قابل للكتابة (الافتراضي `./.crewai/memory`). مرّر `storage="./your_path"` لاستخدام مجلد مختلف، أو عيّن متغير البيئة `CREWAI_STORAGE_DIR`.
+- عند استخدام فريق، تأكد من تعيين `memory=True` أو `memory=Memory(...)`.
+
+**الاسترجاع بطيء؟**
+- استخدم `depth="shallow"` لسياق الوكيل الروتيني. احتفظ بـ `depth="deep"` للاستعلامات المعقدة.
+- زد `query_analysis_threshold` لتخطي تحليل LLM لمزيد من الاستعلامات.
+
+**أخطاء تحليل LLM في السجلات؟**
+- لا تزال الذاكرة تحفظ/تسترجع بإعدادات افتراضية آمنة. تحقق من مفاتيح API وحدود المعدل وتوفر النموذج إذا كنت تريد تحليل LLM كاملاً.
+
+**أخطاء حفظ خلفية في السجلات؟**
+- عمليات حفظ الذاكرة تعمل في خيط خلفي. تُصدر الأخطاء كـ `MemorySaveFailedEvent` لكنها لا تعطل الوكيل. تحقق من السجلات للسبب الجذري (عادة مشاكل اتصال LLM أو المُضمِّن).
+
+**تعارضات الكتابة المتزامنة؟**
+- عمليات LanceDB مُتسلسلة بقفل مشترك وتُعاد تلقائيًا عند التعارض. هذا يتعامل مع مثيلات `Memory` المتعددة التي تشير إلى نفس قاعدة البيانات (مثل ذاكرة وكيل + ذاكرة فريق). لا حاجة لإجراء.
+
+**تصفح الذاكرة من الطرفية:**
+```bash
+crewai memory                              # Opens the TUI browser
+crewai memory --storage-path ./my_memory   # Point to a specific directory
+```
+
+**إعادة تعيين الذاكرة (مثلاً للاختبارات):**
+```python
+crew.reset_memories(command_type="memory")  # Resets unified memory
+# Or on a Memory instance:
+memory.reset()                    # All scopes
+memory.reset(scope="/project/old")  # Only that subtree
+```
+
+
+## مرجع الإعداد
+
+جميع الإعدادات تُمرر كمعاملات كلمة مفتاحية إلى `Memory(...)`. كل معامل له قيمة افتراضية معقولة.
+
+| المعامل | الافتراضي | الوصف |
+| :--- | :--- | :--- |
+| `llm` | `"gpt-4o-mini"` | LLM للتحليل (اسم نموذج أو مثيل `BaseLLM`). |
+| `storage` | `"lancedb"` | واجهة التخزين (`"lancedb"`، سلسلة مسار، أو مثيل `StorageBackend`). |
+| `embedder` | `None` (افتراضي OpenAI) | المُضمِّن (قاموس إعداد، دالة قابلة للاستدعاء، أو `None` لافتراضي OpenAI). |
+| `recency_weight` | `0.3` | وزن الحداثة في الدرجة المركبة. |
+| `semantic_weight` | `0.5` | وزن التشابه الدلالي في الدرجة المركبة. |
+| `importance_weight` | `0.2` | وزن الأهمية في الدرجة المركبة. |
+| `recency_half_life_days` | `30` | أيام لتنصيف درجة الحداثة (اضمحلال أُسي). |
+| `consolidation_threshold` | `0.85` | التشابه الذي يُشغّل فوقه التوحيد عند الحفظ. عيّن إلى `1.0` للتعطيل. |
+| `consolidation_limit` | `5` | أقصى عدد سجلات حالية للمقارنة أثناء التوحيد. |
+| `default_importance` | `0.5` | الأهمية المُعيّنة عندما لا تُوفَّر ويتم تخطي تحليل LLM. |
+| `batch_dedup_threshold` | `0.98` | تشابه جيب التمام لإسقاط النسخ شبه المكررة داخل دفعة `remember_many()`. |
+| `confidence_threshold_high` | `0.8` | ثقة الاسترجاع التي تُعاد فوقها النتائج مباشرة. |
+| `confidence_threshold_low` | `0.5` | ثقة الاسترجاع التي يُشغّل تحتها استكشاف أعمق. |
+| `complex_query_threshold` | `0.7` | للاستعلامات المعقدة، استكشف أعمق تحت هذه الثقة. |
+| `exploration_budget` | `1` | عدد جولات الاستكشاف المدفوعة بـ LLM أثناء الاسترجاع العميق. |
+| `query_analysis_threshold` | `200` | الاستعلامات الأقصر من هذا (بالأحرف) تتخطى تحليل LLM أثناء الاسترجاع العميق. |

docs/v1.15.12/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.12/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.12/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.12/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.12/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.12/ar/concepts/testing.mdx

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

docs/v1.15.12/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.12/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.12/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.12/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.12/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/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.12/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.12/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.12/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.12/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.12/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.12/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-2.0-flash-001`.
+
+## الخطوة 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.12/ar/guides/flows/conversational-flows.mdx

@@ -0,0 +1,473 @@
+---
+title: تدفقات المحادثة
+description: أنشئ تطبيقات دردشة متعددة الجولات مع kickoff لكل جولة وسجل الرسائل وتوجيه النية والتتبع وجسور WebSocket.
+icon: comments
+mode: "wide"
+---
+
+## نظرة عامة
+
+تعامل التطبيقات المحادثية مع كل سطر من المستخدم كـ **تشغيل flow جديد** بنفس **معرّف الجلسة**. توفر CrewAI مساعدات لسجل الرسائل وتصنيف النية الاختياري وتأجيل التتبع وجسور الواجهة، إضافة إلى REPL محلي `flow.chat()` للتدفقات المحادثية.
+
+| المفهوم | التنفيذ |
+|---------|---------|
+| معرّف الجلسة | `handle_turn(..., session_id=...)` → `kickoff(inputs={"id": ...})` → `state.id` |
+| سطر المستخدم | `handle_turn(message)` يضيف الرسالة إلى `state.messages` قبل تشغيل الرسم |
+| اكتمال الجولة | `FlowFinished` لهذا **التشغيل** فقط؛ تستمر المحادثة في `handle_turn` التالي |
+| تتبع الجلسة | `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` محادثي |
+| `chat()` | REPL محلي في الطرفية لـ `Flow` محادثي |
+| `kickoff(inputs={...})` | تشغيل متقدم للـ flow بدون معالجة جولة محادثية |
+| `ask()` | مطالبة حاجزة **داخل** خطوة واحدة |
+| `@human_feedback` | الموافقة/الرفض على **مخرجات خطوة** — وليس السطر التالي |
+| `ChatSession.handle_turn(...)` | طبقة نقل فوق `handle_turn` |
+
+## بداية سريعة
+
+```python
+from uuid import uuid4
+
+from crewai import Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+    ConversationConfig,
+    ConversationState,
+)
+
+
+@ConversationConfig(defer_trace_finalization=True)
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    def route_turn(self, context):
+        message = (self.state.current_user_message or "").lower()
+        if "طلب" in message or "order" in message:
+            return "order"
+        if "وداع" in message or "goodbye" in message:
+            return "goodbye"
+        return "help"
+
+    @listen("order")
+    def handle_order(self):
+        reply = "طلبك في الطريق."
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("help")
+    def handle_help(self):
+        reply = "كيف يمكنني المساعدة؟"
+        self.append_assistant_message(reply)
+        return reply
+
+    @listen("goodbye")
+    def handle_goodbye(self):
+        reply = "وداعاً!"
+        self.append_assistant_message(reply)
+        return reply
+
+
+session_id = str(uuid4())
+flow = SupportFlow()
+
+try:
+    flow.handle_turn("أين طلبي؟", session_id=session_id)
+    flow.handle_turn("وماذا عن الإرجاع؟", session_id=session_id)
+finally:
+    flow.finalize_session_traces()
+```
+
+## دورة حياة الجولة
+
+كل `handle_turn` يشغّل:
+
+1. **`_configure_conversational_kickoff`** — دمج `session_id` / `user_message` في `inputs` وتطبيق `ConversationalConfig`.
+2. **استعادة الحالة** — عند وجود `inputs["id"]` و`@persist`.
+3. **`FlowStarted`** — في أول جولة للجلسة المؤجلة فقط.
+4. **`prepare_conversational_turn`** — إضافة رسالة المستخدم و`last_user_message` وتصنيف اختياري.
+5. **تنفيذ الرسم** — `@start` → `@router` → معالجات `@listen`.
+6. **نهاية التشغيل** — يُتخطى `flow_finished` والتتبع لكل جولة عند التأجيل؛ `Agent.kickoff()` / crews لا تغلق دفعة الأب.
+
+استدعِ **`append_assistant_message(reply)`** في المعالجات. سطر المستخدم محفوظ عبر `handle_turn` — لا تُضفه مرة أخرى.
+
+## `ConversationalConfig` (افتراضيات على مستوى الصنف)
+
+عيّن على صنف `Flow` كـ `conversational_config: ClassVar[ConversationalConfig | None]`.
+
+| الحقل | الافتراضي | الغرض |
+|-------|-----------|--------|
+| `default_intents` | `None` | تسميات outcome للتصنيف التلقائي قبل kickoff |
+| `intent_llm` | `None` | نموذج التصنيف (مطلوب عند وجود intents) |
+| `interactive_prompt` | `"You: "` | مطالبة `kickoff(interactive=True)` |
+| `interactive_timeout` | `None` | مهلة لكل سطر في الوضع التفاعلي |
+| `exit_commands` | `exit`, `quit` | كلمات إنهاء الوضع التفاعلي |
+| `defer_trace_finalization` | `True` | إبقاء دفعة trace واحدة مفتوحة بين الجولات |
+
+يمكن التجاوز لكل kickoff عبر `intents=` و`intent_llm=`.
+
+## `ChatState` (شكل الحالة الموصى به للحفظ)
+
+```python
+from crewai.flow import ChatState
+
+
+class MyChatState(ChatState):
+    # موروث: id, messages, last_user_message, last_intent, session_ready
+    research_turn_count: int = 0
+    custom_flag: bool = False
+```
+
+| الحقل | الدور |
+|-------|------|
+| `id` | UUID الجلسة (مثل `session_id` / `inputs["id"]`) |
+| `messages` | قائمة `{role, content}` لسجل LLM |
+| `last_user_message` | آخر سطر مستخدم في هذه الجولة |
+| `last_intent` | تسمية المسار بعد التصنيف (إن وُجد) |
+| `session_ready` | علم bootstrap لمرة واحدة |
+
+`ConversationalInputs` هو `TypedDict` لـ `kickoff(inputs={...})`: `id`, `user_message`, `last_intent`.
+
+## API المحادثة على `Flow`
+
+### معاملات `kickoff` / `kickoff_async`
+
+| المعامل | الغرض |
+|---------|--------|
+| `user_message` | نص هذه الجولة (أو `{"role": "user", "content": "..."}`) |
+| `session_id` | UUID المحادثة → `inputs["id"]` / `state.id` |
+| `intents` | تسميات outcome لـ `classify_intent` قبل kickoff |
+| `intent_llm` | LLM للتصنيف (مطلوب مع `intents`) |
+| `interactive` | حلقة CLI عبر `ask()` (للعروض المحلية فقط) |
+| `interactive_prompt` | مطالبة الوضع التفاعلي |
+| `interactive_timeout` | مهلة `ask()` لكل سطر |
+| `exit_commands` | كلمات إنهاء الوضع التفاعلي |
+| `inputs` | حقول حالة إضافية |
+| `restore_from_state_id` | استنساخ من flow محفوظ آخر |
+
+### سمات المثيل
+
+| السمة | الغرض |
+|-------|--------|
+| `conversational_config` | افتراضيات `ConversationalConfig` على مستوى الصنف |
+| `defer_trace_finalization` | علم المثيل؛ يُضبط تلقائياً من config عند kickoff |
+| `suppress_flow_events` | يخفي لوحات console؛ **التتبع يُسجّل** |
+| `stream` | بث؛ مع `ChatSession.handle_turn(..., stream=True)` |
+
+### طرق وخصائص
+
+| الاسم | الوصف |
+|------|--------|
+| `append_message(role, content, **extra)` | إضافة إلى `state.messages` |
+| `conversation_messages` | سجل للقراءة فقط لاستدعاءات LLM |
+| `classify_intent(text, outcomes, *, llm, context=None)` | تعيين outcome |
+| `receive_user_message(text, *, outcomes=None, llm=None)` | إضافة رسالة مستخدم؛ `last_intent` اختياري |
+| `finalize_session_traces()` | إصدار `flow_finished` المؤجل وإنهاء دفعة trace |
+| `_should_defer_trace_finalization()` | هل يُؤجل إنهاء trace لكل جولة |
+| `input_history` | سجل تدقيق مطالبات وردود `ask()` |
+
+### مساعدات الوحدة (`crewai.flow.conversation`)
+
+| الدالة | الوصف |
+|--------|--------|
+| `normalize_kickoff_inputs(...)` | دمج kwargs المحادثة في `inputs` |
+| `get_conversation_messages(flow)` | قراءة الرسائل من الحالة أو المخزن |
+| `append_message(flow, ...)` | مثل طريقة المثيل |
+| `prepare_conversational_turn(flow, ...)` | تهيئة الجولة (عادةً kickoff يستدعيها) |
+| `receive_user_message(flow, ...)` | مثل طريقة المثيل |
+| `set_state_field(flow, name, value)` | تعيين حقل dict أو Pydantic |
+| `get_conversational_config(flow)` | قراءة `conversational_config` |
+| `input_history_to_messages(entries)` | تحويل `input_history` لصيغة رسائل LLM |
+
+## أنماط توجيه النية
+
+### أ. تصنيف مسبق عبر `ConversationalConfig` (الأبسط)
+
+عيّن `default_intents` و`intent_llm`. كل kickoff يصنّف قبل `@router`؛ اقرأ `self.state.last_intent` في `route()`.
+
+### ب. تصنيف داخل `@router` (مطالبات أغنى)
+
+عيّن `default_intents=None` ليضيف kickoff الرسالة فقط. في `route()` استدعِ `classify_intent`:
+
+```python
+@router(bootstrap)
+def route(self):
+    intent = self.classify_intent(
+        self._routing_prompt(self.state.last_user_message),
+        ("GREETING", "ORDER", "RESEARCH", "GOODBYE"),
+        llm=self.conversational_config.intent_llm or "gpt-4o-mini",
+    )
+    self.state.last_intent = intent
+    return intent
+```
+
+للبحث على الويب أو أدوات متعددة الخطوات استخدم **`@listen("RESEARCH")`** مع `Agent.kickoff()` وأدوات — وليس `LLM.call()` فقط.
+
+## عندما ينتهي الـ flow ويستمر المستخدم
+
+`FlowFinished` يعني أن **تنفيذ الرسم هذا** اكتمل. تستمر المحادثة بـ `kickoff` آخر ونفس `session_id`. `@persist` يستعيد `messages` والأعلام والسياق.
+
+**نمط الحفظ:** يُفضّل `@persist` على **خطوة نهائية واحدة** (مثل `finalize`) وليس على صنف `Flow` بالكامل. الحفظ على مستوى الصنف بعد كل method قد يفقد تحديثات المعالجات في نفس الجولة.
+
+لا تستخدم `@human_feedback` لأسطر المتابعة في الدردشة إلا عند الحاجة لموافقة بشرية على مخرجات خطوة محددة.
+
+## `Flow` المحادثاتي (تجريبي)
+
+<Warning>
+  **ميزة تجريبية.** سطح `Flow` المحادثاتي (`conversational = True`،
+  `handle_turn`، `ConversationConfig`، `RouterConfig`،
+  `ConversationState`، الرسم البياني المدمج والمساعدات) يقع تحت
+  `crewai.experimental` وقد يتغير شكله قبل التخرج. ثبّت إصدار CrewAI إذا
+  كنت تعتمد على سلوك محدد، وراقب changelog للتحديثات الكاسرة. الملاحظات
+  والمشاكل مرحب بها.
+</Warning>
+
+فعّل الرسم المحادثاتي بتعيين `conversational = True` على صنف فرعي من `Flow`. عندئذٍ يُظهر `Flow` الأساسي رسم `@start` / `@router` / `converse_turn` / `end_conversation` مدمجاً، ويدير `state.messages`، ويُشغّل LLM التوجيه، ويبقي دفعة trace مفتوحة عبر الجولات. أنت تكتب **المسارات المخصصة** فقط؛ والإطار يتولى الباقي.
+
+استخدمه عندما تريد دردشة متعددة الجولات مع موجّه قائم على LLM ومعالجات لكل مسار دون توصيل دورة الحياة يدوياً. استخدم `Flow[ChatState]` (النمط الأدنى مستوى في الأعلى) عندما تحتاج تحكماً كاملاً.
+
+### مثال سريع
+
+```python
+from crewai import LLM, Flow
+from crewai.flow import listen
+from crewai.experimental.conversational import (
+    ConversationConfig,
+    ConversationState,
+    RouterConfig,
+)
+
+
+ROUTER_LLM = LLM(model="gpt-4o-mini")
+
+
+@ConversationConfig(
+    system_prompt="A multi-agent assistant for ordinary chat and tool-backed tasks.",
+    llm=ROUTER_LLM,
+    router=RouterConfig(),  # المسارات + الأوصاف تُكتشف تلقائياً من معالجات @listen
+)
+class SupportFlow(Flow[ConversationState]):
+    conversational = True
+
+    @listen("INTERNET_SEARCH")
+    def handle_internet_search(self) -> str:
+        """Fresh web research, current news, real-time lookups."""
+        ...
+        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."""
+        ...
+        self.append_assistant_message(reply)
+        return reply
+
+
+flow = SupportFlow()
+try:
+    flow.handle_turn("ماذا يمكنك أن تفعل؟")                   # يوجَّه إلى converse (مدمج)
+    flow.handle_turn("ابحث في الويب عن أخبار الذكاء الاصطناعي.")  # يوجَّه إلى INTERNET_SEARCH
+    flow.handle_turn("لخص النتيجة الأولى.")                    # يعود إلى converse
+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. بدونه، يسقط الـ flow دائماً إلى `converse`. |
+| `answer_from_history_prompt` | افتراضي الإطار | رسالة system للمسار الاختياري `answer_from_history`. |
+| `answer_from_history_llm` | `None` | يُفعّل الاختصار `answer_from_history` عند تعيينه. |
+| `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()`. |
+
+### `RouterConfig` وفهرس المسارات المُولَّد تلقائياً
+
+```python
+RouterConfig(
+    prompt="تأطير اختياري للنطاق (سياسة، صوت، شخصية).",
+    response_format=MyRoute,        # اختياري؛ يُولَّد تلقائياً عند الإغفال
+    llm=ROUTER_LLM,                  # يسقط إلى ConversationConfig.llm
+    routes=["INTERNET_SEARCH", "CREWAI_DOCS"],   # اختياري؛ يُستنتج من المستمعين
+    route_descriptions={
+        "INTERNET_SEARCH": "تجاوز الـ docstring لهذا المسار فقط.",
+    },
+    default_intent="converse",       # يُستخدم عند فشل LLM أو غيابه
+    fallback_intent="converse",      # يُستخدم عندما يعيد LLM مساراً غير صالح
+    intent_field="intent",
+)
+```
+
+تُبنى رسالة الموجّه إلى LLM تلقائياً. لكل مسار يختار الإطار وصفاً بهذا الترتيب من الأولوية:
+
+1. `RouterConfig.route_descriptions[label]` — تجاوز صريح.
+2. `Flow.builtin_route_descriptions[label]` — نص جاهز من الإطار لـ `converse` و`end` و`answer_from_history` (مصاغ لـ LLM التوجيه).
+3. أول سطر غير فارغ من docstring معالج `@listen(label)`.
+4. فارغ (المسار يظهر في الفهرس بلا وصف).
+
+عملياً، **إضافة مسار جديد = `@listen("X")` + docstring من سطر واحد**:
+
+```python
+@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`؛ سيختل التزامن لحظة إضافة معالج جديد.
+
+### المسارات المدمجة
+
+| المسار | المعالج | الغرض |
+|--------|---------|-------|
+| `converse` | `converse_turn` | معالج الدردشة الافتراضي. يستدعي `ConversationConfig.llm` بـ system prompt + التاريخ القانوني للرسائل. |
+| `end` | `end_conversation` | يضبط `state.ended = True` ويُصدر رد إنهاء. |
+| `answer_from_history` | `answer_from_history_turn` | اختياري. يُوجَّه إليه عندما يكون `ConversationConfig.answer_from_history_llm` مُعيَّناً ويمكن الإجابة على الرسالة من التاريخ فقط. |
+
+يمكنك تجاوز أي من هذه بتعريف معالج بنفس الاسم في الصنف الفرعي.
+
+### دلالات `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. يُشغّل `conversation_start` → `route_conversation` → معالج `@listen` المختار.
+4. يخزّن الموجّه قراره في `state.last_intent` (يكون مرئياً لسياق التوجيه في الجولة التالية).
+5. إذا أعاد معالجك سلسلة نصية ولم يستدعِ `append_assistant_message`، فإن `handle_turn` يُلحقها نيابةً عنك.
+
+استدعِ `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`.
+
+خصص سلوك الطرفية عبر 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
+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`؛ إعادة `None` تسقط إلى `_route_with_config(...)`.
+
+### `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"` أو قائمة بالأسماء).
+
+## التتبع عبر الجولات
+
+مع `defer_trace_finalization=True` (افتراضي في `ConversationalConfig`):
+
+- **دفعة 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()` أو `kickoff(...)`، استدعِ `finalize_session_traces()` عند انتهاء الجلسة.
+
+`suppress_flow_events=True` يخفي لوحات Rich فقط؛ أحداث trace والـ methods تُصدر.
+
+### دورة حياة trace لـ `Flow` المحادثاتي
+
+يستخدم [`Flow` المحادثاتي](#flow-المحادثاتي-تجريبي) التجريبي نفس دورة حياة tracing: `defer_trace_finalization` افتراضياً `True`، فيبقي كل `handle_turn()` أثر الجلسة مفتوحاً. أنهِ دوماً عند نهاية الجلسة — لُف حلقتك بـ `try/finally` واستدعِ `flow.finalize_session_traces()` عند الخروج. بدون ذلك، تبقى الدفعة مفتوحة وقد لا تُصدَّر آخر محادثة أبداً.
+
+## البث
+
+اضبط `stream = True` على صنف `Flow`. عندئذٍ يُصدر `kickoff(...)` أحداث `assistant_delta` (وما يرتبط بها) عبر ناقل الأحداث القياسي.
+
+## الاستيراد
+
+```python
+from crewai.flow import (
+    ChatState,
+    ConversationalConfig,
+    ConversationalInputs,
+    Flow,
+    listen,
+    persist,
+    router,
+    start,
+)
+```
+
+## مراجع
+
+- [إتقان إدارة حالة Flow](/ar/guides/flows/mastering-flow-state)
+- [أنشئ أول Flow](/ar/guides/flows/first-flow)
+- Demo: `lib/crewai/runner_conversational_flow_simple.py` — REPL بسيط مع `RESEARCH` ووكيل Exa

docs/v1.15.12/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-2.0-flash-001` أو `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.12/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.12/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.12/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.12/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.12/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.12/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>