بخش 6.4 · جریان کنترل در LangGraph

وقفه و ادامه‌ی اجرا (interrupt و resume)

interrupt and resume

فهرست مطالب
  1. نودی که سؤال می‌پرسد
  2. ادامه‌ی اجرا، نود را از خط اول اجرا می‌کند
  3. دو سؤال در یک نود
  4. پاسخی با اسکیما
  5. چهار حالت مهم که باید بشناسید

تابع interrupt اجرای گراف را ذخیره می‌کند و سؤال را به فراخواننده برمی‌گرداند؛ سپس Command(resume=...) نودِ متوقف‌شده را همراه با پاسخ، دوباره از اولین خط آن اجرا می‌کند.

یک مرحله‌ی بازبینی به گرافتان اضافه می‌کنید. این نود یک خط لاگ می‌نویسد، از یک انسان درخواست تأیید می‌کند و سپس حکم ارزیابی (verdict) را ثبت می‌کند. بعد از اینکه فرد پاسخ می‌دهد، آن خط لاگ دو بار چاپ می‌شود. نود از ادامه‌ی همان سؤال پیش نرفته؛ بلکه اجرای آن دوباره از خط اول از سر گرفته شده است.

با پایان این بخش، می‌توانید با interrupt یک نود را متوقف کنید، با Command(resume=...) ادامه‌ی آن را پیش ببرید، و دقیقاً تشخیص دهید کدام کد دو بار اجرا می‌شود. همچنین چهار حالتی را که در آن‌ها وقفه یا ادامه‌ی اجرا طبق انتظار کار نمی‌کند، خواهید شناخت.

نودی که سؤال می‌پرسد

وقفه (Interrupt): فراخوانی interrupt(value) درون یک نود. این تابع اجرا را متوقف می‌کند، یک چک‌پوینت (checkpoint) ذخیره می‌سازد و value را به‌عنوان سؤال به فراخواننده برمی‌گرداند.

گراف کیت دو نود دارد: write یک پیش‌نویس آماده می‌کند و review تأییدیه می‌خواهد. متغیر runs تمام خطوطی را که نود به آن‌ها می‌رسد ثبت می‌کند:

نود review capture/s_persist.py
    def review(state):
        runs.append("review before interrupt")
        answer = interrupt({"question": "Approve this draft?", "draft": state["draft"]})
        runs.append(f"review after interrupt: {answer}")
        return {"verdict": "approved" if answer == "yes" else f"rejected: {answer}"}

این گراف از InMemorySaver به‌عنوان چک‌پوینتر (checkpointer) خود استفاده می‌کند. اولین invoke با آرگومان version="v2" یک وقفه برگرداند و وضعیت گراف مشخص کرد که نود بعدی برای اجرا review است:

وقفه و وضعیت حین انتظار اجرای برنامه capture/out/32-interrupt-resume.txt
interrupts:
[
  {
    "value": {
      "question": "Approve this draft?",
      "draft": "Ship v2 on Friday."
    },
    "id": "<hex-1>",
    "response_schema": null
  }
]

state:
{
  "next": [
    "review"
  ],

بخش وضعیت تا کلید بعدیِ آن خلاصه شده است.

مقدار داخل وقفه باید قابلیت تبدیل به JSON (اصطلاحاً JSON-serializable) را داشته باشد {{docs oss/python/langgraph/interrupts}}. در حالت پیش‌فرضِ invoke، وقفه‌ها درون خروجی و ذیل کلید __interrupt__ بازگردانده می‌شوند {{docs oss/python/langgraph/interrupts}}.

ادامه‌ی اجرا، نود را از خط اول اجرا می‌کند

ادامه‌ی اجرا (Resume): فراخوانی invoke یا stream با ورودی Command(resume=value)، روی همان ریسه‌ای (thread) که وقفه در آن رخ داده است. در این حالت، فراخوانی interrupt مقدار value را برمی‌گرداند.

ادامه‌ی اجرا با پاسخ "yes"، اجرای گراف را با حکم ارزیابی approved به پایان رساند. لاگ خطوط نود نشان می‌دهد چه بخش‌هایی اجرا شده‌اند:

خطوطی که نودها اجرا کردند capture/out/32-interrupt-resume.txt
node runs:
[
  "write",
  "review before interrupt",
  "review before interrupt",
  "review after interrupt: yes"
]

نود write فقط یک بار اجرا شد، چون کارش قبل از وقفه تمام شده بود. نود review دو بار اجرا شد و خطِ پیش از interrupt در هر دو بار به اجرا درآمد. مستندات بخش وقفه‌ها هم همین موضوع را تأیید می‌کند: محیط اجرا (runtime) نود را مجدداً از ابتدا آغاز می‌کند {{docs oss/python/langgraph/interrupts}}. شکل این دو فراخوانی را رسم کرده است.

یک وقفه و یک ازسرگیریازسرگیری، نود review را از خط اول اجرا می‌کند؛ بنابراین خطِ قبل از وقفه دو بار اجرا می‌شود و write دیگر اجرا نمی‌شود.
یک وقفه و یک ازسرگیری پنج خط عمر: کد شما، حلقهٔ گراف، نود write، نود review، و چک‌پوینتر. ستون ششم لاگ بدنهٔ نودهای اجراشده به ترتیب از خروجی است. فراخوانی نخست write و سپس review را تا وقفه‌اش اجرا می‌کند، مکث را با گام بعدی review ذخیره کرده و وقفهٔ «Approve this draft?» را بازمی‌گرداند. ازسرگیری با Command(resume="yes") نود review را مجدداً از خط اولش اجرا می‌کند. لاگ عبارت «review before interrupt» را 2 بار و سپس «review after interrupt: yes» را نشان می‌دهد و حکم ارزیابی approved ذخیره می‌شود. نود write مجدداً اجرا نمی‌شود. کد شما invoke graph حلقهٔ Pregel write نود review نود چک‌پوینتر InMemorySaver بدنه نودهای اجراشده لاگ، به ترتیب INVOKE 1 invoke(input) 2 اجرای write write 3 اجرای review review قبل از وقفه 4 مکث ذخیره شد بعدی: review 5 interrupt: این پیش‌نویس تأیید است؟ ازسرگیری write اجرا نمی‌شود 6 Command(resume='yes') 7 اجرای مجدد review review قبل از وقفه 8 حکم ارزیابی: approved review بعد از وقفه: yes 9 گام ذخیره شد بعدی: هیچ 10 وضعیت نهایی "review before interrupt" 2 بار اجرا شد
سطرها را از بالا به پایین بخوانید. فلش‌های آبی‌نفتی چک‌پوینت‌ها هستند، سطر کهربایی مکث است، و سطرهای نیمهٔ پایینی به ازسرگیری تعلق دارند. ستون راست لاگ بدنهٔ نودهای اجراشده است. از capture/out/32-interrupt-resume.txt.

بنابراین کدهایی که قبل از یک interrupt نوشته می‌شوند، باید طوری باشند که اجرای دوباره‌شان خطری نداشته باشد. مستندات رسمی تأکید می‌کند که اثرات جانبی (side effects) پیش از وقفه باید بی‌اثر در تکرار (idempotent) باشند {{docs oss/python/langgraph/interrupts}}. اثر جانبی را به بعد از فراخوانی interrupt منتقل کنید، یا آن را در نودی جداگانه قبل از نود بازبینی قرار دهید.

دو سؤال در یک نود

یک نود می‌تواند بیش از یک بار interrupt را فراخوانی کند. نود کیت ابتدا عنوان و سپس متن پیام را می‌پرسد. اجرای اول سؤالِ مربوط به عنوان را برگرداند. ارسال ادامه‌ی اجرا با "Release" نود را از ابتدا اجرا کرد و اولین interrupt مقدار "Release" را تحویل داد. سپس دومین interrupt اجرا را متوقف کرد تا متن پیام را بپرسد. ادامه‌ی اجرا با "Friday" کل کار را با پیش‌نویس Release: Friday به اتمام رساند.

فریم‌ورک LangGraph هر پاسخ را بر اساس موقعیت مکانی فراخوانی interrupt درون نود متناظر می‌کند. مستندات درباره‌ی کدهایی که فراخوانی‌های interrupt را بین اجراهای مختلف رد می‌کنند یا ترتیب آن‌ها را به هم می‌زنند، و همچنین قرار دادن interrupt درون حلقه‌ی while True هشدار می‌دهد {{docs oss/python/langgraph/interrupts}}. از نسخه‌ی langgraph 1.2.20، هر interrupt درون یک وظیفه (task) شناسهٔ اختصاصی خودش را دارد (بر اساس یادداشت‌های انتشار langgraph 1.2.20، در کد بررسی نشد). کیت ما هم دو شناسه‌ی متفاوت برای این دو سؤال ثبت کرد.

پاسخی با اسکیما

متد interrupt ورودی response_schema را می‌پذیرد. اگر یک مدل Pydantic به آن بدهید، LangGraph پاسخ را پیش از تحویل به نود اعتبارسنجی می‌کند. کیت با اسکیمای Verdict سؤال می‌پرسد که فیلد approve در آن از نوع بولی (boolean) است. ارسال پاسخ {'approve': 'maybe'} این خطا را صادر کرد:

پاسخی که اسکیما آن را رد می‌کند capture/out/32-interrupt-resume.txt
raised pydantic_core._pydantic_core.ValidationError: 1 validation error for Verdict
approve
  Input should be a valid boolean, unable to interpret input [type=bool_parsing, input_value='maybe', input_type=str]

خط راهنمای pydantic خلاصه شده است.

پس از بروز خطا، اجرای برنامه همچنان منتظر نود typed باقی ماند و ارسال پاسخ {'approve': True} کار را به پایان رساند. بنابراین، پاسخ نامعتبر وضعیت وقفه را دست‌نخورده باقی می‌گذارد و فراخواننده می‌تواند دوباره سؤال را مطرح کند. علاوه بر این، وقفه اسکیمای JSON مربوط به Verdict را هم همراه دارد؛ به این ترتیب رابط کاربری می‌تواند فرم خود را بر اساس آن بسازد.

چهار حالت مهم که باید بشناسید

وقفه بدون چک‌پوینتر. متن مستنداتِ (docstring) متد interrupt صراحتاً می‌گوید که وجود چک‌پوینتر الزامی است {{code libs/langgraph/langgraph/types.py}}. کیت گراف دارای دو سؤال را بدون چک‌پوینتر کامپایل کرد و invoke هم خطایی نداد؛ بلکه وضعیت ورودی و وقفه را برگرداند:

یک وقفه بدون چک‌پوینتر capture/out/32-interrupt-resume.txt
returned:
{
  "value": {
    "draft": "",
    "verdict": "",
    "edits": []
  },
  "interrupts": [
    {
      "value": "Title?",
      "id": "<hex-5>",
      "response_schema": null
    }
  ]
}

اما چون هیچ چیزی وضعیت وقفه را ذخیره نکرده، امکان ادامه‌ی اجرا وجود ندارد. فراخوانی Command(resume=...) بدون چک‌پوینتر، خطای RuntimeError با متن Cannot use Command(resume=...) without checkpointer صادر می‌کند {{code libs/langgraph/langgraph/pregel/_loop.py}}. کیت هنوز این خطا را ثبت نکرده است؛ نمونه‌ی ثبت‌شده‌ی آن به همراه دیگر موارد بازِ بخش 8.8 در نسخه‌ی بعدی خواهد آمد.

ادامه‌ی اجرای ریسه‌ای که منتظر نیست. کیت Command(resume='x') را پس از پایان کارِ ریسه‌ی بازبینی به آن فرستاد. این فراخوانی خطایی نداد؛ وضعیت نهایی را بدون هیچ وقفه‌ای برگرداند و هیچ نودی هم اجرا نشد:

ازسرگیری یک ریسهٔ پایان‌یافته capture/out/32-interrupt-resume.txt
returned:
{
  "value": {
    "draft": "Ship v2 on Friday.",
    "verdict": "approved",
    "edits": []
  },
  "interrupts": []
}

پاسخ x به هیچ جا نرسید و فراخواننده هم هیچ نشانه‌ای از آن دریافت نکرد. قبل از ادامه‌ی اجرا، get_state را فراخوانی کنید و مطمئن شوید که next نام یک نود را در خود دارد و tasks حاوی وقفه است.

پاسخ بیات‌شده (Stale). اگر پاسخی برای وقفه‌ای ارسال شود که قبلاً در یک ادامه‌ی اجرا مصرف شده است، آن پاسخ هم پذیرفته و سپس نادیده گرفته می‌شود. پلتفرم LangGraph می‌تواند در قالب یک حالتِ ادامه‌ی اجرای سخت‌گیرانه (strict resume mode) این پاسخ را رد کند، اما در این نسخه‌ی قفل‌شده، تنها سوییچ موجود، کلید پیکربندی داخلی __pregel_strict_resume است {{code libs/langgraph/langgraph/_internal/_constants.py}}. بررسی پاسخ بیات‌شده در این حالت فقط روی نگاشتِ ادامه‌ی اجرایی اِعمال می‌شود که کلید آن شناسه‌ی وقفه باشد {{code libs/langgraph/langgraph/pregel/_loop.py:1037-1063}}. نام این گزینه با __pregel شروع می‌شود؛ بنابراین آن را خصوصی در نظر بگیرید و کدهایتان را به آن وابسته نکنید.

آزمایش عملی: ما هر دو حالت را روی سیستم مهمان سرور x86 با مدل Qwen3 4B سنجیدیم (3 بار اجرا برای هر حالت). هر مرحله در فرایندی (process) جدید روی SqliteSaver اجرا شد. یک ایجنت (agent) در حالت per_call دو فراخوانی انجام داد که به تأیید نیاز داشتند. اولین فراخوانیِ ادامه‌ی اجرا، یکی از درخواست‌ها را بر اساس شناسه‌ی وقفه‌اش تأیید کرد؛ سپس در دومین فراخوانی، همان پاسخ دوباره فرستاده شد. با فعال بودن __pregel_strict_resume، دومین ادامه‌ی اجرا در هر 3 بار با خطای UnknownInterruptError: Unknown or already-consumed interrupt متوقف شد.

بدون این تنظیم، دومین ادامه‌ی اجرا در هر 3 بار بدون هیچ خطایی پیش رفت و هیچ چیزی را اجرا نکرد. در تمام دفعات، send_email یک بار و مدل هم یک بار اجرا شدند.

کلاس NodeInterrupt. در کدهای قدیمی‌تر، داخل نود استثنای NodeInterrupt پرتاب می‌شد. این کلاس در نسخه‌ی قفل‌شده‌ی فعلی منسوخ (deprecated) شده است و پیام هشدار آن به استفاده از interrupt اشاره می‌کند {{code libs/langgraph/langgraph/errors.py}}.

منابع: capture/s_persist.py، capture/out/32-interrupt-resume.txt؛ capture/lab/summary/approvals-x86.json، capture/lab/T07-approvals-x86/01-cases.jsonl؛ فایل‌های libs/langgraph/langgraph/types.py، libs/langgraph/langgraph/errors.py، libs/langgraph/langgraph/pregel/_loop.py و libs/langgraph/langgraph/_internal/_constants.py در نسخه‌ی 1.2.22 از langgraph؛ سایت docs.langchain.com در commit مستندات 04d4d4a (بخش oss/python/langgraph/interrupts).

ترجمه‌ی فارسی interrupt and resume از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما