Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
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.pyindex 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 andenqueues 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.pyindex 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(