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

کنترل‌کننده‌های خطا، مهلت زمانی گره‌ها و محدودیت بازگشت

Error handlers, node timeouts, and the recursion limit

فهرست مطالب
  1. اول RetryPolicy، سپس کنترل‌کننده‌ی خطا
  2. تنظیم پیش‌فرض retry_on خطای ValueError را دوباره امتحان نمی‌کند
  3. مهلت زمانی گره‌ها
  4. محدودیت بازگشت
  5. RemainingSteps

تلاش ناموفق یک گره ابتدا به RetryPolicy و سپس به error_handler آن ارجاع داده می‌شود؛ پایان مهلت زمانی یک شکست به شمار می‌رود و محدودیت بازگشت جلوی اجرای بی‌پایان را می‌گیرد.

فرض کنید گرهی سرویسی را فراخوانی می‌کند که با خطا روبه‌رو می‌شود؛ شما می‌خواهید گراف دوباره تلاش کند و سپس سراغ ثبت گزارش برود. گره دیگری منتظر سرویسی می‌ماند که هرگز پاسخی نمی‌دهد. حلقه‌ی سومی هم هیچ‌وقت به شرط توقف خود نمی‌رسد. LangGraph برای هر یک از این موارد تنظیمی دارد که با ترتیبی مشخص و ثابت عمل می‌کنند.

با پایان این بخش، می‌توانید به گره‌ها سیاست تلاش مجدد (retry policy)، کنترل‌کننده‌ی خطا (error handler) و مهلت زمانی (timeout) اختصاص دهید. همچنین یاد می‌گیرید تعداد تلاش‌های گره را پیش‌بینی کنید و محدودیت بازگشت (recursion limit) مناسبی برای آن بگذارید.

اول RetryPolicy، سپس کنترل‌کننده‌ی خطا

RetryPolicy: تنظیمات اجرای دوباره‌ی یک گره‌ی ناموفق: max_attempts، زمان انتظار بین تلاش‌ها، و retry_on که استثناهای مجاز برای تلاش مجدد را تعیین می‌کند.

کنترل‌کننده‌ی خطا (Error handler): تابعی که پس از آخرین تلاش ناموفق یک گره اجرا می‌شود. این تابع وضعیت (state) و یک NodeError دریافت می‌کند و یک به‌روزرسانی وضعیت یا یک Command برمی‌گرداند.

گره flaky در کیت آموزشی، در هر تلاش خطای ValueError صادر می‌کند. برای آن سیاستی با 3 بار تلاش جهت تکرار روی ValueError، و کنترل‌کننده‌ای برای رفتن به report تعریف شده است:

یک گره با سیاست تلاش مجدد و یک کنترل‌کننده خطا capture/s_graph.py
    def handler(state, error: NodeError):
        return Command(update={"status": f"recovered from {error.node}: {error.error}"}, goto="report")

    g = StateGraph(S)
    g.add_node("flaky", flaky, retry_policy=RetryPolicy(max_attempts=3, initial_interval=0.0, jitter=False, retry_on=ValueError), error_handler=handler)

متد compile گره‌ای با نام __error_handler__flaky برای کنترل‌کننده اضافه می‌کند. برنامه سه بار تلاش کرد، سپس کنترل‌کننده اجرا شد و گراف به پایان رسید:

سه تلاش، سپس کنترل‌کننده capture/out/37-error-handler-timeout.txt
{
  "status": "recovered from flaky: upstream failed on try 3",
  "attempts": 3
}

tries:
[
  1,
  2,
  3
]

مقدار max_attempts تلاش اول را هم می‌شمارد. در صفحه‌ی تحمل خطا (fault tolerance) این ترتیب قید شده است: سیاست تلاش مجدد اول تصمیم می‌گیرد، و کنترل‌کننده فقط زمانی اجرا می‌شود که تلاشی باقی نمانده باشد {{docs oss/python/langgraph/fault-tolerance}}. فراخوانی set_node_defaults(error_handler=...) روی StateGraph یک کنترل‌کننده‌ی یکسان به همه‌ی گره‌ها می‌دهد. در کیت، گره‌ای که KeyError صادر کرد به همین کنترل‌کننده ارجاع شد و اجرای آن با default handler: KeyError in boom پایان یافت.

تنظیم پیش‌فرض retry_on خطای ValueError را دوباره امتحان نمی‌کند

یک RetryPolicy() بدون ورودی، 3 بار تلاش می‌کند؛ پیش از تلاش دوم 0.5 ثانیه منتظر می‌ماند، در هر مرحله زمان انتظار را دو برابر می‌کند تا به 128 ثانیه برسد، و مقداری نوسان تصادفی (jitter) اضافه می‌کند {{code libs/langgraph/langgraph/types.py}}. مقدار retry_on در این حالت default_retry_on است. این تابع خطاهای ConnectionError و کدهای وضعیت HTTP بین 500 تا 599 را در کتابخانه‌های httpx و requests دوباره امتحان می‌کند. خطای requests.HTTPError بدون پاسخ سرور نیز دوباره امتحان می‌شود. اما خطاهای ValueError، TypeError، ArithmeticError، ImportError، LookupError، NameError، SyntaxError، RuntimeError، ReferenceError، StopIteration، StopAsyncIteration یا سایر انواع OSError را دوباره اجرا نمی‌کند. به جز این موارد، همه‌ی خطاهای دیگر دوباره امتحان می‌شوند {{code libs/langgraph/langgraph/_internal/_retry.py}}.

کیت به flaky سیاستی با 2 بار تلاش و با همان retry_on پیش‌فرض داد. گره فقط یک بار اجرا شد و این خطا را صادر کرد:

یک ValueError با retry_on پیش‌فرض capture/out/37-error-handler-timeout.txt
raised builtins.ValueError: upstream failed on try 1

tries:
[
  1
]

بنابراین سیاستی که برای یک سرویس ناپایدار تنظیم می‌کنید اثری روی خطای تجزیه (parse error) ندارد؛ و در اغلب موارد همین را هم می‌خواهید. از آنجا که KeyError نوعی LookupError است، آن هم دوباره امتحان نمی‌شود. اگر می‌خواهید خطاهای مشخصی مجدداً امتحان شوند، انواع آن‌ها را صراحتاً در retry_on بنویسید.

تلاش مجدد، کل گره را دوباره از اول اجرا می‌کند. صفحه‌ی تحمل خطا بیان می‌کند که تغییرات ثبت‌شده‌ی تلاشِ ناموفق دور ریخته می‌شوند، اما عوارض جانبی (side effects) داخل گره باقی می‌مانند {{docs oss/python/langgraph/fault-tolerance}}. همراه با هر عارضه‌ی جانبی، یک کلید یکتایی تراکنش (idempotency key) ارسال کنید. بخش 1.1 نشان می‌دهد این کلید در آزمایشگاه بررسی خرابی‌ها چه نقشی ایفا کرد.

مهلت زمانی گره‌ها

مهلت زمانی گره (Node timeout): پارامتر timeout در متد add_node بر حسب ثانیه، برای هر تلاش در یک گره ناهمگام (async). اگر اجرای یک تلاش بیشتر طول بکشد، با خطای NodeTimeoutError شکست می‌خورد.

گره slow در کیت آموزشی، 2 ثانیه منتظر می‌ماند و مهلت زمانی آن 0.05 ثانیه است. اجرای ainvoke این خطا را صادر کرد:

یک گره ناهمگام فراتر از زمان انتظار آن capture/out/37-error-handler-timeout.txt
raised langgraph.errors.NodeTimeoutError: Node 'slow' exceeded its run timeout of 0.050s (elapsed: <seconds>).

مهلت زمانی در حکم یک تلاش ناموفق است؛ بنابراین ابتدا سیاست تلاش مجدد و سپس کنترل‌کننده‌ی خطا به آن رسیدگی می‌کنند. با افزودن کنترل‌کننده، همین گره مقدار NodeTimeoutError: Node 'slow' exceeded its run timeout of 0.050s (elapsed: <seconds>). را در فیلد status وضعیت قرار داد و اجرا ادامه پیدا کرد. تصویر مسیر این شکست را نشان می‌دهد.

مسیر تلاش ناموفق یک گرههر تلاش ناموفق، حتی پایان زمان انتظار، ابتدا به retry_on می‌رود و کنترل‌کننده خطا تنها پس از آخرین تلاش اجرا می‌شود، یا اجرای برنامه خطا می‌دهد.
مسیر تلاش ناموفق یک گره نمودار تصمیم‌گیری. یک تلاش گره خطا پرتاب می‌کند یا بیش از زمان مجاز اجرا شده و با NodeTimeoutError شکست می‌خورد. بررسی اول retry_on همراه با تلاش‌های باقی‌مانده است: پاسخ بله گره را دوباره اجرا می‌کند، همان‌طور که برای flaky در تلاش‌های 1 تا 3 با retry_on به صورت ValueError اتفاق افتاد. در صورت نبود تلاش باقی‌مانده یا رد استثنا توسط retry_on، بررسی بعدی error_handler است. در صورت وجود کنترل‌کننده، گره __error_handler__flaky اجرا شده و دستور Command آن به report می‌رود. در صورت نبود کنترل‌کننده، تابع invoke خطا صادر می‌کند، درست مانند خطای ValueError در try 1 با retry_on پیش‌فرض. تلاش گره ناموفق می‌شود یک استثنا، یا NodeTimeoutError پایان زمان انتظار کند، 0.05 ثانیه retry_on matches, attempts left? سیاست RetryPolicy گره بله: اجرای دوباره ناپایدار، تلاش‌های 1 تا 3 error_handler set? on the node or by set_node_defaults no ValueError with the default retry_on __error_handler__flaky Command(goto='report') بله خطای invoke خطای ValueError: upstream در تلاش 1 ناموفق شد no گزارش وضعیت: بازیابی از حالت ناپایدار اجرا تنها در مسیر سمت چپ ادامه می‌یابد. مسیر سمت راست اجرا را پایان می‌دهد.
از تلاش ناموفق در بالا شروع کنید. هر کادر خاکستری یک بررسی است و نتیجه ابزار در کنار فلش آن آمده است. کادر صورتی خطایی است که از invoke خارج می‌شود. از capture/out/37-error-handler-timeout.txt.

مهلت زمانی فقط به گره‌های ناهمگام اعمال می‌شود. کد برنامه مهلت زمانی را روی گره‌های همگام (sync) نمی‌پذیرد و رد می‌کند، زیرا تابع همگام پایتون را نمی‌توان از بیرون متوقف کرد {{code libs/langgraph/langgraph/_internal/_timeout.py}}. در کیت فعلاً گزارشی از این خطای عدم‌پذیرش ثبت نشده است. نمونه‌ی ثبت‌شده‌ی آن در ویرایش بعدی همراه با سایر موارد باز بخش 8.8 ارائه خواهد شد.

محدودیت بازگشت

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

حلقه‌ای با تنظیم recursion_limit=5 در پیکربندی، پس از پنج مرحله با خطا متوقف شد:

یک حلقه فراتر از محدودیت بازگشت آن capture/out/38-recursion-limit.txt
raised langgraph.errors.GraphRecursionError: Recursion limit of 5 reached without hitting a stop condition. You can increase the limit by setting the `recursion_limit` config key.
For troubleshooting, visit: https://docs.langchain.com/oss/python/langgraph/errors/GRAPH_RECURSION_LIMIT

سه مقدار در بخش‌های مختلف به عنوان حد پیش‌فرض تعریف شده‌اند و به‌سادگی ممکن است اشتباه گرفته شوند:

جایگاه پیش‌فرض عامل تنظیم‌کننده
یک StateGraph کامپایل‌شده 10007 ثابت DEFAULT_RECURSION_LIMIT در langgraph، یا متغیر LANGGRAPH_DEFAULT_RECURSION_LIMIT
گراف حاصل از create_agent 9999 پیکربندی که create_agent به گراف خود متصل می‌کند
پیکربندی یک runnable در langchain-core 25 ثابت DEFAULT_RECURSION_LIMIT در langchain_core

صفحه‌ی مستندات API گراف، این عدد را از نسخه‌ی 1.1.4 به بعد langgraph برابر 10,007 و بین نسخه‌های 1.0.6 تا 1.1.3 برابر 10,000 اعلام کرده است {{docs oss/python/langgraph/graph-api}}. راهنماهای قدیمی‌تر عدد 25 را پیش‌فرض گراف معرفی می‌کنند. در نسخه‌ی سنجاق‌شده، عدد 25 پیش‌فرض پیکربندی runnable در langchain_core است و گراف از آن استفاده نمی‌کند {{code libs/core/langchain_core/runnables/config.py}}. مقدار recursion_limit را در بالاترین سطح پیکربندی بفرستید، نه درون بخش configurable {{docs oss/python/langgraph/graph-api}}. این مستند، اختلاف این اعداد را تحت عنوان مغایرت D105 ثبت کرده و بخش 8.1 محدودیت Agent Server را نشان می‌دهد.

ما هر یک از این مقادیر پیش‌فرض را روی سیستم‌عامل Mac در یک حلقه‌ی ساده و بدون مدل سنجیدیم (یک بار اجرا برای هر حالت). حلقه‌ی ساده در گام 10007 متوقف شد. با تنظیم متغیر روی 25 یا با قرار دادن recursion_limit=25، در گام 25 متوقف شد.

ایجنت با مدل Qwen3 4B روی ماشین مهمان در سرور x86 اجرا شد؛ به آن دستور داده شد تا زمانی که ابزار پاسخِ «پایان» نداده مدام آن را فراخوانی کند؛ پاسخی که هرگز نیامد. با recursion_limit=25، ایجنت 13 بار مدل را فراخوانی کرد (مدل Qwen3 4B، ماشین مهمان سرور x86، 3 از 3 مورد). با recursion_limit برابر 101، تعداد فراخوانی‌ها به 51 رسید. بدون تعیین محدودیت، اسکریپت آزمایشگاه آن را در ثانیه‌ی 1200 و پس از 121 بار فراخوانی مدل متوقف کرد. تصویر هر کدام از این اجراها را نشان می‌دهد.

گام‌های پیش از GraphRecursionErrorیک گراف ساده در 10007 گام متوقف می‌شود و هر گام ایجنت یک فراخوانی مدل یا یک فراخوانی ابزار است، بنابراین 25 گام اجازه 13 فراخوانی مدل را می‌دهد.
گام‌های پیش از GraphRecursionError یک نمودار نقطه‌ای در مقیاس لگاریتمی از گام‌هایی که هر اجرا پیش از توقف طی کرده است. یک حلقه StateGraph روی مک، بدون مدل، با recursion_limit برابر 25 و همچنین با تنظیم متغیر محیطی روی 25، در 25 گام و بدون کانفیگ در 10007 گام متوقف شد. یک ایجنت create_agent با مدل Qwen3 4B روی سرور میهمان x86، در هر 3 اجرا از 3 اجرا، با 25 گام پس از 13 فراخوانی مدل و با 101 گام پس از 51 فراخوانی متوقف شد. با حد پیش‌فرض، اسکریپت آزمایشگاه آن را در 242 گام و پس از 121 فراخوانی مدل طی 21 دقیقه متوقف کرد. 10 100 1k 10k گام‌های قبل از توقف، مقیاس لگاریتمی 25 کانفیگ 25 25 متغیر محیطی 25 10007 پیش‌فرض 25 کانفیگ 25 13 فراخوانی 101 کانفیگ 101 51 فراخوانی 242 پیش‌فرض 121 فراخوانی حلقه StateGraph، سیستم‌عامل مک create_agent, Qwen3 4B فراخوانی‌های زیر ایجنت، فراخوانی مدل هستند. ایجنت روی سرور میهمان x86 اجرا شد. اجرای پیش‌فرض صورتی به حد نرسید: اسکریپت آزمایشگاه آن را پس از 1260 ثانیه متوقف کرد.
برای هر مورد یک نقطه در مقیاس لگاریتمی بخوانید. اجراهای گراف از سیستم‌عامل مک و اجراهای ایجنت از مدل Qwen3 4B روی سرور میهمان x86 هستند. برچسب، نام مورد و فراخوانی‌های مدل آن را نشان می‌دهد. برگرفته از capture/lab/summary/recursion-mac.json و capture/lab/summary/recursion-x86.json.

بنابراین هر نوبت گفت‌وگو (turn) در ایجنت شامل دو مرحله است: یکی در model و دیگری در tools. فراخوانی‌های موازی ابزار (parallel tool calls) حاصل از یک نوبت مدل، به صورت وظایف (tasks) مجزا در همان مرحله‌ی tools اجرا می‌شوند {{code libs/langchain_v1/langchain/agents/factory.py}}. ایجنتی که به n نوبت پیاپی از فراخوانی ابزار و یک پاسخ نیاز دارد، دست‌کم به 2n + 1 مرحله نیاز خواهد داشت.

RemainingSteps

RemainingSteps: مقداری مدیریت‌شده که آن را به صورت یک کلید در وضعیت تعریف می‌کنید. LangGraph تعداد گام‌های باقی‌مانده تا سقف مجاز را در آن قرار می‌دهد، و گره یا یال می‌تواند آن را بخواند.

حلقه‌ی تعریف‌شده در کیت، وقتی remaining_steps به 2 یا کمتر برسد مسیر را به END هدایت می‌کند. با تنظیم recursion_limit=5، اجرای برنامه خودبه‌خود در حالی که n برابر 3 بود متوقف شد و هیچ خطایی صادر نکرد. از این متغیر استفاده کنید تا اجرای طولانی را به جای توقف با خطا، با یک پاسخ ناقص به پایان برسانید.

منابع: capture/s_graph.py، capture/out/37-error-handler-timeout.txt، capture/out/38-recursion-limit.txt؛ capture/lab/summary/recursion-mac.json، capture/lab/T17-claims-mac/01-recursion-limit.jsonl، capture/lab/summary/recursion-x86.json، capture/lab/T17-claims-x86/01-claims.jsonl، capture/lab/T17-claims-x86/02-nolimit.jsonl؛ فایلهای libs/langgraph/langgraph/types.py، libs/langgraph/langgraph/_internal/_retry.py، libs/langgraph/langgraph/_internal/_timeout.py، libs/langgraph/langgraph/_internal/_config.py، و libs/langgraph/langgraph/graph/state.py در langgraph 1.2.22؛ libs/core/langchain_core/runnables/config.py و libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0؛ مستندات docs.langchain.com در commit مستندات 04d4d4a (بخش‌های oss/python/langgraph/fault-tolerance و oss/python/langgraph/graph-api).