Skip to content

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

fix(agent): hint after repeated tool errors (#1816)

Yufeng Hee8937a931a0d
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index 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 asyncio
import collections
+import json
import inspect
import re
import 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 compression
threshold, 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 to
every 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
# themselves
diff --git a/src/agentscope/agent/_config.py b/src/agentscope/agent/_config.py
index 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 input
tokens 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.py
index 79764f912..3ae462eec 100644
--- a/tests/agent_injection_test.py
+++ b/tests/agent_injection_test.py
@@ -10,7 +10,12 @@ from pydantic import ValidationError
from utils import AnyString, MockModel
from agentscope.agent import Agent, InjectionConfig
-from agentscope.message import HintBlock
+from agentscope.message import (
+ HintBlock,
+ ToolCallBlock,
+ ToolResultBlock,
+ ToolResultState,
+)
from agentscope.state import Task
from 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 cases
patcher = 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)
+ ],
+ )
+
@staticmethod
def _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 = (