> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkpointing

> حفظ حالة التنفيذ تلقائيا حتى تتمكن الطواقم والتدفقات والوكلاء من الاستئناف بعد الفشل.

الـ Checkpointing يحفظ لقطة من حالة التنفيذ أثناء التشغيل بحيث يمكن لطاقم أو تدفق أو وكيل الاستئناف بعد الفشل أو التفرع إلى فرع بديل.

> **[الشرح](#الشرح)**
>
> كيف يعمل الـ Checkpointing: الأحداث والتخزين والوراثة.

> **[درس تطبيقي](#درس-تطبيقي-استئناف-طاقم-فاشل)**
>
> دليل 5 دقائق: تشغيل، إيقاف، استئناف.

> **[ادلة عملية](#ادلة-عملية)**
>
> وصفات مركزة على المهام لسير العمل الشائع.

> **[المرجع](#المرجع)**
>
> `CheckpointConfig` والأحداث والمزودات وسطر الأوامر.

## الشرح

### ما هي نقطة الحفظ

تلتقط نقطة الحفظ كل ما يحتاجه CrewAI لإعادة إنشاء تشغيل أثناء سيره: الحالة الكاملة للطاقم أو التدفق أو الوكيل — التكوين، وذاكرة الوكلاء ومصادر المعرفة، وتقدم المهام، والمخرجات الوسيطة، والحالة الداخلية والسمات — إلى جانب مدخلات الـ kickoff، وسجل الأحداث حتى تلك النقطة، ومعرف نسب يربط نقطة الحفظ بالتشغيل الذي جاءت منه.

الاستعادة تعيد بناء تلك الحالة وتستمر. تتخطى المهام المكتملة، وتعاد ترطيب الذاكرة والمعرفة، ويعمل العمل التابع على نفس المخرجات التي أنتجها التشغيل الأصلي. التفرع يجري نفس الاستعادة تحت نسب جديد، بحيث يكتب الفرع الجديد والتشغيل الأصلي نقاط الحفظ جنبا إلى جنب دون أن يطمس أحدهما الآخر.

### متى تكتب نقاط الحفظ

الـ Checkpointing مدفوع بالأحداث. يشترك وقت التشغيل في الأحداث التي تحددها عبر `on_events` ويكتب نقطة حفظ عند إطلاق أحدها. الافتراضي `task_completed` ينتج نقطة حفظ لكل مهمة منتهية — توازن معقول بين الدقة واستخدام القرص. الأحداث عالية التردد مثل `llm_call_completed` متاحة للاستعادة الدقيقة لكنها تكتب ملفات أكثر بكثير.

### التخزين

يتضمن CrewAI مزودين:

* `JsonProvider` يكتب ملفا لكل نقطة حفظ. قابل للقراءة وسهل التفقد.
* `SqliteProvider` يكتب إلى قاعدة بيانات SQLite واحدة. أفضل لنقاط الحفظ عالية التردد.

كلاهما يحذف أقدم نقاط الحفظ عند تحديد `max_checkpoints`.

> [!NOTE]
>
> كتابة نقاط الحفظ بأفضل جهد. فشل نقطة حفظ يسجل لكنه لا يقاطع التشغيل.

### نموذج الوراثة

`Crew` و`Flow` و`Agent` كلها تقبل وسيط `checkpoint`. يرث الأبناء من الأب ما لم يحددوا قيمتهم الخاصة أو يمرروا `False` للانسحاب. فعل الـ Checkpointing مرة واحدة على الطاقم وتشارك كل الوكلاء، أو استبعد وكيلا واحدا بشكل انتقائي.

## درس تطبيقي: استئناف طاقم فاشل

هذا الدليل يستغرق حوالي 5 دقائق. ستشغل طاقما بمهمتين، توقفه في المنتصف، ثم تستأنف من نقطة الحفظ المحفوظة.

**1. أنشئ الطاقم مع تفعيل الـ Checkpointing**

```python theme={null}
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,
)
```

**2. شغله وأوقفه بعد المهمة الأولى**

```python theme={null}
result = crew.kickoff()
```

اضغط `Ctrl+C` بعد انتهاء المهمة الأولى. في `./.checkpoints/`، الملف بصيغة `<timestamp>_<uuid>.json` هو نقطة الحفظ.

**3. استأنف من نقطة الحفظ**

```python theme={null}
from crewai import CheckpointConfig

result = crew.kickoff(
    from_checkpoint=CheckpointConfig(
        restore_from="./.checkpoints/<timestamp>_<uuid>.json",
    ),
)
```

يتم تخطي مهمة البحث، ويعمل الكاتب على مخرجات البحث المحفوظة، وينتهي الطاقم.

## ادلة عملية

> **تفعيل الـ Checkpointing بالإعدادات الافتراضية**
>
> ```python theme={null}
> crew = Crew(agents=[...], tasks=[...], checkpoint=True)
> ```
>
> يكتب إلى `./.checkpoints/` عند كل `task_completed`.

> **تخصيص التخزين والتردد**
>
> ```python theme={null}
> from crewai import Crew, CheckpointConfig
>
> crew = Crew(
>     agents=[...],
>     tasks=[...],
>     checkpoint=CheckpointConfig(
>         location="./my_checkpoints",
>         on_events=["task_completed", "crew_kickoff_completed"],
>         max_checkpoints=5,
>     ),
> )
> ```

> **اختيار مزود التخزين**
>
> ```python JsonProvider theme={null}
> 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 theme={null}
> from crewai import Crew, CheckpointConfig
> from crewai.state import SqliteProvider
>
> crew = Crew(
>     agents=[...],
>     tasks=[...],
>     checkpoint=CheckpointConfig(
>         location="./.checkpoints.db",
>         provider=SqliteProvider(),
>         max_checkpoints=50,
>     ),
> )
> ```
>
> > [!TIP]
> >
> > SQLite يفعل وضع journal WAL للقراءات المتزامنة. يفضل لنقاط الحفظ عالية التردد.

> **استبعاد وكيل واحد**
>
> ```python theme={null}
> crew = Crew(
>     agents=[
>         Agent(role="Researcher", ...),
>         Agent(role="Writer", ..., checkpoint=False),
>     ],
>     tasks=[...],
>     checkpoint=True,
> )
> ```

> **التفرع إلى فرع جديد**
>
> `fork()` يستعيد نقطة حفظ تحت نسب جديد بحيث لا يتصادم التشغيل الجديد مع الأصلي.
>
> ```python theme={null}
> config = CheckpointConfig(restore_from="./my_checkpoints/<file>.json")
> crew = Crew.fork(config, branch="experiment-a")
> result = crew.kickoff(inputs={"strategy": "aggressive"})
> ```
>
> تسمية `branch` اختيارية؛ يتم إنشاء واحدة إذا أغفلت.

> **Checkpointing لـ Crew أو Flow أو Agent**
>
> **Crew**
>
> ```python theme={null}
> crew = Crew(
>     agents=[researcher, writer],
>     tasks=[research_task, write_task, review_task],
>     checkpoint=CheckpointConfig(location="./crew_cp"),
> )
> ```
>
> المشغل الافتراضي: `task_completed`.
>
> **Flow**
>
> ```python theme={null}
> 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()
> ```
>
> **Agent**
>
> ```python theme={null}
> 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"}])
> ```

> **كتابة نقطة حفظ يدويا**
>
> سجل معالجا على أي حدث واستدع `state.checkpoint()`.
>
> ```python Sync theme={null}
> 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 theme={null}
> 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}")
> ```
>
> يتم تمرير وسيط `state` تلقائيا عندما يقبل المعالج ثلاثة معاملات. راجع [Event Listeners](https://docs.crewai.com/ar/concepts/event-listener.md) لقائمة الأحداث الكاملة.

> **التصفح والاستئناف والتفرع من سطر الأوامر**
>
> ```bash theme={null}
> crewai checkpoint
> crewai checkpoint --location ./my_checkpoints
> crewai checkpoint --location ./.checkpoints.db
> ```
>
> ![Checkpoint TUI tree view](https://mintcdn.com/crewai/enQiMpD-5gg-SIEO/images/checkpoint-tui-tree.png?fit=max\&auto=format\&n=enQiMpD-5gg-SIEO\&q=85\&s=ecfcf4b1e60db4ad637721f80664c24c)
>
> شجرة نقاط الحفظ — الفروع والتفرعات تتداخل تحت أبيها.
>
> اللوحة اليسرى تجمع نقاط الحفظ حسب الفرع؛ التفرعات تتداخل تحت أبيها. اختيار نقطة حفظ يفتح لوحة التفاصيل مع بياناتها الوصفية وحالة الكيان وتقدم المهام. **Resume** يكمل التشغيل؛ **Fork** يبدأ فرعا جديدا.
>
> ![Checkpoint detail overview tab](https://mintcdn.com/crewai/enQiMpD-5gg-SIEO/images/checkpoint-tui-detail-overview.png?fit=max\&auto=format\&n=enQiMpD-5gg-SIEO\&q=85\&s=e8b0459236049f1c324bc129f47156fe)
>
> تبويب النظرة العامة — البيانات الوصفية وحالة الكيان وملخص التشغيل.
>
> لوحة التفاصيل تعرض منطقتين قابلتين للتحرير:
>
> * **Inputs** — مدخلات الـ kickoff الأصلية، معبأة مسبقا وقابلة للتحرير.
>
>   ![Editable kickoff inputs](https://mintcdn.com/crewai/enQiMpD-5gg-SIEO/images/checkpoint-tui-detail-inputs.png?fit=max\&auto=format\&n=enQiMpD-5gg-SIEO\&q=85\&s=8cf27d43c6f75214449b261c3f898174)
>
> * **مخرجات المهام** — مخرجات المهام المكتملة. تحرير مخرج والضغط على **Fork** يبطل المهام التابعة لتعاد بالسياق المعدل.
>
>   ![Editable task outputs](https://mintcdn.com/crewai/enQiMpD-5gg-SIEO/images/checkpoint-tui-detail-tasks.png?fit=max\&auto=format\&n=enQiMpD-5gg-SIEO\&q=85\&s=b51cce6c1e5fcc39407e88257e97d9fb)
>
> ![Fork confirmation panel](https://mintcdn.com/crewai/enQiMpD-5gg-SIEO/images/checkpoint-tui-details-fork.png?fit=max\&auto=format\&n=enQiMpD-5gg-SIEO\&q=85\&s=4b7545359a4bf5ecad064f3970dbf416)
>
> عرض التفرع — تأكيد فرع جديد من نقطة الحفظ المختارة.
>
> > [!TIP]
> >
> > مفيد لاستكشاف "ماذا لو": تفرع، عدل، راقب.

> **تفقد نقاط الحفظ بدون TUI**
>
> ```bash theme={null}
> crewai checkpoint list ./my_checkpoints
> crewai checkpoint info ./my_checkpoints/<file>.json
> crewai checkpoint info ./.checkpoints.db
> ```

## المرجع

### `CheckpointConfig`

**location** `str` (default: "./.checkpoints")

وجهة التخزين. مجلد لـ `JsonProvider`، مسار ملف قاعدة بيانات لـ `SqliteProvider`.

**on\_events** `list[CheckpointEventType | Literal["*"]]` (default: \["task\_completed"])

أنواع الأحداث التي تطلق نقطة حفظ. `CheckpointEventType` هو `Literal` — مدقق الأنواع يكمل تلقائيا ويرفض القيم غير المدعومة. راجع [أنواع الأحداث](#أنواع-الأحداث) للقائمة الكاملة.

**provider** `BaseProvider` (default: JsonProvider())

واجهة التخزين. `JsonProvider` أو `SqliteProvider`.

**max\_checkpoints** `int | None` (default: None)

الحد الاقصى لنقاط الحفظ المحتفظ بها. الأقدم تحذف بعد كل كتابة.

**restore\_from** `Path | str | None` (default: None)

نقطة الحفظ المراد استعادتها عند تمريرها عبر `from_checkpoint`.

### قيم حقل `checkpoint`

مقبولة في `Crew` و`Flow` و`Agent`.

**None** `افتراضي`

يرث من الأب.

**True** `bool`

تفعيل بالإعدادات الافتراضية.

**False** `bool`

انسحاب صريح. يوقف الوراثة.

**CheckpointConfig(...)** `CheckpointConfig`

إعدادات مخصصة.

### أنواع الأحداث

يقبل `on_events` أي مجموعة من قيم `CheckpointEventType`. الافتراضي `["task_completed"]` يكتب نقطة حفظ لكل مهمة منتهية، و`["*"]` يطابق جميع الأحداث.

> [!WARNING]
>
> `["*"]` والأحداث عالية التردد مثل `llm_call_completed` تكتب نقاط حفظ كثيرة وقد تضر بالاداء. استخدمها مع `max_checkpoints`.

**جميع الأحداث المدعومة**

* **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`
* **حرف بدل** — `"*"` يطابق جميع الأحداث.

### مزودات التخزين

**JsonProvider** `provider`

ملف واحد لكل نقطة حفظ بصيغة `<timestamp>_<uuid>.json` داخل `location`.

**SqliteProvider** `provider`

ملف قاعدة بيانات واحد في `location` مع journaling WAL.

### سطر الأوامر

| الامر | الغرض |
| :- | :- |
| `crewai checkpoint` | تشغيل TUI؛ كشف التخزين تلقائيا. |
| `crewai checkpoint --location <path>` | تشغيل TUI على موقع محدد. |
| `crewai checkpoint list <path>` | سرد نقاط الحفظ. |
| `crewai checkpoint info <path>` | تفقد ملف نقطة حفظ أو آخر مدخل في قاعدة بيانات SQLite. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.