میانافزار
HumanInTheLoopMiddlewareفراخوانیهای ابزار را برای بازبینی متوقف میکند، و حالتper_callانتخاب امنتر است؛ چرا که حالت دستهای اجازه میدهد در ویرایش ابزار عوض شود و میانافزارهای دارای پرش میتوانند بازبینی را دور بزنند.
ایجنت شما میتواند ایمیل بفرستد و فایلها را حذف کند، و پیش از اجرای هر کدام از این فراخوانیها، یک فرد باید آنها را تأیید کند. شما یک میانافزار (middleware) همراه با فهرستی از نام ابزارها اضافه میکنید. فرد بازبین یکی از فراخوانیها را ویرایش میکند تا به ابزار دیگری اشاره کند؛ در یک حالت، آن ابزار جدید اجرا میشود و در حالتی دیگر، همین ویرایش خطا میدهد.
پس از پایان این بخش، میتوانید فراخوانیهای ابزار انتخابی را برای بازبینی متوقف کنید و به هر وقفه با یکی از چهار تصمیم ممکن پاسخ دهید. همچنین یاد میگیرید کدام تنظیمات بازبینی را همیشه پابرجا نگه میدارند.
کدام فراخوانیها متوقف میشوند
HumanInTheLoopMiddleware: میانافزاری است که وقتی مدل ابزاری از نگاشت interrupt_on را درخواست کند، ایجنت را متوقف میکند. این میانافزار برای هر فراخوانی از این دست منتظر تصمیمگیری میماند.
نگاشت interrupt_on نام ابزار و مقدار True (که هر چهار تصمیم را مجاز میکند) یا یک پیکربندی همراه با allowed_decisions میگیرد. در کدهای آزمایشی این بخش، به ابزار add همهی تصمیمها داده شده و به lookup_order دو تصمیم:
agent = create_agent(m, tools=[add, lookup_order], middleware=[HumanInTheLoopMiddleware(interrupt_on={"add": True, "lookup_order": {"allowed_decisions": ["approve", "reject"]}})], checkpointer=checkpointer)ابزاری که در این نگاشت نباشد بدون وقفه اجرا میشود. میانافزار فرایند را با interrupt متوقف میکند، بنابراین ایجنت به یک چکپوینتر (checkpointer) نیاز دارد؛ همانطور که در بخش 6.4 دیدیم. مستندات انسان در چرخه (human-in-the-loop)، ابزار AsyncPostgresSaver را برای محیط عملیاتی (production) پیشنهاد میکند {{docs oss/python/langchain/human-in-the-loop}}.
چهار تصمیم ممکن
تصمیم (Decision): پاسخی است که به یک فراخوانی ابزارِ متوقفشده داده میشود. فیلد type آن یکی از مقادیر approve، edit، reject یا respond است.
| تصمیم | ارسالشده از طرف بازبین | آیا ابزار اجرا میشود؟ | پیام ToolMessage دریافتی توسط مدل |
|---|---|---|---|
approve |
{"type": "approve"} |
بله، با آرگومانهای مدل | نتیجهی ابزار، وضعیت success |
edit |
شیء edited_action با name و args |
بله، با آرگومانهای ویرایششده | یک اعلان، سپس نتیجهی ابزار |
reject |
یک message اختیاری |
خیر | دلیل رد شدن، وضعیت error |
respond |
یک message |
خیر | متن پیام، وضعیت success |
تصمیم respond برای ابزاری است که پاسخ واقعیاش باید از طرف انسان ارسال شود. مدل پیام آن را به عنوان نتیجهای موفقیتآمیز میخواند. مستندات میگوید برای رد کردن ابزاری که اثر جانبی دارد از respond استفاده نکنید {{docs oss/python/langchain/human-in-the-loop}}. کدهای این بخش دلیلش را نشان میدهند: مدل نمیتواند این پاسخ را از نتیجهی واقعی ابزار تشخیص دهد. برای رد کردن، از reject استفاده کنید.
حالت دستهای
حالت دستهای (Batched mode): حالت پیشفرض interrupt_mode است. در این حالت یک وقفه تمام فراخوانیهای متوقفشدهی یک پیام مدل را نگه میدارد، و با یک فرمان ازسرگیری (resume) میتوان به همهی آنها به ترتیب پاسخ داد.
در کدهای آزمایشی، از مدل Qwen3 4B خواسته شد در یک پاسخ هر دو ابزار add و lookup_order را فراخوانی کند، و مدل همین کار را کرد. اجرای برنامه با یک وقفه متوقف شد. مقدار این وقفه، فهرست فراخوانیها و تصمیمهای مجاز هر کدام را در بر دارد:
interrupts:
[
{
"value": {
"action_requests": [
{
"name": "add",
"args": {
"a": 2,
"b": 3
},
…
{
"name": "lookup_order",
…
"review_configs": [
{
"action_name": "add",
"allowed_decisions": [
"approve",
"edit",
"reject",
"respond"
]
},
{
"action_name": "lookup_order",
"allowed_decisions": [
"approve",
"reject"
]
}
]توضیحات و آرگومانهای lookup_order حذف شدهاند.
در زمان انتظار برنامه، مقدار next برابر با HumanInTheLoopMiddleware.after_model است. فرمان ازسرگیری فهرستی از تصمیمها را ارسال میکند؛ برای هر فراخوانی یک تصمیم، دقیقاً به ترتیبی که در action_requests آمده است. در این آزمایش، فراخوانی add با آرگومانهای 20 و 30 ویرایش شد و lookup_order رد شد:
decisions = []
for request in gated(result):
if request["name"] == "add":
decisions.append({"type": "edit", "edited_action": {"name": "add", "args": {"a": 20, "b": 30}}})
else:
decisions.append({"type": "reject", "message": "Do not look up orders."})
result = agent.invoke(Command(resume={"decisions": decisions}), cfg, version="v2")کیت فهرست را از وقفه میسازد، بنابراین برای هر فراخوانی مدل یک تصمیم دارد.
مدل دو شیء ToolMessage دریافت کرد. ابتدا فراخوانی ردشده آمد. سپس فراخوانی ویرایششده با آرگومانهای جدید اجرا شد و نتیجهی آن با اعلانی شروع میشود که به مدل میگوید چه چیزی اجرا شده است:
"type": "ToolMessage",
"content": "User rejected the tool call for `lookup_order` with reason: Do not look up orders.",
…
"tool_call_id": "<uuid-3>",
"status": "error"
…
"type": "ToolMessage",
"content": "Note: a human reviewer replaced this tool call before it ran. The call recorded in your message is the one you produced, not the one that executed. This was intentional and authorized. Do not re-issue your original call. Executed instead: add with arguments {\"a\": 20, \"b\": 30}.\n\nTool response:\n50",
…
"tool_call_id": "<uuid-2>",
"status": "success"نامها و شناسهها حذف شدهاند.
سپس مدل پاسخ داد: The result of the addition is 50.. شیء AIMessage در وضعیت (state) همچنان فراخوانی اولیه با 2 و 3 را نگه میدارد. فرستادن فهرستی با یک تصمیم برای دو فراخوانی، خطای ValueError: Number of human decisions (1) does not match number of hanging tool calls (2). را به همراه داشت و هیچ ابزاری اجرا نشد.
حالت فراخوانیمحور
حالت فراخوانیمحور (Per-call mode): با مقدار interrupt_mode="per_call" مشخص میشود. هر فراخوانی متوقفشده وقفهی اختصاصی خود را همراه با یک response_schema دریافت میکند، و در فرمان ازسرگیری میتوان بر اساس شناسهی وقفه به هر یک از آنها پاسخ داد.
agent = create_agent(m, tools=[add], middleware=[HumanInTheLoopMiddleware(interrupt_on={"add": True}, interrupt_mode="per_call")], checkpointer=InMemorySaver())مدل در یک پاسخ دو بار ابزار add را درخواست کرد؛ یک بار برای 2 و 3، و یک بار برای 4 و 5. اجرای برنامه با دو وقفه متوقف شد و مقدار next برابر با ["tools", "tools"] بود. هر وقفه نام یک فراخوانی را مشخص میکند:
interrupt for add(2, 3):
{
"id": "<hex-1>",
"value": {
"type": "tool_approval",
"tool_call_id": "<uuid-1>",
"name": "add",
"args": {
"a": 2,
"b": 3
},توضیحات حذف شده است.
طرحوارهی پاسخ (response_schema) در هر وقفه، چهار تصمیم را مجاز میداند. در شیء EditedAction آن، نام ابزار یک مقدار ثابت است؛ بنابراین ویرایش نمیتواند نام ابزار دیگری را تعیین کند:
"EditedAction": {
"properties": {
"name": {
"const": "add",
"title": "Name",
"type": "string"
},یک تعریف از اسکیمای اولین وقفه.
کدهای آزمایشی فرایند را با نگاشتی از شناسهی هر وقفه به تصمیم مربوطهاش از سر گرفتند: تأیید فراخوانی اول و رد فراخوانی دوم. فراخوانی اول add مقدار 5 را برگرداند، و فراخوانی دوم دلیل رد شدن را با وضعیت error دریافت کرد. مدل مقدار 5 را گزارش نکرد؛ در عوض پاسخ داد I see that the tool call was rejected. و پیشنهاد کرد دوباره تلاش کند. پاسخی که طرحواره آن را رد کند استثنا تولید میکند و اجرای برنامه در حالت انتظار باقی میماند. کدهای آزمایشی برای یک ابزار فقط approve را مجاز کردند ولی تصمیم reject فرستاده شد:
raised pydantic_core._pydantic_core.ValidationError: 1 validation error for ApproveDecision
type
Input should be 'approve' [type=literal_error, input_value='reject', input_type=str]خط راهنمای pydantic حذف شده است.
پس از بروز خطا، next همچنان ["tools"] بود. حالت فراخوانیمحور به langchain نسخهی 1.4.6 یا بالاتر نیاز دارد. مستندات این حالت را برای ایجنتهای جدید پیشنهاد میکند و قرار است در نسخهی اصلی بعدی پیشفرض شود {{docs oss/python/langchain/human-in-the-loop}}. شکل این دو حالت را کنار هم نشان میدهد.
یافتههای آزمایشگاه
ما میانافزار را روی ماشین مهمان سرور x86 در 25 سناریوی مدلی، هر کدام با 3 بار اجرا ارزیابی کردیم. مدل مورد استفاده Qwen3 4B روی Ollama بود (دمای 0، seed برابر 42). سناریوهای گراف G1 و G2 بدون مدل هستند و از روی Mac آمدهاند. ابزارها send_email و delete_file بودند که هر دو تحت بازبینی قرار داشتند.
هر بار شروع و هر بار ازسرگیری در یک فرایند (process) جدید روی SqliteSaver اجرا شد؛ بنابراین هر ازسرگیری در عمل یک راهاندازی مجدد بود. هر 3 اجرای هر سناریو، فراخوانیهای کاملاً یکسانی از ابزارها ثبت کردند. شکل هر اجرا را نشان میدهد.
خط خاکستری نمودار، تعداد دفعاتی است که بازبین در هر سناریو اجازهی اجرای ابزار را داده است. کدهای رسم نمودار این مقادیر را به صورت ثابت نگه میدارند. این دادهها از تصمیمهای جدول زیر و اسکریپتهای سناریو در capture/lab/T07-approvals-x86/ به دست آمدهاند. سناریوها شناسههای کوتاهی دارند: B یعنی دستهای، P یعنی فراخوانیمحور، J یک میانافزار با پرش به tools اضافه میکند، و G یک گراف ساده است.
| سناریو | اقدام بازبین | نتیجه در 3 اجرا از 3 اجرا |
|---|---|---|
| B2, P2 | ویرایش آرگومانهای send_email |
فقط فراخوانی ویرایششده اجرا شد |
| B3 | ویرایش send_email و تبدیل آن به فراخوانی delete_file |
delete_file اجرا شد |
| P3 | همان ویرایش در حالت فراخوانیمحور | خطای ValidationError رخ داد، هیچچیز اجرا نشد |
| B4, P4 | رد کردن (reject) |
هیچچیز اجرا نشد، وضعیت error |
| B5, P5 | پاسخ دادن (respond) |
هیچچیز اجرا نشد، وضعیت success |
| P7 | پاسخ به دو فراخوانی به صورت یکییکی | هر فراخوانی یک بار اجرا شد |
| P8 | فرستادن یک مقدار ساده برای دو فراخوانی منتظر | خطای RuntimeError رخ داد، هیچچیز اجرا نشد |
| J1, J3 | حالت دستهای، میانافزار پرشکننده در فهرست بعد از میانافزار بازبینی باشد | send_email در همان ابتدا و پیش از هرگونه تصمیمی اجرا شد |
| J2 | حالت دستهای، میانافزار پرشکننده در ابتدا، تصمیم رد | send_email اجرا شد، و وضعیت دو ToolMessage برای یک فراخوانی نگه داشت |
| J4, J5 | حالت فراخوانیمحور، با هر ترتیبی، تصمیم رد | هیچچیز اجرا نشد |
| G1, G2 | دو وقفهی موازی در یک گراف و زیرگراف، پاسخدهی یکییکی | هر branch اثر جانبی خود را یک بار اجرا کرد |
در 10 درخواست شامل دو عملیات، مدلهای Qwen3 4B و Qwen3 8B هر کدام در 9 مورد دو یا چند فراخوانی انجام دادند؛ بنابراین بازبینی دستهای چندین فراخوانی، حالت متداول است.
ردیف B3 به اختلافنظر D102 پایان میدهد. یکی از مثالهای دستهای در مستندات، فراخوانی را به نام ابزار جدیدی تغییر میدهد، اما متن حالت فراخوانیمحور نام را ثابت نگه میدارد. گزارش تغییرات (changelog) نسخهی 1.4.6 میگوید ویرایش نمیتواند ابزار را عوض کند {{docs oss/python/releases/changelog}}. در نسخهی قفلشده، حالت دستهای هنوز اجازه میدهد ابزار عوض شود، اما حالت فراخوانیمحور جلوی آن را میگیرد.
ردیفهای J خطای langchain#40492 را در حالت دستهای بازتولید میکنند {{issue langchain#40492}}. میانافزار پرشکننده مقدار jump_to="tools" را از قلاب after_model برمیگرداند. قلابهای after_model به ترتیب معکوس فهرست میانافزارها اجرا میشوند. بنابراین در J1 و J3 قلاب آن پیش از قلاب بازبینی اجرا شد و آن را دور زد.
در سناریوی J2 بازبینی اجرا شد و فراخوانی رد شد، اما پرش همچنان ابزار را اجرا کرد. ثبت دو ToolMessage برای یک فراخوانی در J2 قاعدهی بخش 3.4 را نقض میکند: یک پاسخ به ازای هر فراخوانی ابزار. حالت فراخوانیمحور وقفهاش را داخل خودِ فراخوانی ابزار قرار میدهد و پرش نتوانست آن را دور بزند.
دو گزارش خطای قدیمیتر بازتولید نشدند. در خطای langchain#33787 آمده بود که یک ویرایش ممکن است باز هم فراخوانی اولیه را اجرا کند {{issue langchain#33787}}. در B2 و P2 فقط فراخوانی ویرایششده اجرا شد. خطای langgraph#9106 میگفت ازسرگیری، یک شاخهی موازیِ پایانیافته را دوباره اجرا میکند {{issue langgraph#9106}}. در G1 و G2 شاخهی پایانیافته دوباره اجرا نشد. شاخهای که همچنان منتظر بود در هر ازسرگیری گره خود را تا رسیدن به interrupt اجرا کرد؛ که همان قاعدهی بخش 6.4 است.
پیکربندی امن
این تنظیمات تضمین کردند تمام بازبینیها در اجراهای آزمایشگاه پابرجا بمانند:
- مقدار
interrupt_mode="per_call"را تنظیم کنید تا ویرایش روی همان ابزار باقی بماند و پرش بهtoolsنتواند بازبینی را دور بزند. - از چکپوینتری استفاده کنید که پس از راهاندازی مجدد دادههایش بماند، مانند
SqliteSaverیاPostgresSaver. - فقط تصمیمهایی را برای هر ابزار مجاز کنید که واقعاً نیاز دارید. برای ابزارهای دارای اثر جانبی، گزینههای
respondوeditرا کنار بگذارید و درخواست را باrejectرد کنید. - به هر وقفه بر اساس شناسهاش پاسخ دهید و پیش از ازسرگیری، مقدار
nextرا باget_stateبررسی کنید. - در ایجنتی که بازبینی دارد، هیچ میانافزاری که به
toolsپرش میکند قرار ندهید، مگر آنکه رفتار آن را در حالت کاری خود آزموده باشید. - همانطور که مستندات میگوید،
HumanInTheLoopMiddlewareرا پیش از میانافزارهای تلاش مجدد (retry) و مدیریت خطای ابزار قرار دهید {{docs oss/python/langchain/human-in-the-loop}}.
رابط کاربری Agent Chat UI فقط به تأییدیههای دستهای پاسخ میدهد و تایپ یک پیام متنی، تأییدیهی در انتظار را به عنوان موفقیت میبندد. به بخش رابط کاربری چت مراجعه کنید.
مستندات همچنین در مورد فرستادن همزمان چند پاسخ که یکی از آنها نامعتبر باشد هشدار میدهد. در این حالت ممکن است ابزارهای پاسخهای معتبر اجرا شوند در حالی که وقفهی آنها هنوز در وضعیت انتظار به نظر میرسد؛ در نتیجه پاسخ دوم آنها را دو بار اجرا خواهد کرد {{docs oss/python/langchain/human-in-the-loop}}. بنابراین به هر وقفه یکییکی پاسخ دهید و آثار جانبی را بیاثر در تکرار (idempotent) پیادهسازی کنید. پس از یک ازسرگیری ناموفق ترکیبی، پیش از ارسال دوبارهی پاسخ بررسی کنید ابزارها چه کاری انجام دادهاند. در آزمایشگاه این مورد و همچنین سناریوهای با PostgresSaver اجرا نشدند. هر دوی آنها در ویرایش بعدی و همراه با سایر موارد بازِ بخش 8.8 بررسی خواهند شد.
منابع: capture/s_middleware.py, capture/out/15-mw-hitl-batched.txt, capture/out/16-mw-hitl-per-call.txt؛ capture/lab/summary/approvals-x86.json, capture/lab/T07-approvals-x86/00-survey.jsonl, capture/lab/T07-approvals-x86/01-cases.jsonl, capture/lab/T07-approvals-x86/02-g3-rerun.jsonl, capture/lab/T07-approvals-x86/t07_child_real.py؛ capture/lab/summary/approvals-mac.json, capture/lab/T07-approvals-mac/01-cases.jsonl؛ کتابخانهی libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py در langchain==1.5.0؛ docs.langchain.com در commit مستندات 04d4d4a (بخشهای oss/python/langchain/human-in-the-loop و oss/python/releases/changelog)؛ ایشوهای langchain-ai/langchain#40492 و #33787 و langchain-ai/langgraph#9106، بازبینیشده در 2026-11-14.