feat(agent): implement core agent functionalities and context management

- Introduced the AgentEngine with methods for executing tool calls, managing context windows, and handling final answer generation.
- Added functionality to stream LLM responses and tool results through the EventBus, enhancing real-time interaction.
- Implemented context management to consolidate messages and prevent exceeding token limits, ensuring efficient use of context.
- Enhanced error handling and logging for tool execution and response analysis, improving robustness and traceability.
- Added unit tests to validate the new functionalities and ensure reliability in agent operations.
This commit is contained in:
wizardchen
2026-03-19 23:12:47 +08:00
committed by lyingbug
parent 2f7e3a8ac1
commit 637376428e
6 changed files with 1105 additions and 1014 deletions
+201
View File
@@ -0,0 +1,201 @@
package agent
import (
"context"
"encoding/json"
"fmt"
"time"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
"github.com/Tencent/WeKnora/internal/common"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types"
)
// executeToolCalls runs every tool call in the LLM response, appending results to step.ToolCalls.
// It also emits tool-call and tool-result events, and optionally runs reflection after each call.
func (e *AgentEngine) executeToolCalls(
ctx context.Context, response *types.ChatResponse,
step *types.AgentStep, iteration int, sessionID string,
) {
if len(response.ToolCalls) == 0 {
return
}
round := iteration + 1
logger.Infof(ctx, "[Agent][Round-%d] Executing %d tool call(s)", round, len(response.ToolCalls))
for i, tc := range response.ToolCalls {
// Normalize tool call ID for cross-provider compatibility
tc.ID = agenttools.NormalizeToolCallID(tc.ID, tc.Function.Name, i)
toolTag := fmt.Sprintf("[Agent][Round-%d][Tool %s (%d/%d)]",
round, tc.Function.Name, i+1, len(response.ToolCalls))
var args map[string]any
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, "%s Failed to parse arguments (repair failed): %v", toolTag, err)
step.ToolCalls = append(step.ToolCalls, 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.]",
},
})
continue
}
logger.Warnf(ctx, "%s Repaired malformed JSON arguments", toolTag)
tc.Function.Arguments = repaired
}
logger.Debugf(ctx, "%s Args: %s", toolTag, tc.Function.Arguments)
toolCallStartTime := time.Now()
e.eventBus.Emit(ctx, event.Event{
ID: tc.ID + "-tool-call",
Type: event.EventAgentToolCall,
SessionID: sessionID,
Data: event.AgentToolCallData{
ToolCallID: tc.ID,
ToolName: tc.Function.Name,
Arguments: args,
Iteration: iteration,
},
})
// Execute tool with timeout to prevent indefinite hangs
common.PipelineInfo(ctx, "Agent", "tool_call_start", map[string]interface{}{
"iteration": iteration,
"round": round,
"tool": tc.Function.Name,
"tool_call_id": tc.ID,
"tool_index": fmt.Sprintf("%d/%d", i+1, len(response.ToolCalls)),
})
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()
toolCall := types.ToolCall{
ID: tc.ID,
Name: tc.Function.Name,
Args: args,
Result: result,
Duration: duration,
}
if err != nil {
logger.Errorf(ctx, "%s Failed in %dms: %v", toolTag, duration, err)
toolCall.Result = &types.ToolResult{
Success: false,
Error: err.Error(),
}
} else {
success := result != nil && result.Success
outputLen := 0
if result != nil {
outputLen = len(result.Output)
}
logger.Infof(ctx, "%s Completed in %dms: success=%v, output=%d chars",
toolTag, duration, success, outputLen)
}
// Pipeline event for monitoring
toolSuccess := toolCall.Result != nil && toolCall.Result.Success
pipelineFields := map[string]interface{}{
"iteration": iteration,
"round": round,
"tool": tc.Function.Name,
"tool_call_id": tc.ID,
"duration_ms": duration,
"success": toolSuccess,
}
if toolCall.Result != nil && toolCall.Result.Error != "" {
pipelineFields["error"] = toolCall.Result.Error
}
if err != nil {
common.PipelineError(ctx, "Agent", "tool_call_result", pipelineFields)
} else if toolSuccess {
common.PipelineInfo(ctx, "Agent", "tool_call_result", pipelineFields)
} else {
common.PipelineWarn(ctx, "Agent", "tool_call_result", pipelineFields)
}
// Debug-level output preview
if toolCall.Result != nil && toolCall.Result.Output != "" {
preview := toolCall.Result.Output
if len(preview) > 500 {
preview = preview[:500] + "... (truncated)"
}
logger.Debugf(ctx, "%s Output preview:\n%s", toolTag, preview)
}
if toolCall.Result != nil && toolCall.Result.Error != "" {
logger.Debugf(ctx, "%s Tool error: %s", toolTag, toolCall.Result.Error)
}
// Store tool call
step.ToolCalls = append(step.ToolCalls, toolCall)
// Emit tool result event (include structured data from tool result)
e.eventBus.Emit(ctx, event.Event{
ID: tc.ID + "-tool-result",
Type: event.EventAgentToolResult,
SessionID: sessionID,
Data: event.AgentToolResultData{
ToolCallID: tc.ID,
ToolName: tc.Function.Name,
Output: result.Output,
Error: result.Error,
Success: result.Success,
Duration: duration,
Iteration: iteration,
Data: result.Data, // Pass structured data for frontend rendering
},
})
// Emit tool execution event (for internal monitoring)
e.eventBus.Emit(ctx, event.Event{
ID: tc.ID + "-tool-exec",
Type: event.EventAgentTool,
SessionID: sessionID,
Data: event.AgentActionData{
Iteration: iteration,
ToolName: tc.Function.Name,
ToolInput: args,
ToolOutput: result.Output,
Success: result.Success,
Error: result.Error,
Duration: duration,
},
})
// Optional: Reflection after each tool call (streaming)
if e.config.ReflectionEnabled && result != nil {
reflection, err := e.streamReflectionToEventBus(
ctx, tc.ID, tc.Function.Name, result.Output,
iteration, sessionID,
)
if err != nil {
logger.Warnf(ctx, "Reflection failed: %v", err)
} else if reflection != "" {
// Store reflection in the corresponding tool call
// Find the tool call we just added and update it
if len(step.ToolCalls) > 0 {
lastIdx := len(step.ToolCalls) - 1
step.ToolCalls[lastIdx].Reflection = reflection
}
}
}
}
}
+55
View File
@@ -1,5 +1,13 @@
package agent
import (
"fmt"
"strings"
"time"
"github.com/google/uuid"
)
const (
// DefaultAgentTemperature is the default temperature for the agent
DefaultAgentTemperature = 0.7
@@ -9,4 +17,51 @@ const (
DefaultAgentReflectionEnabled = false
// DefaultUseCustomSystemPrompt is the default whether to use custom system prompt for the agent
DefaultUseCustomSystemPrompt = false
// defaultLLMCallTimeout is the default maximum time allowed for a single LLM call.
// This prevents a single slow call from consuming the entire pipeline deadline.
// 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
)
// transientErrorMarkers are substrings that indicate a transient (retryable) error.
var transientErrorMarkers = []string{
"429", "rate limit",
"500", "502", "503", "504",
"overloaded", "timeout", "timed out",
"connection", "server error", "temporarily unavailable",
}
// isTransientError checks whether an error is likely transient and worth retrying.
func isTransientError(err error) bool {
if err == nil {
return false
}
errStr := strings.ToLower(err.Error())
for _, marker := range transientErrorMarkers {
if strings.Contains(errStr, marker) {
return true
}
}
return false
}
// getLLMCallTimeout returns the configured LLM call timeout, falling back to default.
func (e *AgentEngine) getLLMCallTimeout() time.Duration {
if e.config.LLMCallTimeout > 0 {
return time.Duration(e.config.LLMCallTimeout) * time.Second
}
return defaultLLMCallTimeout
}
// generateEventID generates a unique event ID with type suffix for better traceability
func generateEventID(suffix string) string {
return fmt.Sprintf("%s-%s", uuid.New().String()[:8], suffix)
}
+28 -1014
View File
File diff suppressed because it is too large Load Diff
+174
View File
@@ -0,0 +1,174 @@
package agent
import (
"context"
"fmt"
"time"
"github.com/Tencent/WeKnora/internal/common"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/Tencent/WeKnora/internal/types"
)
// streamFinalAnswerToEventBus streams the final answer generation through EventBus
func (e *AgentEngine) streamFinalAnswerToEventBus(
ctx context.Context,
query string,
state *types.AgentState,
sessionID string,
) error {
totalToolCalls := countTotalToolCalls(state.RoundSteps)
logger.Infof(ctx, "[Agent][FinalAnswer] Synthesizing from %d steps, %d tool calls",
len(state.RoundSteps), totalToolCalls)
common.PipelineInfo(ctx, "Agent", "final_answer_start", map[string]interface{}{
"session_id": sessionID,
"query": query,
"steps": len(state.RoundSteps),
"tool_results": totalToolCalls,
})
// Build messages with all context
language := types.LanguageNameFromContext(ctx)
systemPrompt := BuildSystemPromptWithOptions(
e.knowledgeBasesInfo,
e.config.WebSearchEnabled,
e.selectedDocs,
&BuildSystemPromptOptions{
Language: language,
Config: e.appConfig,
},
e.systemPromptTemplate,
)
messages := []chat.Message{
{Role: "system", Content: systemPrompt},
{Role: "user", Content: query},
}
// Add all tool call results as context
toolResultCount := 0
for stepIdx, step := range state.RoundSteps {
for toolIdx, toolCall := range step.ToolCalls {
toolResultCount++
messages = append(messages, chat.Message{
Role: "user",
Content: fmt.Sprintf("Tool %s returned: %s", toolCall.Name, toolCall.Result.Output),
})
logger.Debugf(ctx, "[Agent][FinalAnswer] Added tool result [Step-%d][Tool-%d]: %s (output: %d chars)",
stepIdx+1, toolIdx+1, toolCall.Name, len(toolCall.Result.Output))
}
}
logger.Debugf(ctx, "[Agent][FinalAnswer] Built context: %d messages, %d tool results",
len(messages), toolResultCount)
// Add final answer prompt
finalPrompt := fmt.Sprintf(`Based on the above tool call results, generate a complete answer for the user's question.
User question: %s
Requirements:
1. Answer based on the actually retrieved content
2. Clearly cite information sources (chunk_id, document name)
3. Organize the answer in a structured format
4. If information is insufficient, honestly state so
5. IMPORTANT: Respond in the same language as the user's question
Now generate the final answer:`, query)
messages = append(messages, chat.Message{
Role: "user",
Content: finalPrompt,
})
// Generate a single ID for this entire final answer stream
answerID := generateEventID("answer")
logger.Debugf(ctx, "[Agent][FinalAnswer] AnswerID: %s", answerID)
fullAnswer, _, err := e.streamLLMToEventBus(
ctx,
messages,
&chat.ChatOptions{Temperature: e.config.Temperature, Thinking: e.config.Thinking},
func(chunk *types.StreamResponse, fullContent string) {
if chunk.Content != "" {
logger.Debugf(ctx, "[Agent][FinalAnswer] Emitting answer chunk: %d chars", len(chunk.Content))
e.eventBus.Emit(ctx, event.Event{
ID: answerID, // Same ID for all chunks in this stream
Type: event.EventAgentFinalAnswer,
SessionID: sessionID,
Data: event.AgentFinalAnswerData{
Content: chunk.Content,
Done: chunk.Done,
},
})
}
},
)
if err != nil {
logger.Errorf(ctx, "[Agent][FinalAnswer] Final answer generation failed: %v", err)
common.PipelineError(ctx, "Agent", "final_answer_stream_failed", map[string]interface{}{
"session_id": sessionID,
"error": err.Error(),
})
return err
}
logger.Infof(ctx, "[Agent][FinalAnswer] Final answer generated: %d characters", len(fullAnswer))
common.PipelineInfo(ctx, "Agent", "final_answer_done", map[string]interface{}{
"session_id": sessionID,
"answer_len": len(fullAnswer),
})
state.FinalAnswer = fullAnswer
return nil
}
// handleMaxIterations generates a final answer when the agent loop exhausted all iterations
// without the LLM producing a natural stop. It marks state.IsComplete = true.
func (e *AgentEngine) handleMaxIterations(
ctx context.Context, query string, state *types.AgentState, sessionID string,
) {
logger.Info(ctx, "Reached max iterations, generating final answer")
common.PipelineWarn(ctx, "Agent", "max_iterations_reached", map[string]interface{}{
"iterations": state.CurrentRound,
"max": e.config.MaxIterations,
})
// Stream final answer generation through EventBus
if err := e.streamFinalAnswerToEventBus(ctx, query, state, sessionID); err != nil {
logger.Errorf(ctx, "Failed to synthesize final answer: %v", err)
common.PipelineError(ctx, "Agent", "final_answer_failed", map[string]interface{}{
"error": err.Error(),
})
state.FinalAnswer = "Sorry, I was unable to generate a complete answer."
}
state.IsComplete = true
}
// emitCompletionEvent emits the EventAgentComplete event with execution summary.
func (e *AgentEngine) emitCompletionEvent(
ctx context.Context, state *types.AgentState, sessionID, messageID string, startTime time.Time,
) {
// Convert knowledge refs to interface{} slice for event data
knowledgeRefsInterface := make([]interface{}, 0, len(state.KnowledgeRefs))
for _, ref := range state.KnowledgeRefs {
knowledgeRefsInterface = append(knowledgeRefsInterface, ref)
}
e.eventBus.Emit(ctx, event.Event{
ID: generateEventID("complete"),
Type: event.EventAgentComplete,
SessionID: sessionID,
Data: event.AgentCompleteData{
FinalAnswer: state.FinalAnswer,
KnowledgeRefs: knowledgeRefsInterface,
AgentSteps: state.RoundSteps, // Include detailed execution steps for message storage
TotalSteps: len(state.RoundSteps),
TotalDurationMs: time.Since(startTime).Milliseconds(),
MessageID: messageID, // Include message ID for proper message update
},
})
logger.Infof(ctx, "Agent execution completed in %d rounds", state.CurrentRound)
}
+291
View File
@@ -0,0 +1,291 @@
package agent
import (
"context"
"encoding/json"
"fmt"
"time"
agenttoken "github.com/Tencent/WeKnora/internal/agent/token"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
"github.com/Tencent/WeKnora/internal/common"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/Tencent/WeKnora/internal/types"
)
// manageContextWindow consolidates or compresses messages if approaching the token limit.
// It returns the (possibly shortened) message slice.
func (e *AgentEngine) manageContextWindow(ctx context.Context, messages []chat.Message, round int) []chat.Message {
if e.config.MaxContextTokens <= 0 {
return messages
}
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",
round)
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", round, 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)",
round, beforeLen, len(messages), e.config.MaxContextTokens)
}
return messages
}
// responseVerdict captures the result of analyzing an LLM response to determine
// whether the agent loop should stop and what the final answer is (if any).
type responseVerdict struct {
isDone bool
finalAnswer string
step types.AgentStep
}
// analyzeResponse inspects the LLM response for stop conditions:
// - finish_reason == "stop" with no tool calls → agent is done (natural stop)
// - final_answer tool call present → agent is done (explicit tool)
//
// It returns a responseVerdict. If isDone is true the caller should break out of the loop.
func (e *AgentEngine) analyzeResponse(
ctx context.Context, response *types.ChatResponse,
step types.AgentStep, iteration int, sessionID string, roundStart time.Time,
) responseVerdict {
// Case 1: LLM stopped naturally without requesting any tool calls
if response.FinishReason == "stop" && len(response.ToolCalls) == 0 {
logger.Infof(ctx, "[Agent][Round-%d] Agent finished naturally: answer=%d chars, duration=%dms",
iteration+1, len(response.Content), time.Since(roundStart).Milliseconds())
common.PipelineInfo(ctx, "Agent", "round_final_answer", map[string]interface{}{
"iteration": iteration,
"round": iteration + 1,
"answer_len": len(response.Content),
})
// Emit answer as final answer event (thinking events were already streamed)
answerID := generateEventID("answer")
if response.Content != "" {
e.eventBus.Emit(ctx, event.Event{
ID: answerID,
Type: event.EventAgentFinalAnswer,
SessionID: sessionID,
Data: event.AgentFinalAnswerData{
Content: response.Content,
Done: false,
},
})
}
e.eventBus.Emit(ctx, event.Event{
ID: answerID,
Type: event.EventAgentFinalAnswer,
SessionID: sessionID,
Data: event.AgentFinalAnswerData{
Content: "",
Done: true,
},
})
return responseVerdict{
isDone: true,
finalAnswer: response.Content,
step: step,
}
}
// Case 2: final_answer tool call present
if len(response.ToolCalls) > 0 {
for _, tc := range response.ToolCalls {
if tc.Function.Name == agenttools.ToolFinalAnswer {
var faArgs struct {
Answer string `json:"answer"`
}
if err := json.Unmarshal([]byte(tc.Function.Arguments), &faArgs); err != nil {
logger.Warnf(ctx, "[Agent][Round-%d] Failed to parse final_answer args: %v",
iteration+1, err)
} else {
logger.Infof(ctx, "[Agent][Round-%d] final_answer tool: answer=%d chars, duration=%dms",
iteration+1, len(faArgs.Answer), time.Since(roundStart).Milliseconds())
e.eventBus.Emit(ctx, event.Event{
ID: generateEventID("answer-done"),
Type: event.EventAgentFinalAnswer,
SessionID: sessionID,
Data: event.AgentFinalAnswerData{
Content: "",
Done: true,
},
})
common.PipelineInfo(ctx, "Agent", "final_answer_tool", map[string]interface{}{
"iteration": iteration,
"round": iteration + 1,
"answer_len": len(faArgs.Answer),
})
return responseVerdict{
isDone: true,
finalAnswer: faArgs.Answer,
step: step,
}
}
break
}
}
}
// Not done — caller should continue the loop
return responseVerdict{isDone: false, step: step}
}
// listToolNames returns tool.function names for logging
func listToolNames(ts []chat.Tool) []string {
names := make([]string, 0, len(ts))
for _, t := range ts {
names = append(names, t.Function.Name)
}
return names
}
// buildToolsForLLM builds the tools list for LLM function calling
func (e *AgentEngine) buildToolsForLLM() []chat.Tool {
functionDefs := e.toolRegistry.GetFunctionDefinitions()
tools := make([]chat.Tool, 0, len(functionDefs))
for _, def := range functionDefs {
tools = append(tools, chat.Tool{
Type: "function",
Function: chat.FunctionDef{
Name: def.Name,
Description: def.Description,
Parameters: def.Parameters,
},
})
}
return tools
}
// appendToolResults adds tool results to the message history following OpenAI's tool calling format
// Also writes these messages to the context manager for persistence
func (e *AgentEngine) appendToolResults(
ctx context.Context,
messages []chat.Message,
step types.AgentStep,
) []chat.Message {
// Add assistant message with tool calls (if any)
if step.Thought != "" || len(step.ToolCalls) > 0 {
assistantMsg := chat.Message{
Role: "assistant",
Content: step.Thought,
}
// Add tool calls to assistant message (following OpenAI format)
if len(step.ToolCalls) > 0 {
assistantMsg.ToolCalls = make([]chat.ToolCall, 0, len(step.ToolCalls))
for _, tc := range step.ToolCalls {
// Convert arguments back to JSON string
argsJSON, _ := json.Marshal(tc.Args)
assistantMsg.ToolCalls = append(assistantMsg.ToolCalls, chat.ToolCall{
ID: tc.ID,
Type: "function",
Function: chat.FunctionCall{
Name: tc.Name,
Arguments: string(argsJSON),
},
})
}
}
messages = append(messages, assistantMsg)
// Write assistant message to context
if e.contextManager != nil {
if err := e.contextManager.AddMessage(ctx, e.sessionID, assistantMsg); err != nil {
logger.Warnf(ctx, "[Agent] Failed to add assistant message to context: %v", err)
} else {
logger.Debugf(ctx, "[Agent] Added assistant message to context (session: %s)", e.sessionID)
}
}
}
// Add tool result messages (role: "tool", following OpenAI format)
for _, toolCall := range step.ToolCalls {
resultContent := toolCall.Result.Output
if !toolCall.Result.Success {
resultContent = fmt.Sprintf("Error: %s", toolCall.Result.Error)
}
toolMsg := chat.Message{
Role: "tool",
Content: resultContent,
ToolCallID: toolCall.ID,
Name: toolCall.Name,
}
messages = append(messages, toolMsg)
// Write tool message to context
if e.contextManager != nil {
if err := e.contextManager.AddMessage(ctx, e.sessionID, toolMsg); err != nil {
logger.Warnf(ctx, "[Agent] Failed to add tool message to context: %v", err)
} else {
logger.Debugf(ctx, "[Agent] Added tool message to context (session: %s, tool: %s)", e.sessionID, toolCall.Name)
}
}
}
return messages
}
// countTotalToolCalls counts total tool calls across all steps
func countTotalToolCalls(steps []types.AgentStep) int {
total := 0
for _, step := range steps {
total += len(step.ToolCalls)
}
return total
}
// buildMessagesWithLLMContext builds the message array with LLM context
func (e *AgentEngine) buildMessagesWithLLMContext(
systemPrompt, currentQuery string,
llmContext []chat.Message,
imageURLs []string,
) []chat.Message {
messages := []chat.Message{
{Role: "system", Content: systemPrompt},
}
if len(llmContext) > 0 {
for _, msg := range llmContext {
if msg.Role == "system" {
continue
}
if msg.Role == "user" || msg.Role == "assistant" || msg.Role == "tool" {
messages = append(messages, msg)
}
}
logger.Infof(context.Background(), "Added %d history messages to context", len(llmContext))
}
userMsg := chat.Message{
Role: "user",
Content: currentQuery,
Images: imageURLs,
}
messages = append(messages, userMsg)
return messages
}
+356
View File
@@ -0,0 +1,356 @@
package agent
import (
"context"
"fmt"
"time"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
"github.com/Tencent/WeKnora/internal/common"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/Tencent/WeKnora/internal/types"
)
// streamLLMToEventBus streams LLM response through EventBus (generic method)
// emitFunc: callback to emit each chunk event
// Returns: full accumulated content, tool calls (if any), error
func (e *AgentEngine) streamLLMToEventBus(
ctx context.Context,
messages []chat.Message,
opts *chat.ChatOptions,
emitFunc func(chunk *types.StreamResponse, fullContent string),
) (string, []types.LLMToolCall, error) {
logger.Debugf(ctx, "[Agent][Stream] Starting LLM stream with %d messages", len(messages))
// Create a per-call timeout context so that a single LLM call gets a
// guaranteed time window even when the parent context's deadline is almost
// exhausted after previous iterations. The shorter of the two deadlines wins,
// so the parent pipeline timeout is still respected.
llmCtx, llmCancel := context.WithTimeout(ctx, e.getLLMCallTimeout())
defer llmCancel()
stream, err := e.chatModel.ChatStream(llmCtx, messages, opts)
if err != nil {
logger.Errorf(ctx, "[Agent][Stream] Failed to start LLM stream: %v", err)
return "", nil, err
}
fullContent := ""
var toolCalls []types.LLMToolCall
chunkCount := 0
for chunk := range stream {
chunkCount++
if chunk.Content != "" {
// Only accumulate LLM's own text output, not content extracted from tool arguments
// (e.g. final_answer's answer or thinking tool's thought are streamed separately)
isExtracted := chunk.Data != nil && chunk.Data["source"] != nil
if !isExtracted {
fullContent += chunk.Content
}
}
// Collect tool calls if present
if len(chunk.ToolCalls) > 0 {
toolCalls = chunk.ToolCalls
}
// Emit event through callback
if emitFunc != nil {
emitFunc(&chunk, fullContent)
}
}
return fullContent, toolCalls, nil
}
// streamReflectionToEventBus streams reflection process through EventBus
// Note: Reflection is now handled through the think tool in main loop
func (e *AgentEngine) streamReflectionToEventBus(
ctx context.Context,
toolCallID string,
toolName string,
result string,
iteration int,
sessionID string,
) (string, error) {
// Simplified reflection without BuildReflectionPrompt
reflectionPrompt := fmt.Sprintf(`Evaluate the result of calling tool %s and decide the next action.
Tool returned: %s
Think:
1. Does the result satisfy the requirement?
2. What should be done next?`, toolName, result)
messages := []chat.Message{
{Role: "user", Content: reflectionPrompt},
}
// Generate a single ID for this entire reflection stream
reflectionID := generateEventID("reflection")
fullReflection, _, err := e.streamLLMToEventBus(
ctx,
messages,
&chat.ChatOptions{Temperature: 0.5},
func(chunk *types.StreamResponse, fullContent string) {
if chunk.Content != "" {
e.eventBus.Emit(ctx, event.Event{
ID: reflectionID, // Same ID for all chunks in this stream
Type: event.EventAgentReflection,
SessionID: sessionID,
Data: event.AgentReflectionData{
ToolCallID: toolCallID,
Content: chunk.Content,
Iteration: iteration,
Done: chunk.Done,
},
})
}
},
)
if err != nil {
logger.Warnf(ctx, "Reflection failed: %v", err)
return "", err
}
return fullReflection, nil
}
// streamThinkingToEventBus streams the thinking process through EventBus
func (e *AgentEngine) streamThinkingToEventBus(
ctx context.Context,
messages []chat.Message,
tools []chat.Tool,
iteration int,
sessionID string,
) (*types.ChatResponse, error) {
logger.Debugf(ctx, "[Agent][Thinking] Iteration-%d: temp=%.2f, tools=%d, thinking=%v",
iteration+1, e.config.Temperature, len(tools), e.config.Thinking)
opts := &chat.ChatOptions{
Temperature: e.config.Temperature,
Tools: tools,
Thinking: e.config.Thinking,
}
pendingToolCalls := make(map[string]bool)
thinkingToolIDs := make(map[string]string) // tool_call_id -> event ID for thinking tool streams
// Generate IDs for this stream
thinkingID := generateEventID("thinking")
answerID := generateEventID("answer")
fullContent, toolCalls, err := e.streamLLMToEventBus(
ctx,
messages,
opts,
func(chunk *types.StreamResponse, fullContent string) {
if chunk.ResponseType == types.ResponseTypeToolCall && chunk.Data != nil {
toolCallID, _ := chunk.Data["tool_call_id"].(string)
toolName, _ := chunk.Data["tool_name"].(string)
if toolCallID != "" && toolName != "" && !pendingToolCalls[toolCallID] {
pendingToolCalls[toolCallID] = true
e.eventBus.Emit(ctx, event.Event{
ID: fmt.Sprintf("%s-tool-call-pending", toolCallID),
Type: event.EventAgentToolCall,
SessionID: sessionID,
Data: event.AgentToolCallData{
ToolCallID: toolCallID,
ToolName: toolName,
Iteration: iteration,
},
})
}
}
// Handle final_answer tool's streaming answer content
if chunk.ResponseType == types.ResponseTypeAnswer {
if source, _ := chunk.Data["source"].(string); source == "final_answer_tool" {
e.eventBus.Emit(ctx, event.Event{
ID: answerID,
Type: event.EventAgentFinalAnswer,
SessionID: sessionID,
Data: event.AgentFinalAnswerData{
Content: chunk.Content,
Done: false,
},
})
return
}
}
// Handle thinking tool's streaming thought content
if chunk.ResponseType == types.ResponseTypeThinking && chunk.Data != nil {
if source, _ := chunk.Data["source"].(string); source == "thinking_tool" {
toolCallID, _ := chunk.Data["tool_call_id"].(string)
eventID, exists := thinkingToolIDs[toolCallID]
if !exists {
eventID = generateEventID("thinking-tool")
thinkingToolIDs[toolCallID] = eventID
}
e.eventBus.Emit(ctx, event.Event{
ID: eventID,
Type: event.EventAgentThought,
SessionID: sessionID,
Data: event.AgentThoughtData{
Content: chunk.Content,
Iteration: iteration,
Done: false,
},
})
return
}
}
if chunk.Content != "" {
// logger.Debugf(ctx, "[Agent][Thinking][Iteration-%d] Emitting thought chunk: %d chars",
// iteration+1, len(chunk.Content))
e.eventBus.Emit(ctx, event.Event{
ID: thinkingID, // Same ID for all chunks in this stream
Type: event.EventAgentThought,
SessionID: sessionID,
Data: event.AgentThoughtData{
Content: chunk.Content,
Iteration: iteration,
Done: chunk.Done,
},
})
}
},
)
if err != nil {
logger.Errorf(ctx, "[Agent][Thinking] Iteration-%d failed: %v", iteration+1, err)
return nil, err
}
logger.Debugf(ctx, "[Agent][Thinking] Iteration-%d completed: content=%d chars, tool_calls=%d",
iteration+1, len(fullContent), len(toolCalls))
// Build response
return &types.ChatResponse{
Content: fullContent,
ToolCalls: toolCalls,
FinishReason: "stop",
}, nil
}
// callLLMWithRetry logs messages, sanitizes them, calls the LLM with retry on transient errors,
// and handles graceful degradation when prior tool results exist.
// Returns nil response (with state.IsComplete=true) when graceful degradation succeeds.
// Returns a non-nil error only when the call fails irrecoverably.
func (e *AgentEngine) callLLMWithRetry(
ctx context.Context, messages []chat.Message, tools []chat.Tool,
state *types.AgentState, query string, iteration int, sessionID string,
) (*types.ChatResponse, error) {
round := iteration + 1
// Log message summary at Debug level (per-message detail is noisy at Info)
logger.Infof(ctx, "[Agent][Round-%d] Calling LLM: %d messages, %d tools",
round, len(messages), len(tools))
for i, msg := range messages {
if msg.Role == "tool" {
logger.Debugf(ctx, "[Agent][Round-%d] msg[%d]: role=tool, name=%s, len=%d",
round, i, msg.Name, len(msg.Content))
} else if len(msg.ToolCalls) > 0 {
tcNames := make([]string, len(msg.ToolCalls))
for j, tc := range msg.ToolCalls {
tcNames[j] = tc.Function.Name
}
logger.Debugf(ctx, "[Agent][Round-%d] msg[%d]: role=%s, len=%d, tool_calls=%v",
round, i, msg.Role, len(msg.Content), tcNames)
} else {
preview := msg.Content
if len(preview) > 100 {
preview = preview[:100] + "..."
}
logger.Debugf(ctx, "[Agent][Round-%d] msg[%d]: role=%s, len=%d, content=%s",
round, i, msg.Role, len(msg.Content), preview)
}
}
common.PipelineInfo(ctx, "Agent", "think_start", map[string]interface{}{
"iteration": iteration,
"round": round,
"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, iteration, sessionID)
if err != nil && isTransientError(err) {
// Retry transient errors (timeout, rate limit, server errors) up to maxLLMRetries times
for retry := 1; retry <= maxLLMRetries; retry++ {
retryDelay := time.Duration(retry) * time.Second
logger.Warnf(ctx, "[Agent][Round-%d] LLM transient error (attempt %d/%d), retrying in %v: %v",
round, retry, maxLLMRetries, retryDelay, err)
time.Sleep(retryDelay)
response, err = e.streamThinkingToEventBus(ctx, messages, tools, iteration, sessionID)
if err == nil || !isTransientError(err) {
break
}
}
}
if err != nil {
logger.Errorf(ctx, "[Agent][Round-%d] LLM call failed: %v", round, err)
common.PipelineError(ctx, "Agent", "think_failed", map[string]interface{}{
"iteration": iteration,
"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 nil, fmt.Errorf("LLM call failed: %w (synthesis also failed: %v)", err, synthErr)
}
state.IsComplete = true
return nil, nil // graceful degradation succeeded
}
return nil, fmt.Errorf("LLM call failed: %w", err)
}
common.PipelineInfo(ctx, "Agent", "think_result", map[string]interface{}{
"iteration": iteration,
"finish_reason": response.FinishReason,
"tool_calls": len(response.ToolCalls),
"content_len": len(response.Content),
})
// Log LLM response summary
if len(response.ToolCalls) > 0 {
tcNames := make([]string, len(response.ToolCalls))
for i, tc := range response.ToolCalls {
tcNames[i] = tc.Function.Name
}
logger.Infof(ctx, "[Agent][Round-%d] LLM responded: finish=%s, content=%d chars, tools=%v",
round, response.FinishReason, len(response.Content), tcNames)
} else {
logger.Infof(ctx, "[Agent][Round-%d] LLM responded: finish=%s, content=%d chars",
round, response.FinishReason, len(response.Content))
}
if response.Content != "" {
preview := response.Content
if len(preview) > 300 {
preview = preview[:300] + "..."
}
logger.Debugf(ctx, "[Agent][Round-%d] LLM content preview:\n%s", round, preview)
}
return response, nil
}