ارکستراسیون گراف وضعیت‌دار: اجرای پایدار و چک‌پوینت در LangGraph

وقتی یک پایپ‌لاین یا ایجنت چندمرحله‌ای پس از پردازش‌های طولانی و فراخوانی چندین ابزار در مرحله‌ی آخر دچار خطا می‌شود، اجرای دوباره‌ی کل فرایند از صفر یعنی هدررفت شدید زمان و منابع. در سیستم‌های سنتی، وضعیت میانی نادیده گرفته می‌شود و توسعه‌دهنده ناچار است لایه‌های پیچیده و غیرقابل‌اطمینانی از بازآزمایی (retry) پیاده کند که در مقیاس عملیاتی به‌سرعت می‌شکنند.

راهکار استاندارد برای حل این چالش، نگاه به ایجنت به‌عنوان یک ماشین وضعیت (state machine) است. در این الگو، وضعیت به‌صورت یک ساختار داده‌ی نوع‌دار و درجه‌یک مدیریت می‌شود و بعد از اتمام کار هر گره، یک نقطه‌ی بازرسی یا چک‌پوینت (checkpoint) از کل داده‌ها ذخیره می‌گردد. در صورت بروز هرگونه قطعی شبکه یا خطای غیرمنتظره، سیستم دقیقاً از آخرین گامِ موفق و با همان حافظه از سر گرفته می‌شود.

در این درس ساختار پایه‌ای ارکستراسیون وضعیت‌دار، اجرای پایدار (durable execution)، جریان داده‌ها و توپولوژی‌های مختلف نظیر سوپروایزر و سوارم را بررسی می‌کنیم و سپس یک موتور گراف کامل با چک‌پوینت‌گیری را بدون وابستگی اضافه و صرفاً با پایتون استاندارد پیاده‌سازی می‌نماییم.

ایجنت یک ماشین وضعیت (state machine) است؛ گره‌ها تابع‌اند؛ یال‌ها همان جابه‌جایی‌ها هستند؛ وضعیت هم بعد از هر گره چک‌پوینت می‌شود. با این ساختار، بعد از هر خرابی دقیقاً از آخرین چک‌پوینتِ موفق کار را ادامه دهید. در سال 2026، مرجع پیاده‌سازی این الگوی ارکستراسیونِ سطح‌پایین و وضعیت‌دار (stateful)، کتابخانه‌ی LangGraph است.

اهداف یادگیری

• تشریح مدل هسته‌ی LangGraph: ماشین وضعیت با وضعیت نوع‌دار (typed state)، گره‌های تابعی، یال‌های شرطی، و چک‌پوینت‌های پس از اجرای هر گره.
• نام بردن از چهار قابلیتی که در مستندات رسمی برجسته شده‌اند: اجرای پایدار (durable execution)، استریمینگ، انسان در چرخه، و حافظه‌ی جامع.
• توضیح سه توپولوژی ارکستراسیون که LangGraph پشتیبانی می‌کند: سرپرست (supervisor)، همتا‌به‌همتا یا سوارم (peer-to-peer / swarm)، و سلسله‌مراتبی (hierarchical با زیرگراف‌های تو‌در‌تو).
• پیاده‌سازی یک گراف وضعیت با کتابخانه‌ی استاندارد پایتون، با وضعیت نوع‌دار، یال‌های شرطی، و چرخه‌ی چک‌پوینت/ادامه‌ی اجرا (checkpoint/resume).

صورت مسئله

ایجنت‌ها و جریان‌های کاری (workflows) درد مشترکی دارند: وقتی یک اجرای 40 مرحله‌ای در گام 38 شکست می‌خورد، می‌خواهید کار را از همان گام 38 از سر بگیرید، نه اینکه همه‌چیز را از صفر شروع کنید. مدل‌های داده‌ای که وضعیت را شهروند درجه‌یک نمی‌دانند، توسعه‌دهندگان را مجبور می‌کنند دور کتابخانه‌ای که همه‌چیز را یک اجرای تازه فرض می‌کند، سازوکارهای بازآزمایی (retry) دست‌وپاگیر و سرهم‌بندی‌شده بنویسند.

پاسخ معماری LangGraph به این مسئله روشن است: وضعیت، یک شیء نوع‌دار درجه‌یک است؛ تغییراتش کاملاً صریح‌اند؛ و بعد از هر گره، چک‌پوینت ذخیره می‌شود. ادامه‌ی کار هم صرفاً با یک فراخوانیِ load_state(session_id) انجام می‌گیرد.

مفهوم اصلی

گراف

یک گراف از اجزای زیر تشکیل می‌شود:

• نوع وضعیت (State type): یک دیکشنری نوع‌دار (یا مدل Pydantic) که هر گره آن را می‌خواند و تغییر می‌دهد.
• گره‌ها (Nodes): توابع خالص با ساختار (state) -> state_update. این به‌روزرسانی‌ها پس از بازگشت تابع، با وضعیت ادغام (merge) می‌شوند.
• یال‌ها (Edges): جابه‌جایی‌های مستقیم یا شرطی بین گره‌ها.
• ورودی و خروجی: گره‌های نگهبانِ START و END که مرزهای گراف را مشخص می‌کنند.

مثال: ایجنتی با گره‌های classify، refund، bug، sales و done؛ یک جریان کاریِ مسیریابی در قالب گراف.

اجرای پایدار

بعد از بازگشت هر گره، محیط اجرا وضعیت را سریال‌سازی کرده و در یک چک‌پوینتر (SQLite، Postgres، Redis یا سفارشی) می‌نویسد. اگر در گام N خطایی رخ دهد، محیط اجرا با resume(session_id) کار را از گام N+1 با همان وضعیت دقیق از سر می‌گیرد.

مستندات LangGraph صراحتاً به مشتریان سازمانی معتبری اشاره می‌کنند که این قابلیت برایشان حیاتی است: Klarna، Uber و J.P. Morgan. ادعای اصلی بر سر ظاهر گراف نیست؛ بلکه این است که ساختار گراف به همراه چک‌پوینت‌گیری، هزینه‌ی بازیابی پس از خرابی را بسیار ارزان و کم‌هزینه می‌کند.

استریمینگ

هر گره می‌تواند خروجی جزئی (partial output) تولید کند. گراف تغییراتِ هر گره (per-node-delta) را به شکل استریم به فراخواننده تحویل می‌دهد تا رابط کاربری هم‌زمان با اجرای گراف به‌روز شود.

انسان در چرخه

بررسی و دستکاری وضعیت در فاصله‌ی بین اجرای گره‌ها. شیوه‌های پیاده‌سازی: توقف پیش از یک گره‌ی حساس، ارائه‌ی وضعیت به کاربر انسانی، اعمال تغییرات او، و سپس ادامه‌ی اجرا. از آنجا که وضعیت از قبل سریال‌سازی شده، چک‌پوینتر پیاده‌سازی این سناریو را بسیار ساده می‌کند.

حافظه

کوتاه‌مدت (درون یک اجرا — تاریخچه‌ی مکالمه در دل وضعیت) و بلندمدت (میان اجراهای گوناگون — ماندگار به‌کمک چک‌پوینتر به همراه یک مخزن ذخیره‌سازی بلندمدت مجزا). LangGraph از طریق ابزارها با سیستم‌های حافظه‌ی خارجی (مانند Mem0 یا سیستم‌های سفارشی) یکپارچه می‌شود.

سه توپولوژی اصلی

1. سرپرست (Supervisor): یک مدل زبانی مسیریاب مرکزی که کار را به ایجنت‌های فرعی تخصصی محول می‌کند. متد create_supervisor() در بسته‌ی langgraph-supervisor این نقش را بر عهده دارد (هرچند تیم LangChain در سال 2026 توصیه می‌کند برای کنترل بیشتر روی بستر متنی، این کار مستقیماً از طریق فراخوانی ابزار انجام شود).
2. سوارم / همتا‌به‌همتا (Swarm / peer-to-peer): ایجنت‌ها مستقیماً و از طریق ابزارهای مشترک دست‌به‌دست می‌شوند؛ بدون نیاز به هیچ مسیریاب مرکزی.
3. سلسله‌مراتبی (Hierarchical): سرپرست‌هایی که سرپرست‌های زیردست را مدیریت می‌کنند؛ این الگو در قالب زیرگراف‌های تو‌در‌تو پیاده می‌شود.

خطاهای رایج در این الگو

• چک‌پوینت‌های بیش از حد کوچک: اگر فقط نوبت‌های گفت‌وگو ذخیره شوند، وضعیت ابزارها و داده‌های ذخیره‌شده در حافظه بازیابی‌ناپذیر می‌مانند. باید کل وضعیت سریال‌سازی شود.
• گره‌های غیرقطعی (Non-deterministic): ادامه‌ی اجرا فرض می‌کند ورودی‌های یکسان گره خروجی وضعیت یکسانی تولید می‌کنند. متغیرهایی مثل دانه‌های تصادفی (random seeds)، ساعت سیستم و پاسخ ای‌پی‌آی‌های خارجی حتماً باید ثبت و کنترل شوند.
• استفاده‌ی بیش از حد از یال‌های شرطی: گرافی که تک‌تک یال‌هایش شرطی باشند، ماشین وضعیتی می‌سازد که دیگر نمی‌توان رفتارش را تحلیل و بررسی کرد. ترجیحاً از زنجیره‌های خطی با انشعاب‌های انگشت‌شمار استفاده کنید.

پیاده‌سازی از صفر

فایل code/main.py یک گراف وضعیت‌دار را با کتابخانه‌ی استاندارد پایتون پیاده می‌کند:

• State — دیکشنری نوع‌داری شامل messages، step، route، output و human_approval.
• Node — شیء فراخوان‌پذیری (callable) که وضعیت را می‌گیرد و یک دیکشنریِ به‌روزرسانی برمی‌گرداند.
• StateGraph — شامل گره‌ها، یال‌ها، یال‌های شرطی، به همراه متدهای run و resume.
• SQLiteCheckpointer (نسخه‌ی شبیه‌سازی‌شده در حافظه) — وضعیت را پس از هر گره سریال‌سازی می‌کند؛ با متد load(session_id) هم آن را برمی‌گرداند.
• یک گراف نمونه: classify -> branch(refund / bug / sales) -> human gate -> send.

اجرای کد:

python3 code/main.py

ردگیری محاسبات نشان می‌دهد که اجرای اول در مرحله‌ی بررسی انسانی متوقف می‌شود، وضعیت در دیتابیس ماندگار می‌گردد و سپس با ادامه‌ی اجرا (resume)، خروجی نهایی تولید می‌شود.

استفاده از ابزارهای واقعی

• LangGraph — گزینه‌ی مرجع و آماده‌ی محیط پروداکشن. می‌توانید از create_react_agent یا create_supervisor استفاده کنید، یا گراف اختصاصی خودتان را بسازید.
• AutoGen نسخه 0.4 (درس 14) — جایگزینی مبتنی بر مدل اکتور (actor model) برای سناریوهای با هم‌زمانی بالا.
• Claude Agent SDK (درس 17) — بستر آزمایشیِ مدیریت‌شده با مخزن داخلی ذخیره‌سازی نشست‌ها.
• پیاده‌سازی سفارشی — زمانی که به کنترل دقیق روی ساختار وضعیت یا زیرساخت چک‌پوینتر نیاز دارید.

خروجی این درس

سند outputs/skill-state-graph.md یک گراف وضعیت شبیه به معماری LangGraph تولید می‌کند که می‌توان آن را به هر محیط اجرایی دلخواهی منتقل کرد؛ درحالی‌که قابلیت‌های چک‌پوینت‌گیری و ادامه‌ی اجرا از قبل در آن تعبیه شده‌اند.

تمرین‌ها

1. یک یال شرطی از classify به end اضافه کنید تا وقتی میزان اطمینان دسته‌بندی پایین‌تر از آستانه بود فعال شود. کاری کنید اجرای فرایند پس از تعیین دستیِ route توسط انسان ادامه یابد.
2. ماکِ حافظه‌ایِ شبه-SQLite را با یک چک‌پوینتر واقعی SQLite جایگزین کنید. سربار ناشی از سریال‌سازی را در هر گام اندازه بگیرید.
3. یال‌های موازی بسازید: دو گره به‌طور هم‌زمان اجرا شوند و خروجی‌شان با یک کاهنده‌ی (reducer) سفارشی ادغام گردد. وضعیت تغییرناپذیر (immutable) در اینجا چه مزیتی ایجاد می‌کند؟
4. مستندات langgraph-supervisor را مطالعه کنید. کُد نمونه‌ی ساده را با create_supervisor بازنویسی کنید. شکل ردگیری محاسبات (trace) را در دو حالت مقایسه نمایید.
5. قابلیت استریمینگ را اضافه کنید: هر گره حین اجرا خروجی جزئی وضعیت را yield کند. این تغییرات جزئی را به محض رسیدن چاپ کنید.

اصطلاحات کلیدی

برای مطالعه‌ی بیشتر

• نمای کلی LangGraph — مستندات مرجع
• مرجع API برای langgraph-supervisor — ساختار الگوی سرپرست
• معرفی AutoGen نسخه 0.4، بخش تحقیقات مایکروسافت — جایگزینی مبتنی بر مدل اکتور
• نمای کلی Claude Agent SDK — مخزن ذخیره‌ی نشست‌ها و ایجنت‌های فرعی