Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(agent-logs): capture sub-tool invocations (#21518)

Sbaaoui Idrissbf21ddfd9b61
diff --git a/internal/agent/canvas/node_body.go b/internal/agent/canvas/node_body.go
index 602e1071c2..0438d4e468 100644
--- a/internal/agent/canvas/node_body.go
+++ b/internal/agent/canvas/node_body.go
@@ -346,6 +346,9 @@ func withStateBracket(cpnID, componentName string, body nodeBodyFn) nodeBodyFn {
out, err := body(ctx, in)
if err != nil {
if state != nil {
+ if invocations, ok := out["tool_invocations"]; ok {
+ state.SetVar(cpnID, "tool_invocations", invocations)
+ }
nodeFinishedNow(ctx, state, cpnID, componentName, componentName, err)
}
return nil, err
diff --git a/internal/agent/component/agent.go b/internal/agent/component/agent.go
index 7f8ea2196f..316d58767d 100644
--- a/internal/agent/component/agent.go
+++ b/internal/agent/component/agent.go
@@ -101,7 +101,8 @@ type AgentParam struct {
// when it is itself called as a tool by a parent component. Mirrors
// Python's `meta: ToolMeta` field — describes the Agent's own
// inputs (user_prompt / reasoning / context) for callers.
- Meta AgentMeta
+ Meta AgentMeta
+ toolInvocations *toolInvocationRecorder
// Cite enables post-stream citation grounding. When true,
// the Agent reads the chunks recorded in
// state.Retrieval["chunks"] (populated by the Retrieval tool),
@@ -180,6 +181,9 @@ func runEinoReActAgent(ctx context.Context, p AgentParam) (*schema.Message, erro
return nil, fmt.Errorf("build tools: %w", err)
}
tools = wrapReferenceRecordingTools(tools)
+ if p.toolInvocations != nil {
+ tools = wrapToolInvocationRecording(tools, p.toolInvocations)
+ }
input := buildAgentInputMessages(ctx, p)
// Eino's MaxStep counts graph nodes, not model calls. One ReAct round
// consists of a model decision, a tool node, and the following model
@@ -996,6 +1000,7 @@ func (c *AgentComponent) invokeNow(ctx context.Context, db *gorm.DB, inputs map[
defer runtime.FinalizeAgentMessage(ctx)
p := mergeAgentParam(c.param, inputs)
+ p.toolInvocations = &toolInvocationRecorder{}
originalModelID := p.ModelID
hasRuntimeUserPrompt := false
if v, ok := stringFrom(inputs, "user_prompt"); ok {
@@ -1086,6 +1091,9 @@ func (c *AgentComponent) invokeNow(ctx context.Context, db *gorm.DB, inputs map[
}
}
if err != nil {
+ if invocations := p.toolInvocations.snapshot(); len(invocations) > 0 {
+ return map[string]any{"tool_invocations": invocations}, fmt.Errorf("component: Agent.Invoke: %w", err)
+ }
// Only step exhaustion is an _ERROR output. Model/tool failures must
// stop execution before downstream nodes read an absent content output.
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) || !errors.Is(err, compose.ErrExceedMaxSteps) {
@@ -1143,6 +1151,9 @@ func (c *AgentComponent) invokeNow(ctx context.Context, db *gorm.DB, inputs map[
"tool_calls": extractToolCalls(msg),
"artifacts": artifacts,
}
+ if invocations := p.toolInvocations.snapshot(); len(invocations) > 0 {
+ out["tool_invocations"] = invocations
+ }
if len(p.OutputStructure) > 0 {
if parsed, ok := matchOutputStructure(cleanFormattedAnswer(content), p.OutputStructure); ok {
out["structured"] = parsed
diff --git a/internal/agent/component/agent_test.go b/internal/agent/component/agent_test.go
index 55b01a9f82..f648661aad 100644
--- a/internal/agent/component/agent_test.go
+++ b/internal/agent/component/agent_test.go
@@ -66,6 +66,9 @@ func TestAgent_NoToolsReAct(t *testing.T) {
if len(toolCalls) != 0 {
t.Errorf("tool_calls=%d, want 0", len(toolCalls))
}
+ if _, exists := out["tool_invocations"]; exists {
+ t.Errorf("tool_invocations unexpectedly present without tool calls: %#v", out["tool_invocations"])
+ }
if calls != 1 {
t.Errorf("runner called %d times, want 1", calls)
}
diff --git a/internal/agent/component/reference_recording_tool.go b/internal/agent/component/reference_recording_tool.go
index 732df33ddf..6003d072fc 100644
--- a/internal/agent/component/reference_recording_tool.go
+++ b/internal/agent/component/reference_recording_tool.go
@@ -18,13 +18,138 @@ package component
import (
"context"
+ "encoding/json"
+ "regexp"
+ "sort"
+ "strings"
+ "sync"
+ "time"
einotool "github.com/cloudwego/eino/components/tool"
-
"ragflow/internal/agent/runtime"
agenttool "ragflow/internal/agent/tool"
+ "ragflow/internal/utility"
)
+const maxToolLogResultRunes = 4096
+const maxToolLogInputRunes = 8192
+const maxToolLogInvocations = 64
+
+var sensitiveToolLogText = regexp.MustCompile(`(?i)(api[_-]?key|access[_-]?token|authorization|password|secret)(["']?\s*[:=]\s*["']?)([^"'\s,}]+)`)
+
+type toolInvocationRecorder struct {
+ mu sync.Mutex
+ entries []map[string]any
+}
+
+func (r *toolInvocationRecorder) snapshot() []map[string]any {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ entries := append([]map[string]any(nil), r.entries...)
+ sort.SliceStable(entries, func(i, j int) bool {
+ return entries[i]["started_at"].(int64) < entries[j]["started_at"].(int64)
+ })
+ return entries
+}
+
+type toolInvocationRecordingTool struct {
+ einotool.InvokableTool
+ name string
+ recorder *toolInvocationRecorder
+}
+
+func (t *toolInvocationRecordingTool) InvokableRun(ctx context.Context, argsJSON string, opts ...einotool.Option) (string, error) {
+ started := time.Now()
+ result, err := t.InvokableTool.InvokableRun(ctx, argsJSON, opts...)
+ finished := time.Now()
+ args := map[string]any{}
+ if json.Unmarshal([]byte(argsJSON), &args) != nil {
+ args = map[string]any{"input": "[UNPARSEABLE INPUT]"}
+ }
+ status := "success"
+ if err != nil {
+ status = "error"
+ } else {
+ var envelope map[string]any
+ if json.Unmarshal([]byte(result), &envelope) == nil && envelope["_ERROR"] != nil {
+ status = "error"
+ }
+ }
+ logResult := result
+ if err != nil {
+ logResult = err.Error()
+ }
+ var resultJSON any
+ if json.Unmarshal([]byte(logResult), &resultJSON) == nil {
+ if redacted, err := json.Marshal(redactToolLogValue(resultJSON)); err == nil {
+ logResult = string(redacted)
+ }
+ }
+ logResult = sensitiveToolLogText.ReplaceAllString(logResult, "$1$2[REDACTED]")
+ redactedArgs := redactToolLogValue(args)
+ if encoded, marshalErr := json.Marshal(redactedArgs); marshalErr == nil && len(encoded) > maxToolLogInputRunes {
+ redactedArgs = map[string]any{"_truncated": true, "preview": utility.TruncateRunes(string(encoded), maxToolLogInputRunes)}
+ }
+ entry := map[string]any{
+ "tool_name": t.name,
+ "arguments": redactedArgs,
+ "result": utility.TruncateRunes(logResult, maxToolLogResultRunes),
+ "started_at": started.UnixMilli(),
+ "elapsed_time": finished.Sub(started).Seconds(),
+ "status": status,
+ }
+ if err != nil {
+ entry["error"] = utility.TruncateRunes(err.Error(), maxToolLogResultRunes)
+ }
+ t.recorder.mu.Lock()
+ if len(t.recorder.entries) < maxToolLogInvocations {
+ t.recorder.entries = append(t.recorder.entries, entry)
+ }
+ t.recorder.mu.Unlock()
+ return result, err
+}
+
+func wrapToolInvocationRecording(tools []einotool.BaseTool, recorder *toolInvocationRecorder) []einotool.BaseTool {
+ wrapped := append([]einotool.BaseTool(nil), tools...)
+ for i, base := range tools {
+ invokable, ok := base.(einotool.InvokableTool)
+ if !ok {
+ continue
+ }
+ info, err := base.Info(context.Background())
+ if err != nil || info == nil {
+ continue
+ }
+ wrapped[i] = &toolInvocationRecordingTool{InvokableTool: invokable, name: info.Name, recorder: recorder}
+ }
+ return wrapped
+}
+
+func redactToolLogValue(value any) any {
+ switch v := value.(type) {
+ case map[string]any:
+ out := make(map[string]any, len(v))
+ for key, child := range v {
+ lower := strings.ToLower(key)
+ normalized := strings.NewReplacer("_", "", "-", "").Replace(lower)
+ if strings.Contains(normalized, "apikey") || strings.Contains(lower, "token") || strings.Contains(lower, "password") || strings.Contains(lower, "secret") || lower == "authorization" {
+ out[key] = "[REDACTED]"
+ } else {
+ out[key] = redactToolLogValue(child)
+ }
+ }
+ return out
+ case []any:
+ out := make([]any, len(v))
+ for i := range v {
+ out[i] = redactToolLogValue(v[i])
+ }
+ return out
+ default:
+ return value
+ }
+}
+
// referenceRecordingTool decorates an Agent tool so each invocation records
// the retrieval references it produced into the canvas state. Canvas tool
// nodes already do this in ToolBackedComponent.Invoke; tools called from the
diff --git a/internal/handler/agent.go b/internal/handler/agent.go
index 4fd196c2e5..847d4166b4 100644
--- a/internal/handler/agent.go
+++ b/internal/handler/agent.go
@@ -1341,6 +1341,7 @@ func (h *AgentHandler) AgentChatCompletions(c *gin.Context) {
emitted := false
doneSent := false
for ev := range events {
+ h.persistAgentToolInvocations(c.Request.Context(), req.AgentID, ev)
if ev.Type == "error" {
ev = convertAgentRunErrorToMessage(ev)
}
@@ -1404,6 +1405,7 @@ func (h *AgentHandler) AgentChatCompletions(c *gin.Context) {
var finalAns *canvas.RunEvent
hasEvents := false
for ev := range events {
+ h.persistAgentToolInvocations(c.Request.Context(), req.AgentID, ev)
hasEvents = true
if ev.Type == "error" {
ev = convertAgentRunErrorToMessage(ev)
@@ -1550,6 +1552,66 @@ func parseAgentLogs(payload string) interface{} {
return data
}
+func (h *AgentHandler) persistAgentToolInvocations(ctx context.Context, canvasID string, ev canvas.RunEvent) {
+ if h.redisStore == nil || ev.Type != "node_finished" || ev.MessageID == "" {
+ return
+ }
+ var event struct {
+ ComponentID string `json:"component_id"`
+ ComponentName string `json:"component_name"`
+ Outputs struct {
+ Invocations []map[string]any `json:"tool_invocations"`
+ } `json:"outputs"`
+ }
+ if json.Unmarshal([]byte(ev.Data), &event) != nil || len(event.Outputs.Invocations) == 0 {
+ return
+ }
+ key := fmt.Sprintf("%s-%s-logs", canvasID, ev.MessageID)
+ var entries []map[string]any
+ if h.redisGet != nil {
+ if payload, err := h.redisGet(key); err == nil {
+ _ = json.Unmarshal([]byte(payload), &entries)
+ }
+ }
+ if entries == nil {
+ entries = make([]map[string]any, 0, 1)
+ }
+ var traces []any
+ for _, invocation := range event.Outputs.Invocations {
+ trace := map[string]any{
+ "path": event.ComponentName,
+ "tool_name": invocation["tool_name"],
+ "arguments": invocation["arguments"],
+ "result": invocation["result"],
+ "elapsed_time": invocation["elapsed_time"],
+ "timestamp": invocation["started_at"],
+ "status": invocation["status"],
+ }
+ if invocation["error"] != nil {
+ trace["error"] = invocation["error"]
+ }
+ traces = append(traces, trace)
+ }
+ for _, entry := range entries {
+ if entry["component_id"] == event.ComponentID {
+ if old, ok := entry["trace"].([]any); ok {
+ entry["trace"] = append(old, traces...)
+ } else {
+ entry["trace"] = traces
+ }
+ payload, err := json.Marshal(entries)
+ if err == nil {
+ h.redisStore.Set(ctx, key, string(payload), task.DebugLogTTL)
+ }
+ return
+ }
+ }
+ entries = append(entries, map[string]any{"component_id": event.ComponentID, "trace": traces})
+ if payload, err := json.Marshal(entries); err == nil {
+ h.redisStore.Set(ctx, key, string(payload), task.DebugLogTTL)
+ }
+}
+
// GetAgentLogs GET /api/v1/agents/:canvas_id/logs/:message_id
//
// Reads "{agent_id}-{message_id}-logs" from Redis (same key format
diff --git a/internal/handler/agent_logs_test.go b/internal/handler/agent_logs_test.go
index ba5aa184c9..bb6d60a5fb 100644
--- a/internal/handler/agent_logs_test.go
+++ b/internal/handler/agent_logs_test.go
@@ -30,6 +30,7 @@ import (
"github.com/gin-gonic/gin"
goredis "github.com/redis/go-redis/v9"
+ "ragflow/internal/agent/canvas"
"ragflow/internal/common"
"ragflow/internal/dao"
"ragflow/internal/entity"
@@ -146,6 +147,7 @@ func TestGetAgentLogs_E2EViaMiniredis(t *testing.T) {
}
h := NewAgentHandler(ctx, service.NewAgentService(), nil).
+ WithRedisStore(miniredisDebugStore{rdb: rdb}).
WithRedisGetter(func(key string) (string, error) {
return rdb.Get(ctx, key).Result()
})
@@ -169,6 +171,21 @@ func TestGetAgentLogs_E2EViaMiniredis(t *testing.T) {
return resp
}
+ h.persistAgentToolInvocations(ctx, "c1", canvas.RunEvent{
+ Type: "node_finished", MessageID: "tool-msg",
+ Data: `{"component_id":"Agent:one","component_name":"Agent","outputs":{"tool_invocations":[{"tool_name":"youcom_search","arguments":{"query":"ragflow"},"result":"found","elapsed_time":0.25,"started_at":1793070042000,"status":"success"}]}}`,
+ })
+ toolRun := run("tool-msg")
+ toolEntries, ok := toolRun["data"].([]interface{})
+ if !ok || len(toolEntries) != 1 {
+ t.Fatalf("tool logs response data = %#v", toolRun["data"])
+ }
+ toolEntry := toolEntries[0].(map[string]interface{})
+ toolTrace := toolEntry["trace"].([]interface{})[0].(map[string]interface{})
+ if toolEntry["component_id"] != "Agent:one" || toolTrace["tool_name"] != "youcom_search" || toolTrace["status"] != "success" {
+ t.Fatalf("tool trace response = %#v", toolTrace)
+ }
+
// Present key -> data must be the array, with File first and END last.
present := run("msg1")
if code, _ := present["code"].(float64); int(code) != int(common.CodeSuccess) {
@@ -324,6 +341,40 @@ type capturedStore struct {
data map[string]string
}
+func TestPersistAgentToolInvocations_UsesAgentNodeAndExistingLogShape(t *testing.T) {
+ store := &capturedStore{}
+ h := &AgentHandler{
+ redisStore: store,
+ redisGet: func(key string) (string, error) {
+ value, ok := store.Get(t.Context(), key)
+ if !ok {
+ return "", errors.New("missing")
+ }
+ return value, nil
+ },
+ }
+ ev := canvas.RunEvent{
+ Type: "node_finished", MessageID: "message-1",
+ Data: `{"component_id":"Agent:one","component_name":"Agent","outputs":{"tool_invocations":[{"tool_name":"youcom_search","arguments":{"query":"ragflow"},"result":"found","elapsed_time":0.25,"started_at":1793070042000,"status":"success"}]}}`,
+ }
+ h.persistAgentToolInvocations(t.Context(), "agent-1", ev)
+ raw, ok := store.Get(t.Context(), "agent-1-message-1-logs")
+ if !ok {
+ t.Fatal("tool trace was not persisted")
+ }
+ var entries []map[string]any
+ if err := json.Unmarshal([]byte(raw), &entries); err != nil {
+ t.Fatalf("decode persisted trace: %v", err)
+ }
+ if len(entries) != 1 || entries[0]["component_id"] != "Agent:one" {
+ t.Fatalf("entries = %#v", entries)
+ }
+ trace := entries[0]["trace"].([]any)[0].(map[string]any)
+ if trace["tool_name"] != "youcom_search" || trace["path"] != "Agent" || trace["status"] != "success" || trace["arguments"].(map[string]any)["query"] != "ragflow" {
+ t.Fatalf("trace = %#v", trace)
+ }
+}
+
func (s *capturedStore) Set(ctx context.Context, key, value string, _ time.Duration) bool {
s.mu.Lock()
defer s.mu.Unlock()
diff --git a/web/src/pages/agent/log-sheet/tool-timeline-item.tsx b/web/src/pages/agent/log-sheet/tool-timeline-item.tsx
index eb121758b2..70e36cf2f8 100644
--- a/web/src/pages/agent/log-sheet/tool-timeline-item.tsx
+++ b/web/src/pages/agent/log-sheet/tool-timeline-item.tsx
@@ -13,6 +13,7 @@ import {
} from '@/components/ui/accordion';
import { cn } from '@/lib/utils';
import { isEmpty } from 'lodash';
+import dayjs from 'dayjs';
import { Operator } from '../constant';
import { JsonViewer } from '../form/components/json-viewer';
import OperatorIcon, { SVGIconMap } from '@/components/operator-icon';
@@ -164,13 +165,19 @@ const ToolTimelineItem = ({
</span>
)}
<span className="text-text-secondary text-xs">
- {/* 0:00*/}
+ {tool.timestamp
+ ? dayjs(tool.timestamp).format('HH:mm:ss')
+ : ''}
+ {tool.timestamp && ' | '}
{tool.elapsed_time?.toString().slice(0, 6) || ''}
{tool.elapsed_time ? 's' : ''}
</span>
<span
className={cn(
- 'border-background -end-1 -top-1 size-2 rounded-full bg-state--success',
+ 'border-background -end-1 -top-1 size-2 rounded-full',
+ tool.status === 'error'
+ ? 'bg-state--error'
+ : 'bg-state--success',
)}
>
<span className="sr-only">Online</span>
@@ -184,6 +191,10 @@ const ToolTimelineItem = ({
data={tool.result}
title="content"
></JsonViewer>
+ <JsonViewer
+ data={tool.arguments}
+ title="Arguments"
+ ></JsonViewer>
</div>
</AccordionContent>
)}