Skip to content

Build and run agents you can see, understand and trust.

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.rst
index 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_agent
tutorial/task_state
tutorial/task_hook
+ tutorial/task_middleware
tutorial/task_a2a
tutorial/task_realtime
diff --git a/docs/tutorial/en/src/task_middleware.py b/docs/tutorial/en/src/task_middleware.py
new file mode 100644
index 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`` objects
diff --git a/docs/tutorial/zh_CN/index.rst b/docs/tutorial/zh_CN/index.rst
index 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_agent
tutorial/task_state
tutorial/task_hook
+ tutorial/task_middleware
tutorial/task_a2a
tutorial/task_realtime
diff --git a/docs/tutorial/zh_CN/src/task_middleware.py b/docs/tutorial/zh_CN/src/task_middleware.py
new file mode 100644
index 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.py
index decc4dff9..4e5f39360 100644
--- a/src/agentscope/tool/_toolkit.py
+++ b/src/agentscope/tool/_toolkit.py
@@ -8,7 +8,7 @@ import asyncio
import inspect
import os
from copy import deepcopy
-from functools import partial
+from functools import partial, wraps
from 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_toolkit
from .._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 tool
functions, 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 middlewares
self._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_middlewares
async 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.py
index 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_function
method."""
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 generator
return _trace_async_generator_wrapper(res, span)
except Exception as e:
diff --git a/tests/toolkit_middleware_test.py b/tests/toolkit_middleware_test.py
new file mode 100644
index 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]",
+ )