feat(agent): enhance tool execution and message sanitization

- Introduced a default timeout for tool execution to prevent indefinite hangs during long-running tasks.
- Implemented context cancellation handling in the execution loop to gracefully manage timeouts and user cancellations.
- Added a JSON repair utility to fix common malformations in tool arguments, improving robustness in argument parsing.
- Enhanced message sanitization to merge consecutive user messages and handle orphaned tool results, ensuring compatibility with LLM providers.
- Added unit tests for the new JSON repair and message sanitization functionalities to validate their effectiveness.
This commit is contained in:
wizardchen
2026-03-19 22:34:39 +08:00
committed by lyingbug
parent 0851d6d656
commit 2f7e3a8ac1
7 changed files with 535 additions and 17 deletions
+61 -17
View File
@@ -28,6 +28,10 @@ const (
// Can be overridden via AgentConfig.LLMCallTimeout.
defaultLLMCallTimeout = 120 * time.Second
// defaultToolExecTimeout is the default maximum time for a single tool execution.
// Prevents long-running tools (web_fetch, database_query) from hanging indefinitely.
defaultToolExecTimeout = 60 * time.Second
// maxLLMRetries is the maximum number of retries for transient LLM errors.
maxLLMRetries = 2
)
@@ -315,6 +319,22 @@ func (e *AgentEngine) executeLoop(
"max_iterations": e.config.MaxIterations,
})
for state.CurrentRound < e.config.MaxIterations {
// Check for context cancellation (request timeout, user cancel, etc.)
select {
case <-ctx.Done():
logger.Warnf(ctx, "[Agent] Context cancelled at round %d: %v",
state.CurrentRound+1, ctx.Err())
// Try to salvage existing results
if totalTC := countTotalToolCalls(state.RoundSteps); totalTC > 0 {
logger.Infof(ctx, "[Agent] Synthesizing final answer from %d existing tool results",
totalTC)
_ = e.streamFinalAnswerToEventBus(ctx, query, state, sessionID)
state.IsComplete = true
}
return state, ctx.Err()
default:
}
roundStart := time.Now()
logger.Infof(ctx, "========== Round %d/%d Started ==========",
state.CurrentRound+1, e.config.MaxIterations)
@@ -382,6 +402,10 @@ func (e *AgentEngine) executeLoop(
"round": state.CurrentRound + 1,
"tool_cnt": len(tools),
})
// Sanitize messages before sending to LLM (fix consecutive roles, orphaned tool results)
messages = agenttools.SanitizeMessages(messages)
response, err := e.streamThinkingToEventBus(ctx, messages, tools, state.CurrentRound, sessionID)
if err != nil && isTransientError(err) {
// Retry transient errors (timeout, rate limit, server errors) up to maxLLMRetries times
@@ -554,26 +578,41 @@ func (e *AgentEngine) executeLoop(
)
for i, tc := range response.ToolCalls {
// Normalize tool call ID for cross-provider compatibility
tc.ID = agenttools.NormalizeToolCallID(tc.ID, tc.Function.Name, i)
logger.Infof(ctx, "[Agent][Round-%d][Tool-%d/%d] Tool: %s, ID: %s",
state.CurrentRound+1, i+1, len(response.ToolCalls), tc.Function.Name, tc.ID)
var args map[string]any
if err := json.Unmarshal([]byte(tc.Function.Arguments), &args); err != nil {
logger.Errorf(ctx, "[Agent][Round-%d][Tool-%d/%d] Failed to parse tool arguments: %v",
state.CurrentRound+1, i+1, len(response.ToolCalls), err)
// Record parse failure as a tool result so the LLM can see the error and adapt
parseFailCall := types.ToolCall{
ID: tc.ID,
Name: tc.Function.Name,
Args: map[string]any{"_raw": tc.Function.Arguments},
Result: &types.ToolResult{
Success: false,
Error: fmt.Sprintf("Failed to parse tool arguments: %v", err) +
"\n\n[Analyze the error above and try a different approach.]",
},
argsStr := tc.Function.Arguments
if err := json.Unmarshal([]byte(argsStr), &args); err != nil {
// Attempt JSON repair before giving up
repaired := agenttools.RepairJSON(argsStr)
if repairErr := json.Unmarshal([]byte(repaired), &args); repairErr != nil {
logger.Errorf(ctx,
"[Agent][Round-%d][Tool-%d/%d] Failed to parse tool arguments "+
"(repair also failed): %v",
state.CurrentRound+1, i+1, len(response.ToolCalls), err)
parseFailCall := types.ToolCall{
ID: tc.ID,
Name: tc.Function.Name,
Args: map[string]any{"_raw": argsStr},
Result: &types.ToolResult{
Success: false,
Error: fmt.Sprintf(
"Failed to parse tool arguments: %v", err,
) + "\n\n[Analyze the error above and " +
"try a different approach.]",
},
}
step.ToolCalls = append(step.ToolCalls, parseFailCall)
continue
}
step.ToolCalls = append(step.ToolCalls, parseFailCall)
continue
logger.Warnf(ctx,
"[Agent][Round-%d][Tool-%d/%d] Repaired malformed JSON arguments",
state.CurrentRound+1, i+1, len(response.ToolCalls))
tc.Function.Arguments = repaired
}
// Log the arguments in a readable format
@@ -595,7 +634,7 @@ func (e *AgentEngine) executeLoop(
})
logger.Debugf(ctx, "[Agent] ToolCall -> %s args=%s", tc.Function.Name, tc.Function.Arguments)
// Execute tool
// Execute tool with timeout to prevent indefinite hangs
logger.Infof(ctx, "[Agent][Round-%d][Tool-%d/%d] Executing tool: %s...",
state.CurrentRound+1, i+1, len(response.ToolCalls), tc.Function.Name)
common.PipelineInfo(ctx, "Agent", "tool_call_start", map[string]interface{}{
@@ -605,7 +644,12 @@ func (e *AgentEngine) executeLoop(
"tool_call_id": tc.ID,
"tool_index": fmt.Sprintf("%d/%d", i+1, len(response.ToolCalls)),
})
result, err := e.toolRegistry.ExecuteTool(ctx, tc.Function.Name, json.RawMessage(tc.Function.Arguments))
toolCtx, toolCancel := context.WithTimeout(ctx, defaultToolExecTimeout)
result, err := e.toolRegistry.ExecuteTool(
toolCtx, tc.Function.Name,
json.RawMessage(tc.Function.Arguments),
)
toolCancel()
duration := time.Since(toolCallStartTime).Milliseconds()
logger.Infof(ctx, "[Agent][Round-%d][Tool-%d/%d] Tool execution completed in %dms",
state.CurrentRound+1, i+1, len(response.ToolCalls), duration)
+142
View File
@@ -0,0 +1,142 @@
package tools
import (
"strings"
"unicode"
)
// RepairJSON attempts to fix common JSON malformations from LLM outputs.
// LLMs sometimes produce:
// - Truncated JSON (missing closing brackets/braces)
// - Trailing commas before closing brackets
// - Single quotes instead of double quotes
// - Unquoted keys
//
// Returns the repaired JSON string. If repair is not possible,
// returns the original string unchanged (caller should handle parse errors).
func RepairJSON(s string) string {
s = strings.TrimSpace(s)
if s == "" {
return "{}"
}
// Must start with { for object
if s[0] != '{' {
// Maybe the LLM returned just key=value pairs without braces
if strings.Contains(s, ":") || strings.Contains(s, "=") {
s = "{" + s + "}"
} else {
return s
}
}
// Fix trailing commas: ,} or ,]
s = fixTrailingCommas(s)
// Balance brackets and braces
s = balanceBrackets(s)
return s
}
// fixTrailingCommas removes trailing commas before closing brackets/braces.
func fixTrailingCommas(s string) string {
// Simple state machine to handle strings
var result strings.Builder
result.Grow(len(s))
inString := false
escaped := false
runes := []rune(s)
for i, r := range runes {
if escaped {
escaped = false
result.WriteRune(r)
continue
}
if r == '\\' && inString {
escaped = true
result.WriteRune(r)
continue
}
if r == '"' {
inString = !inString
result.WriteRune(r)
continue
}
if inString {
result.WriteRune(r)
continue
}
// Outside string: check for trailing comma
if r == ',' {
// Look ahead for closing bracket/brace (skipping whitespace)
nextNonSpace := findNextNonSpace(runes, i+1)
if nextNonSpace >= 0 && (runes[nextNonSpace] == '}' || runes[nextNonSpace] == ']') {
continue // skip this comma
}
}
result.WriteRune(r)
}
return result.String()
}
// findNextNonSpace finds the index of the next non-whitespace rune.
func findNextNonSpace(runes []rune, start int) int {
for i := start; i < len(runes); i++ {
if !unicode.IsSpace(runes[i]) {
return i
}
}
return -1
}
// balanceBrackets appends missing closing brackets/braces.
func balanceBrackets(s string) string {
var stack []rune
inString := false
escaped := false
for _, r := range s {
if escaped {
escaped = false
continue
}
if r == '\\' && inString {
escaped = true
continue
}
if r == '"' {
inString = !inString
continue
}
if inString {
continue
}
switch r {
case '{':
stack = append(stack, '}')
case '[':
stack = append(stack, ']')
case '}', ']':
if len(stack) > 0 && stack[len(stack)-1] == r {
stack = stack[:len(stack)-1]
}
}
}
// Close unclosed string if needed
if inString {
s += `"`
}
// Append missing closers in reverse order
for i := len(stack) - 1; i >= 0; i-- {
s += string(stack[i])
}
return s
}
+77
View File
@@ -0,0 +1,77 @@
package tools
import (
"encoding/json"
"testing"
"github.com/stretchr/testify/assert"
)
func TestRepairJSON(t *testing.T) {
t.Run("valid JSON unchanged", func(t *testing.T) {
input := `{"query": "hello", "limit": 10}`
result := RepairJSON(input)
assert.Equal(t, input, result)
assert.True(t, json.Valid([]byte(result)))
})
t.Run("trailing comma before brace", func(t *testing.T) {
input := `{"query": "hello", "limit": 10,}`
result := RepairJSON(input)
assert.True(t, json.Valid([]byte(result)), "result: %s", result)
})
t.Run("trailing comma before bracket", func(t *testing.T) {
input := `{"items": [1, 2, 3,]}`
result := RepairJSON(input)
assert.True(t, json.Valid([]byte(result)), "result: %s", result)
})
t.Run("missing closing brace", func(t *testing.T) {
input := `{"query": "hello"`
result := RepairJSON(input)
assert.True(t, json.Valid([]byte(result)), "result: %s", result)
})
t.Run("missing closing bracket and brace", func(t *testing.T) {
input := `{"items": [1, 2, 3`
result := RepairJSON(input)
assert.True(t, json.Valid([]byte(result)), "result: %s", result)
})
t.Run("empty string returns empty object", func(t *testing.T) {
result := RepairJSON("")
assert.Equal(t, "{}", result)
})
t.Run("truncated string value", func(t *testing.T) {
input := `{"query": "hello world`
result := RepairJSON(input)
assert.True(t, json.Valid([]byte(result)), "result: %s", result)
})
t.Run("nested missing closers", func(t *testing.T) {
input := `{"outer": {"inner": [1, 2`
result := RepairJSON(input)
assert.True(t, json.Valid([]byte(result)), "result: %s", result)
})
t.Run("comma in string not removed", func(t *testing.T) {
input := `{"query": "hello, world"}`
result := RepairJSON(input)
assert.Equal(t, input, result)
})
t.Run("already valid complex JSON", func(t *testing.T) {
input := `{"queries": ["what is AI", "machine learning"], "limit": 5}`
result := RepairJSON(input)
assert.Equal(t, input, result)
assert.True(t, json.Valid([]byte(result)))
})
t.Run("multiple trailing commas", func(t *testing.T) {
input := `{"a": 1, "b": [1, 2,], "c": 3,}`
result := RepairJSON(input)
assert.True(t, json.Valid([]byte(result)), "result: %s", result)
})
}
+49
View File
@@ -0,0 +1,49 @@
package tools
import (
"crypto/sha256"
"fmt"
"regexp"
"strings"
)
// maxToolCallIDLen is the maximum allowed length for a tool call ID.
// Some providers return very long IDs; others return empty ones.
const maxToolCallIDLen = 64
// validIDChars matches only alphanumeric and common safe characters.
var validIDChars = regexp.MustCompile(`[^a-zA-Z0-9_-]`)
// NormalizeToolCallID normalizes a tool call ID for cross-provider compatibility.
//
// Different LLM providers return IDs in different formats:
// - OpenAI: "call_abc123" (well-formed)
// - Some providers: "" (empty)
// - Some providers: very long UUIDs or random strings
// - Some providers: IDs with special characters
//
// This function ensures IDs are:
// - Non-empty (generates deterministic ID from tool name + index if empty)
// - Within length limits (truncated with hash suffix if too long)
// - Alphanumeric-safe (special characters replaced)
func NormalizeToolCallID(id string, toolName string, index int) string {
id = strings.TrimSpace(id)
// Generate deterministic ID if empty
if id == "" {
hash := sha256.Sum256([]byte(fmt.Sprintf("%s_%d", toolName, index)))
id = fmt.Sprintf("call_%x", hash[:6])
}
// Remove unsafe characters
id = validIDChars.ReplaceAllString(id, "_")
// Truncate if too long, preserving uniqueness with hash suffix
if len(id) > maxToolCallIDLen {
hash := sha256.Sum256([]byte(id))
suffix := fmt.Sprintf("_%x", hash[:4])
id = id[:maxToolCallIDLen-len(suffix)] + suffix
}
return id
}
+53
View File
@@ -0,0 +1,53 @@
package tools
import (
"testing"
"github.com/stretchr/testify/assert"
)
func TestNormalizeToolCallID(t *testing.T) {
t.Run("normal ID unchanged", func(t *testing.T) {
result := NormalizeToolCallID("call_abc123", "search", 0)
assert.Equal(t, "call_abc123", result)
})
t.Run("empty ID generates deterministic ID", func(t *testing.T) {
id1 := NormalizeToolCallID("", "search", 0)
id2 := NormalizeToolCallID("", "search", 0)
id3 := NormalizeToolCallID("", "search", 1)
assert.NotEmpty(t, id1)
assert.Equal(t, id1, id2, "same tool+index should produce same ID")
assert.NotEqual(t, id1, id3, "different index should produce different ID")
assert.True(t, len(id1) > 0 && len(id1) <= maxToolCallIDLen)
})
t.Run("whitespace-only ID treated as empty", func(t *testing.T) {
id := NormalizeToolCallID(" ", "search", 0)
assert.NotEmpty(t, id)
assert.True(t, len(id) <= maxToolCallIDLen)
})
t.Run("special characters replaced", func(t *testing.T) {
id := NormalizeToolCallID("call/foo@bar#baz", "search", 0)
assert.NotContains(t, id, "/")
assert.NotContains(t, id, "@")
assert.NotContains(t, id, "#")
})
t.Run("long ID truncated with hash", func(t *testing.T) {
longID := "call_" + string(make([]byte, 200))
id := NormalizeToolCallID(longID, "search", 0)
assert.LessOrEqual(t, len(id), maxToolCallIDLen)
})
t.Run("ID at exact limit unchanged", func(t *testing.T) {
exactID := "call_" + "a"
for len(exactID) < maxToolCallIDLen {
exactID += "a"
}
id := NormalizeToolCallID(exactID, "search", 0)
assert.Equal(t, exactID, id)
})
}
+67
View File
@@ -0,0 +1,67 @@
package tools
import (
"github.com/Tencent/WeKnora/internal/models/chat"
)
// SanitizeMessages validates and fixes a message array for LLM compatibility.
// It handles common issues that cause provider API errors:
// - Ensures no consecutive same-role messages (some providers reject these)
// - Verifies tool result messages have matching tool_call in the preceding assistant message
// - Removes empty content messages that can cause API errors
//
// Returns the sanitized message slice (may be shorter than input).
func SanitizeMessages(messages []chat.Message) []chat.Message {
if len(messages) == 0 {
return messages
}
result := make([]chat.Message, 0, len(messages))
for i, msg := range messages {
// Skip empty non-system messages (some providers reject these)
if msg.Content == "" && msg.Role != "system" &&
msg.Role != "tool" && len(msg.ToolCalls) == 0 {
continue
}
// Prevent consecutive same-role messages (except tool results)
if len(result) > 0 && msg.Role != "tool" {
prev := result[len(result)-1]
if prev.Role == msg.Role && prev.Role != "tool" {
// Merge with previous message
result[len(result)-1].Content += "\n\n" + msg.Content
continue
}
}
// Verify tool result messages reference a valid tool call
if msg.Role == "tool" && msg.ToolCallID != "" {
if !hasMatchingToolCall(messages[:i], msg.ToolCallID) {
// Orphaned tool result — convert to system message
msg.Role = "system"
msg.Content = "[Tool result for " + msg.Name + "]: " + msg.Content
msg.ToolCallID = ""
msg.Name = ""
}
}
result = append(result, msg)
}
return result
}
// hasMatchingToolCall checks if any preceding assistant message has a tool call with the given ID.
func hasMatchingToolCall(messages []chat.Message, toolCallID string) bool {
for i := len(messages) - 1; i >= 0; i-- {
msg := messages[i]
if msg.Role == "assistant" {
for _, tc := range msg.ToolCalls {
if tc.ID == toolCallID {
return true
}
}
}
}
return false
}
@@ -0,0 +1,86 @@
package tools
import (
"testing"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestSanitizeMessages(t *testing.T) {
t.Run("normal messages unchanged", func(t *testing.T) {
messages := []chat.Message{
{Role: "system", Content: "You are helpful"},
{Role: "user", Content: "Hello"},
{Role: "assistant", Content: "Hi there"},
}
result := SanitizeMessages(messages)
assert.Len(t, result, 3)
})
t.Run("consecutive user messages merged", func(t *testing.T) {
messages := []chat.Message{
{Role: "system", Content: "You are helpful"},
{Role: "user", Content: "Hello"},
{Role: "user", Content: "How are you?"},
}
result := SanitizeMessages(messages)
require.Len(t, result, 2) // system + merged user
assert.Contains(t, result[1].Content, "Hello")
assert.Contains(t, result[1].Content, "How are you?")
})
t.Run("consecutive tool messages not merged", func(t *testing.T) {
messages := []chat.Message{
{Role: "system", Content: "system"},
{Role: "assistant", Content: "thinking", ToolCalls: []chat.ToolCall{
{ID: "call_1"}, {ID: "call_2"},
}},
{Role: "tool", Content: "result1", ToolCallID: "call_1"},
{Role: "tool", Content: "result2", ToolCallID: "call_2"},
}
result := SanitizeMessages(messages)
assert.Len(t, result, 4) // all preserved
})
t.Run("empty content messages removed and consecutive merged", func(t *testing.T) {
messages := []chat.Message{
{Role: "system", Content: "system"},
{Role: "user", Content: "hello"},
{Role: "assistant", Content: ""},
{Role: "user", Content: "bye"},
}
result := SanitizeMessages(messages)
// empty assistant removed → two user messages merge
assert.Len(t, result, 2)
assert.Contains(t, result[1].Content, "hello")
assert.Contains(t, result[1].Content, "bye")
})
t.Run("empty system message preserved", func(t *testing.T) {
messages := []chat.Message{
{Role: "system", Content: ""},
{Role: "user", Content: "hello"},
}
result := SanitizeMessages(messages)
assert.Len(t, result, 2) // system preserved even if empty
})
t.Run("orphaned tool result converted", func(t *testing.T) {
messages := []chat.Message{
{Role: "system", Content: "system"},
{Role: "tool", Content: "some result",
ToolCallID: "nonexistent_id", Name: "search"},
}
result := SanitizeMessages(messages)
require.Len(t, result, 2)
assert.Equal(t, "system", result[1].Role) // converted
assert.Contains(t, result[1].Content, "search")
})
t.Run("empty slice", func(t *testing.T) {
result := SanitizeMessages(nil)
assert.Empty(t, result)
})
}