Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
fix(agent): hint after repeated tool errors (#1816)
Yufeng Hee8937a931a0d
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex 06ef01479..319b67717 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -2,6 +2,7 @@"""The unified agent class in AgentScope library."""import asyncioimport collections+import jsonimport inspectimport reimport warnings@@ -1194,6 +1195,65 @@ class Agent:finished_reason=ReplyFinishedReason.INTERRUPTED,)+ def _get_repeated_tool_error(self) -> tuple[str, int] | None:+ """Detect the same tool call, i.e. the same tool name and arguments,+ failing in the trailing consecutive tool results.++ Returns:+ `tuple[str, int] | None`:+ The tool name and the number of consecutive failures when it+ reaches ``injection_config.tool_retries_limit``, or ``None``+ when there is no such streak.+ """+ last_msg = self._get_last_msg()+ if last_msg is None:+ return None++ # The agent is only stuck when the latest tool call fails+ results = last_msg.get_content_blocks("tool_result")+ if not results or results[-1].state != ToolResultState.ERROR:+ return None++ # The trailing results that failed on the same tool, latest first+ tool_name = results[-1].name+ streak = []+ for result in reversed(results):+ if (+ result.state != ToolResultState.ERROR+ or result.name != tool_name+ ):+ break+ streak.append(result.id)++ limit = self.injection_config.tool_retries_limit+ if len(streak) < limit:+ return None++ # The same tool isn't enough, the arguments must repeat as well. They+ # live in the tool call blocks, normalized so that the same arguments+ # in a different key order still match, while invalid JSON, e.g.+ # truncated by the model, is compared as-is.+ inputs = {+ _.id: _.input for _ in last_msg.get_content_blocks("tool_call")+ }+ arguments = []+ for block_id in streak:+ raw = inputs.get(block_id, "")+ try:+ arguments.append(json.dumps(json.loads(raw), sort_keys=True))+ except (TypeError, ValueError):+ arguments.append(raw.strip())++ count = 0+ for value in arguments:+ if value != arguments[0]:+ break+ count += 1++ if count < limit:+ return None+ return tool_name, count+async def _inject_runtime_state(self,) -> AsyncGenerator[HintBlockEvent, None]:@@ -1229,6 +1289,10 @@ class Agent:``injection_config.context_buffer_ratio`` of the compressionthreshold, letting the agent perceive that a compression is near.This dimension is evaluated independently of the two above.+ - **Tool error**: injected when the same tool call, i.e. the same tool+ name and arguments, has failed in the last+ ``injection_config.tool_retries_limit`` consecutive tool results, so+ that the agent stops retrying a call that keeps failing.The user defined ``injection_config.extra_fields`` are attached toevery injection, but never trigger one by themselves.@@ -1409,6 +1473,20 @@ class Agent:f"your context will be compressed.")+ # =====================================================================+ # Step 5: Check Repeated Tool Errors+ # =====================================================================+ # The agent keeps retrying the same failing call, so remind it to try+ # something else+ repeated_error = self._get_repeated_tool_error()+ if repeated_error is not None:+ tool_name, count = repeated_error+ template = self.injection_config.tool_retries_hint+ injections["tool-error"] = template.replace(+ "{tool_name}",+ tool_name,+ ).replace("{count}", str(count))+if injections:# The user defined fields, which don't trigger an injection by# themselvesdiff --git a/src/agentscope/agent/_config.py b/src/agentscope/agent/_config.pyindex 666c17e2a..384a3f60e 100644--- a/src/agentscope/agent/_config.py+++ b/src/agentscope/agent/_config.py@@ -220,6 +220,34 @@ class InjectionConfig(BaseModel):of 0.8 and a buffer of 0.2, the context length is injected once the inputtokens exceed 60% of the model context size."""+ tool_retries_limit: int = Field(+ title="Tool Retries Limit",+ default=3,+ ge=3,+ description=(+ "The number of consecutive failures of the same tool call that "+ "triggers the tool error injection."+ ),+ )+ """The number of consecutive failures of the same tool call, i.e. the same+ tool name and arguments, that triggers the tool error injection."""++ tool_retries_hint: str = Field(+ title="Tool Retries Hint",+ default=(+ "The last {count} calls to '{tool_name}' with the same arguments "+ "all failed. Stop retrying the same call as-is, check the error "+ "message and try a different approach."+ ),+ description=(+ "The hint injected when the same tool call keeps failing, where "+ "the '{tool_name}' and '{count}' placeholders will be replaced "+ "by the failing tool name and the number of consecutive failures."+ ),+ )+ """The hint injected when the same tool call keeps failing, which supports+ the ``{tool_name}`` and ``{count}`` placeholders."""+template: str = Field(title="Template",default="""<system-reminder>Treat the following as the ground truth \diff --git a/tests/agent_injection_test.py b/tests/agent_injection_test.pyindex 79764f912..3ae462eec 100644--- a/tests/agent_injection_test.py+++ b/tests/agent_injection_test.py@@ -10,7 +10,12 @@ from pydantic import ValidationErrorfrom utils import AnyString, MockModelfrom agentscope.agent import Agent, InjectionConfig-from agentscope.message import HintBlock+from agentscope.message import (+ HintBlock,+ ToolCallBlock,+ ToolResultBlock,+ ToolResultState,+)from agentscope.state import Taskfrom agentscope.tool import Toolkit@@ -53,6 +58,7 @@ class AgentInjectionTest(IsolatedAsyncioTestCase):)self.agent.state.reply_id = "reply-1"self.agent.state.cur_iter = 0+ self._batch_index = 0# Freeze the wall-clock time for all the test casespatcher = patch("agentscope.agent._agent.datetime", _FrozenDatetime)@@ -84,6 +90,26 @@ class AgentInjectionTest(IsolatedAsyncioTestCase):],)+ def _add_tool_batch(+ self,+ *calls: tuple[str, str, ToolResultState],+ ) -> None:+ """Append one reasoning-acting iteration to the context, where each+ call is a ``(tool name, arguments, result state)`` triple."""+ self._batch_index += 1+ ids = [f"tc-{self._batch_index}-{_}" for _ in range(len(calls))]+ self.agent.state.append_context(+ self.agent.name,+ [+ ToolCallBlock(id=id_, name=name, input=arguments)+ for id_, (name, arguments, _) in zip(ids, calls)+ ]+ + [+ ToolResultBlock(id=id_, name=name, output="boom", state=state)+ for id_, (name, _, state) in zip(ids, calls)+ ],+ )+@staticmethoddef _expected_event(hint: str, reply_id: str = "reply-1") -> dict:"""Build the expected ``HintBlockEvent`` dump for the given hint."""@@ -360,6 +386,114 @@ class AgentInjectionTest(IsolatedAsyncioTestCase):[evt.model_dump() for evt in events],)+ async def test_repeated_tool_errors_trigger_injection(self) -> None:+ """The same tool call failing in consecutive iterations should trigger+ a tool-error injection."""+ expected_hint = (+ "<system-reminder>Treat the following as the ground truth at this "+ "point of the conversation. Anything stated earlier is outdated, "+ "and a later reminder, if any, supersedes this one:\n"+ "<tool-error>The last 3 calls to 'read' with the same arguments "+ "all failed. Stop retrying the same call as-is, check the error "+ "message and try a different approach.</tool-error>\n"+ "</system-reminder>"+ )+ self.agent.state.cur_iter = 1+ # A recent injection so the time branch is not triggered.+ self._add_injection("2026-07-01T12:00:00")++ # Two failures are still below the default threshold of three.+ self._add_tool_batch(+ ("read", '{"path": "a.py"}', ToolResultState.ERROR),+ )+ self._add_tool_batch(+ ("read", '{"path": "a.py"}', ToolResultState.ERROR),+ )+ self.assertEqual([], await self._run_injection())++ self._add_tool_batch(+ ("read", '{"path": "a.py"}', ToolResultState.ERROR),+ )+ self.assertEqual(+ [self._expected_event(expected_hint)],+ [evt.model_dump() for evt in await self._run_injection()],+ )++ async def test_arguments_are_normalized(self) -> None:+ """Semantically equal arguments should count as the same call, while+ different ones break the streak."""+ expected_hint = (+ "<system-reminder>Treat the following as the ground truth at this "+ "point of the conversation. Anything stated earlier is outdated, "+ "and a later reminder, if any, supersedes this one:\n"+ "<tool-error>The last 3 calls to 'read' with the same arguments "+ "all failed. Stop retrying the same call as-is, check the error "+ "message and try a different approach.</tool-error>\n"+ "</system-reminder>"+ )+ self.agent.state.cur_iter = 1+ self._add_injection("2026-07-01T12:00:00")++ # Different arguments, which the streak below shouldn't count in.+ self._add_tool_batch(+ ("read", '{"path": "other.py"}', ToolResultState.ERROR),+ )+ # The same arguments in a different key order and spacing.+ self._add_tool_batch(+ ("read", '{"a": 1, "b": 2}', ToolResultState.ERROR),+ )+ self._add_tool_batch(("read", '{"b":2,"a":1}', ToolResultState.ERROR))+ self.assertEqual([], await self._run_injection())++ self._add_tool_batch(+ ("read", '{"a": 1, "b": 2}', ToolResultState.ERROR),+ )+ self.assertEqual(+ [self._expected_event(expected_hint)],+ [evt.model_dump() for evt in await self._run_injection()],+ )++ async def test_fan_out_errors_do_not_trigger_injection(self) -> None:+ """Failing calls with different arguments are not retries, even when+ they repeat across iterations."""+ self.agent.state.cur_iter = 1+ self._add_injection("2026-07-01T12:00:00")++ for _ in range(3):+ self._add_tool_batch(+ ("read", '{"path": "a.py"}', ToolResultState.ERROR),+ ("read", '{"path": "b.py"}', ToolResultState.ERROR),+ )++ self.assertEqual([], await self._run_injection())++ async def test_interleaved_results_break_the_streak(self) -> None:+ """The streak is counted over the trailing tool results, so another+ tool succeeding in between breaks it."""+ self.agent.state.cur_iter = 1+ self._add_injection("2026-07-01T12:00:00")++ for _ in range(3):+ self._add_tool_batch(+ ("read", '{"path": "a.py"}', ToolResultState.ERROR),+ ("TaskUpdate", "{}", ToolResultState.SUCCESS),+ )++ self.assertEqual([], await self._run_injection())++ async def test_non_error_results_break_the_streak(self) -> None:+ """Only the ``ERROR`` state counts, so denied or successful results+ break the streak."""+ self.agent.state.cur_iter = 1+ self._add_injection("2026-07-01T12:00:00")++ self._add_tool_batch(("read", "{}", ToolResultState.ERROR))+ self._add_tool_batch(("read", "{}", ToolResultState.DENIED))+ self._add_tool_batch(("read", "{}", ToolResultState.ERROR))+ self._add_tool_batch(("read", "{}", ToolResultState.ERROR))++ self.assertEqual([], await self._run_injection())+async def test_invalid_timezone_falls_back_to_utc(self) -> None:"""An unresolvable timezone shouldn't break the reply loop."""expected_hint = (