تلاش ناموفق یک گره ابتدا به
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 تعریف شده است:
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 برای کنترلکننده اضافه میکند. برنامه سه بار تلاش کرد، سپس کنترلکننده اجرا شد و گراف به پایان رسید:
{
"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 پیشفرض داد. گره فقط یک بار اجرا شد و این خطا را صادر کرد:
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 این خطا را صادر کرد:
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 وضعیت قرار داد و اجرا ادامه پیدا کرد. تصویر مسیر این شکست را نشان میدهد.
مهلت زمانی فقط به گرههای ناهمگام اعمال میشود. کد برنامه مهلت زمانی را روی گرههای همگام (sync) نمیپذیرد و رد میکند، زیرا تابع همگام پایتون را نمیتوان از بیرون متوقف کرد {{code libs/langgraph/langgraph/_internal/_timeout.py}}. در کیت فعلاً گزارشی از این خطای عدمپذیرش ثبت نشده است. نمونهی ثبتشدهی آن در ویرایش بعدی همراه با سایر موارد باز بخش 8.8 ارائه خواهد شد.
محدودیت بازگشت
محدودیت بازگشت (Recursion limit): تعداد مراحلی که پس از آن، اجرای برنامه با خطای GraphRecursionError متوقف میشود. هر مرحله از حلقهی Pregel، فارغ از اینکه چه تعداد گره در آن اجرا شوند، یک واحد شمرده میشود.
حلقهای با تنظیم recursion_limit=5 در پیکربندی، پس از پنج مرحله با خطا متوقف شد:
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 بار فراخوانی مدل متوقف کرد. تصویر هر کدام از این اجراها را نشان میدهد.
بنابراین هر نوبت گفتوگو (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).