Files
Enterprise-Knowledge-Base/internal/agent/tools/registry.go
T
young1lin 29bec4204a fix(agent/tools): sort function definitions for deterministic ordering
`ToolRegistry.GetFunctionDefinitions` and `ListTools` previously ranged
over the internal map directly. Go map iteration is intentionally
randomized, so the resulting `tools` array reshuffled on every request.

That reshuffling silently breaks provider-side prompt caches that key on
a byte-level prefix match — most visibly Qwen explicit caching, which
requires the messages (system + tools + history) to be byte-identical up
to the `cache_control` marker. With random ordering the serialized tools
block changes every call, so the cache prefix never matches and the
hit rate stays at 0%.

Sort by tool name in both functions. Output is now byte-stable across
calls and `cache_control: ephemeral` can actually take effect.

Tests in registry_test.go cover:
- Deterministic ordering across 50 iterations
- JSON byte-stability across 20 iterations (the real motivation)
- Field projection (Name / Description / Parameters)
- Empty registry returns `[]` not `null`
- ListTools sorting
- First-wins duplicate registration policy (GHSA-67q9-58vj-32qx)
2026-05-25 16:47:14 +08:00

187 lines
5.7 KiB
Go

package tools
import (
"context"
"encoding/json"
"fmt"
"sort"
"github.com/Tencent/WeKnora/internal/common"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types"
)
// toolErrorHint is appended to tool error messages to guide the LLM to retry with a different approach.
const toolErrorHint = "\n\n[Analyze the error above and try a different approach.]"
// ToolRegistry manages the registration and retrieval of tools
type ToolRegistry struct {
tools map[string]types.Tool
maxToolOutputSize int // maximum chars for tool output (0 = use DefaultMaxToolOutput)
}
// NewToolRegistry creates a new tool registry
func NewToolRegistry() *ToolRegistry {
return &ToolRegistry{
tools: make(map[string]types.Tool),
}
}
// SetMaxToolOutputSize sets the maximum character length for tool output.
// Values <= 0 will use DefaultMaxToolOutput.
func (r *ToolRegistry) SetMaxToolOutputSize(maxChars int) {
r.maxToolOutputSize = maxChars
}
// getMaxToolOutput returns the effective max tool output size.
func (r *ToolRegistry) getMaxToolOutput() int {
if r.maxToolOutputSize > 0 {
return r.maxToolOutputSize
}
return DefaultMaxToolOutput
}
// RegisterTool adds a tool to the registry.
// If a tool with the same name is already registered, the existing one is kept
// (first-wins) to prevent tool execution hijacking via name collision (GHSA-67q9-58vj-32qx).
func (r *ToolRegistry) RegisterTool(tool types.Tool) {
name := tool.Name()
if _, exists := r.tools[name]; exists {
logger.Warnf(context.Background(),
"[ToolRegistry] Duplicate tool registration rejected: %s (first-wins policy)", name)
return
}
r.tools[name] = tool
}
// GetTool retrieves a tool by name
func (r *ToolRegistry) GetTool(name string) (types.Tool, error) {
tool, exists := r.tools[name]
if !exists {
return nil, fmt.Errorf("tool not found: %s", name)
}
return tool, nil
}
// ListTools returns all registered tool names sorted alphabetically.
// Sorting keeps the order stable across calls — Go map iteration is
// intentionally randomized.
func (r *ToolRegistry) ListTools() []string {
names := make([]string, 0, len(r.tools))
for name := range r.tools {
names = append(names, name)
}
sort.Strings(names)
return names
}
// GetFunctionDefinitions returns function definitions for all registered tools.
// The slice is sorted by tool name so the serialized payload sent to the LLM
// is byte-identical across requests. Providers that key prompt caching on a
// byte-level prefix match (e.g. Qwen explicit caching) require this — map
// iteration order would otherwise reshuffle the tools block and break cache
// hits.
func (r *ToolRegistry) GetFunctionDefinitions() []types.FunctionDefinition {
names := make([]string, 0, len(r.tools))
for name := range r.tools {
names = append(names, name)
}
sort.Strings(names)
definitions := make([]types.FunctionDefinition, 0, len(names))
for _, name := range names {
tool := r.tools[name]
definitions = append(definitions, types.FunctionDefinition{
Name: tool.Name(),
Description: tool.Description(),
Parameters: tool.Parameters(),
})
}
return definitions
}
// ExecuteTool executes a tool by name with the given arguments
func (r *ToolRegistry) ExecuteTool(
ctx context.Context,
name string,
args json.RawMessage,
) (*types.ToolResult, error) {
common.PipelineInfo(ctx, "AgentTool", "execute_start", map[string]interface{}{
"tool": name,
"args": args,
})
tool, err := r.GetTool(name)
if err != nil {
common.PipelineError(ctx, "AgentTool", "execute_failed", map[string]interface{}{
"tool": name,
"error": err.Error(),
})
return &types.ToolResult{
Success: false,
Error: err.Error() + toolErrorHint,
}, err
}
// Cast parameters to match expected schema types before execution.
// This handles common LLM quirks like returning "true" instead of true.
args = CastParams(args, tool.Parameters())
// Validate parameters against the tool's JSON Schema before execution.
// This catches invalid arguments early, avoiding a wasted tool execution + LLM round.
if validationErrs := ValidateParams(args, tool.Parameters()); len(validationErrs) > 0 {
errMsg := FormatValidationErrors(validationErrs) + toolErrorHint
common.PipelineWarn(ctx, "AgentTool", "validation_failed", map[string]interface{}{
"tool": name,
"errors": errMsg,
})
return &types.ToolResult{
Success: false,
Error: errMsg,
}, nil
}
result, execErr := tool.Execute(ctx, args)
// Truncate large tool outputs to prevent context window poisoning.
maxOutput := r.getMaxToolOutput()
if result != nil && len(result.Output) > maxOutput {
result.Output = TruncateToolOutput(result.Output, maxOutput)
}
fields := map[string]interface{}{
"tool": name,
"args": args,
}
if result != nil {
fields["success"] = result.Success
if result.Error != "" {
fields["error"] = result.Error
}
}
if execErr != nil {
fields["error"] = execErr.Error()
common.PipelineError(ctx, "AgentTool", "execute_done", fields)
} else if result != nil && !result.Success {
// Append error hint to guide LLM to retry with a different approach
if result.Error != "" {
result.Error = result.Error + toolErrorHint
}
common.PipelineWarn(ctx, "AgentTool", "execute_done", fields)
} else {
common.PipelineInfo(ctx, "AgentTool", "execute_done", fields)
}
return result, execErr
}
// Cleanup cleans up all registered tools that implement the types.Cleanable interface.
// This is called at the end of agent sessions to release tool-specific resources.
func (r *ToolRegistry) Cleanup(ctx context.Context) {
for name, tool := range r.tools {
if cleanable, ok := tool.(types.Cleanable); ok {
logger.Infof(ctx, "[ToolRegistry] Cleaning up tool: %s", name)
cleanable.Cleanup(ctx)
}
}
}