بخش 2.1 · درون محیط اجرا

حلقه‌ی ابرگام: برنامه‌ریزی، اجرا، به‌روزرسانی

The superstep loop: plan, execute, update

فهرست مطالب
  1. سه فاز در یک حلقه
  2. ثبت اجرای یک ایجنت واقعی
  3. نسخه‌ها تعیین می‌کنند چه چیزی در نوبت بعد اجرا شود
  4. ادغامِ نوشتن‌ها بر اساس ترتیب مسیر وظیفه
  5. محدودیت بازگشت دقیقاً چه چیزی را می‌شمارد؟
  6. راهنمای عملیاتی

با هر ابرگام (superstep) مثل یک تراکنش رفتار کنید: نوشتن‌های موازی هم‌زمان و بر اساس ترتیب مسیر وظیفه پدیدار می‌شوند؛ بنابراین هرگز نگذارید وضعیت به این وابسته باشد که کدام گره زودتر تمام شده است.

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

با پایان این بخش، می‌توانید ردگیری محاسبات (trace) یک ابرگام را خط‌به‌خط بخوانید و از روی نسخه‌ی کانال‌ها پیش‌بینی کنید کدام گره در نوبت بعد اجرا می‌شود. همچنین می‌توانید ترتیب ادغامِ (merge) نوشتن‌های موازی را حدس بزنید و محدودیت بازگشت (recursion limit) را طوری تنظیم کنید که متغیر درستی را بشمارد.

سه فاز در یک حلقه

ابرگام: یک نوبت از حلقه‌ی LangGraph. وظایف آماده را برنامه‌ریزی می‌کند، آن‌ها را اجرا می‌کند، و سپس همه‌ی نوشتن‌های آن‌ها را یک‌جا اعمال می‌نماید.

حلقه کوتاه است: loop.tick() برنامه‌ریزی می‌کند، runner.tick() هر وظیفه‌ی برنامه‌ریزی‌شده‌ای را که هنوز تغییری ثبت نکرده اجرا می‌کند، و loop.after_tick() نوشتن‌ها را اعمال کرده و یک چک‌پوینت (checkpoint) ذخیره می‌کند {{code libs/langgraph/langgraph/pregel/main.py:3081-3105}}. یک گره هرگز تغییرات ثبت‌شده در ابرگام خودش را نمی‌بیند؛ مقادیری که می‌خواند، همان مقادیر انتهای ابرگام قبلی هستند.

برنامه‌ریزی (Plan). تابع prepare_next_tasks دو نوع وظیفه (task) می‌سازد {{code libs/langgraph/langgraph/pregel/_algo.py:392}}. وظیفه‌ی PULL گرهی است که کانال راه‌انداز آن مقداری در خود دارد و نسخه‌اش از آخرین نسخه‌ای که گره دیده جدیدتر است {{code libs/langgraph/langgraph/pregel/_algo.py:1260-1277}}. وظیفه‌ی PUSH یک Send در حال انتظار در کانال __pregel_tasks است {{code libs/langgraph/langgraph/pregel/_algo.py:441-466}}.

اجرا (Execute). اجراکننده (runner) وظایف را به‌صورت موازی شروع می‌کند. با پایان هر وظیفه، حلقه تغییرات آن را ثبت کرده و در پس‌زمینه به چک‌پوینتر (checkpointer) می‌سپارد. بخش 2.3 همین مسیرِ نوشتن را پیگیری می‌کند.

به‌روزرسانی (Update). پس از آخرین وظیفه، apply_writes وظایف را مرتب می‌کند، نوشتن‌های آن‌ها را بر اساس کانال دسته‌بندی می‌نماید، و هر کانال را یک بار با کل دسته‌ی مربوط به خودش صدا می‌زند {{code libs/langgraph/langgraph/pregel/_loop.py:732-738}}. در نهایت _put_checkpoint نتیجه را ذخیره می‌کند {{code libs/langgraph/langgraph/pregel/_loop.py:774}}.

ثبت اجرای یک ایجنت واقعی

توابع حلقه‌ی langgraph نسخه‌ی 1.2.22 را پچ (patch) کردیم تا هر فراخوانی را ثبت کند. سپس create_agent را با مدل Qwen3 4B روی Ollama، در یک ماشین مهمان x86 و با دمای 0 اجرا کردیم. پرامپت این بود: Weather in Paris and Oslo?. مدل در اولین پاسخش دو فراخوانی get_weather درخواست کرد که 3.64 ثانیه طول کشید، و در پاسخ دومش جواب نهایی را داد که 1.59 ثانیه زمان برد. این زمان‌ها مربوط به یک بار اجرا روی ماشین مهمان زیر بار هستند؛ پس ترتیب‌ها و شمارش‌ها را ملاک قرار دهید، نه ثانیه‌ها را. این مراحل، گام‌های 1 و 2 از این ردگیری محاسبات هستند:

برنامه‌ریزی، اجرا و به‌روزرسانی برای گام مدل و گام ابزارها capture/lab/internals/01-superstep/trace.txt
[ 12] PLAN step=1 stop=9999 updated_channels=['branch:to:model', 'messages']
        task __pregel_pull model  id=c716c241 path=('__pregel_pull', 'model') triggers=['branch:to:model']
        versions_seen(before)={'__input__': {}, '__start__': {'__start__': 1}}
[ 13] TICK step=1 returns=True status=pending run=['model']
        channel_versions={'__start__': 2, 'branch:to:model': 2, 'messages': 2}
…
[ 15] UPDATE order=["model@('__pregel_pull', 'model')"]
…
        versions_changed={'__pregel_tasks': [None, 3], 'branch:to:model': [2, 3], 'messages': [2, 3]}
        versions_seen_updated={'model': {'branch:to:model': 2}}
        updated_channels=['__pregel_tasks', 'messages']
…
[ 18] PLAN step=2 stop=9999 updated_channels=['__pregel_tasks', 'messages']
        task __pregel_push tools  id=7bd87c87 path=('__pregel_push', 0, False) triggers=['__pregel_push']
        task __pregel_push tools  id=81e79e5c path=('__pregel_push', 1, False) triggers=['__pregel_push']
…
[ 25] UPDATE order=["tools@('__pregel_push', 0, False)", "tools@('__pregel_push', 1, False)"]

گام‌های 1 و 2 اجرا. نوشتن‌های مدل و خطوط ذخیره‌ساز میان فازها حذف شده‌اند.

تابع create_agent هر فراخوانی ابزار (tool call) را به یک Send مستقل تبدیل می‌کند؛ در نتیجه دو فراخوانی ابزار تبدیل به دو وظیفه‌ی PUSH از گره tools می‌شوند {{code libs/langchain_v1/langchain/agents/factory.py:2031-2032}}. به هرکدام یک شناسه‌ی وظیفه و اندیس اختصاصی در مسیر تعلق می‌گیرد. شکل هر شش ابرگام اجرا را به همراه نسخه‌ی هر کانال نمایش می‌دهد.

شش ابرگام از یک اجرای create_agent، همراه با نسخه‌های کانالهر نوشتن در یک ابرگام، نسخه جدید یکسانی می‌گیرد و یک نود تنها وقتی اجرا می‌شود که کانال محرک آن جدیدتر از آخرین نسخه‌ای باشد که دیده است.
شش ابرگام از یک اجرای create_agent، همراه با نسخه‌های کانال شبکه‌ای از 6 ابرگام برنامه‌ریزی‌شده از یک اجرای create_agent با دو فراخوانی ابزار، از گام ورودی 1- تا گام 4 که هیچ وظیفه‌ای پیدا نمی‌کند. سطر بالا نام وظایف برنامه‌ریزی‌شده در هر گام را نشان می‌دهد: __start__، model، دو وظیفه PUSH ابزارها، مجدداً model، و سپس none. چهار سطر پایین نسخه __start__، messages، branch:to:model و __pregel_tasks را پس از هر گام نشان می‌دهند. خانه پر کانالی است که در آن گام نوشته شده، خانه خط‌چین‌دار کانالی است که خواننده‌اش آن را با یک نسخه جدید پاک کرده، و عدد خاکستری ساده نسخه‌ای است که از گام قبل منتقل شده است. هر کانالی که در یک گام تغییر کند، همان عدد را می‌گیرد. فلش‌های کهربایی از نسخه کانالی که محرک یک وظیفه است به آن وظیفه در گام بعدی کشیده شده‌اند. سطر پایین نسخه‌ای از branch:to:model است که model دیده بود. در گام 4 کانال در نسخه 5 است و model نسخه 4 را دیده بود، اما کانال خالی است، بنابراین هیچ وظیفه‌ای اجرا نمی‌شود. SUPERSTEP -1 0 1 2 3 4 وظایف برنامه‌ریزی‌شده PULL یا PUSH __start__ پیام‌ها branch:to:model __pregel_tasks model دیده بود branch:to:model input v1 - __start__ v2 v2 v2 - model v2 v3 v3 v3 - tools[0] tools[1] v2 v4 v4 v4 v2 model v2 v5 v5 v4 v2 هیچ v2 v5 v5 v4 v4 1 1 step 1: messages, __pregel_tasks and branch:to:model all get v3 2 2 گام 3: v4 در branch:to:model از v2 دیده‌شده جدیدتر است، پس model اجرا می‌شود 3 3 گام 4: v5 از v4 دیده‌شده جدیدتر است، اما کانال خالی است: هیچ وظیفه‌ای نیست نوشته‌شده، نسخه جدید خوانده و پاک‌شده، نسخه جدید وظیفه PUSH از یک Send نسخه‌ای که وظیفه بعدی را تحریک می‌کند عدد خاکستری: نسخه منتقل‌شده کانال خالی، چیزی را تحریک نمی‌کند
ستون‌ها ابرگام‌ها هستند، از گام ورودی تا گامی که هیچ وظیفه‌ای پیدا نمی‌کند. برچسب‌های کهربایی وظایف برنامه‌ریزی‌شده هستند. در سطرهای کانال، خانه پر نشان‌دهنده یک نوشتن با نسخه جدیدش است، و خانه خط‌چین‌دار خوانده و پاک شده است. فلش‌های کهربایی از یک نسخه به وظیفه‌ای اشاره دارند که آن را تحریک می‌کند. برگرفته از capture/lab/internals/01-superstep/trace.jsonl.

نسخه‌ها تعیین می‌کنند چه چیزی در نوبت بعد اجرا شود

نسخه‌ی کانال (Channel version): عددی که حلقه برای هر کانال در چک‌پوینت ذخیره می‌کند. کانالی که در یک ابرگام تغییر کند، نسخه‌ی جدیدی می‌گیرد.

قاعده ساده و البته سراسری است. apply_writes بالاترین نسخه‌ی موجود میان همه‌ی کانال‌ها را می‌گیرد و یک واحد به آن اضافه می‌کند {{code libs/langgraph/langgraph/pregel/_algo.py:271-282}}. تمام کانال‌هایی که در آن ابرگام تغییر می‌کنند دقیقاً همین عدد را دریافت خواهند کرد. در گام 1 بالا، کانال‌های messages، __pregel_tasks و branch:to:model همگی به نسخه‌ی 3 ارتقا یافتند.

versions_seen: نگاشتی در چک‌پوینت، از هر گره به نسخه‌ی هریک از کانال‌های راه‌انداز آن در زمان آخرین باری که آن گره اجرا شده است.

تابع apply_writes مقدار versions_seen را فقط برای کانال‌هایی به‌روزرسانی می‌کند که وظیفه را فعال کرده‌اند {{code libs/langgraph/langgraph/pregel/_algo.py:262-269}}. پس از گام 1، گره model کانال branch:to:model را در نسخه‌ی 2 دیده است. در گام 3 آن کانال روی نسخه‌ی 4 قرار دارد؛ بنابراین model دوباره اجرا می‌شود. راه‌انداز وظیفه‌ی PUSH برابر با __pregel_push است که یک کانال واقعی نیست؛ به همین دلیل در ردگیری محاسبات، مقدار versions_seen برای tools به‌صورت {} خالی می‌ماند.

یک نکته‌ی ظریف مشخص می‌کند چرا اجرا به پایان می‌رسد. کانال branch:to:model از نوع EphemeralValue است. وقتی model آن را می‌خواند، حلقه مقدار آن را پاک می‌کند، ولی همچنان یک نسخه‌ی جدید به آن اختصاص می‌دهد {{code libs/langgraph/langgraph/pregel/_algo.py:284-292}}. در گام 4 نسخه‌ی آن 5 است و model نسخه‌ی 4 را دیده، اما کانال خالی است. مرحله‌ی برنامه‌ریزی هم نسخه‌ی جدیدتر می‌خواهد و هم وجود مقدار؛ در نتیجه وظیفه‌ای اجرا نمی‌شود و حلقه متوقف می‌گردد.

ادغامِ نوشتن‌ها بر اساس ترتیب مسیر وظیفه

تابع apply_writes وظایف را پیش از اعمال هر تغییری بر اساس مسیرشان مرتب می‌کند {{code libs/langgraph/langgraph/pregel/_algo.py:256}}. سپس کاهنده (reducer) فارغ از اینکه وظایف به چه ترتیبی تمام شده‌اند، نوشتن‌ها را با همان ترتیب دریافت می‌کند.

ما این رفتار را اندازه‌گیری کردیم؛ روی ماشین مهمان x86 با مدل Qwen3 4B، و 3 اجرا برای هر حالت. دو گره‌ی موازی، a و b، هرکدام از مدل پاسخی می‌خواهند و آن را با operator.add به یک لیست پیوست می‌کنند. یکی از گره‌ها متنی 60 کلمه‌ای می‌خواهد و دیگری متنی تک‌کلمه‌ای:

شش اجرا، دو ترتیب پایان، یک ترتیب merge capture/lab/internals/02-channels/trace.txt
slow node=a: finish order (node, model seconds)=[('a', 5.58), ('b', 5.75)]  merged list=['a', 'b']
slow node=a: finish order (node, model seconds)=[('b', 0.6), ('a', 5.93)]  merged list=['a', 'b']
slow node=a: finish order (node, model seconds)=[('b', 0.6), ('a', 5.85)]  merged list=['a', 'b']
slow node=b: finish order (node, model seconds)=[('b', 5.48), ('a', 5.62)]  merged list=['a', 'b']
slow node=b: finish order (node, model seconds)=[('b', 5.7), ('a', 5.83)]  merged list=['a', 'b']
slow node=b: finish order (node, model seconds)=[('b', 5.67), ('a', 5.8)]  merged list=['a', 'b']

هر جفت شامل نود و ثانیه‌های فراخوانی مدل آن است، به ترتیبی که نودها بازگشتند.

فراخوانی‌های مدل به اندازه‌ی طول درخواستی زمان نبردند. یک سرور Ollama روی CPU به هر دو گره پاسخ می‌داد، در نتیجه پاسخ کوتاه ممکن بود پشت سر پاسخ بلند معطل شود. گره b در 5 بار از 6 اجرا زودتر بازگشت، اما در هر 6 بار لیست خروجی ['a', 'b'] بود.

مسیرهای PULL قبل از مسیرهای PUSH مرتب می‌شوند. نوشتن‌های گرهی که Command(goto=...) با نام مشخص راه‌اندازی کرده، پیش از نوشتن‌های وظایف Send در همان ابرگام اعمال می‌شوند. در داده‌های ثبت‌شده، گره a نام یک شهر را از مدل پرسید و وظیفه‌ی c را برای دیدن وضعیت هوای آن فرستاد. بخش برنامه‌ریزی ابتدا c را در لیست آورد، و در به‌روزرسانی ابتدا b اعمال شد:

یک وظیفه PULL و یک وظیفه PUSH در یک ابرگام capture/lab/internals/06-send-command/trace.txt
  PLAN step=2: push c path=('__pregel_push', 0, False) triggers=['__pregel_push'] id=5f91e09b; pull b path=('__pregel_pull', 'b') triggers=['branch:to:b'] id=5bbd9a1a
  UPDATE order=["b@('__pregel_pull', 'b')", "c@('__pregel_push', 0, False)"] -> updated=['results'] versions={'__pregel_tasks': [3, 4], 'branch:to:b': [3, 4], 'results': [3, 4]}

شکل این دو ترتیب را در کنار یکدیگر قرار می‌دهد. بنابراین، ترتیب لیست ادغام‌شده در طول اجراهای مختلف پایدار است و می‌توانید آن را تست کنید. این نکته همچنین نشان می‌دهد کاهنده‌ای که فقط آخرین مقدار را نگه می‌دارد، مقدار وظیفه‌ای را حفظ می‌کند که مسیرش در آخرین جایگاهِ مرتب‌سازی قرار می‌گیرد؛ کندترین وظیفه هیچ تأثیری در این نتیجه ندارد.

ترتیب پایان وظایف در برابر ترتیب اعمال نوشتن‌های آن‌هانودها در طی شش اجرا به دو ترتیب مختلف بازگشتند، و نوشتن‌های آن‌ها در هر شش اجرا ابتدا به صورت a و سپس b اعمال شد، زیرا apply_writes بر اساس مسیر مرتب‌سازی می‌کند.
ترتیب پایان وظایف در برابر ترتیب اعمال نوشتن‌های آن‌ها هفت ابرگام هر کدام با دو وظیفه موازی، ضبط‌شده با Qwen3 4B روی سرور مهمان x86. سمت چپ، وظایف به ترتیبی که بازگشتند، به همراه ثانیه‌های فراخوانی مدل آن‌ها. سمت راست، ترتیبی که apply_writes نوشتن‌های آن‌ها را اعمال کرد. در شش اجرا، نودهای a و b هر کدام پاسخی از مدل می‌خواهند و با operator.add به یک لیست اضافه می‌کنند. b در 5 اجرا از 6 اجرا زودتر بازگشت، و لیست در هر 6 اجرا به ترتیب a و b بود. در آخرین ابرگام، نود b توسط Command(goto) به عنوان یک وظیفه PULL و نود c توسط یک Send به عنوان یک وظیفه PUSH آغاز شد. c زودتر به پایان رسید، و b همچنان اول اعمال شد، زیرا مسیرهای PULL قبل از مسیرهای PUSH مرتب می‌شوند. ترتیب بازگشت آن‌ها ترتیب اعمال‌شده ثانیه‌های مدل زیر هر کدام مرتب‌شده با مسیر وظیفه a درخواست 60 کلمه کرد a 5.58 s b 5.75 s a آیتم 1 b آیتم 2 apply_writes a درخواست 60 کلمه کرد b 0.60 s a 5.93 s a آیتم 1 b آیتم 2 a درخواست 60 کلمه کرد b 0.60 s a 5.85 s a آیتم 1 b آیتم 2 b درخواست 60 کلمه کرد b 5.48 s a 5.62 s a آیتم 1 b آیتم 2 b درخواست 60 کلمه کرد b 5.70 s a 5.83 s a آیتم 1 b آیتم 2 b درخواست 60 کلمه کرد b 5.67 s a 5.80 s a آیتم 1 b آیتم 2 Command و Send c PUSH b PULL b PULL c PUSH یک وظیفه PUSH از Send b در 5 از 6 اول برگشت، در 6 از 6 به صورت a سپس b ترکیب شد
هر سطر یک اجرا است. سمت چپ، نودها به ترتیبی که بازگشتند، همراه با مدت‌زمان (ثانیه) فراخوانی مدل آن‌ها. سمت راست، ترتیبی که apply_writes استفاده کرده است. سطر آخر یک ابرگام با یک وظیفه PULL و یک وظیفه PUSH است و کادر خط‌چین‌دار وظیفه PUSH است. برگرفته از capture/lab/internals/02-channels/trace.txt و capture/lab/internals/06-send-command/trace.txt.

محدودیت بازگشت دقیقاً چه چیزی را می‌شمارد؟

حلقه مقدار stop را برابر با گام فعلی به‌اضافه‌ی حد مجاز به‌اضافه‌ی یک قرار می‌دهد، و زمانی که گام از stop فراتر رود با خطا متوقف می‌شود {{code libs/langgraph/langgraph/pregel/_loop.py:1923}} {{code libs/langgraph/langgraph/pregel/_loop.py:666}}. پس این محدودیت ابرگام‌ها را می‌شمارد، و گام پنهان __start__ هم یکی از آن‌هاست.

ما شمارش را اندازه‌گیری کردیم؛ روی سرور مهمان x86 با Qwen3 4B، با یک بار اجرا به ازای هر مقدار محدودیت. پرامپت به مدل می‌گوید در هر نوبت گفت‌وگو (turn) یک ابزار صدا بزند:

recursion_limit ابرگام‌های اجراشده فراخوانی‌های مدل پیش از خطا
1 2 1
4 5 2
5 6 3
10 11 5
25 26 13

محدودیت k به ازای ورودی جدید، k به‌اضافه‌ی یک ابرگام اجرا می‌کند، و مدل تقریباً k تقسیم بر 2 بار اجرا می‌شود. ازسرگیری یک نخ (thread) متوقف‌شده با وقفه (interrupt) که محدودیت 4 داشت، 6 ابرگام اجرا کرد: گام‌های 2 تا 7. تابع create_agent این محدودیت را روی گراف خودش 9,999 می‌گذارد {{code libs/langchain_v1/langchain/agents/factory.py:1902}}. یک StateGraph ساده مقدار 10,007 دریافت می‌کند {{code libs/langgraph/langgraph/_internal/_config.py:42-44}}.

راهنمای عملیاتی

اگر ترتیب اهمیتی ندارد، کاهنده‌هایی بنویسید که خروجی‌شان وابسته به ترتیب نباشد؛ مثل عملگر جمع یا مجموعه‌ها (set). اگر ترتیب مهم است، به ترتیب مسیر تکیه کنید و برای آن تست بنویسید، چون کاملاً پایدار است. هرگز به لاگِ زمان پایان اجرای وظایف به عنوان ترتیب نهایی وضعیت نگاه نکنید.

برای کلیدی که دو گره‌ی موازی روی آن می‌نویسند یک کاهنده تعریف کنید، حتی اگر انتظار دارید فقط یک نویسنده داشته باشد. بخش 2.2 نشان می‌دهد نبود یک کاهنده چه بر سر یک نخ می‌آورد.

هنگام تنظیم محدودیت برای یک ایجنت، فراخوانی‌های مدل را بشمارید نه گام‌ها را. برای بودجه‌ی n فراخوانی مدل، مقدار recursion_limit را برابر با 2 برابر n قرار دهید. هر گره‌ی قلاب (hook) before_model یا after_model به ازای هر فراخوانی مدل یک ابرگام اضافه می‌کند؛ بنابراین آن‌ها را هم به حساب آورید.

منابع: capture/lab/internals/01-superstep/trace.txt, capture/lab/internals/01-superstep/trace.jsonl, capture/lab/internals/01-superstep/run.py, capture/lab/internals/02-channels/trace.txt, capture/lab/internals/06-send-command/trace.txt, capture/lab/internals/07-create-agent/trace.txt, capture/lab/internals/common/instrument.py, capture/lab/internals/common/real.py؛ فایل‌های libs/langgraph/langgraph/pregel/main.py, libs/langgraph/langgraph/pregel/_loop.py, libs/langgraph/langgraph/pregel/_algo.py, و libs/langgraph/langgraph/_internal/_config.py در langgraph 1.2.22؛ libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0.

ترجمه‌ی فارسی The superstep loop: plan, execute, update از راهنمای LangChain 101 دوره‌ی AI Engineering from Scratch، نوشته‌ی Rohit Ghumare، تحت مجوز MIT. دستورها، لاگ‌ها و اعداد عیناً از اجراهای ثبت‌شده‌ی متن اصلی‌اند. فهرست راهنما