Skip to content

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

feat(app): mark offloaded tool placeholders with structured metadata (#3853)

konlue72911f830e9b
diff --git a/src/agentscope/app/middleware/_tool_offload_middleware.py b/src/agentscope/app/middleware/_tool_offload_middleware.py
index 5811ccaa7..3c1d48bb1 100644
--- a/src/agentscope/app/middleware/_tool_offload_middleware.py
+++ b/src/agentscope/app/middleware/_tool_offload_middleware.py
@@ -6,7 +6,10 @@ When a tool times out, this middleware:
- Lets the underlying asyncio task keep running via
:class:`BackgroundTaskManager` (the task is **never cancelled**).
- Yields a synthetic placeholder :class:`ToolResponse` so the agent
- loop unblocks immediately.
+ loop unblocks immediately. The placeholder carries structured
+ metadata (``background_task_id`` / ``tool_name`` / ``tool_state`` /
+ ``offloaded_at``) so downstream consumers can distinguish it from a
+ real tool success without parsing the placeholder text.
- On task completion, pushes the real result as a
:class:`HintBlock` to the session's inbox via the message bus and
enqueues a wakeup. From there the result follows the same path as a
@@ -461,13 +464,23 @@ any tool, which ends the current reasoning loop — just do nothing and end \
this run.
</system-reminder>"""
+ # Identify background placeholders without parsing their text.
+ offload_metadata = {
+ "background_task_id": task_id,
+ "tool_name": tool_name,
+ "tool_state": "running",
+ "offloaded_at": time.time(),
+ }
+
yield ToolChunk(
content=[TextBlock(text=placeholder_text)],
state=ToolResultState.SUCCESS,
+ metadata=dict(offload_metadata),
)
yield ToolResponse(
content=[TextBlock(text=placeholder_text)],
state=ToolResultState.SUCCESS,
id=tool_call.id,
+ metadata=dict(offload_metadata),
)
diff --git a/tests/tool_offload_middleware_test.py b/tests/tool_offload_middleware_test.py
index 3a0aa2242..5d04577bc 100644
--- a/tests/tool_offload_middleware_test.py
+++ b/tests/tool_offload_middleware_test.py
@@ -345,38 +345,49 @@ class ToolOffloadMiddlewareTest(IsolatedAsyncioTestCase):
input=json.dumps({"delay": 0.5}),
)
- results: list = []
- # pylint: disable=protected-access
- async for item in agent._acting(tool_call):
- results.append(item)
+ offloaded_at = 1794240000.0
+ with patch(
+ "agentscope.app.middleware._tool_offload_middleware.time",
+ ) as mock_time:
+ mock_time.time.return_value = offloaded_at
+ results = [item async for item in agent._acting(tool_call)]
- # Should yield a synthetic ToolResponse immediately
- responses = [r for r in results if isinstance(r, ToolResponse)]
- self.assertEqual(len(responses), 1)
- self.assertDictEqual(
- responses[0].model_dump(),
- {
- "content": [
- {
- "type": "text",
- "text": AnyString(),
- "id": AnyString(),
- "created_at": AnyString(),
- "finished_at": None,
- },
- ],
- "state": "success",
- "metadata": {},
- "id": "call_slow",
+ self.assertEqual(len(self.bg_manager.tasks), 1)
+ task_id = next(iter(self.bg_manager.tasks))
+ expected_response = {
+ "content": [
+ {
+ "type": "text",
+ "text": AnyString(),
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "finished_at": None,
+ },
+ ],
+ "state": "success",
+ "metadata": {
+ "background_task_id": task_id,
+ "tool_name": "slow_tool",
+ "tool_state": "running",
+ "offloaded_at": offloaded_at,
},
+ "id": "call_slow",
+ }
+ self.assertEqual(
+ [item.model_dump() for item in results],
+ [
+ {
+ **expected_response,
+ "id": AnyString(),
+ "is_last": True,
+ },
+ expected_response,
+ ],
)
- text = responses[0].content[0].text # type: ignore[union-attr]
+ text = results[1].content[0].text # type: ignore[union-attr]
self.assertIn("background", text)
self.assertIn("id=", text)
- # Background task should be registered
- self.assertEqual(len(self.bg_manager.tasks), 1)
-
async def test_execution_start_is_captured_before_offload(self) -> None:
"""Capture execution start before the handler changes the clock."""
agent, middleware = self._make_agent(