Skip to content

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

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.py
index dd8331b88..fa3c7c09a 100644
--- a/src/agentscope/agent/_agent.py
+++ b/src/agentscope/agent/_agent.py
@@ -4,6 +4,7 @@ import asyncio
import collections
import inspect
import re
+import warnings
from asyncio import Queue
from 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 cannot
check 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 item
async def _close_unfinished_tool_calls(
self,
@@ -756,7 +770,7 @@ class Agent:
),
)
- async def _reply_impl(
+ async def _reply_impl( # pylint: disable=too-many-branches
self,
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 = True
while 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
+ continue
case Reasoning(hint=hint, tool_choice=tool_choice):
+ made_progress = True
final_msg = None
if hint:
self.state.append_context(self.name, [hint])
@@ -916,6 +956,7 @@ class Agent:
return
case Acting(tool_calls=tool_calls):
+ made_progress = True
for 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.py
index 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 ReplyFinishedReason
if 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.py
index cc2eae1fe..ddf68d023 100644
--- a/src/agentscope/console/_renderer.py
+++ b/src/agentscope/console/_renderer.py
@@ -10,7 +10,6 @@ from rich.text import Text
from ..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.py
index 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.py
index 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 middleware
input_kwargs: Dictionary containing:
diff --git a/tests/agui_protocol_test.py b/tests/agui_protocol_test.py
index 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.py
index 26b008537..8f261cb4f 100644
--- a/tests/middleware_test.py
+++ b/tests/middleware_test.py
@@ -5,9 +5,9 @@ from unittest.async_case import IsolatedAsyncioTestCase
from unittest.mock import AsyncMock, patch
from typing import Any, AsyncGenerator, Awaitable, Callable, Union
-from utils import MockModel
+from utils import AnyString, MockModel
from pydantic import BaseModel
-from agentscope.event import AgentEvent
+from agentscope.event import AgentEvent, ReplyEndEvent
from agentscope.agent import Agent, ContextConfig, InjectionConfig
from agentscope.middleware import MiddlewareBase
from 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."""