کلاس
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.