Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(middleware): support toolkit middleware to control the tool execution (#1232)
DavdGao597be683fc90
diff --git a/docs/tutorial/en/index.rst b/docs/tutorial/en/index.rstindex b8450a5f7..d39955f75 100644--- a/docs/tutorial/en/index.rst+++ b/docs/tutorial/en/index.rst@@ -56,6 +56,7 @@ Welcome to AgentScope's documentation!tutorial/task_agenttutorial/task_statetutorial/task_hook+ tutorial/task_middlewaretutorial/task_a2atutorial/task_realtimediff --git a/docs/tutorial/en/src/task_middleware.py b/docs/tutorial/en/src/task_middleware.pynew file mode 100644index 000000000..de984c8a5--- /dev/null+++ b/docs/tutorial/en/src/task_middleware.py@@ -0,0 +1,403 @@+# -*- coding: utf-8 -*-+"""+.. _middleware:++Middleware+===========================++AgentScope provides a flexible middleware system that allows developers to intercept and modify the execution of various operations.+Currently, middleware support is available for **tool execution** in the ``Toolkit`` class.++The middleware system follows an **onion model**, where each middleware wraps around the previous one, forming layers.+This allows developers to:++- Perform **pre-processing** before the operation+- **Intercept and modify** responses during execution+- Perform **post-processing** after the operation completes+- **Skip** the operation execution entirely based on conditions++.. tip:: Future versions of AgentScope will expand middleware support to other components such as agents and models.++"""+import asyncio+from typing import AsyncGenerator, Callable++from agentscope.message import TextBlock, ToolUseBlock+from agentscope.tool import ToolResponse, Toolkit+++# %%+# Tool Execution Middleware+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+#+# The ``Toolkit`` class supports middleware for tool execution via the ``register_middleware`` method.+# Each middleware can intercept the tool call and modify the input or output.+#+# Middleware Signature+# ------------------------------+#+# A middleware function should have the following signature:+#+# .. code-block:: python+#+# async def middleware(+# kwargs: dict,+# next_handler: Callable,+# ) -> AsyncGenerator[ToolResponse, None]:+# # Access parameters from kwargs+# tool_call = kwargs["tool_call"]+#+# # Pre-processing+# # ...+#+# # Call the next middleware or tool function+# async for response in await next_handler(**kwargs):+# # Post-processing+# yield response+#+# .. list-table:: Middleware Parameters+# :header-rows: 1+#+# * - Parameter+# - Type+# - Description+# * - ``kwargs``+# - ``dict``+# - Context parameters. Currently, includes ``tool_call`` (ToolUseBlock). May include additional parameters in future versions.+# * - ``next_handler``+# - ``Callable``+# - A callable that accepts kwargs dict and returns a coroutine yielding AsyncGenerator of ToolResponse objects+# * - **Returns**+# - ``AsyncGenerator[ToolResponse, None]``+# - An async generator that yields ToolResponse objects+#+# Basic Example+# ------------------------------+#+# Here is a simple middleware that logs tool calls:+#+++async def logging_middleware(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """A middleware that logs tool execution."""+ # Access the tool call from kwargs+ tool_call = kwargs["tool_call"]++ # Pre-processing: log before tool execution+ print(f"[Middleware] Calling tool: {tool_call['name']}")+ print(f"[Middleware] Input: {tool_call['input']}")++ # Call the next handler (either another middleware or the actual tool)+ async for response in await next_handler(**kwargs):+ # Post-processing: log the response+ print(f"[Middleware] Response: {response.content[0]['text']}")+ yield response++ # This will execute after all responses are yielded+ print(f"[Middleware] Tool {tool_call['name']} completed")+++# %%+# Let's register this middleware with a toolkit and test it:+#+++async def search_tool(query: str) -> ToolResponse:+ """A simple search tool.++ Args:+ query (`str`):+ The search query.++ Returns:+ `ToolResponse`:+ The search result.+ """+ return ToolResponse(+ content=[+ TextBlock(+ type="text",+ text=f"Search results for '{query}'",+ ),+ ],+ )+++async def example_logging_middleware() -> None:+ """Example of using logging middleware."""+ # Create a toolkit and register the tool+ toolkit = Toolkit()+ toolkit.register_tool_function(search_tool)++ # Register the middleware+ toolkit.register_middleware(logging_middleware)++ # Call the tool+ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="1",+ name="search_tool",+ input={"query": "AgentScope"},+ ),+ )++ async for response in result:+ print(f"\n[Final] {response.content[0]['text']}\n")+++print("=" * 60)+print("Example 1: Logging Middleware")+print("=" * 60)+asyncio.run(example_logging_middleware())++# %%+# Modifying Input and Output+# ------------------------------+#+# Middleware can also modify the tool call input and the response content:+#+++async def transform_middleware(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """A middleware that transforms input and output."""+ # Access the tool call from kwargs+ tool_call = kwargs["tool_call"]++ # Pre-processing: modify the input+ original_query = tool_call["input"]["query"]+ tool_call["input"]["query"] = f"[TRANSFORMED] {original_query}"++ async for response in await next_handler(**kwargs):+ # Post-processing: modify the response+ original_text = response.content[0]["text"]+ response.content[0]["text"] = f"{original_text} [MODIFIED]"+ yield response+++async def example_transform_middleware() -> None:+ """Example of transforming middleware."""+ toolkit = Toolkit()+ toolkit.register_tool_function(search_tool)+ toolkit.register_middleware(transform_middleware)++ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="2",+ name="search_tool",+ input={"query": "middleware"},+ ),+ )++ async for response in result:+ print(f"Result: {response.content[0]['text']}")+++print("\n" + "=" * 60)+print("Example 2: Transform Middleware")+print("=" * 60)+asyncio.run(example_transform_middleware())++# %%+# Authorization Middleware+# ------------------------------+#+# You can use middleware to implement authorization checks and skip tool execution if not authorized:+#+++async def authorization_middleware(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """A middleware that checks authorization."""+ # Access the tool call from kwargs+ tool_call = kwargs["tool_call"]++ # Check if the tool is authorized (simple example)+ authorized_tools = {"search_tool"}++ if tool_call["name"] not in authorized_tools:+ # Skip execution and return error directly+ print(f"[Auth] Tool {tool_call['name']} is not authorized")+ yield ToolResponse(+ content=[+ TextBlock(+ type="text",+ text=f"Error: Tool '{tool_call['name']}' is not authorized", # noqa: E501+ ),+ ],+ )+ return++ # Tool is authorized, proceed+ print(f"[Auth] Tool {tool_call['name']} is authorized")+ async for response in await next_handler(**kwargs):+ yield response+++async def unauthorized_tool(data: str) -> ToolResponse:+ """An unauthorized tool.++ Args:+ data (`str`):+ Some data.++ Returns:+ `ToolResponse`:+ The result.+ """+ return ToolResponse(+ content=[TextBlock(type="text", text=f"Processing {data}")],+ )+++async def example_authorization_middleware() -> None:+ """Example of authorization middleware."""+ toolkit = Toolkit()+ toolkit.register_tool_function(search_tool)+ toolkit.register_tool_function(unauthorized_tool)+ toolkit.register_middleware(authorization_middleware)++ # Try authorized tool+ print("\nCalling authorized tool:")+ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="3",+ name="search_tool",+ input={"query": "test"},+ ),+ )+ async for response in result:+ print(f"Result: {response.content[0]['text']}")++ # Try unauthorized tool+ print("\nCalling unauthorized tool:")+ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="4",+ name="unauthorized_tool",+ input={"data": "test"},+ ),+ )+ async for response in result:+ print(f"Result: {response.content[0]['text']}")+++print("\n" + "=" * 60)+print("Example 3: Authorization Middleware")+print("=" * 60)+asyncio.run(example_authorization_middleware())++# %%+# Multiple Middleware (Onion Model)+# ------------------------------+#+# When multiple middleware are registered, they form an onion-like structure.+# The execution order follows the onion model:+#+# - **Pre-processing**: Executes in the order middleware are registered+# - **Post-processing**: Executes in reverse order (inner to outer)+#+# This is because the actual tool response object is passed through the middleware chain,+# and each middleware modifies it in place.+#+++async def middleware_1(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """First middleware."""+ # Access the tool call from kwargs+ tool_call = kwargs["tool_call"]++ # Pre-processing+ print("[M1] Pre-processing")+ tool_call["input"]["query"] += " [M1]"++ async for response in await next_handler(**kwargs):+ # Post-processing+ response.content[0]["text"] += " [M1]"+ print("[M1] Post-processing")+ yield response+++async def middleware_2(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """Second middleware."""+ # Access the tool call from kwargs+ tool_call = kwargs["tool_call"]++ # Pre-processing+ print("[M2] Pre-processing")+ tool_call["input"]["query"] += " [M2]"++ async for response in await next_handler(**kwargs):+ # Post-processing+ response.content[0]["text"] += " [M2]"+ print("[M2] Post-processing")+ yield response+++async def example_multiple_middleware() -> None:+ """Example of multiple middleware."""+ toolkit = Toolkit()+ toolkit.register_tool_function(search_tool)++ # Register middleware in order+ toolkit.register_middleware(middleware_1)+ toolkit.register_middleware(middleware_2)++ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="5",+ name="search_tool",+ input={"query": "test"},+ ),+ )++ async for response in result:+ print(f"\nFinal result: {response.content[0]['text']}")+++print("\n" + "=" * 60)+print("Example 4: Multiple Middleware (Onion Model)")+print("=" * 60)+print("\nExecution flow:")+print("M1 Pre → M2 Pre → Tool → M2 Post → M1 Post")+print()+asyncio.run(example_multiple_middleware())++# %%+# Use Cases+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+#+# The middleware system is useful for various scenarios:+#+# - **Logging and Monitoring**: Track tool usage and performance+# - **Authorization**: Control access to specific tools+# - **Rate Limiting**: Limit the frequency of tool calls+# - **Caching**: Cache tool responses for repeated calls+# - **Error Handling**: Add retry logic or graceful degradation+# - **Input Validation**: Validate and sanitize tool inputs+# - **Output Transformation**: Format or filter tool outputs+# - **Metrics Collection**: Collect statistics about tool usage+#+# .. note::+# - Middleware are applied in the order they are registered+# - The same ``ToolResponse`` object is passed through the middleware chain and modified in place+# - Middleware can completely skip tool execution by not calling ``next_handler``+# - All middleware must be async generator functions that yield ``ToolResponse`` objectsdiff --git a/docs/tutorial/zh_CN/index.rst b/docs/tutorial/zh_CN/index.rstindex b1e642524..2e9914fab 100644--- a/docs/tutorial/zh_CN/index.rst+++ b/docs/tutorial/zh_CN/index.rst@@ -57,6 +57,7 @@ Welcome to AgentScope's documentation!tutorial/task_agenttutorial/task_statetutorial/task_hook+ tutorial/task_middlewaretutorial/task_a2atutorial/task_realtimediff --git a/docs/tutorial/zh_CN/src/task_middleware.py b/docs/tutorial/zh_CN/src/task_middleware.pynew file mode 100644index 000000000..da9f27c9c--- /dev/null+++ b/docs/tutorial/zh_CN/src/task_middleware.py@@ -0,0 +1,403 @@+# -*- coding: utf-8 -*-+"""+.. _middleware:++中间件+===========================++AgentScope 提供了灵活的中间件系统,允许开发者拦截和修改各种操作的执行。+目前,中间件支持已在 ``Toolkit`` 类中实现,用于**工具执行**。++中间件系统遵循**洋葱模型**,每个中间件包裹在前一个中间件之外,形成层次结构。+这使得开发者可以:++- 在操作前进行**预处理**+- 在执行过程中**拦截和修改**响应+- 在操作完成后进行**后处理**+- 根据条件**跳过**操作执行++.. tip:: 未来版本的 AgentScope 将扩展中间件支持到其他组件,如智能体和模型。++"""+import asyncio+from typing import AsyncGenerator, Callable++from agentscope.message import TextBlock, ToolUseBlock+from agentscope.tool import ToolResponse, Toolkit+++# %%+# 工具执行中间件+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+#+# ``Toolkit`` 类通过 ``register_middleware`` 方法支持工具执行的中间件。+# 每个中间件可以拦截工具调用并修改输入或输出。+#+# 中间件签名+# ------------------------------+#+# 中间件函数应具有以下签名:+#+# .. code-block:: python+#+# async def middleware(+# kwargs: dict,+# next_handler: Callable,+# ) -> AsyncGenerator[ToolResponse, None]:+# # 从 kwargs 访问参数+# tool_call = kwargs["tool_call"]+#+# # 预处理+# # ...+#+# # 调用下一个中间件或工具函数+# async for response in await next_handler(**kwargs):+# # 后处理+# yield response+#+# .. list-table:: 中间件参数+# :header-rows: 1+#+# * - 参数+# - 类型+# - 描述+# * - ``kwargs``+# - ``dict``+# - 上下文参数。当前包含 ``tool_call`` (ToolUseBlock)。未来版本可能包含更多参数。+# * - ``next_handler``+# - ``Callable``+# - 一个可调用对象,接受 kwargs dict 并返回产生 AsyncGenerator[ToolResponse] 的协程+# * - **返回值**+# - ``AsyncGenerator[ToolResponse, None]``+# - 产生 ToolResponse 对象的异步生成器+#+# 基本示例+# ------------------------------+#+# 以下是一个记录工具调用的简单中间件:+#+++async def logging_middleware(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """记录工具执行的中间件。"""+ # 从 kwargs 访问工具调用+ tool_call = kwargs["tool_call"]++ # 预处理:在工具执行前记录日志+ print(f"[中间件] 调用工具:{tool_call['name']}")+ print(f"[中间件] 输入:{tool_call['input']}")++ # 调用下一个处理器(另一个中间件或实际工具)+ async for response in await next_handler(**kwargs):+ # 后处理:记录响应+ print(f"[中间件] 响应:{response.content[0]['text']}")+ yield response++ # 在所有响应产生后执行+ print(f"[中间件] 工具 {tool_call['name']} 完成")+++# %%+# 让我们将这个中间件注册到工具包并测试它:+#+++async def search_tool(query: str) -> ToolResponse:+ """一个简单的搜索工具。++ Args:+ query (`str`):+ 搜索查询。++ Returns:+ `ToolResponse`:+ 搜索结果。+ """+ return ToolResponse(+ content=[+ TextBlock(+ type="text",+ text=f"'{query}' 的搜索结果",+ ),+ ],+ )+++async def example_logging_middleware() -> None:+ """使用日志中间件的示例。"""+ # 创建工具包并注册工具+ toolkit = Toolkit()+ toolkit.register_tool_function(search_tool)++ # 注册中间件+ toolkit.register_middleware(logging_middleware)++ # 调用工具+ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="1",+ name="search_tool",+ input={"query": "AgentScope"},+ ),+ )++ async for response in result:+ print(f"\n[最终] {response.content[0]['text']}\n")+++print("=" * 60)+print("示例 1:日志中间件")+print("=" * 60)+asyncio.run(example_logging_middleware())++# %%+# 修改输入和输出+# ------------------------------+#+# 中间件还可以修改工具调用的输入和响应内容:+#+++async def transform_middleware(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """转换输入和输出的中间件。"""+ # 从 kwargs 访问工具调用+ tool_call = kwargs["tool_call"]++ # 预处理:修改输入+ original_query = tool_call["input"]["query"]+ tool_call["input"]["query"] = f"[已转换] {original_query}"++ async for response in await next_handler(**kwargs):+ # 后处理:修改响应+ original_text = response.content[0]["text"]+ response.content[0]["text"] = f"{original_text} [已修改]"+ yield response+++async def example_transform_middleware() -> None:+ """转换中间件的示例。"""+ toolkit = Toolkit()+ toolkit.register_tool_function(search_tool)+ toolkit.register_middleware(transform_middleware)++ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="2",+ name="search_tool",+ input={"query": "中间件"},+ ),+ )++ async for response in result:+ print(f"结果:{response.content[0]['text']}")+++print("\n" + "=" * 60)+print("示例 2:转换中间件")+print("=" * 60)+asyncio.run(example_transform_middleware())++# %%+# 授权中间件+# ------------------------------+#+# 可以使用中间件实现授权检查,如果未授权则跳过工具执行:+#+++async def authorization_middleware(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """检查授权的中间件。"""+ # 从 kwargs 访问工具调用+ tool_call = kwargs["tool_call"]++ # 检查工具是否已授权(简单示例)+ authorized_tools = {"search_tool"}++ if tool_call["name"] not in authorized_tools:+ # 跳过执行并直接返回错误+ print(f"[授权] 工具 {tool_call['name']} 未授权")+ yield ToolResponse(+ content=[+ TextBlock(+ type="text",+ text=f"错误:工具 '{tool_call['name']}' 未授权",+ ),+ ],+ )+ return++ # 工具已授权,继续执行+ print(f"[授权] 工具 {tool_call['name']} 已授权")+ async for response in await next_handler(**kwargs):+ yield response+++async def unauthorized_tool(data: str) -> ToolResponse:+ """一个未授权的工具。++ Args:+ data (`str`):+ 一些数据。++ Returns:+ `ToolResponse`:+ 结果。+ """+ return ToolResponse(+ content=[TextBlock(type="text", text=f"处理 {data}")],+ )+++async def example_authorization_middleware() -> None:+ """授权中间件的示例。"""+ toolkit = Toolkit()+ toolkit.register_tool_function(search_tool)+ toolkit.register_tool_function(unauthorized_tool)+ toolkit.register_middleware(authorization_middleware)++ # 尝试授权的工具+ print("\n调用已授权的工具:")+ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="3",+ name="search_tool",+ input={"query": "测试"},+ ),+ )+ async for response in result:+ print(f"结果:{response.content[0]['text']}")++ # 尝试未授权的工具+ print("\n调用未授权的工具:")+ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="4",+ name="unauthorized_tool",+ input={"data": "测试"},+ ),+ )+ async for response in result:+ print(f"结果:{response.content[0]['text']}")+++print("\n" + "=" * 60)+print("示例 3:授权中间件")+print("=" * 60)+asyncio.run(example_authorization_middleware())++# %%+# 多个中间件(洋葱模型)+# ------------------------------+#+# 当注册多个中间件时,它们形成类似洋葱的结构。+# 执行顺序遵循洋葱模型:+#+# - **预处理**:按照中间件注册的顺序执行+# - **后处理**:按相反顺序执行(从内到外)+#+# 这是因为实际的工具响应对象会通过中间件链传递,+# 每个中间件都会原地修改它。+#+++async def middleware_1(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """第一个中间件。"""+ # 从 kwargs 访问工具调用+ tool_call = kwargs["tool_call"]++ # 预处理+ print("[M1] 预处理")+ tool_call["input"]["query"] += " [M1]"++ async for response in await next_handler(**kwargs):+ # 后处理+ response.content[0]["text"] += " [M1]"+ print("[M1] 后处理")+ yield response+++async def middleware_2(+ kwargs: dict,+ next_handler: Callable,+) -> AsyncGenerator[ToolResponse, None]:+ """第二个中间件。"""+ # 从 kwargs 访问工具调用+ tool_call = kwargs["tool_call"]++ # 预处理+ print("[M2] 预处理")+ tool_call["input"]["query"] += " [M2]"++ async for response in await next_handler(**kwargs):+ # 后处理+ response.content[0]["text"] += " [M2]"+ print("[M2] 后处理")+ yield response+++async def example_multiple_middleware() -> None:+ """多个中间件的示例。"""+ toolkit = Toolkit()+ toolkit.register_tool_function(search_tool)++ # 按顺序注册中间件+ toolkit.register_middleware(middleware_1)+ toolkit.register_middleware(middleware_2)++ result = await toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ id="5",+ name="search_tool",+ input={"query": "测试"},+ ),+ )++ async for response in result:+ print(f"\n最终结果:{response.content[0]['text']}")+++print("\n" + "=" * 60)+print("示例 4:多个中间件(洋葱模型)")+print("=" * 60)+print("\n执行流程:")+print("M1 预处理 → M2 预处理 → 工具 → M2 后处理 → M1 后处理")+print()+asyncio.run(example_multiple_middleware())++# %%+# 使用场景+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+#+# 中间件系统适用于各种场景:+#+# - **日志和监控**:跟踪工具使用情况和性能+# - **授权**:控制对特定工具的访问+# - **速率限制**:限制工具调用的频率+# - **缓存**:缓存重复调用的工具响应+# - **错误处理**:添加重试逻辑或优雅降级+# - **输入验证**:验证和清理工具输入+# - **输出转换**:格式化或过滤工具输出+# - **指标收集**:收集有关工具使用情况的统计信息+#+# .. note::+# - 中间件按注册顺序应用+# - 同一个 ``ToolResponse`` 对象通过中间件链传递并原地修改+# - 中间件可以通过不调用 ``next_handler`` 来完全跳过工具执行+# - 所有中间件必须是产生 ``ToolResponse`` 对象的异步生成器函数diff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.pyindex decc4dff9..4e5f39360 100644--- a/src/agentscope/tool/_toolkit.py+++ b/src/agentscope/tool/_toolkit.py@@ -8,7 +8,7 @@ import asyncioimport inspectimport osfrom copy import deepcopy-from functools import partial+from functools import partial, wrapsfrom typing import (AsyncGenerator,Literal,@@ -17,6 +17,7 @@ from typing import (Generator,Callable,Awaitable,+ Coroutine,)import mcp@@ -53,6 +54,66 @@ from ..tracing._trace import trace_toolkitfrom .._logging import logger+def _apply_middlewares(+ func: Callable[+ ...,+ Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]],+ ],+) -> Callable[..., AsyncGenerator[ToolResponse, None]]:+ """Decorator that applies registered middlewares at runtime.++ This decorator reads the middleware list from the instance and constructs+ the middleware chain dynamically during each invocation.++ .. note:: Middlewares must be async generator functions that yield+ `ToolResponse` objects.+ """++ @wraps(func)+ async def wrapper(+ self: "Toolkit",+ tool_call: ToolUseBlock,+ ) -> AsyncGenerator[ToolResponse, None]:+ """Wrapper that applies middleware chain."""+ middlewares = getattr(self, "_middlewares", [])++ if not middlewares:+ # No middlewares, call the original function directly+ async for chunk in await func(self, tool_call):+ yield chunk+ return++ # Build the middleware chain from innermost to outermost+ async def base_handler(+ **kwargs: Any,+ ) -> AsyncGenerator[ToolResponse, None]:+ """Base handler that calls the original function."""+ return await func(self, **kwargs)++ # Wrap with each middleware in reverse order+ current_handler = base_handler+ for middleware in reversed(middlewares):++ def make_handler(mw: Callable, handler: Callable) -> Callable:+ """Create wrapped handler for middleware."""++ async def wrapped(+ **kwargs: Any,+ ) -> AsyncGenerator[ToolResponse, None]:+ """Handler that applies middleware."""+ return mw(kwargs, handler)++ return wrapped++ current_handler = make_handler(middleware, current_handler)++ # Execute the middleware chain+ async for chunk in await current_handler(tool_call=tool_call):+ yield chunk++ return wrapper++class Toolkit(StateModule):"""Toolkit is the core module to register, manage and delete toolfunctions, MCP clients, Agent skills in AgentScope.@@ -109,6 +170,7 @@ Check "{dir}/SKILL.md" for how to use this skill"""self.tools: dict[str, RegisteredToolFunction] = {}self.groups: dict[str, ToolGroup] = {}self.skills: dict[str, AgentSkill] = {}+ self._middlewares: list = [] # Store registered middlewaresself._agent_skill_instruction = (agent_skill_instruction or self._DEFAULT_AGENT_SKILL_INSTRUCTION@@ -608,6 +670,7 @@ Check "{dir}/SKILL.md" for how to use this skill""")@trace_toolkit+ @_apply_middlewaresasync def call_tool_function(self,tool_call: ToolUseBlock,@@ -1151,3 +1214,103 @@ Check "{dir}/SKILL.md" for how to use this skill"""for _ in self.skills.values()]return "\n".join(skill_descriptions)++ def register_middleware(+ self,+ middleware: Callable[+ ...,+ Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]]+ | AsyncGenerator[ToolResponse, None],+ ],+ ) -> None:+ """Register an onion-style middleware for the `call_tool_function`,+ which will wrap around the `call_tool_function` method, allowing+ pre-processing, post-processing, or even skipping the execution of+ the tool function.++ The middleware follows an onion model, where each registered+ middleware wraps around the previous one, forming layers. The+ middleware can:++ - Perform pre-processing before calling the tool function+ - Intercept and modify each ToolResponse chunk+ - Perform post-processing after the tool function completes+ - Skip the tool function execution entirely++ The middleware function should accept a ``kwargs`` dict as the first+ parameter and ``next_handler`` as the second parameter. The ``kwargs``+ dict currently contains:++ - ``tool_call`` (`ToolUseBlock`): The tool call request++ When calling ``next_handler``, pass ``**kwargs`` to unpack the dict.++ Example:+ .. code-block:: python++ # Simple direct consumption style (recommended)+ async def my_middleware(+ kwargs: dict,+ next_handler: Callable,+ ) -> AsyncGenerator[ToolResponse, None]:+ # Access the tool call+ tool_call = kwargs["tool_call"]++ # Pre-processing+ print(f"Calling tool: {tool_call['name']}")++ # Call next handler with **kwargs+ async for response in await next_handler(**kwargs):+ # Intercept and modify response if needed+ yield response++ # Post-processing after tool completes+ print(f"Tool {tool_call['name']} completed")++ toolkit.register_middleware(my_middleware)++ .. code-block:: python++ # Alternative: Skip execution based on conditions+ async def my_middleware(+ kwargs: dict,+ next_handler: Callable,+ ) -> AsyncGenerator[ToolResponse, None]:+ tool_call = kwargs["tool_call"]++ # Pre-processing+ if not is_authorized(tool_call):+ # Skip execution and return error directly+ yield ToolResponse(+ content=[+ TextBlock(+ type="text",+ text="Unauthorized",+ ),+ ],+ )+ return++ # Call next handler with **kwargs+ async for response in await next_handler(**kwargs):+ yield response++ toolkit.register_middleware(my_middleware)++ Args:+ middleware (`Callable[..., Coroutine[Any, Any, \+AsyncGenerator[ToolResponse, None]] | AsyncGenerator[ToolResponse, None]]`):+ The middleware function that accepts ``kwargs`` (dict) and+ ``next_handler`` (Callable), and returns a coroutine that+ yields AsyncGenerator of ToolResponse objects. The ``kwargs``+ dict currently includes ``tool_call`` (ToolUseBlock), and may+ include additional context in future versions.++ .. note:: The middleware chain is applied inside the+ `call_tool_function` via the `@apply_middlewares` decorator. This+ ensures that the `@trace_toolkit` decorator remains at the outermost+ layer for complete observability.+ """+ # Simply append the middleware to the list+ # The @apply_middlewares decorator will handle the execution+ self._middlewares.append(middleware)diff --git a/src/agentscope/tracing/_trace.py b/src/agentscope/tracing/_trace.pyindex 9aaf08656..9c0ecd605 100644--- a/src/agentscope/tracing/_trace.py+++ b/src/agentscope/tracing/_trace.py@@ -320,10 +320,7 @@ def trace(def trace_toolkit(- func: Callable[- ...,- Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]],- ],+ func: Callable[..., AsyncGenerator[ToolResponse, None]],) -> Callable[..., Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]]]:"""Trace the toolkit `call_tool_function` method with OpenTelemetry."""@@ -335,7 +332,7 @@ def trace_toolkit("""The wrapper function for tracing the toolkit call_tool_functionmethod."""if not _check_tracing_enabled():- return await func(self, tool_call=tool_call)+ return func(self, tool_call=tool_call)tracer = _get_tracer()@@ -352,10 +349,11 @@ def trace_toolkit(end_on_exit=False,) as span:try:- # Call the toolkit function- res = await func(self, tool_call=tool_call)+ # Call the toolkit function (returns AsyncGenerator)+ res = func(self, tool_call=tool_call)- # The result must be an AsyncGenerator of ToolResponse objects+ # The result must be an AsyncGenerator+ # Return the wrapped generatorreturn _trace_async_generator_wrapper(res, span)except Exception as e:diff --git a/tests/toolkit_middleware_test.py b/tests/toolkit_middleware_test.pynew file mode 100644index 000000000..20c2396dc--- /dev/null+++ b/tests/toolkit_middleware_test.py@@ -0,0 +1,86 @@+# -*- coding: utf-8 -*-+"""The unittests for toolkit middleware."""+from typing import Callable, AsyncGenerator, Coroutine, Any+from unittest.async_case import IsolatedAsyncioTestCase++from agentscope.message import TextBlock, ToolUseBlock+from agentscope.tool import Toolkit, ToolResponse+++async def middleware_1(+ kwargs: dict,+ next_handler: Callable[+ ...,+ Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]],+ ],+) -> AsyncGenerator[ToolResponse, None]:+ """A simple middleware that adds a key-value pair to the kwargs."""+ # Pre-processing+ tool_call = kwargs["tool_call"]+ tool_call["input"]["a"] += "[pre1]"++ async for chunk in await next_handler(**kwargs):+ chunk.content[0]["text"] += "[post1]"+ yield chunk+++async def middleware_2(+ kwargs: dict,+ next_handler: Callable[+ ...,+ Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]],+ ],+) -> AsyncGenerator[ToolResponse, None]:+ """Another middleware that adds a key-value pair to the kwargs."""+ # Pre-processing+ tool_call = kwargs["tool_call"]+ tool_call["input"]["a"] += "[pre2]"++ async for chunk in await next_handler(**kwargs):+ chunk.content[0]["text"] += "[post2]"+ yield chunk+++async def tool(a: str) -> ToolResponse:+ """The test tool function.++ Args:+ a (`str`):+ A string input.++ Returns:+ `ToolResponse`:+ The tool response containing the input value.+ """+ return ToolResponse(+ content=[TextBlock(type="text", text=a)],+ )+++class ToolkitMiddlewareTest(IsolatedAsyncioTestCase):+ """Test the toolkit middleware."""++ async def asyncSetUp(self) -> None:+ """Set up the test case."""+ self.toolkit = Toolkit()+ self.toolkit.register_tool_function(tool)++ async def test_toolkit_middleware(self) -> None:+ """Test the toolkit middleware."""+ self.toolkit.register_middleware(middleware_1)+ self.toolkit.register_middleware(middleware_2)++ res = await self.toolkit.call_tool_function(+ ToolUseBlock(+ type="tool_use",+ name="tool",+ input={"a": "[ori]"},+ id="123",+ ),+ )++ async for chunk in res:+ self.assertEqual(+ chunk.content[0]["text"],+ "[ori][pre1][pre2][post2][post1]",+ )