مرجع R.2

قلاب‌ها و کلاس‌های میدل‌ور

Middleware hooks and classes

فهرست مطالب
  1. شش قلاب اصلی
  2. ترتیب اجرا و نام‌گذاری
  3. دکوراتورها
  4. انواع درخواست و پاسخ
  5. 19 کلاس میدل‌ور
  6. انواع بازبینی انسانی (Human Review)

کلاس AgentMiddleware شش قلاب (hook) دارد که هرکدام در دو قالب همگام (sync) و ناهمگام (async) ارائه می‌شوند و langchain نسخه 1.5.0 بر پایه‌ی آن‌ها 19 کلاس میدل‌ور می‌سازد.

هر میدل‌ور زیرکلاسی از AgentMiddleware در langchain.agents.middleware است. این ماژول 50 نام مختلف را صادر (export) می‌کند {{code libs/langchain_v1/langchain/agents/middleware/init.py}}. همه‌ی مسیرهای این صفحه نسبت به libs/langchain_v1/langchain/agents/middleware/ در langchain==1.5.0 هستند، مگر اینکه نام پکیج دیگری صریحاً آمده باشد. بخش 4.5 ترتیب اجرای قلاب‌ها را نشان می‌دهد و بخش 4.6 زمان استفاده از هر کلاس را مشخص می‌کند.

شش قلاب اصلی

کد AgentMiddleware از خط 387 فایل types.py شروع می‌شود {{code libs/langchain_v1/langchain/agents/middleware/types.py:387}}.

قلاب حالت ناهمگام نوع آرگومان‌ها خروجی خط
before_agent abefore_agent node state, runtime یک به‌روزرسانی وضعیت یا None 433, 444
before_model abefore_model node state, runtime یک به‌روزرسانی وضعیت یا None 457, 468
wrap_model_call awrap_model_call wrap request, handler یکی از موارد ModelResponse، AIMessage یا ExtendedModelResponse 505, 600
after_model aafter_model node state, runtime یک به‌روزرسانی وضعیت یا None 481, 492
wrap_tool_call awrap_tool_call wrap request, handler یک ToolMessage یا Command 676, 758
after_agent aafter_agent node state, runtime یک به‌روزرسانی وضعیت یا None 652, 663

اگر میدل‌وری فقط حالت همگام یک قلاب wrap را پیاده کند، هنگام فراخوانی با ainvoke خطای NotImplementedError صادر می‌شود. پیام خطا سه راهکار برای رفع آن ارائه می‌دهد؛ حالت معکوس نیز دقیقاً همین خطا را ایجاد می‌کند {{code libs/langchain_v1/langchain/agents/middleware/types.py:588-598}} {{code libs/langchain_v1/langchain/agents/middleware/types.py:640-650}}.

ترتیب اجرا و نام‌گذاری

قاعده جایگاه در کد
هر قلابِ node به یک گره در گراف با ساختار <name>.<hook> تبدیل می‌شود؛ مثل HumanInTheLoopMiddleware.after_model. {{code libs/langchain_v1/langchain/agents/factory.py:1639-1716}}
مقدار پیش‌فرض name همان نام کلاس است. وجود دو میدل‌ور با نام یکسان خطای AssertionError بالا می‌آورد. {{code libs/langchain_v1/langchain/agents/middleware/types.py:425-431}} {{code libs/langchain_v1/langchain/agents/factory.py:1163-1165}}
before_agent و before_model دقیقاً به همان ترتیبِ موجود در لیست اجرا می‌شوند. {{code libs/langchain_v1/langchain/agents/factory.py:1816-1857}}
after_model به ترتیب معکوس لیست اجرا می‌شود، چون گره model به آخرین مورد متصل است. {{code libs/langchain_v1/langchain/agents/factory.py:1858-1873}}
after_agent هم به ترتیب معکوس لیست و تنها یک بار در پایان اجرای کل جریان کار می‌کند. {{code libs/langchain_v1/langchain/agents/factory.py:1875-1898}}
اولین میدل‌ور لیست، بیرونی‌ترین لایه‌ی هر قلاب wrap خواهد بود. {{code libs/langchain_v1/langchain/agents/middleware/types.py:515-517}}
قلاب‌های node فقط در صورتی می‌توانند به مقصدی jump_to برگردانند که آن را از قبل با hook_config(can_jump_to=...) تعریف کرده باشند. {{code libs/langchain_v1/langchain/agents/middleware/types.py:881}}

فایل 09-middleware-order.txt ترتیب اجرای مراحل را برای یک چرخه رفت‌وبرگشت فراخوانی ابزار به همراه سه میدل‌ور ثبت کرده است.

دکوراتورها

هر دکوراتور یک تابع را به یک کلاس میدل‌ور با یک قلاب واحد تبدیل می‌کند {{code libs/langchain_v1/langchain/agents/middleware/types.py:881-2039}}.

دکوراتور قلاب خط
before_agent before_agent 1320
before_model before_model 954
after_model after_model 1143
after_agent after_agent 1532
wrap_model_call wrap_model_call 1866
wrap_tool_call wrap_tool_call 2039
dynamic_prompt wrap_model_call، به‌علاوه تنظیم پیام سیستمی (System Message) 1706
hook_config هیچ‌کدام؛ صرفاً can_jump_to را روی متد قلاب تعریف می‌کند 881

دکوراتورهای قلاب node آرگومان‌های نام‌دار state_schema، tools، can_jump_to و name را می‌پذیرند. دو دکوراتور wrap آرگومان can_jump_to را دریافت نمی‌کنند.

انواع درخواست و پاسخ

نوع فیلدها خط
ModelRequest فیلدهای model، messages (بدون پیام سیستمی)، system_message، tool_choice، tools، response_format، state، runtime و model_settings. با override(**kw) قابل تغییر است types.py:90
ModelResponse فیلدهای result، یک لیست از پیام‌ها و structured_response types.py:275
ExtendedModelResponse فیلد model_response و یک command اختیاری types.py:293
ToolCallRequest فیلدهای tool_call، tool، state و runtime. با override(**kw) قابل تغییر است langgraph.prebuilt tool_node.py:141

{{code libs/langchain_v1/langchain/agents/middleware/types.py:90-317}} {{code libs/prebuilt/langgraph/prebuilt/tool_node.py:141-175}}

19 کلاس میدل‌ور

در هر سطر، قلاب‌ها، مقادیر پیش‌فرض سازنده که رفتار کلاس را تغییر می‌دهند و نام فایل و خط مربوط به کلاس و متد __init__ آن آمده است. پارامترهای بدون مقدار پیش‌فرض الزامی هستند.

کلاس قلاب‌ها مقادیر پیش‌فرض سازنده فایل و خط
SummarizationMiddleware before_model پارامتر model الزامی است، trigger=None، keep=("messages", 20)، trim_tokens_to_summarize=4000 summarization.py:263، :282
ContextEditingMiddleware wrap_model_call edits=None، token_count_method="approximate" context_editing.py:187، :201
HumanInTheLoopMiddleware after_model, wrap_tool_call پارامتر interrupt_on الزامی است، description_prefix="Tool execution requires approval"، interrupt_mode="batched" human_in_the_loop.py:398، :491
ModelCallLimitMiddleware before_model, after_model thread_limit=None، run_limit=None، exit_behavior="end" model_call_limit.py:94، :126
ToolCallLimitMiddleware after_model tool_name=None، thread_limit=None، run_limit=None، exit_behavior="continue" tool_call_limit.py:141، :202
ToolRetryMiddleware wrap_tool_call max_retries=2، tools=None، on_failure="continue"، backoff_factor=2.0، initial_delay=1.0، max_delay=60.0، jitter=True tool_retry.py:32، :133
ModelRetryMiddleware wrap_model_call max_retries=2، on_failure="continue"، backoff_factor=2.0، initial_delay=1.0، max_delay=60.0، jitter=True model_retry.py:33، :116
ModelFallbackMiddleware wrap_model_call ابتدا first_model و سپس هر تعداد مدل دیگر model_fallback.py:342، :368
ModelRefusalMiddleware wrap_model_call بدون پارامتر model_refusal.py:39
ToolErrorMiddleware wrap_tool_call on_error=None، aon_error=None، tools=None. در صورت نبود هر دو کنترل‌کننده (handler)، خطای ValueError صادر می‌کند tool_error.py:37، :84
PIIMiddleware before_model, after_model پارامتر pii_type الزامی است، strategy="redact"، apply_to_input=True، apply_to_output=False، apply_to_tool_results=False pii.py:513، :577
ModelRouterMiddleware before_agent, wrap_model_call پارامترهای choices، instructions و classifier الزامی هستند. طبق یادداشت‌های انتشار، آزمایشی (Beta) با دکوراتور @beta و جدید در نسخه 1.5.0 model_router.py:72، :121
AutoModeMiddleware wrap_tool_call پارامترهای tools و classifier الزامی هستند، criteria=None. طبق یادداشت‌های انتشار در نسخه 1.5.0 اضافه شده و وضعیت Beta تنها در داک‌استرینگ آن آمده و بدون نشان @beta یا هشدار است auto_mode.py:64، :117
TodoListMiddleware wrap_model_call, after_model دارای پرامپت سیستمی و توضیحات ابزار پیش‌فرض todo.py:174، :203
LLMToolSelectorMiddleware wrap_model_call model=None، max_tools=None، always_include=None، max_retries=1 tool_selection.py:121، :150
LLMToolEmulator wrap_tool_call tools=None، model=None tool_emulator.py:27، :71
ProviderToolSearchMiddleware wrap_model_call searchable_tools=None provider_tool_search.py:57، :93
ShellToolMiddleware before_agent, after_agent workspace_root=None، execution_policy=None (که به HostExecutionPolicy() تبدیل می‌شود)، tool_name="shell" shell_tool.py:518، :537
FilesystemFileSearchMiddleware هیچ‌کدام؛ فقط ابزار اضافه می‌کند پارامتر root_path الزامی است، use_ripgrep=True، max_file_size_mb=10 file_search.py:108، :133

{{code libs/langchain_v1/langchain/agents/middleware/model_retry.py:116-125}} {{code libs/langchain_v1/langchain/agents/middleware/tool_call_limit.py:202-208}} {{code libs/langchain_v1/langchain/agents/middleware/model_call_limit.py:126-131}} {{code libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py:491-498}} {{code libs/langchain_v1/langchain/agents/middleware/summarization.py:282-292}} {{code libs/langchain_v1/langchain/agents/middleware/pii.py:577-586}} {{code libs/langchain_v1/langchain/agents/middleware/file_search.py:133-138}} {{code libs/langchain_v1/langchain/agents/middleware/auto_mode.py:117-124}} {{code libs/langchain_v1/langchain/agents/middleware/model_router.py:121-127}}

مقدار 2 برای max_retries یعنی در مجموع 3 بار تلاش انجام می‌شود. همان‌طور که در بخش 4.7 آمده، مقدار پیش‌فرض retry_on در هر دو کلاس تلاش مجدد برابر با default_retry_on است. با مقدار پیش‌فرض trigger=None، کلاس SummarizationMiddleware هرگز خلاصه‌سازی نمی‌کند {{code libs/langchain_v1/langchain/agents/middleware/summarization.py:698-701}}.

انواع بازبینی انسانی (Human Review)

نام مقادیر یا فیلدها خط در human_in_the_loop.py
DecisionType approve, edit, reject, respond 87
InterruptMode batched, per_call 170
HITLRequest action_requests, review_configs 107
HITLResponse decisions 289
InterruptOnConfig allowed_decisions, description, args_schema, when 306

مقدار True در interrupt_on اجازه‌ی هر چهار تصمیم را صادر می‌کند {{code libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py:586}}. بخش 6.5 هر دو حالت را اجرا می‌کند.

منابع: libs/langchain_v1/langchain/agents/middleware/init.py، types.py، summarization.py، context_editing.py، human_in_the_loop.py، model_call_limit.py، tool_call_limit.py، tool_retry.py، model_retry.py، model_fallback.py، model_refusal.py، tool_error.py، pii.py، model_router.py، auto_mode.py، todo.py، tool_selection.py، tool_emulator.py، provider_tool_search.py، shell_tool.py، file_search.py، و libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0؛ libs/prebuilt/langgraph/prebuilt/tool_node.py در langgraph 1.2.22؛ و capture/out/09-middleware-order.txt.

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