Checkpointing

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

الشرح

كيف يعمل الـ Checkpointing: الأحداث والتخزين والوراثة.

درس تطبيقي

دليل 5 دقائق: تشغيل، إيقاف، استئناف.

ادلة عملية

وصفات مركزة على المهام لسير العمل الشائع.

المرجع

CheckpointConfig والأحداث والمزودات وسطر الأوامر.

الشرح

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

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

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

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

التخزين

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

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

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

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

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

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

ما لا تعيده الاستعادة

تبني الاستعادة الطاقم أو التدفق أو الوكيل من ملف نقطة الحفظ، وليس من الكائن الذي تستدعي عليه kickoff(). يشغّل crew.kickoff(from_checkpoint=...) الطاقم المخزن في الملف، لذلك لا تنسخ الكائنات القابلة للاستدعاء التي عيّنتها على crew. تحفظ نقطة الحفظ دالة الاستدعاء كمسار منقط لدالة على مستوى الوحدة، مثل "my_project.hooks.on_task_done"، ثم تستوردها مجددا عند الاستعادة. نقطة الحفظ بيانات، لذلك لا يستورد CrewAI هذه المسارات إلا عند تعيين متغير البيئة CREWAI_DESERIALIZE_CALLBACKS=1. بدونه، تؤدي استعادة نقطة حفظ تسمي دالة استدعاء إلى ValueError. عيّنه فقط لملفات نقاط الحفظ التي تثق بها. لا تحفظ العناصر التالية ولا تعمل بعد الاستعادة:

دوال lambda، والـ closures، والدوال المرتبطة مثل notifier.on_task_done، وكائنات functools.partial، والكائنات القابلة للاستدعاء. يعرض CrewAI التحذير A ... callback cannot be saved in a checkpoint عند تمرير أي منها إلى Task أو Agent أو Crew أو أداة؛ أما تعيين الخاصية لاحقا فلا يعرض تحذيرا. تُستعاد دالة cache_function لأداة من هذا النوع كدالة لا تخزن أي نتيجة مؤقتا.
الـ guardrails القابلة للاستدعاء. يعرض CrewAI تحذيرا عند كتابة نقطة الحفظ. تحفظ الـ guardrails النصية.
خطافات @before_kickoff و@after_kickoff في فئة @CrewBase.

للاحتفاظ بدالة استدعاء لا يمكن حفظها، استعد باستخدام Crew.from_checkpoint() وعيّنها مجددا قبل kickoff():

from crewai import CheckpointConfig, Crew


class Notifier:
    def on_task_done(self, output):
        print(f"Finished: {output.description}")


notifier = Notifier()
crew = Crew.from_checkpoint(
    CheckpointConfig(restore_from="./.checkpoints/<timestamp>_<uuid>.json")
)
crew.tasks[-1].callback = notifier.on_task_done
result = crew.kickoff()

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

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

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

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,
)

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

result = crew.kickoff()

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

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

from crewai import CheckpointConfig

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

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

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

ادلة عملية

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

crew = Crew(agents=[...], tasks=[...], checkpoint=True)

يكتب إلى ./.checkpoints/ عند كل task_completed.

تخصيص التخزين والتردد

from crewai import Crew, CheckpointConfig

crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
        location="./my_checkpoints",
        on_events=["task_completed", "crew_kickoff_completed"],
        max_checkpoints=5,
    ),
)

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

from crewai import Crew, CheckpointConfig
from crewai.state import JsonProvider

crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
        location="./my_checkpoints",
        provider=JsonProvider(),
        max_checkpoints=5,
    ),
)

from crewai import Crew, CheckpointConfig
from crewai.state import SqliteProvider

crew = Crew(
    agents=[...],
    tasks=[...],
    checkpoint=CheckpointConfig(
        location="./.checkpoints.db",
        provider=SqliteProvider(),
        max_checkpoints=50,
    ),
)

SQLite يفعل وضع journal WAL للقراءات المتزامنة. يفضل لنقاط الحفظ عالية التردد.

استبعاد وكيل واحد

crew = Crew(
    agents=[
        Agent(role="Researcher", ...),
        Agent(role="Writer", ..., checkpoint=False),
    ],
    tasks=[...],
    checkpoint=True,
)

التفرع إلى فرع جديد

fork() يستعيد نقطة حفظ تحت نسب جديد بحيث لا يتصادم التشغيل الجديد مع الأصلي.

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
Flow
Agent

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task, review_task],
    checkpoint=CheckpointConfig(location="./crew_cp"),
)

المشغل الافتراضي: task_completed.

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 = 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().

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}")

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 لقائمة الأحداث الكاملة.

التصفح والاستئناف والتفرع من سطر الأوامر

crewai checkpoint
crewai checkpoint --location ./my_checkpoints
crewai checkpoint --location ./.checkpoints.db

Checkpoint TUI tree view — شجرة نقاط الحفظ — الفروع والتفرعات تتداخل تحت أبيها.

اللوحة اليسرى تجمع نقاط الحفظ حسب الفرع؛ التفرعات تتداخل تحت أبيها. اختيار نقطة حفظ يفتح لوحة التفاصيل مع بياناتها الوصفية وحالة الكيان وتقدم المهام. Resume يكمل التشغيل؛ Fork يبدأ فرعا جديدا.

Checkpoint detail overview tab — تبويب النظرة العامة — البيانات الوصفية وحالة الكيان وملخص التشغيل.

لوحة التفاصيل تعرض منطقتين قابلتين للتحرير:

Inputs — مدخلات الـ kickoff الأصلية، معبأة مسبقا وقابلة للتحرير.
مخرجات المهام — مخرجات المهام المكتملة. تحرير مخرج والضغط على Fork يبطل المهام التابعة لتعاد بالسياق المعدل.

Fork confirmation panel — عرض التفرع — تأكيد فرع جديد من نقطة الحفظ المختارة.

مفيد لاستكشاف “ماذا لو”: تفرع، عدل، راقب.

تفقد نقاط الحفظ بدون TUI

crewai checkpoint list ./my_checkpoints
crewai checkpoint info ./my_checkpoints/<file>.json
crewai checkpoint info ./.checkpoints.db

المرجع

`CheckpointConfig`

str

افتراضي:"\"./.checkpoints\""

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

list[CheckpointEventType | Literal["*"]]

افتراضي:"[\"task_completed\"]"

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

BaseProvider

افتراضي:"JsonProvider()"

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

int | None

افتراضي:"None"

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

Path | str | None

افتراضي:"None"

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

قيم حقل `checkpoint`

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

افتراضي

يرث من الأب.

bool

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

bool

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

CheckpointConfig

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

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

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

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

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

provider

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

provider

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

سطر الأوامر

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

البدء

الأدلّة

المفاهيم الأساسية

تكامل MCP

الأدوات

Observability

التعلّم

Telemetry

الشرح

درس تطبيقي

ادلة عملية

المرجع

الشرح

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

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

التخزين

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

ما لا تعيده الاستعادة

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

ادلة عملية

المرجع

`CheckpointConfig`

قيم حقل `checkpoint`

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

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

سطر الأوامر

الشرح

درس تطبيقي

ادلة عملية

المرجع

​الشرح

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

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

​التخزين

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

​ما لا تعيده الاستعادة

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

​ادلة عملية

​المرجع

​CheckpointConfig

​قيم حقل checkpoint

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

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

​سطر الأوامر

الشرح

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

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

التخزين

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

ما لا تعيده الاستعادة

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

ادلة عملية

المرجع

`CheckpointConfig`

قيم حقل `checkpoint`

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

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

سطر الأوامر