Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(middleware): add on_check_permission hook (#2001)
Miracle778c613a8602c7f
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex 2e0b1d793..69ad6d44d 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -87,6 +87,7 @@ from ..message import ()from ..tool import (Toolkit,+ ToolBase,ToolChunk,ToolChoice,ToolResponse,@@ -140,8 +141,8 @@ class Agent:middlewares (`list[MiddlewareBase] | None`, optional):Middlewares applied to the agent to modify its behaviorwithout altering its source code. Supported hook points- include: reply, reasoning, acting, model call, and system- prompt retrieval.+ include: reply, reasoning, permission checking, acting, model+ call, context compression, and system prompt retrieval.state (`AgentState | None`, optional):The agent state. A new state will be created if not provided.offloader (`Offloader | None`, optional):@@ -193,6 +194,9 @@ class Agent:self._reasoning_middlewares = [_ for _ in middlewares if _.is_implemented("on_reasoning")]+ self._check_permission_middlewares = [+ _ for _ in middlewares if _.is_implemented("on_check_permission")+ ]self._acting_middlewares = [_ for _ in middlewares if _.is_implemented("on_acting")]@@ -1916,6 +1920,97 @@ class Agent:async for evt in self._execute_tool_call(tool_call, kept_rules):await queue.put(evt)+ async def _check_permission(+ self,+ tool_call: ToolCallBlock,+ tool: ToolBase,+ tool_input: dict[str, Any],+ ) -> PermissionDecision:+ """Run permission checking through the middleware onion.++ The middleware chain receives copies of the tool call and tool input;+ changes to these copies do not alter the eventual tool invocation. A+ call already allowed by user confirmation still traverses the+ middleware chain, but skips re-evaluation by the built-in engine.++ Args:+ tool_call (`ToolCallBlock`):+ The validated tool call metadata.+ tool (`ToolBase`):+ The resolved tool instance.+ tool_input (`dict[str, Any]`):+ The parsed and schema-validated tool input.++ Returns:+ `PermissionDecision`:+ The decision that the agent should consume.+ """++ if not self._check_permission_middlewares:+ return await self._check_permission_impl(+ tool_call,+ tool,+ tool_input,+ )++ # Copy so middleware cannot mutate what the agent consumes later.+ tool_call = deepcopy(tool_call)+ tool_input = deepcopy(tool_input)++ async def execute_chain(+ index: int = 0,+ tool_call: ToolCallBlock = tool_call,+ tool: ToolBase = tool,+ tool_input: dict[str, Any] = tool_input,+ ) -> PermissionDecision:+ """Execute the check_permission middleware chain."""+ if index >= len(self._check_permission_middlewares):+ return await self._check_permission_impl(+ tool_call,+ tool,+ tool_input,+ )++ mw = self._check_permission_middlewares[index]+ input_kwargs = {+ "tool_call": tool_call,+ "tool": tool,+ "tool_input": tool_input,+ }++ async def next_handler(**kwargs: Any) -> PermissionDecision:+ return await execute_chain(+ index + 1,+ **{**input_kwargs, **kwargs},+ )++ return await mw.on_check_permission(+ agent=self,+ input_kwargs=input_kwargs,+ next_handler=next_handler,+ )++ return await execute_chain()++ async def _check_permission_impl(+ self,+ tool_call: ToolCallBlock,+ tool: ToolBase,+ tool_input: dict[str, Any],+ ) -> PermissionDecision:+ """Core permission resolution, wrapped by ``on_check_permission``.++ A call already allowed by user confirmation short-circuits to ALLOW;+ otherwise the built-in engine evaluates the tool and its input. See+ :meth:`_check_permission` for the argument and return semantics.+ """+ if tool_call.state == ToolCallState.ALLOWED:+ return PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="Already allowed by user confirmation.",+ )+ return await self._engine.check_permission(tool, tool_input)+async def _execute_tool_call(self,tool_call: ToolCallBlock,@@ -2006,17 +2101,11 @@ class Agent:# ===================================================================# Step 2: Check permission by toolkit and permission engine# ===================================================================- if tool_call.state == ToolCallState.ALLOWED:- # Already allowed by user confirmation, skip permission checking- decision = PermissionDecision(- behavior=PermissionBehavior.ALLOW,- message="Already allowed by user confirmation.",- )- else:- decision = await self._engine.check_permission(- tool,- parsed_input,- )+ decision = await self._check_permission(+ tool_call,+ tool,+ parsed_input,+ )# ===================================================================# Step 3: Handle the permission and execute the tool call if alloweddiff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.pyindex 2fc4de95b..33eae7082 100644--- a/src/agentscope/middleware/_base.py+++ b/src/agentscope/middleware/_base.py@@ -7,19 +7,22 @@ from ..tool import ToolBaseif TYPE_CHECKING:from ..agent import Agentfrom ..model import ChatResponse+ from ..permission import PermissionDecisionclass MiddlewareBase: # pylint: disable=unused-argument"""Base class for all middleware implementations.- Middleware provides interception mechanisms at 5 key execution points+ Middleware provides interception mechanisms at 7 key execution pointsin the Agent lifecycle:**Onion Pattern Hooks** (with before/after logic):- `on_reply`: Intercepts the entire reply process- `on_reasoning`: Intercepts the reasoning/model call phase+ - `on_check_permission`: Intercepts permission checking for a tool call- `on_acting`: Intercepts individual tool call execution- `on_model_call`: Intercepts the raw model API call+ - `on_compress_context`: Intercepts context compression**Transformer Pattern Hook** (sequential pipeline):- `on_system_prompt`: Transforms the system prompt string@@ -157,6 +160,49 @@ class MiddlewareBase: # pylint: disable=unused-argument)yield # pylint: disable=unreachable+ async def on_check_permission(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable["PermissionDecision"]],+ ) -> "PermissionDecision":+ """Hook for intercepting permission checking for one tool call.++ This hook runs after the tool has been resolved and its input has been+ parsed and validated, but before the resulting decision is consumed by+ the agent.++ Middleware can delegate with ``next_handler(**input_kwargs)``, replace+ the returned decision, or return a decision without delegating. The+ chain receives copies of ``tool_call`` and ``tool_input``; changes to+ these copies do not alter the eventual tool invocation.++ .. note::+ Returning without calling ``next_handler`` bypasses the built-in+ permission resolution for that call.++ Args:+ agent (`Agent`):+ The Agent instance performing the permission check.+ input_kwargs (`dict`):+ Dictionary containing:++ - ``tool_call`` (``ToolCallBlock``): validated call metadata+ used to correlate the permission decision.+ - ``tool`` (``ToolBase``): the resolved tool instance.+ - ``tool_input`` (``dict``): the parsed and validated input.+ next_handler (`Callable[..., Awaitable[PermissionDecision]]`):+ Callable that executes the next middleware or the built-in+ permission resolution.++ Returns:+ `PermissionDecision`:+ The decision the agent should consume.+ """+ raise RuntimeError(+ f"{type(self).__name__} does not implement on_check_permission",+ )+async def on_model_call(self,agent: "Agent",diff --git a/tests/middleware_test.py b/tests/middleware_test.pyindex 761252c0b..26b008537 100644--- a/tests/middleware_test.py+++ b/tests/middleware_test.py@@ -1,9 +1,9 @@# -*- coding: utf-8 -*--# pylint: disable=abstract-method+# pylint: disable=abstract-method,protected-access"""Unit tests for middleware system."""from unittest.async_case import IsolatedAsyncioTestCasefrom unittest.mock import AsyncMock, patch-from typing import Any, AsyncGenerator, Callable, Union+from typing import Any, AsyncGenerator, Awaitable, Callable, Unionfrom utils import MockModelfrom pydantic import BaseModel@@ -18,6 +18,7 @@ from agentscope.message import (SystemMsg,Msg,ToolCallBlock,+ ToolCallState,)from agentscope.tool import Toolkit, ToolBase, ToolChunkfrom agentscope.permission import (@@ -1312,3 +1313,555 @@ class TestMiddleware(IsolatedAsyncioTestCase):async def asyncTearDown(self) -> None:"""Clean up test fixtures."""self.execution_log.clear()+++class TestCheckPermissionMiddleware(IsolatedAsyncioTestCase):+ """Test the permission-checking middleware onion."""++ async def asyncSetUp(self) -> None:+ """Set up permission middleware test fixtures."""+ self.mock_model = MockModel()+ self.execution_log: list[str] = []++ async def test_on_check_permission_middleware_detection(self) -> None:+ """Only middleware overriding the permission hook is selected."""++ class CheckPermissionMiddleware(MiddlewareBase):+ """Middleware implementing only the permission hook."""++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ """Delegate permission checking unchanged."""+ return await next_handler(**input_kwargs)++ self.assertFalse(+ MiddlewareBase().is_implemented("on_check_permission"),+ )+ self.assertTrue(+ CheckPermissionMiddleware().is_implemented(+ "on_check_permission",+ ),+ )++ async def test_on_check_permission_without_middleware_calls_engine(+ self,+ ) -> None:+ """The no-middleware path preserves the direct engine call."""+ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ )+ tool = AsyncMock(spec=ToolBase)+ tool_input = {"value": "original"}+ expected = PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="allowed",+ )+ engine = AsyncMock(return_value=expected)++ with patch.object(agent._engine, "check_permission", new=engine):+ actual = await agent._check_permission(+ ToolCallBlock(id="call_permission", name="tool", input="{}"),+ tool,+ tool_input,+ )++ self.assertIs(actual, expected)+ engine.assert_awaited_once_with(tool, tool_input)++ async def test_on_check_permission_follows_onion_order(self) -> None:+ """Permission middleware wraps the engine in registration order."""++ class PermissionTool(ToolBase):+ """Minimal tool used to exercise permission checking."""++ name = "permission_tool"+ description = "A tool used by permission middleware tests."+ input_schema = {+ "type": "object",+ "properties": {"value": {"type": "string"}},+ "required": ["value"],+ }+ is_concurrency_safe = True+ is_read_only = False++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ """Return a regular ASK when exercised without a mock."""+ return PermissionDecision(+ behavior=PermissionBehavior.ASK,+ message="permission required",+ )++ class OrderedMiddleware(MiddlewareBase):+ """Record before and after delegating to the next layer."""++ def __init__(self, name: str) -> None:+ self.name = name++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ self_outer.execution_log.append(f"{self.name}_pre")+ self_outer.assertEqual(+ set(input_kwargs),+ {"tool_call", "tool", "tool_input"},+ )+ decision = await next_handler(**input_kwargs)+ self_outer.execution_log.append(f"{self.name}_post")+ return decision++ self_outer = self+ tool = PermissionTool()+ tool_call = ToolCallBlock(+ id="call_permission",+ name=tool.name,+ input='{"value": "original"}',+ )+ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=Toolkit(tools=[tool]),+ middlewares=[OrderedMiddleware("mw1"), OrderedMiddleware("mw2")],+ )+ engine_decision = PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="allowed by engine",+ )++ async def check_permission(+ checked_tool: ToolBase,+ checked_input: dict,+ ) -> PermissionDecision:+ self.execution_log.append("engine")+ self.assertIs(checked_tool, tool)+ self.assertEqual(checked_input, {"value": "original"})+ return engine_decision++ with patch.object(+ agent._engine, # pylint: disable=protected-access+ "check_permission",+ side_effect=check_permission,+ ):+ decision = await agent._check_permission(+ tool_call,+ tool,+ {"value": "original"},+ )++ self.assertIs(decision, engine_decision)+ self.assertListEqual(+ self.execution_log,+ ["mw1_pre", "mw2_pre", "engine", "mw2_post", "mw1_post"],+ )++ async def test_on_check_permission_observes_final_engine_decisions(+ self,+ ) -> None:+ """The hook observes each final behavior returned by the engine."""++ class ObserveMiddleware(MiddlewareBase):+ """Record and preserve the engine's final decision."""++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ decision = await next_handler(**input_kwargs)+ observed.append(decision.behavior)+ return decision++ observed: list[PermissionBehavior] = []+ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ middlewares=[ObserveMiddleware()],+ )+ tool = AsyncMock(spec=ToolBase)+ tool_call = ToolCallBlock(+ id="call_permission",+ name="permission_tool",+ input="{}",+ )++ for behavior in (+ PermissionBehavior.ALLOW,+ PermissionBehavior.ASK,+ PermissionBehavior.DENY,+ ):+ engine_decision = PermissionDecision(+ behavior=behavior,+ message=behavior.value,+ )+ with patch.object(+ agent._engine, # pylint: disable=protected-access+ "check_permission",+ new=AsyncMock(return_value=engine_decision),+ ):+ decision = await agent._check_permission(+ tool_call,+ tool,+ {},+ )+ self.assertIs(decision, engine_decision)++ self.assertListEqual(+ observed,+ [+ PermissionBehavior.ALLOW,+ PermissionBehavior.ASK,+ PermissionBehavior.DENY,+ ],+ )++ async def test_on_check_permission_can_replace_decision(self) -> None:+ """Post-processing may replace the engine decision."""++ replacement = PermissionDecision(+ behavior=PermissionBehavior.DENY,+ message="denied by application policy",+ )++ class ReplaceMiddleware(MiddlewareBase):+ """Replace the built-in engine result after observing it."""++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ await next_handler(**input_kwargs)+ return replacement++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ middlewares=[ReplaceMiddleware()],+ )+ engine = AsyncMock(+ return_value=PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="allowed by engine",+ ),+ )+ with patch.object(+ agent._engine, # pylint: disable=protected-access+ "check_permission",+ new=engine,+ ):+ decision = await agent._check_permission(+ ToolCallBlock(id="call_permission", name="tool", input="{}"),+ AsyncMock(spec=ToolBase),+ {},+ )++ engine.assert_awaited_once()+ self.assertIs(decision, replacement)++ async def test_on_check_permission_can_short_circuit(self) -> None:+ """A middleware may return a decision without running the engine."""++ short_circuit = PermissionDecision(+ behavior=PermissionBehavior.DENY,+ message="tenant policy denied the call",+ )++ class TenantPolicyMiddleware(MiddlewareBase):+ """Deny without delegating to the built-in engine."""++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ return short_circuit++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ middlewares=[TenantPolicyMiddleware()],+ )+ engine = AsyncMock()+ with patch.object(+ agent._engine, # pylint: disable=protected-access+ "check_permission",+ new=engine,+ ):+ decision = await agent._check_permission(+ ToolCallBlock(id="call_permission", name="tool", input="{}"),+ AsyncMock(spec=ToolBase),+ {},+ )++ engine.assert_not_awaited()+ self.assertIs(decision, short_circuit)++ async def test_on_check_permission_forwards_replaced_input(+ self,+ ) -> None:+ """Explicitly forwarded inputs reach downstream permission checks."""++ forwarded_input = {"value": "original"}+ seen_by_inner: list[dict[str, str]] = []++ class ForwardingMiddleware(MiddlewareBase):+ """Replace the chain-local input with an equivalent object."""++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ return await next_handler(+ **{+ **input_kwargs,+ "tool_input": forwarded_input,+ },+ )++ class ObserveInnerMiddleware(MiddlewareBase):+ """Record the input forwarded by the outer middleware."""++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ seen_by_inner.append(input_kwargs["tool_input"])+ return await next_handler(**input_kwargs)++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ middlewares=[ForwardingMiddleware(), ObserveInnerMiddleware()],+ )+ tool = AsyncMock(spec=ToolBase)+ tool_call = ToolCallBlock(+ id="call_permission",+ name="tool",+ input='{"value": "original"}',+ )+ tool_input = {"value": "original"}+ engine = AsyncMock(+ return_value=PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="allowed",+ ),+ )+ with patch.object(+ agent._engine, # pylint: disable=protected-access+ "check_permission",+ new=engine,+ ):+ await agent._check_permission( # pylint: disable=protected-access+ tool_call,+ tool,+ tool_input,+ )++ self.assertEqual(tool_call.input, '{"value": "original"}')+ self.assertEqual(tool_input, {"value": "original"})+ self.assertIs(seen_by_inner[0], forwarded_input)+ engine.assert_awaited_once_with(tool, forwarded_input)++ async def test_on_check_permission_exception_propagates(self) -> None:+ """Permission middleware failures propagate to the caller."""++ class FailingMiddleware(MiddlewareBase):+ """Raise before delegating permission checking."""++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ raise RuntimeError("policy service unavailable")++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ middlewares=[FailingMiddleware()],+ )+ engine = AsyncMock()+ with patch.object(+ agent._engine, # pylint: disable=protected-access+ "check_permission",+ new=engine,+ ):+ with self.assertRaisesRegex(+ RuntimeError,+ "policy service unavailable",+ ):+ await agent._check_permission(+ ToolCallBlock(+ id="call_permission",+ name="tool",+ input="{}",+ ),+ AsyncMock(spec=ToolBase),+ {},+ )++ engine.assert_not_awaited()++ async def test_execute_tool_call_consumes_short_circuit_decision(+ self,+ ) -> None:+ """The tool lifecycle consumes the middleware's returned decision."""++ executed: list[bool] = []++ class PermissionTool(ToolBase):+ """Tool that records whether its body was reached."""++ name = "permission_tool"+ description = "A tool used by permission middleware tests."+ input_schema = {"type": "object", "properties": {}}+ is_concurrency_safe = True+ is_read_only = False++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ raise AssertionError("the engine should be short-circuited")++ async def call(self) -> ToolChunk:+ executed.append(True)+ return ToolChunk(content=[TextBlock(text="executed")])++ class DenyMiddleware(MiddlewareBase):+ """Deny the call before the built-in engine runs."""++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ return PermissionDecision(+ behavior=PermissionBehavior.DENY,+ message="denied by application policy",+ )++ tool = PermissionTool()+ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=Toolkit(tools=[tool]),+ middlewares=[DenyMiddleware()],+ )+ events = [+ event+ async for event in agent._execute_tool_call(+ ToolCallBlock(+ id="call_permission",+ name=tool.name,+ input="{}",+ ),+ )+ ]++ self.assertTrue(events)+ self.assertListEqual(executed, [])++ async def test_confirmed_tool_call_runs_hook_without_rechecking_engine(+ self,+ ) -> None:+ """Application policy can override a user-confirmed ALLOW."""++ executed: list[bool] = []++ class PermissionTool(ToolBase):+ """Minimal allowed tool for the confirmation-resume path."""++ name = "permission_tool"+ description = "A tool used by permission middleware tests."+ input_schema = {"type": "object", "properties": {}}+ is_concurrency_safe = True+ is_read_only = False++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ """The confirmed path must skip this method."""+ raise AssertionError("permission should not be rechecked")++ async def call(self) -> ToolChunk:+ executed.append(True)+ return ToolChunk(content=[TextBlock(text="executed")])++ class ObserveMiddleware(MiddlewareBase):+ """Record the confirmed decision returned by the inner handler."""++ async def on_check_permission(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[PermissionDecision]],+ ) -> PermissionDecision:+ decision = await next_handler(**input_kwargs)+ self_outer.execution_log.append(decision.behavior.value)+ return PermissionDecision(+ behavior=PermissionBehavior.DENY,+ message="application policy changed while awaiting user",+ )++ self_outer = self+ tool = PermissionTool()+ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=Toolkit(tools=[tool]),+ middlewares=[ObserveMiddleware()],+ )+ tool_call = ToolCallBlock(+ id="call_permission",+ name=tool.name,+ input="{}",+ state=ToolCallState.ALLOWED,+ )++ events = [+ event+ async for event in agent._execute_tool_call(+ tool_call,+ )+ ]++ self.assertTrue(events)+ self.assertListEqual(self.execution_log, ["allow"])+ self.assertListEqual(executed, [])++ async def asyncTearDown(self) -> None:+ """Clean up test fixtures."""+ self.execution_log.clear()