Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(agent): let on_reply middlewares swallow ReplyEndEvent to continue the reply loop (#2322)
DavdGao66ddaad8ec66
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex dd8331b88..fa3c7c09a 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -4,6 +4,7 @@ import asyncioimport collectionsimport inspectimport re+import warningsfrom asyncio import Queuefrom copy import deepcopy@@ -211,6 +212,10 @@ class Agent:_ for _ in middlewares if _.is_implemented("on_compress_context")]+ # Set when a `ReplyEndEvent` escapes the reply middleware chain; the+ # reply loop only exits after the event is delivered (not swallowed)+ self._receive_reply_end: bool = False+def _validate_configs(self) -> None:"""Validate the config combinations that a single config class cannotcheck by itself.@@ -640,13 +645,15 @@ class Agent:| None = None,structured_schema: Type[BaseModel] | None = None,) -> AsyncGenerator[AgentEvent | Msg, None]:- """Reply entry point (maybe wrapped by middleware)."""+ """Reply entry point (maybe wrapped by middleware). The reply loop+ exits only after its ``ReplyEndEvent`` escapes the middleware chain,+ so an ``on_reply`` middleware can swallow the event (receive it+ without yielding) to force another reasoning-acting round."""if not self._reply_middlewares:- async for item in self._reply_impl(+ agen = self._reply_impl(inputs=inputs,structured_schema=structured_schema,- ):- yield item+ )else:async def execute_chain(@@ -688,8 +695,15 @@ class Agent:):yield item- async for item in execute_chain():- yield item+ agen = execute_chain()++ self._receive_reply_end = False+ async for item in agen:+ # Set before the yield: the suspended `_reply_impl` checks the+ # flag once resumed by the next pull+ if isinstance(item, ReplyEndEvent):+ self._receive_reply_end = True+ yield itemasync def _close_unfinished_tool_calls(self,@@ -756,7 +770,7 @@ class Agent:),)- async def _reply_impl(+ async def _reply_impl( # pylint: disable=too-many-branchesself,inputs: Msg| list[Msg]@@ -860,6 +874,9 @@ class Agent:# or no more tool calls to execute# =================================================================final_msg: Msg | None = None+ # Detects middlewares swallowing the ReplyEndEvent repeatedly+ # without any reasoning/acting in between (a busy loop)+ made_progress = Truewhile True:# =============================================================# Step 3.1: Decide the next action based on the current state@@ -868,13 +885,36 @@ class Agent:match next_action:case Exit(exit_msg=exit_msg, exit_events=exit_events):- for exit_event in exit_events or []:+ if not exit_events:+ # Parked on HITL: the reply is not finished, so+ # the continuation protocol doesn't apply+ yield exit_msg+ return++ for exit_event in exit_events:yield exit_event- if exit_msg:++ # Exit unless a middleware swallowed the ReplyEndEvent+ # to force another reasoning-acting round+ if self._receive_reply_end:yield exit_msg- return+ return++ if not made_progress:+ raise RuntimeError(+ "A middleware swallowed the ReplyEndEvent "+ "twice without any reasoning/acting in "+ "between. Unblock the next round (e.g. "+ "adjust 'cur_iter', 'max_iters' or the "+ "structured output state) before swallowing "+ "the event again.",+ )+ made_progress = False+ final_msg = None+ continuecase Reasoning(hint=hint, tool_choice=tool_choice):+ made_progress = Truefinal_msg = Noneif hint:self.state.append_context(self.name, [hint])@@ -916,6 +956,7 @@ class Agent:returncase Acting(tool_calls=tool_calls):+ made_progress = Truefor batch in await self._batch_tool_calls(tool_calls):if batch.type == "sequential":evt_generator = (@@ -3141,12 +3182,17 @@ class Agent:>= self.react_config.max_iters+ self.react_config.structured_output_grace_iters):+ # Deprecated but still emitted for backward compatibility;+ # suppressed since the warning targets consumers+ with warnings.catch_warnings():+ warnings.simplefilter("ignore", DeprecationWarning)+ exceed_event = ExceedMaxItersEvent(+ reply_id=self.state.reply_id,+ name=self.name,+ )return Exit(exit_events=[- ExceedMaxItersEvent(- reply_id=self.state.reply_id,- name=self.name,- ),+ exceed_event,ReplyEndEvent(session_id=self.state.session_id,reply_id=self.state.reply_id,@@ -3220,12 +3266,17 @@ class Agent:self.react_config.max_iters,)+ # Deprecated but still emitted for backward compatibility;+ # suppressed since the warning targets consumers+ with warnings.catch_warnings():+ warnings.simplefilter("ignore", DeprecationWarning)+ exceed_event = ExceedMaxItersEvent(+ reply_id=self.state.reply_id,+ name=self.name,+ )return Exit(exit_events=[- ExceedMaxItersEvent(- reply_id=self.state.reply_id,- name=self.name,- ),+ exceed_event,ReplyEndEvent(session_id=self.state.session_id,reply_id=self.state.reply_id,diff --git a/src/agentscope/app/middleware/_protocol/_agui.py b/src/agentscope/app/middleware/_protocol/_agui.pyindex 48730ca5f..361790e39 100644--- a/src/agentscope/app/middleware/_protocol/_agui.py+++ b/src/agentscope/app/middleware/_protocol/_agui.py@@ -33,6 +33,7 @@ from ....event import (ToolResultTextDeltaEvent,UserConfirmResultEvent,)+from ....types import ReplyFinishedReasonif TYPE_CHECKING:from ag_ui.core.events import BaseEvent as AGUIBaseEvent@@ -99,15 +100,23 @@ class AGUIProtocolMiddleware(ProtocolMiddlewareBase):)if isinstance(event, ReplyEndEvent):+ if event.finished_reason == ReplyFinishedReason.EXCEED_MAX_ITERS:+ return AGUIRunErrorEvent(+ message="The agent exceeded the maximum reasoning-acting "+ "iterations",+ code="exceed_max_iters",+ )return AGUIRunFinishedEvent(thread_id=event.session_id,run_id=event.reply_id,)if isinstance(event, ExceedMaxItersEvent):- return AGUIRunErrorEvent(- message=(f"Agent '{event.name}' exceeded max iterations"),- code="exceed_max_iters",+ # Deprecated event, still emitted for backward compatibility;+ # the RUN_ERROR semantics now come from the ReplyEndEvent+ return AGUICustomEvent(+ name="exceed_max_iters",+ value=event.model_dump(exclude_none=True),)if isinstance(event, ModelCallStartEvent):diff --git a/src/agentscope/console/_renderer.py b/src/agentscope/console/_renderer.pyindex cc2eae1fe..ddf68d023 100644--- a/src/agentscope/console/_renderer.py+++ b/src/agentscope/console/_renderer.py@@ -10,7 +10,6 @@ from rich.text import Textfrom ..event import (AgentEvent,DataBlockEndEvent,- ExceedMaxItersEvent,HintBlockEvent,ModelCallEndEvent,ModelCallStartEvent,@@ -177,13 +176,6 @@ class ConsoleRenderer:event.tool_calls,"Tool calls awaiting external execution:",)- elif isinstance(event, ExceedMaxItersEvent):- if self._show(1):- self._break_line()- self.console.print(- "⚠ Exceeded the maximum reasoning-acting iterations.",- style="yellow",- )elif isinstance(event, ReplyEndEvent):self._render_reply_end(event)else:@@ -422,4 +414,14 @@ class ConsoleRenderer:self.console.print(Text("⚠ Reply interrupted by the user.", style="yellow"),)+ elif (+ event.finished_reason == ReplyFinishedReason.EXCEED_MAX_ITERS+ and self._show(1)+ ):+ self.console.print(+ Text(+ "⚠ Exceeded the maximum reasoning-acting iterations.",+ style="yellow",+ ),+ )self._debug_line(f"reply end · {event.finished_reason}")diff --git a/src/agentscope/event/_event.py b/src/agentscope/event/_event.pyindex 68ee5e189..ad2e65465 100644--- a/src/agentscope/event/_event.py+++ b/src/agentscope/event/_event.py@@ -394,8 +394,14 @@ class ToolResultEndEvent(EventBase):"""Optional metadata attached to the tool result event."""+@deprecated(+ "ExceedMaxItersEvent is deprecated and will be removed; check the "+ "'finished_reason' field of ReplyEndEvent against "+ "ReplyFinishedReason.EXCEED_MAX_ITERS instead.",+)class ExceedMaxItersEvent(EventBase):- """Exceeded max iteration event."""+ """Deprecated exceeded max iteration event, still emitted for backward+ compatibility without semantics; use ``ReplyEndEvent.finished_reason``."""type: Literal[EventType.EXCEED_MAX_ITERS] = EventType.EXCEED_MAX_ITERS"""Event type."""diff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.pyindex 33eae7082..e2c999e59 100644--- a/src/agentscope/middleware/_base.py+++ b/src/agentscope/middleware/_base.py@@ -73,6 +73,13 @@ class MiddlewareBase: # pylint: disable=unused-argument) -> AsyncGenerator:"""Hook for intercepting the reply process.+ Swallowing a completed reply's ``ReplyEndEvent`` (receiving it+ without yielding) forces another reasoning-acting round; the final+ ``Msg`` is only produced once the event escapes the whole chain.+ When swallowing an exceed-max-iters end, unblock the next round+ first (e.g. adjust ``cur_iter`` or ``max_iters``). Interrupted+ ends cannot be swallowed to continue the reply.+Args:agent: The Agent instance executing this middlewareinput_kwargs: Dictionary containing:diff --git a/tests/agui_protocol_test.py b/tests/agui_protocol_test.pyindex f706c8972..c574edd07 100644--- a/tests/agui_protocol_test.py+++ b/tests/agui_protocol_test.py@@ -223,17 +223,28 @@ class AGUIProtocolLifecycleTest(IsolatedAsyncioTestCase):self.assertEqual(result["runId"], "reply_1")async def test_exceed_max_iters_to_run_error(self) -> None:- """Test ExceedMaxItersEvent -> RUN_ERROR."""- event = ExceedMaxItersEvent(+ """Test ReplyEndEvent with EXCEED_MAX_ITERS -> RUN_ERROR."""+ event = ReplyEndEvent(+ session_id="sess_1",reply_id="reply_1",- name="my_agent",+ finished_reason=ReplyFinishedReason.EXCEED_MAX_ITERS,)result = self.mw._convert_to_protocol(event)self.assertEqual(result["type"], "RUN_ERROR")- self.assertIn("my_agent", result["message"])self.assertEqual(result["code"], "exceed_max_iters")+ async def test_deprecated_exceed_max_iters_to_custom(self) -> None:+ """Test the deprecated ExceedMaxItersEvent -> CUSTOM."""+ event = ExceedMaxItersEvent(+ reply_id="reply_1",+ name="my_agent",+ )+ result = self.mw._convert_to_protocol(event)++ self.assertEqual(result["type"], "CUSTOM")+ self.assertEqual(result["name"], "exceed_max_iters")+async def asyncTearDown(self) -> None:"""The async teardown method."""diff --git a/tests/middleware_test.py b/tests/middleware_test.pyindex 26b008537..8f261cb4f 100644--- a/tests/middleware_test.py+++ b/tests/middleware_test.py@@ -5,9 +5,9 @@ from unittest.async_case import IsolatedAsyncioTestCasefrom unittest.mock import AsyncMock, patchfrom typing import Any, AsyncGenerator, Awaitable, Callable, Union-from utils import MockModel+from utils import AnyString, MockModelfrom pydantic import BaseModel-from agentscope.event import AgentEvent+from agentscope.event import AgentEvent, ReplyEndEventfrom agentscope.agent import Agent, ContextConfig, InjectionConfigfrom agentscope.middleware import MiddlewareBasefrom agentscope.model import ChatResponse@@ -122,6 +122,117 @@ class TestMiddleware(IsolatedAsyncioTestCase):]self.assertListEqual(self.execution_log, expected)+ async def test_on_reply_middleware_swallow_reply_end(self) -> None:+ """Test swallowing the ReplyEndEvent forces another reasoning+ round within the same reply."""++ class SwallowOnceMiddleware(MiddlewareBase):+ """Middleware swallowing the first ReplyEndEvent."""++ def __init__(self) -> None:+ self.swallowed = False++ async def on_reply(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[[], AsyncGenerator],+ ) -> AsyncGenerator:+ """Swallow the first ReplyEndEvent, deliver the rest."""+ async for item in next_handler():+ if isinstance(item, ReplyEndEvent) and not self.swallowed:+ self.swallowed = True+ continue+ yield item++ self.mock_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="first answer")],+ is_last=True,+ ),+ ChatResponse(+ content=[TextBlock(text="second answer")],+ is_last=True,+ ),+ ],+ )++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ middlewares=[SwallowOnceMiddleware()],+ injection_config=InjectionConfig(inject_runtime_state=False),+ )++ events, final_msg = [], None+ async for item in agent.reply_stream(+ UserMsg("user", "test message"),+ yield_final_msg=True,+ ):+ if isinstance(item, Msg):+ final_msg = item+ else:+ events.append(item)++ # A single reply whose swallowed end forced a second reasoning round+ self.assertListEqual(+ [str(_.type) for _ in events],+ [+ "REPLY_START",+ "MODEL_CALL_START",+ "TEXT_BLOCK_START",+ "TEXT_BLOCK_DELTA",+ "TEXT_BLOCK_END",+ "MODEL_CALL_END",+ "MODEL_CALL_START",+ "TEXT_BLOCK_START",+ "TEXT_BLOCK_DELTA",+ "TEXT_BLOCK_END",+ "MODEL_CALL_END",+ "REPLY_END",+ ],+ )+ self.assertDictEqual(+ events[-1].model_dump(),+ {+ "id": AnyString(),+ "created_at": AnyString(),+ "metadata": {},+ "type": "REPLY_END",+ "session_id": agent.state.session_id,+ "reply_id": agent.state.reply_id,+ "finished_reason": "completed",+ "error": None,+ },+ )+ self.assertDictEqual(+ final_msg.model_dump(),+ {+ "id": agent.state.reply_id,+ "created_at": AnyString(),+ "finished_at": None,+ "finished_reason": "completed",+ "structured_output": None,+ "error": None,+ "metadata": {},+ "name": "test_agent",+ "role": "assistant",+ "usage": None,+ "content": [+ {+ "type": "text",+ "created_at": AnyString(),+ "finished_at": None,+ "id": AnyString(),+ "text": "second answer",+ },+ ],+ },+ )+async def test_on_reasoning_middleware_pre_yield(self) -> None:"""Test on_reasoning middleware pre and yield positions."""