در نسخهی 1.5.0 کتابخانهی
langchain، تعداد 19 کلاس میدلویر وجود دارد که هرکدام بر پایهی یک یا دو هوک (hook) از مجموعهی شش هوک اصلی ساخته شدهاند؛ مستندات رسمی نیز سه مورد دیگر را فهرست کرده است که به Deep Agents تعلق دارند.
گاهی لازم است روی فراخوانیهای مدل سقف بگذارید، ابزاری را که مدام خطا میدهد دوباره امتحان کنید، یا پیش از ارسال ایمیل یک مرحلهی بازبینی قرار دهید. برای هرکدام از این کارها، کلاسی در langchain.agents.middleware در نظر گرفته شده است؛ البته مقادیر پیشفرض برخی از آنها، کمتر از آن چیزی کار میکنند که نامشان نشان میدهد.
پس از پایان این بخش، میتوانید میدلویر توکار (built-in middleware) مناسب برای هر نیاز را انتخاب کنید، بگویید از کدام هوک بهره میبرد و پارامتر پیشفرض حیاتی آن را نام ببرید. همچنین میتوانید بخش مربوط به آزمون هر میدلویر را در این راهنما پیدا کنید.
19 کلاس در نسخهی پینشده
میدلویر توکار: کلاس میدلویری است که پکیج langchain آن را از ماژول langchain.agents.middleware اکسپورت میکند.
این پکیج 50 نام مختلف را از آن ماژول اکسپورت میکند که 19 تای آنها کلاسهای میدلویر هستند {{code libs/langchain_v1/langchain/agents/middleware/init.py}}. جدول زیر هر کلاس را به همراه هوکهای مربوطه و مقدار پیشفرضی که حتماً باید بدانید فهرست کرده است:
| کلاس | هوکها | کارکرد و مقدار پیشفرض مهم | بخش |
|---|---|---|---|
SummarizationMiddleware |
before_model |
پیامهای قدیمی را با خلاصهی حاصل از یک مدل دوم جایگزین میکند. با مقدار پیشفرض trigger=None هرگز اجرا نمیشود. |
5.5 |
ContextEditingMiddleware |
wrap_model_call |
نتایج قدیمی ابزارها را با استفاده از ClearToolUsesEdit از درخواست پاک میکند. این نتایج در وضعیت (state) باقی میمانند. |
همین بخش |
HumanInTheLoopMiddleware |
after_model، wrap_tool_call |
برای تصمیمگیری انسانی روی ابزارهای مشخصشده توقف میکند. حالت پیشفرض آن batched است. |
6.5 |
ModelCallLimitMiddleware |
before_model، after_model |
پس از تعداد معینی فراخوانی مدل در هر اجرا یا هر ترد متوقف میشود. مقدار پیشفرض exit_behavior برابر با end است. |
همین بخش |
ToolCallLimitMiddleware |
after_model |
فراخوانی ابزارها را برای یک ابزار یا همهی آنها محدود میکند. مقدار پیشفرض exit_behavior برابر با continue است. |
همین بخش |
ToolRetryMiddleware |
wrap_tool_call |
در صورت بروز هرگونه استثنا، ابزار ناموفق را دوباره اجرا میکند (بهطور پیشفرض در مجموع 3 تلاش). | 4.7 |
ModelRetryMiddleware |
wrap_model_call |
پس از بروز خطا، مدل را دوباره فراخوانی میکند (بهطور پیشفرض در مجموع 3 تلاش). | 4.7 |
ModelFallbackMiddleware |
wrap_model_call |
هنگامی که یک مدل دچار خطا میشود، مدل بعدی موجود در فهرست را فراخوانی میکند. | 4.7 |
ModelRefusalMiddleware |
wrap_model_call |
وقتی پاسخ مدل یک بلوک امتناع مدل (refusal) باشد، خطای ModelRefusalError صادر میکند. |
4.7 |
ToolErrorMiddleware |
wrap_tool_call |
استثنای درون ابزار را به یک ToolMessage حاوی خطا تبدیل میکند. به on_error نیاز دارد. |
3.4 |
PIIMiddleware |
before_model، after_model |
نوعی از دادههای شخصی را شناسایی کرده و آن را پاکسازی دادههای حساس، ماسک، هش یا مسدود میکند. بهطور پیشفرض فقط روی ورودی اعمال میشود. | 4.8 |
ModelRouterMiddleware |
before_agent، wrap_model_call |
از یک مدل تصمیمگیر میپرسد که برای این اجرا از کدام مدل استفاده شود. طبق گزارش تغییرات (release notes)، این ویژگی بتا و جدید در نسخهی 1.5.0 است. | 4.8 |
AutoModeMiddleware |
wrap_tool_call |
از یک مدل تصمیمگیر پرخطر بودن فراخوانی ابزار را استعلام میکند و جلوی آن را میگیرد. طبق گزارش تغییرات، ویژگی بتا و جدید در 1.5.0 است. | 4.8 |
TodoListMiddleware |
wrap_model_call، after_model |
ابزار write_todos و یک پرامپت را اضافه میکند و فهرست را در state["todos"] نگه میدارد. |
همین بخش |
LLMToolSelectorMiddleware |
wrap_model_call |
پیش از هر بار فراخوانی مدل، از یک مدل (بهطور پیشفرض خودِ مدل ایجنت) میپرسد کدام ابزارها را متصل (bind) کند. | همین بخش، 4.4 |
LLMToolEmulator |
wrap_tool_call |
به یک مدل اجازه میدهد نتیجهی اجرای ابزار را برای آزمون بسازد؛ خودِ ابزار هرگز اجرا نمیشود. | همین بخش |
ProviderToolSearchMiddleware |
wrap_model_call |
فراخوانی ابزارها را به ابزار جستجوی سمت سرور Anthropic یا OpenAI واگذار میکند. | همین بخش |
ShellToolMiddleware |
before_agent، after_agent |
ابزار shell را اضافه میکند و در هر اجرا یک نشست شل اختصاص میدهد. بهطور پیشفرض روی سیستم میزبان اجرا میشود. |
همین بخش |
FilesystemFileSearchMiddleware |
ندارد، فقط ابزارها | دو ابزار glob_search و grep_search را روی یک پوشهی ریشه اضافه میکند. |
همین بخش |
تصویر این کلاسها را بر اساس هوک مورد استفاده دستهبندی میکند. هوک نشان میدهد که یک کلاس دقیقاً در کجا وارد عمل میشود: روی درخواست، روی نتیجه، یا روی وضعیت بین مراحل.
مستندات رسمی 22 مورد را ذکر کرده است
صفحهی میدلویرهای ازپیشساختهشده 22 میدلویر مستقل از ارائهدهنده را فهرست کرده است {{docs oss/python/langchain/middleware/built-in}}. نوزده مورد از آنها همان کلاسهای بالاست. سه مورد دیگر شامل FilesystemMiddleware، SubAgentMiddleware و RubricMiddleware هستند که از deepagents ایمپورت میشوند. مستندات نحوهی ایمپورت را نشان میدهد، اما جدول مشخص نکرده که هرکدام به چه پکیجی نیاز دارند. این راهنما 19 موردی را که مستقیماً داخل langchain هستند شمارش میکند و این مغایرت را با عنوان تعارض D130 ثبت کرده است. بخش 7.4 به بررسی میدلویرهای Deep Agents میپردازد و در ادامهی همین بخش نیز RubricMiddleware را میسنجیم.
محدودیت فراخوانیها
کلاس ModelCallLimitMiddleware تعداد فراخوانیهای مدل را در هر اجرا با run_limit و در هر ترد با thread_limit شمارش میکند. با مقدار پیشفرض exit_behavior="end"، فرایند اجرا به جای ارسال فراخوانی بعدی به مدل، با یک پیام هوش مصنوعی پایان مییابد:
"type": "AIMessage",
"content": "Model call limits exceeded: run limit (1/1)",آخرین پیام اجرا. فراخوانی ابزار و نتیجهی ابزار قبل از آن حذف شدهاند.
در صورت تنظیم exit_behavior="error"، برنامه با همان متن خطای ModelCallLimitExceededError صادر میکند. از آنجا که شمارش مربوط به ترد در چکپوینت ذخیره میشود، استفاده از thread_limit به چکپوینتر نیاز دارد. در نوبت گفتوگوی سوم از یک ترد با تنظیم thread_limit=2، پاسخ دریافتی به این صورت بود: Model call limits exceeded: thread limit (2/2).
کلاس ToolCallLimitMiddleware تعداد فراخوانی ابزارها را میشمارد. با رفتار پیشفرض exit_behavior="continue"، فراخوانیِ فراتر از حد مجاز یک ToolMessage حاوی خطا دریافت میکند و سایر فراخوانیها اجرا میشوند:
"type": "ToolMessage",
"content": "Tool call limit exceeded. Do not call 'add' again.",
"name": "add",
…
"tool_call_id": "<uuid-10>",
"status": "error"
},
{
"type": "ToolMessage",
"content": "2",
"name": "add",
…
"tool_call_id": "<uuid-9>",
"status": "success"دو ToolMessage. شناسهها برش خوردهاند.
مدل در قالب یک پاسخ، درخواست اجرای add(1, 1) با شناسهی <uuid-9> و add(2, 2) با شناسهی <uuid-10> را داد. فراخوانی دوم مسدود شد و پیام خطای آن در وضعیت، قبل از بقیه قرار گرفت. با این حال مدل با حسابوکتاب خودش پاسخ داد که حاصل 2 + 2 برابر با 4 است.
با تنظیم exit_behavior="end"، فرایند پس از آن دسته فراخوانی با پیام Tool call limit reached: run limit exceeded (2/1 calls). متوقف میشود. با انتخاب error نیز خطای ToolCallLimitExceededError صادر میکند. از آنجا که مدل پس از حالت continue همچنان میتواند دوباره درخواست بدهد یا بدون ابزار به پاسخدهی ادامه دهد، چنانچه هزینه برایتان مهم است، محدودیت فراخوانی مدل را هم در کنار آن بگذارید.
برنامهریزی و بافتار
میدلویر TodoListMiddleware ابزار write_todos و بخشی متناسب با آن را در پرامپت سیستمی اضافه میکند. هر فراخوانی، فهرست موجود در state["todos"] را بازنویسی میکند. در کیت، از مدل Qwen3 4B خواسته شد برنامهریزی کند، جمع را انجام دهد و پایان برنامه را علامت بزند. این مدل ابزار write_todos، سپس add و دوباره write_todos را فراخوانی کرد و برنامهی خودش شامل دو مورد بود. در پایان اجرا، فهرست نهایی در وضعیت ذخیره شده بود:
todos:
[
{
"content": "Understand the task: calculate 2 + 3",
"status": "completed"
},
{
"content": "Perform the addition: 2 + 3",
"status": "completed"
}
]کلید todos در وضعیت خروجی.
میدلویر ContextEditingMiddleware به کمک ClearToolUsesEdit نتایج قدیمی ابزارها را در درخواست با متن [cleared] جایگزین میکند. کیت سه نتیجهی ابزار را با تنظیمات trigger=10 و keep=1 ارسال کرد. مدل فقط جدیدترین نتیجه و دو جاینگهدار (placeholder) را دریافت کرد:
[
"Add three pairs: 1 + 1, 2 + 2, and 3 + 3.",
"",
"[cleared]",
"",
"[cleared]",
"",
"result 6 result 6 result 6 result 6 result 6 "
]مدل همچنان مقادیر 2، 4 و 6 را بازگرداند، چون صورت سؤال جفتها را مشخص کرده بود. این ویرایش از نوع هوک wrap_model_call است و فقط روی درخواست اثر میگذارد. وضعیت، همهی نتایج ابزارها را در خود نگه میدارد و حجم چکپوینت مثل گذشته افزایش مییابد. بخش 5.5 این روش را با خلاصهسازی مقایسه میکند.
انتخاب، شبیهسازی و جستجوی ابزار
میدلویر LLMToolSelectorMiddleware از یک مدل میپرسد که کدام ابزارها متصل شوند. اگر آرگومان model تعیین نشود، این کار را از خودِ مدل ایجنت استعلام میکند {{code libs/langchain_v1/langchain/agents/middleware/tool_selection.py:278}}. بخش 4.4 تأثیر این کار بر دقت و هزینه را میسنجد. با تنظیم max_tools=1، مدل ایجنت فقط یکی از سه ابزار را میدید. انتخابگر پیش از هر فراخوانی مدل ایجنت یک بار اجرا شد؛ بنابراین اجرایی که دو فراخوانی مدل داشت، در مجموع چهار فراخوانی مدل ثبت کرد:
"model": "agent",
"call": 1,
"messages": [
"human: Weather in Pune?"
],
"tools": [
"get_weather"
]نخستین فراخوانی مدل ایجنت. ایجنت ابزارهای add، get_weather و send_email را در اختیار داشت.
میدلویر LLMToolEmulator هر فراخوانی مشخصشدهی ابزار را به یک مدل میفرستد و متن آن را به عنوان نتیجه برمیگرداند؛ در واقع بدنهی ابزار اصلاً اجرا نشد. مدل شبیهساز نتیجه را تولید کرد و ToolMessage شامل متن Email sent successfully to ops@example.com. 📩 بود. حتماً پارامتر model را مقداردهی کنید؛ چون مقدار پیشفرض آن یک مدل مشخص از Anthropic است و هشدار منسوخشدن دارد {{code libs/langchain_v1/langchain/agents/middleware/tool_emulator.py}}.
میدلویر ProviderToolSearchMiddleware به ارائهدهندهای وابسته است که از جستجوی ابزار سمت سرور پشتیبانی کند. این کلاس روی ChatOllama خطای ValueError با متن but got 'ollama'; supported providers: anthropic, openai صادر کرد. بدون ابزاری برای واگذاری، درخواست را مستقیماً عبور داد. ما آن را روی یک ارائهدهنده اجرا نکردیم و تست آن در ویرایش بعدی ارائه خواهد شد؛ بخش 8.8 این مورد را آورده است.
شل و جستجوی فایل
میدلویر ShellToolMiddleware یک ابزار shell به سیستم میافزاید. این میدلویر در before_agent یک شل را راهاندازی میکند و در after_agent آن را میبندد. کیت در دو اجرا از Qwen3 4B خواست تا فرمانی را در محیط کاری خود اجرا کند. این مدل هرگز دستوری اجرا نکرد؛ چرا که به جای رشته، 13 بار فرمان را در قالب یک شیء فرستاد و هر بار اعتبارسنجی شکست خورد:
"content": "Error invoking tool 'shell' with kwargs {'command': {'command': 'ls'}} with error:\n command: Input should be a valid string\n Please fix the error and try again.",محتوای نخستین ToolMessage اجرا که دستور ls را درخواست کرده بود.
سپس مدل ادعا کرد که خودِ ابزار دچار اشکال است. بنابراین پیش از تکیه بر ابزار یک میدلویر، حتماً عملکرد آن را با مدلی که در عمل استفاده میکنید بسنجید.
اگر مقدار execution_policy مشخص نشود، میدلویر به سراغ HostExecutionPolicy میرود که دستورات را مستقیماً روی ماشین شما و با دسترسیهای خودتان اجرا میکند {{code libs/langchain_v1/langchain/agents/middleware/shell_tool.py}}. گزینههای ایزولهشده شامل DockerExecutionPolicy و CodexSandboxExecutionPolicy هستند. بخش 8.4 خطرات امنیتی مربوطه را شرح میدهد.
میدلویر FilesystemFileSearchMiddleware امکان استفاده از glob_search و grep_search را در زیرمسیر root_path مهیا میکند. مسیر نتایج برگشتی از همان ریشه شروع میشوند. با تنظیم use_ripgrep=False، فرایند جستجو در محیط پایتون انجام میشود. در کیت، اجرای glob_search با الگوی **/*.py مسیر /src/app.py را برگرداند. هر 8 فراخوانی grep_search شکست خوردند؛ چون مدل پارامتر include را در قالب یک شیء (مانند {'pattern': '*.py'}) میفرستاد. در نهایت پس از 10 بار فراخوانی مدل، تسلیم شد و ابزار را مقصر دانست.
کلاس RubricMiddleware؛ ارزیاب پکیج Deep Agents
RubricMiddleware: میدلویری از پکیج deepagents است که پاسخهای ایجنت را بر اساس یک شیوهنامهی نمرهدهی میسنجد. فراخواننده، شیوهنامه را با کلید rubric در وضعیت قرار میدهد. اگر شیوهنامهای نباشد، این میدلویر کاری انجام نمیدهد {{code libs/deepagents/deepagents/middleware/rubric.py}}. زمانی که ایجنت میخواهد کارش را تمام کند، مدلی در نقش ارزیاب، رونوشت گفتگو را میخواند و برای هر معیار، یک حکم ارزیابی صادر میکند. صدور حکم needs_revision ایجنت را برای یک دور دیگر به کار وامیدارد. پس از گذشت max_iterations دور، اجرا با وضعیت max_iterations_reached تمام میشود.
ما این میدلویر را روی 25 وظیفهای سنجیدیم که یک حلقهی سادهی Qwen3 8B در بنچمارک اول از پس آنها برنیامده بود. در این آزمون، Qwen3 8B نقش کارگر (worker) را در create_agent به همراه میدلویر و با شرط max_iterations=3 بر عهده داشت. مدل ارزیاب، Qwen3 14B بود که روی نمونهی دوم Ollama 0.31.1 در سیستم Mac اجرا میشد.
شیوهنامهی نمرهدهی شامل چهار معیار بود: هر دادهی واقعی مستقیماً از نتیجهی یک ابزار به دست آمده باشد؛ پاسخ فقط یکبار و با مقدار درست ثبت شود؛ همهی تغییرات درخواستی اعمال شده باشد؛ و همهی بخشهای درخواست انجام شده باشد.
هر وظیفه یک بار اجرا شد. دستهی 25 وظیفهای حجم کمی دارد و موارد از میان شکستهای حلقهی ساده انتخاب شده بودند. تصویر وضعیت هر اجرا را نشان میدهد.
سه وظیفه قبول شدند: r06، sql03 و sql09. دوازده اجرا در همان نگاه اول حکم satisfied گرفتند، اما 11 تای آنها در ارزیابیِ وضعیت شکست خوردند. یازده اجرا به سقف تعداد دورها رسیدند که r06 یکی از آنها بود.
حضور شیوهنامهی نمرهدهی، فراخوانیهای کارگر را از 108 به 173 و توکنهای پرامپت کارگر را از 75,987 به 174,192 رساند. ارزیاب نیز 56 فراخوانی و 113,851 توکن پرامپت اضافه کرد. در وظیفهی سهنوبتهی multi13، در هر نوبت دورهای ارزیابی وجود داشت که در مجموع به 9 فراخوانی ارزیاب و 22 فراخوانی کارگر انجامید. کل 25 اجرا 16,841 ثانیه طول کشید (در مقایسه با 446 ثانیه برای اجراهای ساده)، که 11,379 ثانیهی آن صرف مدل ارزیاب شد. سیستم Mac به اشتراک گذاشته شده بود، بنابراین این زمانها حد بالا هستند.
پس ارزیاب فقط به اندازهی مدلی که پشت آن است خوب عمل میکند. یک ارزیاب 14B در اجراهایی حکم رضایت داد که در آزمون وضعیت رد شده بودند. پیش از اعتماد به حکم ارزیاب، سازوکار آن را در برابر بررسی وضعیت خودتان بیازمایید.
منابع: capture/out/09-middleware-order.txt, capture/out/11-mw-call-limits.txt, capture/out/17-mw-todo-context-editing.txt, capture/out/18-mw-selection-emulation.txt, capture/out/19-mw-shell-files.txt, capture/s_middleware.py؛ docs.langchain.com در commit مستندات 04d4d4a (oss/python/langchain/middleware/built-in)؛ libs/langchain_v1/langchain/agents/middleware در langchain==1.5.0؛ capture/lab/bench2/summary-bench2.json, capture/lab/bench2/runs/rubric.jsonl, capture/lab/bench2/logs/q-rubric.log, capture/lab/bench2/kit2/run2.py؛ libs/deepagents/deepagents/middleware/rubric.py در deepagents==0.7.38.