feat(agent): implement memory consolidation and context management
- Introduced a memory consolidator to summarize older messages when the context window exceeds a specified limit, preserving key facts and tool results. - Enhanced the AgentEngine to utilize the new token estimator and memory consolidator for improved context window management. - Implemented logic to compress message history when approaching token limits, ensuring efficient use of context. - Added unit tests for the memory consolidator and token estimator to validate functionality and performance. - Updated tool execution to validate parameters against JSON schema before execution, improving error handling and robustness.
This commit is contained in:
@@ -8,7 +8,9 @@ import (
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
agentmemory "github.com/Tencent/WeKnora/internal/agent/memory"
|
||||
"github.com/Tencent/WeKnora/internal/agent/skills"
|
||||
agenttoken "github.com/Tencent/WeKnora/internal/agent/token"
|
||||
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
|
||||
"github.com/Tencent/WeKnora/internal/common"
|
||||
appconfig "github.com/Tencent/WeKnora/internal/config"
|
||||
@@ -77,8 +79,10 @@ type AgentEngine struct {
|
||||
sessionID string // Session ID for context management
|
||||
systemPromptTemplate string // System prompt template (optional, uses default if empty)
|
||||
skillsManager *skills.Manager // Skills manager for Progressive Disclosure (optional)
|
||||
appConfig *appconfig.Config // Application config for prompt template resolution (optional)
|
||||
imageDescriber ImageDescriberFunc // VLM function for describing images in tool results (optional)
|
||||
appConfig *appconfig.Config // Application config for prompt template resolution (optional)
|
||||
imageDescriber ImageDescriberFunc // VLM function for describing images in tool results (optional)
|
||||
tokenEstimator *agenttoken.Estimator // Token estimator for context window management
|
||||
memoryConsolidator *agentmemory.Consolidator // Memory consolidator for LLM-powered summarization (optional)
|
||||
}
|
||||
|
||||
// ImageDescriberFunc generates a text description of an image.
|
||||
@@ -109,7 +113,8 @@ func NewAgentEngine(
|
||||
if eventBus == nil {
|
||||
eventBus = event.NewEventBus()
|
||||
}
|
||||
return &AgentEngine{
|
||||
tokenEst := agenttoken.NewEstimator(0)
|
||||
engine := &AgentEngine{
|
||||
config: config,
|
||||
toolRegistry: toolRegistry,
|
||||
chatModel: chatModel,
|
||||
@@ -119,7 +124,17 @@ func NewAgentEngine(
|
||||
contextManager: contextManager,
|
||||
sessionID: sessionID,
|
||||
systemPromptTemplate: systemPromptTemplate,
|
||||
tokenEstimator: tokenEst,
|
||||
}
|
||||
|
||||
// Initialize memory consolidator if context window management is configured
|
||||
if config.MaxContextTokens > 0 {
|
||||
engine.memoryConsolidator = agentmemory.NewConsolidator(
|
||||
chatModel, tokenEst, config.MaxContextTokens, 0,
|
||||
)
|
||||
}
|
||||
|
||||
return engine
|
||||
}
|
||||
|
||||
// NewAgentEngineWithSkills creates a new agent engine with skills support
|
||||
@@ -301,8 +316,37 @@ func (e *AgentEngine) executeLoop(
|
||||
})
|
||||
for state.CurrentRound < e.config.MaxIterations {
|
||||
roundStart := time.Now()
|
||||
logger.Infof(ctx, "========== Round %d/%d Started ==========", state.CurrentRound+1, e.config.MaxIterations)
|
||||
logger.Infof(ctx, "[Agent][Round-%d] Message history size: %d messages", state.CurrentRound+1, len(messages))
|
||||
logger.Infof(ctx, "========== Round %d/%d Started ==========",
|
||||
state.CurrentRound+1, e.config.MaxIterations)
|
||||
|
||||
// Context window management: consolidate or compress messages if approaching token limit
|
||||
if e.config.MaxContextTokens > 0 {
|
||||
beforeLen := len(messages)
|
||||
|
||||
// Try LLM-powered consolidation first (preserves more semantic content)
|
||||
if e.memoryConsolidator != nil && e.memoryConsolidator.ShouldConsolidate(messages) {
|
||||
logger.Infof(ctx, "[Agent][Round-%d] Token threshold exceeded, consolidating memory",
|
||||
state.CurrentRound+1)
|
||||
consolidated, consolidateErr := e.memoryConsolidator.Consolidate(ctx, messages)
|
||||
if consolidateErr != nil {
|
||||
logger.Warnf(ctx, "[Agent][Round-%d] Memory consolidation failed: %v, "+
|
||||
"falling back to simple compression", state.CurrentRound+1, consolidateErr)
|
||||
} else {
|
||||
messages = consolidated
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback: simple context compression if still over the hard limit (80%)
|
||||
messages = agenttoken.CompressContext(messages, e.tokenEstimator, e.config.MaxContextTokens)
|
||||
|
||||
if len(messages) < beforeLen {
|
||||
logger.Infof(ctx, "[Agent][Round-%d] Context managed: %d → %d messages (max_tokens=%d)",
|
||||
state.CurrentRound+1, beforeLen, len(messages), e.config.MaxContextTokens)
|
||||
}
|
||||
}
|
||||
|
||||
logger.Infof(ctx, "[Agent][Round-%d] Message history size: %d messages",
|
||||
state.CurrentRound+1, len(messages))
|
||||
common.PipelineInfo(ctx, "Agent", "round_start", map[string]interface{}{
|
||||
"iteration": state.CurrentRound,
|
||||
"round": state.CurrentRound + 1,
|
||||
@@ -359,6 +403,25 @@ func (e *AgentEngine) executeLoop(
|
||||
"iteration": state.CurrentRound,
|
||||
"error": err.Error(),
|
||||
})
|
||||
|
||||
// Graceful degradation: if we have tool results from previous rounds,
|
||||
// try to synthesize a final answer from them instead of losing everything.
|
||||
if totalTC := countTotalToolCalls(state.RoundSteps); totalTC > 0 {
|
||||
logger.Warnf(ctx, "[Agent] LLM failed but have %d steps with %d tool calls — "+
|
||||
"attempting final answer synthesis from existing results",
|
||||
len(state.RoundSteps), totalTC)
|
||||
common.PipelineWarn(ctx, "Agent", "llm_failed_synthesizing", map[string]interface{}{
|
||||
"steps": len(state.RoundSteps),
|
||||
"tool_calls": totalTC,
|
||||
})
|
||||
if synthErr := e.streamFinalAnswerToEventBus(ctx, query, state, sessionID); synthErr != nil {
|
||||
logger.Errorf(ctx, "[Agent] Final answer synthesis also failed: %v", synthErr)
|
||||
return state, fmt.Errorf("LLM call failed: %w (synthesis also failed: %v)", err, synthErr)
|
||||
}
|
||||
state.IsComplete = true
|
||||
break
|
||||
}
|
||||
|
||||
return state, fmt.Errorf("LLM call failed: %w", err)
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,323 @@
|
||||
// Package memory provides LLM-powered memory consolidation for agent conversations.
|
||||
// When the context window grows too large, older messages are summarized by the LLM
|
||||
// into a compact memory block that preserves key facts and tool results.
|
||||
package memory
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/Tencent/WeKnora/internal/agent/token"
|
||||
"github.com/Tencent/WeKnora/internal/logger"
|
||||
"github.com/Tencent/WeKnora/internal/models/chat"
|
||||
"github.com/Tencent/WeKnora/internal/types"
|
||||
)
|
||||
|
||||
const (
|
||||
// DefaultConsolidationThreshold is the ratio of context window that triggers consolidation.
|
||||
// When token count exceeds MaxContextTokens * threshold, consolidation is triggered.
|
||||
DefaultConsolidationThreshold = 0.5
|
||||
|
||||
// maxConsolidationAttempts is the maximum number of LLM calls for consolidation.
|
||||
// After this many failures, fall back to raw archiving.
|
||||
maxConsolidationAttempts = 3
|
||||
|
||||
// consolidationTimeout is the timeout for the consolidation LLM call.
|
||||
consolidationTimeout = 60 * time.Second
|
||||
)
|
||||
|
||||
// Consolidator compresses agent conversation history using LLM summarization.
|
||||
// When the message history grows too large for the context window, it summarizes
|
||||
// older messages into a compact system message that preserves key facts.
|
||||
type Consolidator struct {
|
||||
chatModel chat.Chat
|
||||
estimator *token.Estimator
|
||||
maxTokens int // context window size
|
||||
threshold float64 // trigger ratio (default 0.5)
|
||||
}
|
||||
|
||||
// NewConsolidator creates a memory consolidator.
|
||||
// maxContextTokens is the total context window budget.
|
||||
// threshold is the ratio (0-1) at which consolidation triggers (0 = use default 0.5).
|
||||
func NewConsolidator(
|
||||
chatModel chat.Chat,
|
||||
estimator *token.Estimator,
|
||||
maxContextTokens int,
|
||||
threshold float64,
|
||||
) *Consolidator {
|
||||
if threshold <= 0 || threshold >= 1 {
|
||||
threshold = DefaultConsolidationThreshold
|
||||
}
|
||||
return &Consolidator{
|
||||
chatModel: chatModel,
|
||||
estimator: estimator,
|
||||
maxTokens: maxContextTokens,
|
||||
threshold: threshold,
|
||||
}
|
||||
}
|
||||
|
||||
// ShouldConsolidate checks if the messages need consolidation based on token count.
|
||||
func (c *Consolidator) ShouldConsolidate(messages []chat.Message) bool {
|
||||
if c.maxTokens <= 0 || len(messages) <= 3 {
|
||||
return false
|
||||
}
|
||||
tokenCount := c.estimator.EstimateMessages(messages)
|
||||
triggerAt := int(float64(c.maxTokens) * c.threshold)
|
||||
return tokenCount > triggerAt
|
||||
}
|
||||
|
||||
// Consolidate summarizes older messages and returns a compressed message array.
|
||||
// It preserves:
|
||||
// - The system prompt (first message)
|
||||
// - The current user query (last message)
|
||||
// - Recent messages that fit within the token budget
|
||||
//
|
||||
// Older messages are replaced with a summary system message.
|
||||
// On LLM failure after maxConsolidationAttempts, falls back to raw text archiving.
|
||||
func (c *Consolidator) Consolidate(
|
||||
ctx context.Context,
|
||||
messages []chat.Message,
|
||||
) ([]chat.Message, error) {
|
||||
if len(messages) <= 3 {
|
||||
return messages, nil
|
||||
}
|
||||
|
||||
systemMsg := messages[0]
|
||||
lastMsg := messages[len(messages)-1]
|
||||
middle := messages[1 : len(messages)-1]
|
||||
|
||||
// Determine how many messages to keep vs. consolidate.
|
||||
// We want to consolidate enough to bring tokens below the threshold.
|
||||
targetTokens := int(float64(c.maxTokens) * c.threshold * 0.6) // aim for 60% of threshold
|
||||
keepFromEnd := c.findKeepBoundary(middle, targetTokens, &systemMsg, &lastMsg)
|
||||
|
||||
if keepFromEnd >= len(middle) {
|
||||
// Nothing to consolidate
|
||||
return messages, nil
|
||||
}
|
||||
|
||||
toConsolidate := middle[:len(middle)-keepFromEnd]
|
||||
toKeep := middle[len(middle)-keepFromEnd:]
|
||||
|
||||
// Try LLM-powered summarization
|
||||
summary, err := c.summarizeWithRetry(ctx, toConsolidate)
|
||||
if err != nil {
|
||||
// Fall back to raw archiving
|
||||
logger.Warnf(ctx, "[MemoryConsolidator] LLM summarization failed after retries, "+
|
||||
"falling back to raw archive: %v", err)
|
||||
summary = c.rawArchive(toConsolidate)
|
||||
}
|
||||
|
||||
// Build consolidated messages
|
||||
summaryMsg := chat.Message{
|
||||
Role: "system",
|
||||
Content: fmt.Sprintf(
|
||||
"[Memory Summary - %d earlier messages consolidated]\n\n%s",
|
||||
len(toConsolidate), summary,
|
||||
),
|
||||
}
|
||||
|
||||
result := make([]chat.Message, 0, 3+len(toKeep))
|
||||
result = append(result, systemMsg)
|
||||
result = append(result, summaryMsg)
|
||||
result = append(result, toKeep...)
|
||||
result = append(result, lastMsg)
|
||||
|
||||
logger.Infof(ctx, "[MemoryConsolidator] Consolidated %d messages → summary (%d chars), "+
|
||||
"keeping %d recent messages",
|
||||
len(toConsolidate), len(summary), len(toKeep))
|
||||
|
||||
return result, nil
|
||||
}
|
||||
|
||||
// findKeepBoundary determines how many messages from the end of middle to keep.
|
||||
// Returns the count of messages to keep (from the end), respecting tool_call/tool_result boundaries.
|
||||
func (c *Consolidator) findKeepBoundary(
|
||||
middle []chat.Message,
|
||||
targetTokens int,
|
||||
systemMsg, lastMsg *chat.Message,
|
||||
) int {
|
||||
// Budget for kept messages = target - system - last
|
||||
budget := targetTokens -
|
||||
c.estimator.EstimateMessage(systemMsg) -
|
||||
c.estimator.EstimateMessage(lastMsg) -
|
||||
500 // reserve for summary message
|
||||
|
||||
if budget <= 0 {
|
||||
return 0
|
||||
}
|
||||
|
||||
// Walk from the end, accumulating tokens, respecting tool boundaries
|
||||
tokens := 0
|
||||
keepCount := 0
|
||||
i := len(middle) - 1
|
||||
|
||||
for i >= 0 {
|
||||
msg := middle[i]
|
||||
msgTokens := c.estimator.EstimateMessage(&msg)
|
||||
|
||||
// If this is a tool result, we must also keep its assistant message
|
||||
if msg.Role == "tool" {
|
||||
// Walk back to find the assistant message with tool_calls
|
||||
groupTokens := msgTokens
|
||||
groupSize := 1
|
||||
j := i - 1
|
||||
for j >= 0 && middle[j].Role == "tool" {
|
||||
groupTokens += c.estimator.EstimateMessage(&middle[j])
|
||||
groupSize++
|
||||
j--
|
||||
}
|
||||
// Include the assistant message
|
||||
if j >= 0 && middle[j].Role == "assistant" {
|
||||
groupTokens += c.estimator.EstimateMessage(&middle[j])
|
||||
groupSize++
|
||||
}
|
||||
|
||||
if tokens+groupTokens > budget {
|
||||
break
|
||||
}
|
||||
tokens += groupTokens
|
||||
keepCount += groupSize
|
||||
i -= groupSize
|
||||
} else {
|
||||
if tokens+msgTokens > budget {
|
||||
break
|
||||
}
|
||||
tokens += msgTokens
|
||||
keepCount++
|
||||
i--
|
||||
}
|
||||
}
|
||||
|
||||
return keepCount
|
||||
}
|
||||
|
||||
// summarizeWithRetry attempts LLM summarization with retries.
|
||||
func (c *Consolidator) summarizeWithRetry(
|
||||
ctx context.Context,
|
||||
messages []chat.Message,
|
||||
) (string, error) {
|
||||
prompt := c.buildConsolidationPrompt(messages)
|
||||
var lastErr error
|
||||
|
||||
for attempt := 1; attempt <= maxConsolidationAttempts; attempt++ {
|
||||
summarizeCtx, cancel := context.WithTimeout(ctx, consolidationTimeout)
|
||||
|
||||
resp, err := c.chatModel.Chat(summarizeCtx, []chat.Message{
|
||||
{Role: "system", Content: consolidationSystemPrompt},
|
||||
{Role: "user", Content: prompt},
|
||||
}, &chat.ChatOptions{
|
||||
Temperature: 0.3, // low temperature for factual summarization
|
||||
MaxTokens: 2000,
|
||||
})
|
||||
cancel()
|
||||
|
||||
if err != nil {
|
||||
lastErr = err
|
||||
logger.Warnf(ctx, "[MemoryConsolidator] Summarization attempt %d/%d failed: %v",
|
||||
attempt, maxConsolidationAttempts, err)
|
||||
continue
|
||||
}
|
||||
|
||||
if resp != nil && resp.Content != "" {
|
||||
return resp.Content, nil
|
||||
}
|
||||
lastErr = fmt.Errorf("empty response from LLM")
|
||||
}
|
||||
|
||||
return "", fmt.Errorf("summarization failed after %d attempts: %w",
|
||||
maxConsolidationAttempts, lastErr)
|
||||
}
|
||||
|
||||
// buildConsolidationPrompt creates the prompt for LLM to summarize messages.
|
||||
func (c *Consolidator) buildConsolidationPrompt(messages []chat.Message) string {
|
||||
var sb strings.Builder
|
||||
sb.WriteString("Summarize the following conversation history, preserving:\n")
|
||||
sb.WriteString("1. Key facts and decisions made\n")
|
||||
sb.WriteString("2. Tool execution results and their outcomes\n")
|
||||
sb.WriteString("3. User's original intent and requirements\n")
|
||||
sb.WriteString("4. Any errors encountered and how they were resolved\n\n")
|
||||
sb.WriteString("Conversation to summarize:\n\n")
|
||||
|
||||
for _, msg := range messages {
|
||||
switch msg.Role {
|
||||
case "user":
|
||||
sb.WriteString(fmt.Sprintf("**User**: %s\n\n", truncateForPrompt(msg.Content, 2000)))
|
||||
case "assistant":
|
||||
if len(msg.ToolCalls) > 0 {
|
||||
names := make([]string, len(msg.ToolCalls))
|
||||
for i, tc := range msg.ToolCalls {
|
||||
names[i] = tc.Function.Name
|
||||
}
|
||||
sb.WriteString(fmt.Sprintf("**Assistant** [called tools: %s]: %s\n\n",
|
||||
strings.Join(names, ", "), truncateForPrompt(msg.Content, 1000)))
|
||||
} else {
|
||||
sb.WriteString(fmt.Sprintf("**Assistant**: %s\n\n",
|
||||
truncateForPrompt(msg.Content, 2000)))
|
||||
}
|
||||
case "tool":
|
||||
sb.WriteString(fmt.Sprintf("**Tool [%s]**: %s\n\n",
|
||||
msg.Name, truncateForPrompt(msg.Content, 1000)))
|
||||
}
|
||||
}
|
||||
|
||||
return sb.String()
|
||||
}
|
||||
|
||||
// rawArchive creates a simple text dump of messages as fallback when LLM fails.
|
||||
func (c *Consolidator) rawArchive(messages []chat.Message) string {
|
||||
var sb strings.Builder
|
||||
sb.WriteString("Raw conversation archive (LLM summarization unavailable):\n\n")
|
||||
|
||||
for _, msg := range messages {
|
||||
content := truncateForPrompt(msg.Content, 500)
|
||||
switch msg.Role {
|
||||
case "user":
|
||||
sb.WriteString(fmt.Sprintf("- User: %s\n", content))
|
||||
case "assistant":
|
||||
if len(msg.ToolCalls) > 0 {
|
||||
names := make([]string, len(msg.ToolCalls))
|
||||
for j, tc := range msg.ToolCalls {
|
||||
names[j] = tc.Function.Name
|
||||
}
|
||||
sb.WriteString(fmt.Sprintf("- Assistant [tools: %s]: %s\n",
|
||||
strings.Join(names, ","), content))
|
||||
} else {
|
||||
sb.WriteString(fmt.Sprintf("- Assistant: %s\n", content))
|
||||
}
|
||||
case "tool":
|
||||
sb.WriteString(fmt.Sprintf("- Tool[%s]: %s\n", msg.Name, content))
|
||||
}
|
||||
}
|
||||
|
||||
return sb.String()
|
||||
}
|
||||
|
||||
// truncateForPrompt truncates a string to maxLen characters for use in prompts.
|
||||
func truncateForPrompt(s string, maxLen int) string {
|
||||
runes := []rune(s)
|
||||
if len(runes) <= maxLen {
|
||||
return s
|
||||
}
|
||||
return string(runes[:maxLen]) + "..."
|
||||
}
|
||||
|
||||
//nolint:lll // raw string literal used for prompt readability
|
||||
const consolidationSystemPrompt = "" +
|
||||
"You are a conversation summarizer. " +
|
||||
"Your task is to create a concise but comprehensive summary " +
|
||||
"of a conversation between a user and an AI assistant.\n\n" +
|
||||
"The summary should:\n" +
|
||||
"- Be written in the same language as the original conversation\n" +
|
||||
"- Preserve all key facts, numbers, and specific details\n" +
|
||||
"- Include the outcomes of any tool executions\n" +
|
||||
"- Note any errors or issues encountered\n" +
|
||||
"- Be structured with clear sections if the conversation covered multiple topics\n" +
|
||||
"- Be concise — aim for 30% or less of the original length\n\n" +
|
||||
"Output only the summary, no preamble or explanation."
|
||||
|
||||
// ChatResponse is used to extract content from LLM response.
|
||||
// This avoids a direct dependency on the types package for the response format.
|
||||
var _ = (*types.ChatResponse)(nil) // compile-time check that types.ChatResponse exists
|
||||
@@ -0,0 +1,101 @@
|
||||
package memory
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
"github.com/Tencent/WeKnora/internal/agent/token"
|
||||
"github.com/Tencent/WeKnora/internal/models/chat"
|
||||
"github.com/stretchr/testify/assert"
|
||||
)
|
||||
|
||||
func TestConsolidator_ShouldConsolidate(t *testing.T) {
|
||||
est := token.NewEstimator(0)
|
||||
|
||||
t.Run("below threshold returns false", func(t *testing.T) {
|
||||
c := NewConsolidator(nil, est, 100000, 0)
|
||||
messages := []chat.Message{
|
||||
{Role: "system", Content: "system prompt"},
|
||||
{Role: "user", Content: "hello"},
|
||||
{Role: "assistant", Content: "hi"},
|
||||
{Role: "user", Content: "current"},
|
||||
}
|
||||
assert.False(t, c.ShouldConsolidate(messages))
|
||||
})
|
||||
|
||||
t.Run("too few messages returns false", func(t *testing.T) {
|
||||
c := NewConsolidator(nil, est, 10, 0)
|
||||
messages := []chat.Message{
|
||||
{Role: "system", Content: "system"},
|
||||
{Role: "user", Content: "hello"},
|
||||
}
|
||||
assert.False(t, c.ShouldConsolidate(messages))
|
||||
})
|
||||
|
||||
t.Run("disabled returns false", func(t *testing.T) {
|
||||
c := NewConsolidator(nil, est, 0, 0) // disabled
|
||||
messages := []chat.Message{
|
||||
{Role: "system", Content: "system"},
|
||||
{Role: "user", Content: "hello"},
|
||||
{Role: "assistant", Content: "hi"},
|
||||
{Role: "user", Content: "current"},
|
||||
}
|
||||
assert.False(t, c.ShouldConsolidate(messages))
|
||||
})
|
||||
}
|
||||
|
||||
func TestTruncateForPrompt(t *testing.T) {
|
||||
t.Run("short string unchanged", func(t *testing.T) {
|
||||
assert.Equal(t, "hello", truncateForPrompt("hello", 100))
|
||||
})
|
||||
|
||||
t.Run("long string truncated", func(t *testing.T) {
|
||||
result := truncateForPrompt("hello world this is long", 10)
|
||||
assert.Equal(t, "hello worl...", result)
|
||||
})
|
||||
|
||||
t.Run("CJK string truncated by rune", func(t *testing.T) {
|
||||
input := "你好世界测试数据中文字符串"
|
||||
result := truncateForPrompt(input, 5)
|
||||
assert.Equal(t, "你好世界测...", result)
|
||||
})
|
||||
}
|
||||
|
||||
func TestRawArchive(t *testing.T) {
|
||||
est := token.NewEstimator(0)
|
||||
c := NewConsolidator(nil, est, 100000, 0)
|
||||
|
||||
messages := []chat.Message{
|
||||
{Role: "user", Content: "search for X"},
|
||||
{
|
||||
Role: "assistant", Content: "let me search",
|
||||
ToolCalls: []chat.ToolCall{
|
||||
{Function: chat.FunctionCall{Name: "knowledge_search"}},
|
||||
},
|
||||
},
|
||||
{Role: "tool", Content: "result data", Name: "knowledge_search"},
|
||||
}
|
||||
|
||||
result := c.rawArchive(messages)
|
||||
assert.Contains(t, result, "Raw conversation archive")
|
||||
assert.Contains(t, result, "User: search for X")
|
||||
assert.Contains(t, result, "knowledge_search")
|
||||
assert.Contains(t, result, "Tool[knowledge_search]: result data")
|
||||
}
|
||||
|
||||
func TestBuildConsolidationPrompt(t *testing.T) {
|
||||
est := token.NewEstimator(0)
|
||||
c := NewConsolidator(nil, est, 100000, 0)
|
||||
|
||||
messages := []chat.Message{
|
||||
{Role: "user", Content: "find info about AI"},
|
||||
{Role: "assistant", Content: "searching...", ToolCalls: []chat.ToolCall{
|
||||
{Function: chat.FunctionCall{Name: "web_search"}},
|
||||
}},
|
||||
{Role: "tool", Content: "results here", Name: "web_search"},
|
||||
}
|
||||
|
||||
prompt := c.buildConsolidationPrompt(messages)
|
||||
assert.Contains(t, prompt, "**User**: find info about AI")
|
||||
assert.Contains(t, prompt, "web_search")
|
||||
assert.Contains(t, prompt, "**Tool [web_search]**: results here")
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
package token
|
||||
|
||||
import (
|
||||
"github.com/Tencent/WeKnora/internal/models/chat"
|
||||
)
|
||||
|
||||
// DefaultContextThresholdRatio is the ratio of context window usage that triggers compression.
|
||||
// When message tokens exceed MaxContextTokens * threshold, old messages are trimmed.
|
||||
const DefaultContextThresholdRatio = 0.8
|
||||
|
||||
// CompressContext trims older messages to bring total token count below the threshold.
|
||||
// It preserves:
|
||||
// - The first message (system prompt)
|
||||
// - The last message (current user query)
|
||||
// - tool_call / tool_result message pairs (never splits them)
|
||||
//
|
||||
// Returns the compressed message slice. If no compression is needed, returns the original.
|
||||
func CompressContext(
|
||||
messages []chat.Message,
|
||||
estimator *Estimator,
|
||||
maxTokens int,
|
||||
) []chat.Message {
|
||||
if maxTokens <= 0 || len(messages) <= 2 {
|
||||
return messages
|
||||
}
|
||||
|
||||
threshold := int(float64(maxTokens) * DefaultContextThresholdRatio)
|
||||
currentTokens := estimator.EstimateMessages(messages)
|
||||
if currentTokens <= threshold {
|
||||
return messages
|
||||
}
|
||||
|
||||
// Strategy: keep system prompt (first) + current query (last),
|
||||
// trim from the oldest messages inward, respecting tool_call/tool_result boundaries.
|
||||
|
||||
systemMsg := messages[0]
|
||||
lastMsg := messages[len(messages)-1]
|
||||
middle := messages[1 : len(messages)-1]
|
||||
|
||||
// Find groups of messages that form tool_call/tool_result pairs.
|
||||
// A group = one assistant message with tool_calls + all following tool result messages.
|
||||
groups := groupToolMessages(middle)
|
||||
|
||||
// Remove groups from the front until we're under the threshold.
|
||||
tokensToFree := currentTokens - threshold
|
||||
freed := 0
|
||||
removeUpTo := 0
|
||||
|
||||
for i, group := range groups {
|
||||
groupTokens := 0
|
||||
for _, msg := range group {
|
||||
groupTokens += estimator.EstimateMessage(&msg)
|
||||
}
|
||||
freed += groupTokens
|
||||
removeUpTo = i + 1
|
||||
if freed >= tokensToFree {
|
||||
break
|
||||
}
|
||||
}
|
||||
|
||||
// Rebuild messages: system + remaining groups + current query
|
||||
remaining := make([]chat.Message, 0, len(messages))
|
||||
remaining = append(remaining, systemMsg)
|
||||
for i := removeUpTo; i < len(groups); i++ {
|
||||
remaining = append(remaining, groups[i]...)
|
||||
}
|
||||
remaining = append(remaining, lastMsg)
|
||||
|
||||
return remaining
|
||||
}
|
||||
|
||||
// groupToolMessages groups middle messages into logical units:
|
||||
// - An assistant message with tool_calls + its corresponding tool result messages = one group
|
||||
// - A standalone message (user, assistant without tool_calls) = one group
|
||||
//
|
||||
// This ensures tool_call/tool_result pairs are never split during compression.
|
||||
func groupToolMessages(messages []chat.Message) [][]chat.Message {
|
||||
var groups [][]chat.Message
|
||||
i := 0
|
||||
for i < len(messages) {
|
||||
msg := messages[i]
|
||||
|
||||
// If this is an assistant message with tool_calls, group it with following tool results
|
||||
if msg.Role == "assistant" && len(msg.ToolCalls) > 0 {
|
||||
group := []chat.Message{msg}
|
||||
i++
|
||||
// Collect all following tool result messages
|
||||
for i < len(messages) && messages[i].Role == "tool" {
|
||||
group = append(group, messages[i])
|
||||
i++
|
||||
}
|
||||
groups = append(groups, group)
|
||||
} else {
|
||||
groups = append(groups, []chat.Message{msg})
|
||||
i++
|
||||
}
|
||||
}
|
||||
return groups
|
||||
}
|
||||
@@ -0,0 +1,116 @@
|
||||
// Package token provides token estimation for LLM context window management.
|
||||
package token
|
||||
|
||||
import (
|
||||
"unicode"
|
||||
|
||||
"github.com/Tencent/WeKnora/internal/models/chat"
|
||||
)
|
||||
|
||||
const (
|
||||
// DefaultCharsPerToken is a blended ratio for mixed English/CJK text.
|
||||
// English ≈ 4 chars/token, CJK ≈ 1.5 chars/token, blended ≈ 3.5.
|
||||
DefaultCharsPerToken = 3.5
|
||||
|
||||
// perMessageOverhead is the estimated token overhead per message
|
||||
// (role label, formatting, separator tokens).
|
||||
perMessageOverhead = 4
|
||||
)
|
||||
|
||||
// Estimator estimates token counts for messages and strings.
|
||||
// Uses a character-based heuristic that accounts for CJK characters.
|
||||
type Estimator struct {
|
||||
charsPerToken float64
|
||||
}
|
||||
|
||||
// NewEstimator creates a token estimator.
|
||||
// If charsPerToken <= 0, DefaultCharsPerToken is used.
|
||||
func NewEstimator(charsPerToken float64) *Estimator {
|
||||
if charsPerToken <= 0 {
|
||||
charsPerToken = DefaultCharsPerToken
|
||||
}
|
||||
return &Estimator{charsPerToken: charsPerToken}
|
||||
}
|
||||
|
||||
// EstimateString estimates the token count for a string.
|
||||
// It uses a CJK-aware heuristic: CJK characters are counted at ~1.5 chars/token,
|
||||
// while ASCII/Latin characters use the configured charsPerToken ratio.
|
||||
func (e *Estimator) EstimateString(s string) int {
|
||||
if len(s) == 0 {
|
||||
return 0
|
||||
}
|
||||
|
||||
var cjkRunes, otherRunes int
|
||||
for _, r := range s {
|
||||
if isCJK(r) {
|
||||
cjkRunes++
|
||||
} else {
|
||||
otherRunes++
|
||||
}
|
||||
}
|
||||
|
||||
// CJK characters are roughly 1.5 chars per token
|
||||
cjkTokens := float64(cjkRunes) / 1.5
|
||||
otherTokens := float64(otherRunes) / e.charsPerToken
|
||||
|
||||
return int(cjkTokens+otherTokens) + 1 // +1 to avoid underestimation
|
||||
}
|
||||
|
||||
// EstimateMessages estimates the total token count for a slice of chat messages.
|
||||
func (e *Estimator) EstimateMessages(messages []chat.Message) int {
|
||||
total := 0
|
||||
for i := range messages {
|
||||
total += e.EstimateMessage(&messages[i])
|
||||
}
|
||||
return total
|
||||
}
|
||||
|
||||
// EstimateMessage estimates the token count for a single message.
|
||||
func (e *Estimator) EstimateMessage(msg *chat.Message) int {
|
||||
tokens := perMessageOverhead
|
||||
tokens += e.EstimateString(msg.Role)
|
||||
tokens += e.EstimateString(msg.Content)
|
||||
tokens += e.EstimateString(msg.Name)
|
||||
|
||||
// Tool calls in assistant messages
|
||||
for _, tc := range msg.ToolCalls {
|
||||
tokens += e.EstimateString(tc.Function.Name)
|
||||
tokens += e.EstimateString(tc.Function.Arguments)
|
||||
tokens += 4 // overhead for tool call structure
|
||||
}
|
||||
|
||||
return tokens
|
||||
}
|
||||
|
||||
// isCJK checks if a rune is a CJK (Chinese, Japanese, Korean) character.
|
||||
func isCJK(r rune) bool {
|
||||
// CJK Unified Ideographs
|
||||
if r >= 0x4E00 && r <= 0x9FFF {
|
||||
return true
|
||||
}
|
||||
// CJK Unified Ideographs Extension A
|
||||
if r >= 0x3400 && r <= 0x4DBF {
|
||||
return true
|
||||
}
|
||||
// CJK Unified Ideographs Extension B
|
||||
if r >= 0x20000 && r <= 0x2A6DF {
|
||||
return true
|
||||
}
|
||||
// CJK Compatibility Ideographs
|
||||
if r >= 0xF900 && r <= 0xFAFF {
|
||||
return true
|
||||
}
|
||||
// Hiragana + Katakana
|
||||
if r >= 0x3040 && r <= 0x30FF {
|
||||
return true
|
||||
}
|
||||
// Hangul Syllables
|
||||
if r >= 0xAC00 && r <= 0xD7AF {
|
||||
return true
|
||||
}
|
||||
// Full-width characters
|
||||
if unicode.Is(unicode.Han, r) {
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
@@ -0,0 +1,187 @@
|
||||
package token
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/Tencent/WeKnora/internal/models/chat"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestEstimator(t *testing.T) {
|
||||
e := NewEstimator(0) // use default
|
||||
|
||||
t.Run("empty string", func(t *testing.T) {
|
||||
assert.Equal(t, 0, e.EstimateString(""))
|
||||
})
|
||||
|
||||
t.Run("english text", func(t *testing.T) {
|
||||
// "hello world" = 11 chars ≈ 11/3.5 + 1 ≈ 4 tokens
|
||||
tokens := e.EstimateString("hello world")
|
||||
assert.Greater(t, tokens, 0)
|
||||
assert.Less(t, tokens, 20)
|
||||
})
|
||||
|
||||
t.Run("chinese text", func(t *testing.T) {
|
||||
// 10 Chinese chars at ~1.5 chars/token ≈ 7 tokens
|
||||
tokens := e.EstimateString("你好世界测试数据中文")
|
||||
assert.Greater(t, tokens, 3)
|
||||
assert.Less(t, tokens, 20)
|
||||
})
|
||||
|
||||
t.Run("CJK is more tokens per char than latin", func(t *testing.T) {
|
||||
// Same number of characters, but CJK should estimate more tokens
|
||||
latin := strings.Repeat("a", 100)
|
||||
cjk := strings.Repeat("中", 100)
|
||||
latinTokens := e.EstimateString(latin)
|
||||
cjkTokens := e.EstimateString(cjk)
|
||||
assert.Greater(t, cjkTokens, latinTokens,
|
||||
"CJK text should estimate more tokens per character")
|
||||
})
|
||||
|
||||
t.Run("message estimation includes overhead", func(t *testing.T) {
|
||||
msg := chat.Message{
|
||||
Role: "assistant",
|
||||
Content: "hello",
|
||||
}
|
||||
tokens := e.EstimateMessage(&msg)
|
||||
contentTokens := e.EstimateString("hello")
|
||||
assert.Greater(t, tokens, contentTokens,
|
||||
"message tokens should include overhead beyond just content")
|
||||
})
|
||||
|
||||
t.Run("message with tool calls", func(t *testing.T) {
|
||||
msg := chat.Message{
|
||||
Role: "assistant",
|
||||
Content: "thinking...",
|
||||
ToolCalls: []chat.ToolCall{
|
||||
{
|
||||
Function: chat.FunctionCall{
|
||||
Name: "knowledge_search",
|
||||
Arguments: `{"query": "test"}`,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
tokens := e.EstimateMessage(&msg)
|
||||
assert.Greater(t, tokens, 10)
|
||||
})
|
||||
|
||||
t.Run("estimate messages", func(t *testing.T) {
|
||||
messages := []chat.Message{
|
||||
{Role: "system", Content: "You are a helpful assistant."},
|
||||
{Role: "user", Content: "Hello"},
|
||||
{Role: "assistant", Content: "Hi there!"},
|
||||
}
|
||||
tokens := e.EstimateMessages(messages)
|
||||
assert.Greater(t, tokens, 10)
|
||||
})
|
||||
}
|
||||
|
||||
func TestCompressContext(t *testing.T) {
|
||||
e := NewEstimator(0)
|
||||
|
||||
t.Run("no compression needed", func(t *testing.T) {
|
||||
messages := []chat.Message{
|
||||
{Role: "system", Content: "system prompt"},
|
||||
{Role: "user", Content: "hello"},
|
||||
}
|
||||
result := CompressContext(messages, e, 100000)
|
||||
assert.Equal(t, messages, result)
|
||||
})
|
||||
|
||||
t.Run("preserves system and last message", func(t *testing.T) {
|
||||
// Create messages that exceed the token limit
|
||||
messages := []chat.Message{
|
||||
{Role: "system", Content: "system prompt"},
|
||||
{Role: "user", Content: strings.Repeat("old message ", 1000)},
|
||||
{Role: "assistant", Content: strings.Repeat("old response ", 1000)},
|
||||
{Role: "user", Content: "current query"},
|
||||
}
|
||||
result := CompressContext(messages, e, 100) // very low limit to force compression
|
||||
require.GreaterOrEqual(t, len(result), 2)
|
||||
assert.Equal(t, "system", result[0].Role)
|
||||
assert.Equal(t, "current query", result[len(result)-1].Content)
|
||||
})
|
||||
|
||||
t.Run("keeps tool_call and tool_result paired", func(t *testing.T) {
|
||||
messages := []chat.Message{
|
||||
{Role: "system", Content: "system prompt"},
|
||||
// Old conversation
|
||||
{Role: "user", Content: strings.Repeat("x", 500)},
|
||||
{Role: "assistant", Content: strings.Repeat("y", 500)},
|
||||
// Tool interaction that should stay together
|
||||
{Role: "assistant", Content: "thinking", ToolCalls: []chat.ToolCall{
|
||||
{ID: "call_1", Function: chat.FunctionCall{Name: "search", Arguments: `{"q":"test"}`}},
|
||||
}},
|
||||
{Role: "tool", Content: strings.Repeat("result ", 100), ToolCallID: "call_1", Name: "search"},
|
||||
// Current query
|
||||
{Role: "user", Content: "what did you find?"},
|
||||
}
|
||||
|
||||
result := CompressContext(messages, e, 200) // force some compression
|
||||
|
||||
b, _ := json.Marshal(result)
|
||||
fmt.Println(string(b))
|
||||
|
||||
// Check that tool_call and tool_result are still paired
|
||||
for i, msg := range result {
|
||||
if msg.Role == "tool" {
|
||||
// The previous message should be an assistant with tool_calls
|
||||
require.Greater(t, i, 0)
|
||||
assert.Equal(t, "assistant", result[i-1].Role)
|
||||
assert.Greater(t, len(result[i-1].ToolCalls), 0)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("zero maxTokens returns unchanged", func(t *testing.T) {
|
||||
messages := []chat.Message{
|
||||
{Role: "system", Content: "system"},
|
||||
{Role: "user", Content: "hello"},
|
||||
}
|
||||
result := CompressContext(messages, e, 0)
|
||||
assert.Equal(t, messages, result)
|
||||
})
|
||||
|
||||
t.Run("two messages returns unchanged", func(t *testing.T) {
|
||||
messages := []chat.Message{
|
||||
{Role: "system", Content: "system"},
|
||||
{Role: "user", Content: "hello"},
|
||||
}
|
||||
result := CompressContext(messages, e, 1) // even with tiny limit
|
||||
assert.Equal(t, messages, result)
|
||||
})
|
||||
}
|
||||
|
||||
func TestGroupToolMessages(t *testing.T) {
|
||||
t.Run("standalone messages", func(t *testing.T) {
|
||||
messages := []chat.Message{
|
||||
{Role: "user", Content: "hello"},
|
||||
{Role: "assistant", Content: "hi"},
|
||||
}
|
||||
groups := groupToolMessages(messages)
|
||||
assert.Len(t, groups, 2)
|
||||
})
|
||||
|
||||
t.Run("tool call with results grouped", func(t *testing.T) {
|
||||
messages := []chat.Message{
|
||||
{Role: "user", Content: "search for X"},
|
||||
{Role: "assistant", Content: "thinking", ToolCalls: []chat.ToolCall{
|
||||
{ID: "call_1", Function: chat.FunctionCall{Name: "search"}},
|
||||
{ID: "call_2", Function: chat.FunctionCall{Name: "fetch"}},
|
||||
}},
|
||||
{Role: "tool", Content: "result1", ToolCallID: "call_1"},
|
||||
{Role: "tool", Content: "result2", ToolCallID: "call_2"},
|
||||
{Role: "user", Content: "thanks"},
|
||||
}
|
||||
groups := groupToolMessages(messages)
|
||||
assert.Len(t, groups, 3) // user, (assistant+2 tools), user
|
||||
assert.Len(t, groups[1], 3) // assistant + 2 tool results
|
||||
b, _ := json.Marshal(groups)
|
||||
fmt.Println(string(b))
|
||||
})
|
||||
}
|
||||
@@ -0,0 +1,234 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// ValidationError describes a specific parameter validation failure.
|
||||
type ValidationError struct {
|
||||
Param string // parameter name (or "" for top-level errors)
|
||||
Message string // human-readable error description
|
||||
}
|
||||
|
||||
// ValidateParams checks args against the JSON Schema declared by tool.Parameters().
|
||||
// Returns nil if valid, or a list of validation errors.
|
||||
//
|
||||
// Supported checks:
|
||||
// - required: ensures all required fields are present and non-null
|
||||
// - type: verifies the JSON type matches (string, number, integer, boolean, array, object)
|
||||
// - enum: checks the value is in the allowed set
|
||||
// - minimum / maximum: numeric bounds
|
||||
// - minLength / maxLength: string length bounds
|
||||
func ValidateParams(args json.RawMessage, schema json.RawMessage) []ValidationError {
|
||||
if len(schema) == 0 || len(args) == 0 {
|
||||
return nil
|
||||
}
|
||||
|
||||
var schemaDef map[string]any
|
||||
if err := json.Unmarshal(schema, &schemaDef); err != nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
properties, _ := schemaDef["properties"].(map[string]any)
|
||||
if len(properties) == 0 {
|
||||
return nil
|
||||
}
|
||||
|
||||
var argsMap map[string]any
|
||||
if err := json.Unmarshal(args, &argsMap); err != nil {
|
||||
return nil
|
||||
}
|
||||
|
||||
var errs []ValidationError
|
||||
|
||||
// Check required fields
|
||||
if reqRaw, ok := schemaDef["required"]; ok {
|
||||
if reqList, ok := reqRaw.([]any); ok {
|
||||
for _, r := range reqList {
|
||||
fieldName, ok := r.(string)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
val, exists := argsMap[fieldName]
|
||||
if !exists || val == nil {
|
||||
errs = append(errs, ValidationError{
|
||||
Param: fieldName,
|
||||
Message: fmt.Sprintf("required parameter '%s' is missing", fieldName),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Validate each provided argument against its property schema
|
||||
for key, val := range argsMap {
|
||||
propDef, exists := properties[key]
|
||||
if !exists {
|
||||
continue // extra params are allowed (LLMs sometimes add them)
|
||||
}
|
||||
prop, ok := propDef.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
|
||||
propErrs := validateProperty(key, val, prop)
|
||||
errs = append(errs, propErrs...)
|
||||
}
|
||||
|
||||
return errs
|
||||
}
|
||||
|
||||
// validateProperty validates a single parameter value against its schema definition.
|
||||
func validateProperty(name string, val any, prop map[string]any) []ValidationError {
|
||||
if val == nil {
|
||||
return nil // nil values are handled by required check
|
||||
}
|
||||
|
||||
var errs []ValidationError
|
||||
|
||||
targetType, _ := prop["type"].(string)
|
||||
|
||||
// Type check
|
||||
if targetType != "" && !checkType(val, targetType) {
|
||||
errs = append(errs, ValidationError{
|
||||
Param: name,
|
||||
Message: fmt.Sprintf("parameter '%s' should be type '%s'", name, targetType),
|
||||
})
|
||||
return errs // skip further checks if type is wrong
|
||||
}
|
||||
|
||||
// Enum check
|
||||
if enumRaw, ok := prop["enum"]; ok {
|
||||
if enumList, ok := enumRaw.([]any); ok && len(enumList) > 0 {
|
||||
if !isInEnum(val, enumList) {
|
||||
allowed := formatEnum(enumList)
|
||||
errs = append(errs, ValidationError{
|
||||
Param: name,
|
||||
Message: fmt.Sprintf("parameter '%s' must be one of [%s]", name, allowed),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Numeric bounds
|
||||
if targetType == "number" || targetType == "integer" {
|
||||
numVal := toFloat64(val)
|
||||
if minVal, ok := getFloat(prop, "minimum"); ok && numVal < minVal {
|
||||
errs = append(errs, ValidationError{
|
||||
Param: name,
|
||||
Message: fmt.Sprintf("parameter '%s' must be >= %v", name, minVal),
|
||||
})
|
||||
}
|
||||
if maxVal, ok := getFloat(prop, "maximum"); ok && numVal > maxVal {
|
||||
errs = append(errs, ValidationError{
|
||||
Param: name,
|
||||
Message: fmt.Sprintf("parameter '%s' must be <= %v", name, maxVal),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// String length bounds
|
||||
if targetType == "string" {
|
||||
if s, ok := val.(string); ok {
|
||||
if minLen, ok := getFloat(prop, "minLength"); ok && float64(len(s)) < minLen {
|
||||
errs = append(errs, ValidationError{
|
||||
Param: name,
|
||||
Message: fmt.Sprintf("parameter '%s' must have at least %d characters",
|
||||
name, int(minLen)),
|
||||
})
|
||||
}
|
||||
if maxLen, ok := getFloat(prop, "maxLength"); ok && float64(len(s)) > maxLen {
|
||||
errs = append(errs, ValidationError{
|
||||
Param: name,
|
||||
Message: fmt.Sprintf("parameter '%s' must have at most %d characters",
|
||||
name, int(maxLen)),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return errs
|
||||
}
|
||||
|
||||
// checkType verifies that val matches the expected JSON Schema type.
|
||||
func checkType(val any, targetType string) bool {
|
||||
switch targetType {
|
||||
case "string":
|
||||
_, ok := val.(string)
|
||||
return ok
|
||||
case "number":
|
||||
_, ok := val.(float64)
|
||||
return ok
|
||||
case "integer":
|
||||
f, ok := val.(float64)
|
||||
return ok && f == float64(int64(f))
|
||||
case "boolean":
|
||||
_, ok := val.(bool)
|
||||
return ok
|
||||
case "array":
|
||||
_, ok := val.([]any)
|
||||
return ok
|
||||
case "object":
|
||||
_, ok := val.(map[string]any)
|
||||
return ok
|
||||
default:
|
||||
return true // unknown type, don't reject
|
||||
}
|
||||
}
|
||||
|
||||
// isInEnum checks if val matches any value in the enum list.
|
||||
func isInEnum(val any, enumList []any) bool {
|
||||
for _, e := range enumList {
|
||||
if fmt.Sprintf("%v", val) == fmt.Sprintf("%v", e) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// formatEnum formats enum values for error messages.
|
||||
func formatEnum(enumList []any) string {
|
||||
parts := make([]string, len(enumList))
|
||||
for i, e := range enumList {
|
||||
parts[i] = fmt.Sprintf("%v", e)
|
||||
}
|
||||
return strings.Join(parts, ", ")
|
||||
}
|
||||
|
||||
// getFloat extracts a float64 value from a map by key.
|
||||
func getFloat(m map[string]any, key string) (float64, bool) {
|
||||
v, ok := m[key]
|
||||
if !ok {
|
||||
return 0, false
|
||||
}
|
||||
f, ok := v.(float64)
|
||||
return f, ok
|
||||
}
|
||||
|
||||
// toFloat64 converts a numeric value to float64.
|
||||
func toFloat64(val any) float64 {
|
||||
switch v := val.(type) {
|
||||
case float64:
|
||||
return v
|
||||
case int64:
|
||||
return float64(v)
|
||||
case int:
|
||||
return float64(v)
|
||||
default:
|
||||
return 0
|
||||
}
|
||||
}
|
||||
|
||||
// FormatValidationErrors formats a list of validation errors into a human-readable string.
|
||||
func FormatValidationErrors(errs []ValidationError) string {
|
||||
if len(errs) == 0 {
|
||||
return ""
|
||||
}
|
||||
msgs := make([]string, len(errs))
|
||||
for i, e := range errs {
|
||||
msgs[i] = e.Message
|
||||
}
|
||||
return "Parameter validation failed: " + strings.Join(msgs, "; ")
|
||||
}
|
||||
@@ -0,0 +1,144 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"testing"
|
||||
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestValidateParams(t *testing.T) {
|
||||
schema := json.RawMessage(`{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"query": {"type": "string", "minLength": 1},
|
||||
"limit": {"type": "integer", "minimum": 1, "maximum": 100},
|
||||
"mode": {"type": "string", "enum": ["fast", "deep"]},
|
||||
"score": {"type": "number", "minimum": 0, "maximum": 1},
|
||||
"enabled": {"type": "boolean"}
|
||||
},
|
||||
"required": ["query"]
|
||||
}`)
|
||||
|
||||
t.Run("valid params pass", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": "hello", "limit": 10, "mode": "fast"}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
assert.Empty(t, errs)
|
||||
})
|
||||
|
||||
t.Run("missing required field", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"limit": 10}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
require.Len(t, errs, 1)
|
||||
assert.Equal(t, "query", errs[0].Param)
|
||||
assert.Contains(t, errs[0].Message, "required")
|
||||
})
|
||||
|
||||
t.Run("null required field", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": null}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
require.Len(t, errs, 1)
|
||||
assert.Contains(t, errs[0].Message, "required")
|
||||
})
|
||||
|
||||
t.Run("wrong type", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": 123}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
require.Len(t, errs, 1)
|
||||
assert.Equal(t, "query", errs[0].Param)
|
||||
assert.Contains(t, errs[0].Message, "type")
|
||||
})
|
||||
|
||||
t.Run("enum violation", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": "test", "mode": "slow"}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
require.Len(t, errs, 1)
|
||||
assert.Equal(t, "mode", errs[0].Param)
|
||||
assert.Contains(t, errs[0].Message, "one of")
|
||||
})
|
||||
|
||||
t.Run("minimum violation", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": "test", "limit": 0}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
require.Len(t, errs, 1)
|
||||
assert.Equal(t, "limit", errs[0].Param)
|
||||
assert.Contains(t, errs[0].Message, ">= 1")
|
||||
})
|
||||
|
||||
t.Run("maximum violation", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": "test", "limit": 200}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
require.Len(t, errs, 1)
|
||||
assert.Equal(t, "limit", errs[0].Param)
|
||||
assert.Contains(t, errs[0].Message, "<= 100")
|
||||
})
|
||||
|
||||
t.Run("minLength violation", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": ""}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
require.Len(t, errs, 1)
|
||||
assert.Equal(t, "query", errs[0].Param)
|
||||
assert.Contains(t, errs[0].Message, "at least 1 characters")
|
||||
})
|
||||
|
||||
t.Run("number bounds", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": "test", "score": 1.5}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
require.Len(t, errs, 1)
|
||||
assert.Equal(t, "score", errs[0].Param)
|
||||
})
|
||||
|
||||
t.Run("multiple errors", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"limit": -1, "mode": "invalid"}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
assert.GreaterOrEqual(t, len(errs), 3) // missing query + limit min + mode enum
|
||||
})
|
||||
|
||||
t.Run("extra params allowed", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": "test", "unknown_param": "value"}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
assert.Empty(t, errs)
|
||||
})
|
||||
|
||||
t.Run("nil schema returns nil", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": "test"}`)
|
||||
errs := ValidateParams(args, nil)
|
||||
assert.Nil(t, errs)
|
||||
})
|
||||
|
||||
t.Run("empty args returns nil", func(t *testing.T) {
|
||||
errs := ValidateParams(nil, schema)
|
||||
assert.Nil(t, errs)
|
||||
})
|
||||
|
||||
t.Run("boolean type check", func(t *testing.T) {
|
||||
args := json.RawMessage(`{"query": "test", "enabled": "yes"}`)
|
||||
errs := ValidateParams(args, schema)
|
||||
require.Len(t, errs, 1)
|
||||
assert.Equal(t, "enabled", errs[0].Param)
|
||||
assert.Contains(t, errs[0].Message, "boolean")
|
||||
})
|
||||
}
|
||||
|
||||
func TestFormatValidationErrors(t *testing.T) {
|
||||
t.Run("empty errors", func(t *testing.T) {
|
||||
assert.Equal(t, "", FormatValidationErrors(nil))
|
||||
})
|
||||
|
||||
t.Run("single error", func(t *testing.T) {
|
||||
errs := []ValidationError{{Param: "q", Message: "required parameter 'q' is missing"}}
|
||||
result := FormatValidationErrors(errs)
|
||||
assert.Contains(t, result, "Parameter validation failed")
|
||||
assert.Contains(t, result, "required parameter 'q' is missing")
|
||||
})
|
||||
|
||||
t.Run("multiple errors joined", func(t *testing.T) {
|
||||
errs := []ValidationError{
|
||||
{Param: "a", Message: "error a"},
|
||||
{Param: "b", Message: "error b"},
|
||||
}
|
||||
result := FormatValidationErrors(errs)
|
||||
assert.Contains(t, result, "error a; error b")
|
||||
})
|
||||
}
|
||||
@@ -15,7 +15,8 @@ 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
|
||||
tools map[string]types.Tool
|
||||
maxToolOutputSize int // maximum chars for tool output (0 = use DefaultMaxToolOutput)
|
||||
}
|
||||
|
||||
// NewToolRegistry creates a new tool registry
|
||||
@@ -25,6 +26,20 @@ func NewToolRegistry() *ToolRegistry {
|
||||
}
|
||||
}
|
||||
|
||||
// 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).
|
||||
@@ -95,7 +110,28 @@ func (r *ToolRegistry) ExecuteTool(
|
||||
// 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,
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"unicode/utf8"
|
||||
)
|
||||
|
||||
const (
|
||||
// DefaultMaxToolOutput is the default maximum character (rune) count for tool output.
|
||||
// Outputs exceeding this limit are truncated with head + tail preservation.
|
||||
// This counts Unicode characters (runes), not bytes, so CJK text is treated fairly.
|
||||
DefaultMaxToolOutput = 16000
|
||||
|
||||
// headRatio controls the head/tail split when truncating (70% head, 30% tail).
|
||||
headRatio = 0.7
|
||||
|
||||
// truncationMarkerReserve is the rune budget reserved for the truncation marker itself.
|
||||
truncationMarkerReserve = 200
|
||||
)
|
||||
|
||||
// TruncateToolOutput truncates tool output that exceeds maxChars runes, preserving
|
||||
// the head (70%) and tail (30%) sections with a truncation marker in between.
|
||||
// This prevents large tool results from consuming the entire LLM context window
|
||||
// while keeping the most useful parts (headers/summaries at the start, conclusions at the end).
|
||||
//
|
||||
// maxChars is counted in Unicode characters (runes), not bytes, ensuring consistent
|
||||
// behavior across English, Chinese, and other multi-byte character sets.
|
||||
//
|
||||
// If maxChars <= 0 or the output is within the limit, it is returned unchanged.
|
||||
func TruncateToolOutput(output string, maxChars int) string {
|
||||
runeCount := utf8.RuneCountInString(output)
|
||||
if maxChars <= 0 || runeCount <= maxChars {
|
||||
return output
|
||||
}
|
||||
|
||||
usable := maxChars - truncationMarkerReserve
|
||||
if usable <= 0 {
|
||||
return string([]rune(output)[:maxChars])
|
||||
}
|
||||
|
||||
headSize := int(float64(usable) * headRatio)
|
||||
tailSize := usable - headSize
|
||||
if tailSize <= 0 {
|
||||
tailSize = 0
|
||||
}
|
||||
|
||||
runes := []rune(output)
|
||||
marker := fmt.Sprintf(
|
||||
"\n\n... [output truncated: %d → %d chars, showing first %d + last %d] ...\n\n",
|
||||
runeCount, maxChars, headSize, tailSize,
|
||||
)
|
||||
|
||||
if tailSize == 0 {
|
||||
return string(runes[:headSize]) + marker
|
||||
}
|
||||
return string(runes[:headSize]) + marker + string(runes[len(runes)-tailSize:])
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
package tools
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
"unicode/utf8"
|
||||
|
||||
"github.com/stretchr/testify/assert"
|
||||
)
|
||||
|
||||
func TestTruncateToolOutput(t *testing.T) {
|
||||
t.Run("short output unchanged", func(t *testing.T) {
|
||||
input := "hello world"
|
||||
result := TruncateToolOutput(input, 1000)
|
||||
assert.Equal(t, input, result)
|
||||
})
|
||||
|
||||
t.Run("exact limit unchanged", func(t *testing.T) {
|
||||
input := strings.Repeat("a", 16000)
|
||||
result := TruncateToolOutput(input, 16000)
|
||||
assert.Equal(t, input, result)
|
||||
})
|
||||
|
||||
t.Run("zero maxChars returns unchanged", func(t *testing.T) {
|
||||
input := strings.Repeat("a", 100)
|
||||
result := TruncateToolOutput(input, 0)
|
||||
assert.Equal(t, input, result)
|
||||
})
|
||||
|
||||
t.Run("negative maxChars returns unchanged", func(t *testing.T) {
|
||||
input := strings.Repeat("a", 100)
|
||||
result := TruncateToolOutput(input, -1)
|
||||
assert.Equal(t, input, result)
|
||||
})
|
||||
|
||||
t.Run("large output truncated with marker", func(t *testing.T) {
|
||||
input := strings.Repeat("H", 10000) + strings.Repeat("T", 10000)
|
||||
result := TruncateToolOutput(input, 5000)
|
||||
|
||||
runeCount := utf8.RuneCountInString(result)
|
||||
assert.LessOrEqual(t, runeCount, 5000+truncationMarkerReserve,
|
||||
"truncated output rune count should be within limits")
|
||||
assert.True(t, strings.HasPrefix(result, "HHHH"),
|
||||
"should preserve head content")
|
||||
assert.True(t, strings.HasSuffix(result, "TTTT"),
|
||||
"should preserve tail content")
|
||||
assert.Contains(t, result, "output truncated")
|
||||
assert.Contains(t, result, "20000 → 5000 chars")
|
||||
})
|
||||
|
||||
t.Run("50k output truncated to 16k default", func(t *testing.T) {
|
||||
input := strings.Repeat("x", 50000)
|
||||
result := TruncateToolOutput(input, DefaultMaxToolOutput)
|
||||
|
||||
runeCount := utf8.RuneCountInString(result)
|
||||
assert.Less(t, runeCount, DefaultMaxToolOutput+truncationMarkerReserve)
|
||||
assert.Contains(t, result, "output truncated")
|
||||
})
|
||||
|
||||
t.Run("head and tail are from correct positions", func(t *testing.T) {
|
||||
head := strings.Repeat("A", 5000)
|
||||
mid := strings.Repeat("B", 5000)
|
||||
tail := strings.Repeat("C", 5000)
|
||||
input := head + mid + tail
|
||||
result := TruncateToolOutput(input, 5000)
|
||||
|
||||
assert.True(t, strings.HasPrefix(result, "AAAA"))
|
||||
assert.True(t, strings.HasSuffix(result, "CCCC"))
|
||||
})
|
||||
|
||||
t.Run("Chinese text truncated by rune count not bytes", func(t *testing.T) {
|
||||
// Each Chinese character is 3 bytes in UTF-8 but 1 rune.
|
||||
// 10000 Chinese chars = 30000 bytes. With maxChars=5000 runes,
|
||||
// the result should have ~5000 runes, not be cut at 5000 bytes.
|
||||
head := strings.Repeat("你", 5000)
|
||||
tail := strings.Repeat("好", 5000)
|
||||
input := head + tail
|
||||
result := TruncateToolOutput(input, 5000)
|
||||
|
||||
resultRunes := utf8.RuneCountInString(result)
|
||||
assert.LessOrEqual(t, resultRunes, 5000+truncationMarkerReserve,
|
||||
"should truncate by rune count, not byte count")
|
||||
assert.True(t, strings.HasPrefix(result, "你你你"),
|
||||
"should preserve Chinese head content")
|
||||
assert.True(t, strings.HasSuffix(result, "好好好"),
|
||||
"should preserve Chinese tail content")
|
||||
assert.Contains(t, result, "10000 → 5000 chars")
|
||||
})
|
||||
|
||||
t.Run("mixed CJK and ASCII", func(t *testing.T) {
|
||||
// Mix of 1-byte and 3-byte chars
|
||||
input := strings.Repeat("a", 3000) + strings.Repeat("中", 3000) +
|
||||
strings.Repeat("b", 3000) + strings.Repeat("文", 3000)
|
||||
result := TruncateToolOutput(input, 5000)
|
||||
|
||||
resultRunes := utf8.RuneCountInString(result)
|
||||
assert.LessOrEqual(t, resultRunes, 5000+truncationMarkerReserve)
|
||||
assert.True(t, strings.HasPrefix(result, "aaa"))
|
||||
assert.True(t, strings.HasSuffix(result, "文文文"))
|
||||
})
|
||||
|
||||
t.Run("CJK within limit unchanged", func(t *testing.T) {
|
||||
input := strings.Repeat("测", 100)
|
||||
result := TruncateToolOutput(input, 200)
|
||||
assert.Equal(t, input, result)
|
||||
})
|
||||
}
|
||||
@@ -102,6 +102,11 @@ func (s *agentService) CreateAgentEngine(
|
||||
// Create tool registry
|
||||
toolRegistry := tools.NewToolRegistry()
|
||||
|
||||
// Apply configurable tool output size limit
|
||||
if config.MaxToolOutputChars > 0 {
|
||||
toolRegistry.SetMaxToolOutputSize(config.MaxToolOutputChars)
|
||||
}
|
||||
|
||||
// Register tools
|
||||
if err := s.registerTools(ctx, toolRegistry, config, rerankModel, chatModel, sessionID); err != nil {
|
||||
return nil, fmt.Errorf("failed to register tools: %w", err)
|
||||
|
||||
@@ -43,6 +43,15 @@ type AgentConfig struct {
|
||||
VLMModelID string `json:"-"` // VLM model ID for tool result image analysis (set from CustomAgent config)
|
||||
// LLM call timeout in seconds (default: 120). Controls the maximum time for a single LLM call.
|
||||
LLMCallTimeout int `json:"llm_call_timeout,omitempty"`
|
||||
|
||||
// Maximum character length for tool output (default: 16000).
|
||||
// Outputs exceeding this limit are truncated with head + tail preservation.
|
||||
MaxToolOutputChars int `json:"max_tool_output_chars,omitempty"`
|
||||
|
||||
// Maximum context window tokens for the agent (default: 0 = disabled).
|
||||
// When set, the agent compresses older messages to stay within this limit,
|
||||
// preserving tool_call/tool_result pairs.
|
||||
MaxContextTokens int `json:"max_context_tokens,omitempty"`
|
||||
}
|
||||
|
||||
// SessionAgentConfig represents session-level agent configuration
|
||||
|
||||
Reference in New Issue
Block a user