بخش 4.5 · ایجنت، خروجی ساختاریافته و میان‌افزار

میان‌افزار: هوک‌ها و ترتیب اجرای آن‌ها

Middleware: hooks and their order

فهرست مطالب
  1. شش هوک اصلی
  2. هوک‌ها گره می‌شوند
  3. ترتیب اجرای یک چرخه‌ی کامل ابزار
  4. تغییر ترتیب چه پیامدهایی دارد
  5. نام‌ها باید یکتا باشند

هر میان‌افزار (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، به ازای اجرای هر هوک یک خط می‌نویسد. هوک پوششی مدل آن، ساختار همه‌ی هوک‌های پوششی را نشان می‌دهد:

یک قلاب wrap_model_call capture/s_agents.py
    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> تبدیل می‌شود. یال‌ها در مسیر رفت، آن‌ها را بر اساس ترتیب فهرست به هم زنجیر می‌کنند:

یال‌های ورودی به نود model capture/out/09-middleware-order.txt
  "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 ابتدا به آخرین میان‌افزار می‌رود:

یال‌های خروجی از نود model capture/out/09-middleware-order.txt
  "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 و B و Cقلاب‌های before به ترتیب لیست به نود model زنجیر می‌شوند، قلاب‌های after_model به ترتیب معکوس زنجیر می‌شوند، و A.after_model بین tools، پایان و A.before_model انتخاب می‌کند.
گراف میدل‌ویرهای A و B و C گراف کامپایل‌شده‌ی create_agent با tools=[add] و middleware=[A, B, C]، رسم‌شده از خروجی draw_mermaid آن. این گراف 16 نود دارد که 12 تای آن‌ها نودهای قلاب هستند، و 17 یال دارد که 4 تای آن‌ها شرطی است. قلاب‌های before به ترتیب A، B و C از بالا اجرا می‌شوند. قلاب‌های after_model به صورت C، B و A زیر نود model اجرا می‌شوند. نود A.after_model دارای سه یال شرطی است: به tools، به C.after_agent، و بازگشت به A.before_model. نود tools نیز به A.before_model برمی‌گردد. GET_GRAPH() OF THE AGENT 16 نود، 12 تا قلاب __start__ model tools __tools = add A.before_agent A.before_model A.after_model A.after_agent B.before_agent B.before_model B.after_model B.after_agent C.before_agent C.before_model C.after_model C.after_agent __end__ یال ساده یال شرطی، انتخاب در زمان اجرا
از __start__ در بالا بخوانید. جعبه‌های آبی نودهای قلاب هستند. خطوط خط‌چین کهربایی در طرفین به سمت بالا و به A.before_model برمی‌گردند. از capture/out/49-draw-middleware.txt.

ترتیب اجرای یک چرخه‌ی کامل ابزار

کد کمکی یک پرسش را همراه با یک فراخوانی ابزار اجرا کرد و تمام هوک‌ها را به ثبت رساند:

ترتیب قلاب‌ها برای یک رفت‌وبرگشت ابزار capture/out/09-middleware-order.txt
  "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 اجرا را خاتمه می‌دهند.

سه قاعده این ترتیب را تعیین می‌کنند و شکل آن‌ها را رسم کرده است:

  1. هوک‌های before_agent و before_model به ترتیب فهرست اجرا می‌شوند: اول A، بعد B و سپس C.
  2. هوک‌های after_model و after_agent با ترتیب معکوس فهرست اجرا می‌شوند: اول C، بعد B و سپس A.
  3. هوک‌های پوششی تودرتو می‌شوند. اولین میان‌افزار فهرست، بیرونی‌ترین لایه است؛ بنابراین A اول از همه وارد و آخر از همه خارج می‌شود.
ترتیب قلاب‌ها از سه میدل‌ویرقلاب‌های نود قبل از مدل به صورت A، B، C و بعد از آن به صورت C، B، A اجرا می‌شوند، و قلاب‌های wrap به‌صورت تودرتو با لایه‌ی بیرونی A قرار می‌گیرند.
ترتیب قلاب‌ها از سه میدل‌ویر ردگیری 38 فراخوانی قلاب که middleware=[A, B, C] در یک رفت‌وبرگشت ابزار لاگ کردند، از چپ به راست خوانده می‌شود. سه خط A، B و C، و خط چهارم برای مدل و ابزار. هر نقطه یک قلاب نود است. هر میله یک قلاب wrap است، از ورود تا خروج. 9 فاز شماره‌دار در بالا اجرا می‌شوند: before_agent A B C، before_model A B C، ورود به wrap_model_call به صورت A B C با مدل درون آن و خروج به صورت C B A، after_model C B A، ورود به wrap_tool_call به صورت A B C اطراف ابزار add و خروج به صورت C B A، مجدداً همان گذر مدل، و after_agent C B A. میله‌های A طولانی‌ترین هستند، بنابراین A لایه‌ی بیرونی است. زیر ردگیری، یال‌های گراف ایجنت کامپایل‌شده خوانده می‌شوند: C.before_model به model به C.after_model به B.after_model به A.after_model. 38 فراخوانی قلاب به ترتیبی که اجرا شدند 1 2 3 4 5 6 7 8 9 A B C model، tool فازها 1 before_agent: A B C 2 before_model: A B C 3 wrap_model_call: A B C 4 after_model: C B A 5 wrap_tool_call: A B C 6 before_model: A B C 7 wrap_model_call: A B C 8 after_model: C B A 9 after_agent: C B A before_ node hook after_ node hook wrap_model_call wrap_tool_call یال‌های گراف در اطراف نود MODEL C.before_model model C.after_model B.after_model A.after_model Each after_model hook is its own node, and the edges run in the reverse of the list order.
ردگیری را از چپ به راست بخوانید. هر نقطه یک قلاب نود در خط A، B یا C است و هر میله یک قلاب wrap از ورود تا خروج است. فازهای شماره‌دار زیر ردگیری راهنما دارند و سطر پایین یال‌های اطراف نود model هستند. از capture/out/09-middleware-order.txt.

مستندات میان‌افزار سفارشی نیز همین سه قاعده را بیان می‌کند {{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 آن برمی‌دارد که به‌طور پیش‌فرض همان نام کلاس است. دو نمونه از یک کلاس نام یکسانی دارند و ایجنت آن‌ها را رد می‌کند:

دو میدل‌ویر با نام یکسان capture/out/09-middleware-order.txt
create_agent(middleware=[A, A]):

raised builtins.AssertionError: Please remove duplicate middleware instances.

برای استفاده از دو نمونه از یک کلاس، به هر کدام یک name اختصاصی بدهید. میان‌افزار Traced در کتابخانه‌ی کمکی ما، برچسب خود را به عنوان نام برمی‌گرداند:

یک پراپرتی name capture/s_agents.py
    @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.

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