Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(agent): stop repeated failed tool calls (#4334)

LuckVd4aefbe64cb6a
diff --git a/internal/agent/const.go b/internal/agent/const.go
index 881ee06f9..9a64ae0a4 100644
--- a/internal/agent/const.go
+++ b/internal/agent/const.go
@@ -70,6 +70,10 @@ const (
// rounds are the clearest stuck loop there is.
maxRepeatedResponseRounds = 2
+ // maxConsecutiveFailedToolCalls is the number of identical failed tool
+ // calls allowed before the model is asked to switch tools or strategies.
+ maxConsecutiveFailedToolCalls = 3
+
// maxConsecutiveLengthRounds is how many rounds in a row may be cut off at
// the completion-token cap before the loop gives up. A truncated answer
// already ends the turn (analyzeResponse Case 2), so reaching this limit
diff --git a/internal/agent/engine.go b/internal/agent/engine.go
index 2133fb85f..8694477fa 100644
--- a/internal/agent/engine.go
+++ b/internal/agent/engine.go
@@ -544,9 +544,8 @@ func (e *AgentEngine) withinIterationBudget(round int) bool {
}
// loopGuards is the per-turn state the ReAct loop uses to notice it is not
-// making progress. All three counters exist because a model can keep the loop
-// spinning without ever finishing: empty answers, the same answer repeated,
-// and rounds cut off at the completion-token cap.
+// making progress. The counters cover empty answers, repeated answers,
+// completion-token cutoffs, and identical failed tool calls.
type loopGuards struct {
// emptyRetries counts nudges sent after a stop with no content.
emptyRetries int
@@ -563,6 +562,48 @@ type loopGuards struct {
// consecutiveLength counts rounds in a row that the provider cut off at
// the completion-token cap.
consecutiveLength int
+ // failedToolCallSignature and consecutiveFailedToolCalls track identical
+ // failed calls across rounds. A single guidance message is sent per streak.
+ failedToolCallSignature string
+ consecutiveFailedToolCalls int
+ failedToolCallNudged bool
+}
+
+// recordFailedToolCall tracks consecutive failures of the same model-facing
+// tool name and arguments. A successful or different call breaks the streak.
+func (g *loopGuards) recordFailedToolCall(call types.ToolCall) (string, int, bool) {
+ if call.Result != nil && call.Result.Success {
+ g.resetFailedToolCallStreak()
+ return "", 0, false
+ }
+ if call.Name == "" {
+ g.resetFailedToolCallStreak()
+ return "", 0, false
+ }
+ args, err := json.Marshal(call.Args)
+ if err != nil {
+ g.resetFailedToolCallStreak()
+ return "", 0, false
+ }
+ signature := call.Name + "\x00" + string(args)
+ if signature != g.failedToolCallSignature {
+ g.failedToolCallSignature = signature
+ g.consecutiveFailedToolCalls = 1
+ g.failedToolCallNudged = false
+ } else {
+ g.consecutiveFailedToolCalls++
+ }
+ if g.consecutiveFailedToolCalls >= maxConsecutiveFailedToolCalls && !g.failedToolCallNudged {
+ g.failedToolCallNudged = true
+ return call.Name, g.consecutiveFailedToolCalls, true
+ }
+ return "", g.consecutiveFailedToolCalls, false
+}
+
+func (g *loopGuards) resetFailedToolCallStreak() {
+ g.failedToolCallSignature = ""
+ g.consecutiveFailedToolCalls = 0
+ g.failedToolCallNudged = false
}
// closeAnswerStream emits the Done:true marker for an answer that is actually
@@ -1018,6 +1059,7 @@ func (e *AgentEngine) runReActIteration(
// round, which used to land in the else branch and reset the counter, so
// the guard could never fire on the one shape that needs it most (#3446).
if len(response.ToolCalls) == 0 {
+ guards.resetFailedToolCallStreak()
if guards.sawPlainRound && response.Content == guards.lastResponseContent {
guards.consecutiveSameContent++
} else {
@@ -1328,9 +1370,31 @@ func (e *AgentEngine) runReActIteration(
toolCallCount = len(step.ToolCalls)
// 4. Observe: Add tool results to messages and write to context
+ var (
+ failedToolName string
+ failedToolAttempts int
+ )
+ for _, toolCall := range step.ToolCalls {
+ if name, attempts, shouldNudge := guards.recordFailedToolCall(toolCall); shouldNudge {
+ failedToolName = name
+ failedToolAttempts = attempts
+ }
+ }
+
state.RoundSteps = append(state.RoundSteps, step)
*messagesPtr = e.appendToolResults(*messagesPtr, step)
*messagesPtr = e.appendToolImages(ctx, *messagesPtr, step)
+ if failedToolName != "" {
+ logger.Warnf(ctx, "[Agent][Round-%d] Repeated failed call to %q (%d attempts); "+
+ "asking the model to change strategy", round, failedToolName, failedToolAttempts)
+ guidance := fmt.Sprintf(
+ "The tool %q has failed %d consecutive times with identical arguments. "+
+ "Do not call it again with those arguments. Switch to a different tool "+
+ "or use another approach to complete the task.",
+ failedToolName, failedToolAttempts,
+ )
+ *messagesPtr = append(*messagesPtr, chat.Message{Role: "user", Content: guidance})
+ }
common.PipelineInfo(ctx, "Agent", "round_end", map[string]interface{}{
"iteration": state.CurrentRound,
"round": round,
diff --git a/internal/agent/failed_tool_loop_test.go b/internal/agent/failed_tool_loop_test.go
new file mode 100644
index 000000000..fe50b182d
--- /dev/null
+++ b/internal/agent/failed_tool_loop_test.go
@@ -0,0 +1,75 @@
+package agent
+
+import (
+ "context"
+ "encoding/json"
+ "strings"
+ "testing"
+
+ agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+type alwaysFailingTool struct {
+ agenttools.BaseTool
+ calls int
+}
+
+func (t *alwaysFailingTool) Execute(context.Context, json.RawMessage) (*types.ToolResult, error) {
+ t.calls++
+ return &types.ToolResult{Success: false, Error: "browser unavailable"}, nil
+}
+
+func failedToolResponse(id string) mockResponse {
+ return mockResponse{chunks: []types.StreamResponse{{
+ ResponseType: types.ResponseTypeAnswer,
+ ToolCalls: []types.LLMToolCall{{
+ ID: id,
+ Type: "function",
+ Function: types.FunctionCall{
+ Name: "failing_browser",
+ Arguments: `{"url":"https://example.com"}`,
+ },
+ }},
+ Done: true,
+ FinishReason: "tool_calls",
+ }}}
+}
+
+func TestExecuteLoopPromptsForAlternativeAfterRepeatedFailedToolCall(t *testing.T) {
+ model := &mockChat{responses: []mockResponse{
+ failedToolResponse("call-1"),
+ failedToolResponse("call-2"),
+ failedToolResponse("call-3"),
+ {chunks: []types.StreamResponse{{
+ ResponseType: types.ResponseTypeAnswer,
+ Content: "I will try another approach.",
+ Done: true,
+ FinishReason: "stop",
+ }}},
+ }}
+ engine := newTestEngine(t, model)
+ tool := &alwaysFailingTool{BaseTool: agenttools.NewBaseTool(
+ "failing_browser", "always fails in this test", json.RawMessage(`{"type":"object"}`),
+ )}
+ engine.toolRegistry = agenttools.NewToolRegistry()
+ engine.toolRegistry.RegisterTool(tool)
+
+ state, err := engine.executeLoop(context.Background(), &types.AgentState{}, "visit the website",
+ emptyMessages(), emptyTools(), "session", "message")
+
+ require.NoError(t, err)
+ require.True(t, state.IsComplete)
+ require.Equal(t, 3, tool.calls, "identical failed calls must be bounded before trying again")
+ require.Len(t, model.calls, 4)
+
+ var retryGuidance strings.Builder
+ for _, message := range model.calls[3] {
+ if message.Role == "user" {
+ retryGuidance.WriteString(message.Content)
+ }
+ }
+ require.Contains(t, retryGuidance.String(), "Do not call it again with those arguments")
+ require.Contains(t, retryGuidance.String(), "Switch to a different tool or use another approach")
+}