هر میانافزار (middleware) شش هوک (hook) دارد؛ چهار هوکِ گرهای به گرههای گراف تبدیل میشوند و هوکهای
before_*به ترتیب فهرست و هوکهایafter_*به ترتیب معکوس اجرا میشوند.
فرض کنید یک میانافزار ثبت لاگ و یک میانافزار پاکسازی دادههای حساس (redaction) به یک ایجنت اضافه میکنید. لاگ نهایی، متن پاکسازیشده را در مسیر رفت و متن خام را در مسیر برگشت نشان میدهد. دلیل این رفتار، ترتیب قرارگیری در فهرست middleware است که در دو جهت رفتوبرگشت عمل میکند.
پس از پایان این بخش، میتوانید میانافزار بنویسید و نقطهی اجرای هر کدام از هوکهایش را مشخص کنید. همچنین میتوانید ترتیب اجرای هوکهای چند میانافزار را پیشبینی کنید و بگویید تغییر ترتیب، چه بخشهایی از کار را خراب میکند.
شش هوک اصلی
میانافزار: شیئی از زیرکلاس AgentMiddleware که create_agent آن را در نقاط مشخصی از حلقهی ایجنت (agent loop) اجرا میکند.
هوک گرهای (Node hook): هوکی که create_agent آن را به یک گره در گراف تبدیل میکند. این هوک وضعیت (state) و محیط اجرا (runtime) را میگیرد و یک بهروزرسانی وضعیت یا None برمیگرداند.
هوک پوششی (Wrap hook): هوکی که درخواست و یک کنترلکننده (handler) را تحویل میگیرد و با فراخوانی کنترلکننده، مدل یا ابزار را اجرا میکند. این هوک میتواند درخواست را تغییر دهد، کنترلکننده را دوباره فراخوانی کند یا اصلاً بدون فراخوانی آن نتیجه را برگرداند.
| هوک | نوع | زمان اجرا | مقدار بازگشتی |
|---|---|---|---|
before_agent |
گرهای | یکبار، در شروع هر اجرا | بهروزرسانی وضعیت یا None |
before_model |
گرهای | قبل از هر بار فراخوانی مدل | بهروزرسانی وضعیت یا None |
wrap_model_call |
پوششی | پیرامون هر فراخوانی مدل، درون گره model |
یک ModelResponse، یک AIMessage یا یک ExtendedModelResponse |
after_model |
گرهای | بعد از هر بار فراخوانی مدل | بهروزرسانی وضعیت یا None |
wrap_tool_call |
پوششی | پیرامون هر فراخوانی ابزار، درون گره tools |
یک ToolMessage یا یک Command |
after_agent |
گرهای | یکبار، در پایان هر اجرا | بهروزرسانی وضعیت یا None |
هر هوک یک همتای ناهمگام (async) هم دارد که با حرف a شروع میشود، مثل abefore_model. میانافزاری که فقط wrap_model_call همگام داشته باشد، هنگام اجرای ایجنت با ainvoke خطای NotImplementedError میدهد {{code libs/langchain_v1/langchain/agents/middleware/types.py}}. میانافزار میتواند tools و یک state_schema هم تعریف کند و create_agent هر دوی آنها را به ایجنت میافزاید.
میانافزار کمکی کتابخانه یعنی Traced، به ازای اجرای هر هوک یک خط مینویسد. هوک پوششی مدل آن، ساختار همهی هوکهای پوششی را نشان میدهد:
def wrap_model_call(self, request, handler):
self.log.append(f"{self.label}.wrap_model_call enter")
response = handler(request)
self.log.append(f"{self.label}.wrap_model_call exit")
return responseیکی از متدهای میدلویر Traced. سایر قلابها هر کدام یک خط اضافه میکنند.
اگر فقط به یک یا دو هوک نیاز دارید، دکوراتورهای before_model، after_model، before_agent، after_agent، wrap_model_call، wrap_tool_call و dynamic_prompt یک تابع ساده را به میانافزار تبدیل میکنند.
هوکها گره میشوند
کد کمکی ما ایجنتی با middleware=[A, B, C] میسازد که شامل سه نمونه از Traced است. هر هوک گرهای به گرهای با نام <middleware name>.<hook> تبدیل میشود. یالها در مسیر رفت، آنها را بر اساس ترتیب فهرست به هم زنجیر میکنند:
"A.before_agent -> B.before_agent",
"A.before_model -> B.before_model",
…
"B.before_agent -> C.before_agent",
"B.before_model -> C.before_model",
…
"C.before_agent -> A.before_model",
"C.before_model -> model",
…
"__start__ -> A.before_agent",محدودشده به یالهای از __start__ به model.
در مسیر برگشت، یال خروجی از model ابتدا به آخرین میانافزار میرود:
"A.after_model -> A.before_model",
"A.after_model -> C.after_agent",
"A.after_model -> tools",
…
"B.after_model -> A.after_model",
…
"C.after_model -> B.after_model",
…
"model -> C.after_model",محدودشده به یالهای after_model.
هوک A.after_model آخرین هوک گرهای پس از مدل است. سه یال خروجی آن به tools، به پایان مسیر از طریق C.after_agent، یا برای پرش به A.before_model میروند. پس از tools، حلقه دوباره به A.before_model برمیگردد؛ بنابراین هوکهای before_agent برای هر اجرا فقط یکبار اجرا میشوند.
شکل همین گراف را از روی متن Mermaid آن رسم میکند. هوکهای پیشین (before) به سمت پایین و تا model اجرا میشوند و هوکهای پسین (after) با ترتیبی معکوس به سمت انتها پیش میروند.
ترتیب اجرای یک چرخهی کامل ابزار
کد کمکی یک پرسش را همراه با یک فراخوانی ابزار اجرا کرد و تمام هوکها را به ثبت رساند:
"A.before_agent",
"B.before_agent",
"C.before_agent",
"A.before_model",
"B.before_model",
"C.before_model",
"A.wrap_model_call enter",
"B.wrap_model_call enter",
"C.wrap_model_call enter",
" model called",
"C.wrap_model_call exit",
"B.wrap_model_call exit",
"A.wrap_model_call exit",
"C.after_model",
"B.after_model",
"A.after_model",
"A.wrap_tool_call enter add",
"B.wrap_tool_call enter add",
"C.wrap_tool_call enter add",
"C.wrap_tool_call exit",
"B.wrap_tool_call exit",
"A.wrap_tool_call exit",
…
"C.after_agent",
"B.after_agent",
"A.after_agent"محدودشده به نخستین فراخوانی مدل و فراخوانی ابزار. دومین فراخوانی مدل بخش مدل را تکرار میکند و سه قلاب after_agent اجرا را خاتمه میدهند.
سه قاعده این ترتیب را تعیین میکنند و شکل آنها را رسم کرده است:
- هوکهای
before_agentوbefore_modelبه ترتیب فهرست اجرا میشوند: اول A، بعد B و سپس C. - هوکهای
after_modelوafter_agentبا ترتیب معکوس فهرست اجرا میشوند: اول C، بعد B و سپس A. - هوکهای پوششی تودرتو میشوند. اولین میانافزار فهرست، بیرونیترین لایه است؛ بنابراین A اول از همه وارد و آخر از همه خارج میشود.
مستندات میانافزار سفارشی نیز همین سه قاعده را بیان میکند {{docs oss/python/langchain/middleware/custom}}. خروجی ثبتشدهی ما در نسخهی پینشده نیز آن را تأیید میکند.
تغییر ترتیب چه پیامدهایی دارد
میانافزاری را در ابتدای فهرست بگذارید که باید درخواست خام و پاسخ نهایی را ببیند. هوک پوششی در ابتدای فهرست، هر کاری را که هوکهای بعدی انجام میدهند میبیند. هوک گرهای در ابتدای فهرست، قبل از مدل اولین و بعد از مدل آخرین هوکی است که اجرا میشود.
ترتیب معکوس after_model هزینههایی هم دارد. میانافزاری که jump_to را از after_model مقداردهی کند، قبل از هوکهای after_model تمام میانافزارهای جلوی خودش اجرا میشود. اگر یکی از آنها HumanInTheLoopMiddleware باشد، این پرش میتواند بازبینی انسان را دور بزند. ترتیب برعکس هم در حالت دستهای (batched) با شکست مواجه شد: فراخوانی ردشده باز هم اجرا شد. بخش 6.5 هر دو حالت را نشان میدهد، همانطور که ایشوی langchain#40492 گزارش کرده است؛ هرچند حالت فراخوانیمحور (per-call) در هر دو ترتیب ایمن بود {{issue langchain#40492}}. صفحهی انسان در چرخه (human in the loop) توصیه میکند HumanInTheLoopMiddleware قبل از میانافزارهای تلاش مجدد (retry) و خطا در فهرست بیاید {{docs oss/python/langchain/human-in-the-loop}}.
jump_to: کلیدی که یک هوک گرهای برای انتقال ادامهی اجرا به model، tools یا end برمیگرداند. هوک تنها در صورتی میتواند از آن استفاده کند که مقصدهای مجاز را با hook_config(can_jump_to=...) یا گزینهی can_jump_to در دکوراتور اعلان کرده باشد.
نامها باید یکتا باشند
تابع create_agent نام هر میانافزار را از ویژگی name آن برمیدارد که بهطور پیشفرض همان نام کلاس است. دو نمونه از یک کلاس نام یکسانی دارند و ایجنت آنها را رد میکند:
create_agent(middleware=[A, A]):
raised builtins.AssertionError: Please remove duplicate middleware instances.برای استفاده از دو نمونه از یک کلاس، به هر کدام یک name اختصاصی بدهید. میانافزار Traced در کتابخانهی کمکی ما، برچسب خود را به عنوان نام برمیگرداند:
@property
def name(self):
return self.labelبخش 8.3 هزینهی اندازهگیریشدهی هر هوک را ارائه میدهد.
منابع: capture/s_agents.py، capture/out/09-middleware-order.txt، capture/out/49-draw-middleware.txt؛ docs.langchain.com در commit مستندات به شناسهی 04d4d4a (oss/python/langchain/middleware/custom، oss/python/langchain/human-in-the-loop)؛ ایشوی langchain#40492؛ libs/langchain_v1/langchain/agents/middleware/types.py و libs/langchain_v1/langchain/agents/factory.py در langchain==1.5.0.