Skip to content

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

57.0 KB
Raw Blame
// Package component — Agent unit tests.
//
// Tests inject a canned agentRunner to verify the component contract
// without requiring a real model or eino react agent runtime:
//
//  1. NoToolsReAct: the runner returns a plain answer → component
//     surfaces content with empty tool_calls.
//  2. ToolCallRound: the runner returns a message with ToolCalls →
//     component extracts them into the tool_calls output.
//  3. ExhaustRoundsError: the runner returns an error → component
//     exposes it through the Python-compatible _ERROR output.
//  4. MissingModelID: the component rejects before calling the runner.
package component

import (
	"context"
	"database/sql"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"strings"
	"testing"
	"time"

	"github.com/DATA-DOG/go-sqlmock"
	"github.com/cloudwego/eino/components/model"
	einotool "github.com/cloudwego/eino/components/tool"
	"github.com/cloudwego/eino/compose"
	"github.com/cloudwego/eino/flow/agent/react"
	"github.com/cloudwego/eino/schema"
	"gorm.io/gorm"

	"ragflow/internal/agent/runtime"
	agenttool "ragflow/internal/agent/tool"
	"ragflow/internal/common"
	"ragflow/internal/entity/models"
)

// withAgentRunner replaces the package-level agentRunner for the duration
// of t.
func withAgentRunner(t *testing.T, fn func(context.Context, AgentParam) (*schema.Message, error)) {
	t.Helper()
	prev := agentRunner
	agentRunner = fn
	t.Cleanup(func() { agentRunner = prev })
}

func TestAgent_NoToolsReAct(t *testing.T) {
	var calls int
	withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
		calls++
		return &schema.Message{Role: schema.Assistant, Content: "the answer is 42"}, nil
	})

	c := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 3})
	out, err := c.Invoke(t.Context(), nil, map[string]any{
		"user_prompt": "what is 6*7?",
	})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if got, want := out["content"], "the answer is 42"; got != want {
		t.Errorf("content=%v, want %v", got, want)
	}
	toolCalls, ok := out["tool_calls"].([]map[string]any)
	if !ok {
		t.Fatalf("tool_calls missing or wrong type: %T", out["tool_calls"])
	}
	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)
	}
}

func TestAgent_PopulatesStructuredFromOutputsSchema(t *testing.T) {
	withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
		return &schema.Message{
			Role:    schema.Assistant,
			Content: "```json\n{\"records\":[{\"ruleId\":\"r1\",\"verdict\":\"PASS\"}],\"opinion\":{\"conclusion\":\"PASS\"}}\n```",
		}, nil
	})

	c := NewAgentComponent(agentParamFromMap(map[string]any{
		"model_id": "stub",
		"outputs": map[string]any{
			"structured": map[string]any{
				"type": "object",
				"properties": map[string]any{
					"records": map[string]any{"type": "array"},
					"opinion": map[string]any{"type": "object"},
				},
				"required": []any{"records"},
			},
		},
	}))
	out, err := c.Invoke(t.Context(), nil, map[string]any{
		"user_prompt": "summarize",
	})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	structured, ok := out["structured"].(map[string]any)
	if !ok {
		t.Fatalf("structured missing or wrong type: %T (%v)", out["structured"], out["structured"])
	}
	if _, ok := structured["records"]; !ok {
		t.Fatalf("structured.records missing: %#v", structured)
	}
	if got, want := out["content"], `{"records":[{"ruleId":"r1","verdict":"PASS"}],"opinion":{"conclusion":"PASS"}}`; got != want {
		t.Errorf("content=%q, want cleaned JSON %q", got, want)
	}
}

func TestAgentOutputStructureFromPreservesSchema(t *testing.T) {
	schema := agentOutputStructureFrom(map[string]any{
		"outputs": map[string]any{
			"structured": map[string]any{
				"type": "object",
				"properties": map[string]any{
					"records": map[string]any{"type": "array"},
					"opinion": map[string]any{"type": "object"},
				},
				"required": []any{"records"},
			},
		},
	})
	if got, _ := schema["type"].(string); got != "object" {
		t.Fatalf("expected full schema preserved, got %#v", schema)
	}
	keys := structuredExpectedKeySet(schema)
	if len(keys) != 1 {
		t.Fatalf("expected only required keys, got %#v", keys)
	}
	if _, ok := keys["records"]; !ok {
		t.Fatalf("records key missing: %#v", keys)
	}
}

func TestStructuredExpectedKeySet_PropertiesWithoutRequired(t *testing.T) {
	keys := structuredExpectedKeySet(map[string]any{
		"type": "object",
		"properties": map[string]any{
			"id":   map[string]any{"type": "integer"},
			"note": map[string]any{"type": "string"},
		},
	})
	if len(keys) != 0 {
		t.Fatalf("properties without required must not imply required keys, got %#v", keys)
	}
	parsed, ok := matchAgentOutputStructure(`{"id":1}`, map[string]any{
		"type": "object",
		"properties": map[string]any{
			"id":   map[string]any{"type": "integer"},
			"note": map[string]any{"type": "string"},
		},
	})
	if !ok {
		t.Fatal("optional note missing should still match")
	}
	if _, ok := parsed["id"]; !ok {
		t.Fatalf("parsed=%#v", parsed)
	}
}

func TestMatchAgentOutputStructure_RejectsWrongType(t *testing.T) {
	schema := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"id": map[string]any{"type": "integer"},
		},
		"required": []any{"id"},
	}
	if _, ok := matchAgentOutputStructure(`{"id":"wrong"}`, schema); ok {
		t.Fatal("string id must fail integer type check")
	}
	if _, ok := matchAgentOutputStructure(`{"id":1}`, schema); !ok {
		t.Fatal("integer id should pass")
	}
}

func TestMatchAgentOutputStructure_RejectsNullForObjectSchema(t *testing.T) {
	schema := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"id": map[string]any{"type": "integer"},
		},
	}
	if _, ok := matchAgentOutputStructure("null", schema); ok {
		t.Fatal("null must fail an object schema")
	}
	if _, ok := matchAgentOutputStructure("null", map[string]any{
		"properties": map[string]any{
			"id": map[string]any{"type": "integer"},
		},
	}); !ok {
		t.Fatal("omitted type must still accept null")
	}
	if _, ok := matchAgentOutputStructure("null", map[string]any{
		"type":       []any{"object", "null"},
		"properties": map[string]any{"id": map[string]any{"type": "integer"}},
		"required":   []any{"id"},
	}); !ok {
		t.Fatal("type union that includes null must accept null")
	}
}

func TestMatchAgentOutputStructure_RejectsAdditionalProperties(t *testing.T) {
	schema := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"id": map[string]any{"type": "integer"},
		},
		"additionalProperties": false,
	}
	if _, ok := matchAgentOutputStructure(`{"id":1,"unexpected":true}`, schema); ok {
		t.Fatal("undeclared key must fail when additionalProperties is false")
	}
	if _, ok := matchAgentOutputStructure(`{"id":1}`, schema); !ok {
		t.Fatal("declared key should pass")
	}
}

func TestMatchAgentOutputStructure_AcceptsTypeUnion(t *testing.T) {
	schema := map[string]any{
		"type": "object",
		"properties": map[string]any{
			"note": map[string]any{"type": []any{"string", "null"}},
		},
		"required": []any{"note"},
	}
	if _, ok := matchAgentOutputStructure(`{"note":1}`, schema); ok {
		t.Fatal("number must fail a string|null property")
	}
	if _, ok := matchAgentOutputStructure(`{"note":"ok"}`, schema); !ok {
		t.Fatal("string should pass a string|null property")
	}
	if _, ok := matchAgentOutputStructure(`{"note":null}`, schema); !ok {
		t.Fatal("null should pass a string|null property")
	}
}

func TestAgent_StructuredDeferredEmitsCleanedContent(t *testing.T) {
	withAgentRunner(t, func(ctx context.Context, _ AgentParam) (*schema.Message, error) {
		runtime.EmitAgentMessage(ctx, "", "thinking")
		return &schema.Message{
			Role:    schema.Assistant,
			Content: "```json\n{\"records\":[]}\n```",
		}, nil
	})

	ctx := runtime.WithComponentExecutionOptions(t.Context(), runtime.ComponentExecutionOptions{
		DeferAgentToMessage: true,
	})
	c := NewAgentComponent(agentParamFromMap(map[string]any{
		"model_id": "stub",
		"outputs": map[string]any{
			"structured": map[string]any{
				"type": "object",
				"properties": map[string]any{
					"records": map[string]any{"type": "array"},
				},
				"required": []any{"records"},
			},
		},
	}))
	out, err := c.Invoke(ctx, nil, map[string]any{"user_prompt": "hello"})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	deferred, ok := out["content"].(*runtime.DeferredStream)
	if !ok || deferred == nil {
		t.Fatalf("content=%T, want *runtime.DeferredStream", out["content"])
	}

	var streamed strings.Builder
	final, err := deferred.Open(ctx, func(contentDelta, _ string) {
		streamed.WriteString(contentDelta)
	})
	if err != nil {
		t.Fatalf("Open: %v", err)
	}
	want := `{"records":[]}`
	if got := streamed.String(); got != want {
		t.Fatalf("streamed=%q, want cleaned %q", got, want)
	}
	if got, _ := final["content"].(string); got != want {
		t.Fatalf("final content=%q, want %q", got, want)
	}
}

func TestScanAllStreamForToolCallWaitsPastTextChunks(t *testing.T) {
	stream := schema.StreamReaderFromArray([]*schema.Message{
		{Role: schema.Assistant, Content: "I will calculate this."},
		{
			Role: schema.Assistant,
			ToolCalls: []schema.ToolCall{{
				ID:   "call-1",
				Type: "function",
				Function: schema.FunctionCall{
					Name:      "execute_code",
					Arguments: `{"lang":"python","script":"def main(): return 2"}`,
				},
			}},
		},
	})

	hasToolCall, err := scanAllStreamForToolCall(t.Context(), stream)
	if err != nil {
		t.Fatalf("scanAllStreamForToolCall: %v", err)
	}
	if !hasToolCall {
		t.Fatal("scanAllStreamForToolCall = false, want true")
	}
}

func TestScanAllStreamForToolCallAllowsDirectAnswer(t *testing.T) {
	stream := schema.StreamReaderFromArray([]*schema.Message{
		{Role: schema.Assistant, Content: "No tool is needed."},
	})

	hasToolCall, err := scanAllStreamForToolCall(t.Context(), stream)
	if err != nil {
		t.Fatalf("scanAllStreamForToolCall: %v", err)
	}
	if hasToolCall {
		t.Fatal("scanAllStreamForToolCall = true, want false")
	}
}

func TestHasCodeExecTool(t *testing.T) {
	for _, name := range []string{"CodeExec", "code_exec", "execute_code"} {
		if !hasCodeExecTool([]string{name}) {
			t.Fatalf("hasCodeExecTool(%q) = false, want true", name)
		}
	}
	if hasCodeExecTool([]string{"Retrieval"}) {
		t.Fatal("hasCodeExecTool(Retrieval) = true, want false")
	}
}

type textThenToolCallModel struct {
	turn       int
	boundTools []*schema.ToolInfo
}

func (m *textThenToolCallModel) WithTools(tools []*schema.ToolInfo) (model.ToolCallingChatModel, error) {
	m.boundTools = append([]*schema.ToolInfo(nil), tools...)
	return m, nil
}

func (m *textThenToolCallModel) Generate(_ context.Context, _ []*schema.Message, _ ...model.Option) (*schema.Message, error) {
	m.turn++
	if m.turn == 1 {
		return &schema.Message{
			Role: schema.Assistant,
			ToolCalls: []schema.ToolCall{{
				ID:   "call-1",
				Type: "function",
				Function: schema.FunctionCall{
					Name:      "execute_code",
					Arguments: `{"lang":"python","script":"def main(): return 2"}`,
				},
			}},
		}, nil
	}
	return &schema.Message{Role: schema.Assistant, Content: "2"}, nil
}

func (m *textThenToolCallModel) Stream(_ context.Context, _ []*schema.Message, _ ...model.Option) (*schema.StreamReader[*schema.Message], error) {
	m.turn++
	if m.turn == 1 {
		return schema.StreamReaderFromArray([]*schema.Message{
			{Role: schema.Assistant, Content: "I will calculate this."},
			{
				Role: schema.Assistant,
				ToolCalls: []schema.ToolCall{{
					ID:   "call-1",
					Type: "function",
					Function: schema.FunctionCall{
						Name:      "execute_code",
						Arguments: `{"lang":"python","script":"def main(): return 2"}`,
					},
				}},
			},
		}), nil
	}
	return schema.StreamReaderFromArray([]*schema.Message{
		{Role: schema.Assistant, Content: "2"},
	}), nil
}

func TestReactStreamCheckerExecutesToolCallAfterText(t *testing.T) {
	mdl := &textThenToolCallModel{}
	tool := &passthroughTool{name: "execute_code"}
	agent, err := react.NewAgent(t.Context(), &react.AgentConfig{
		ToolCallingModel: mdl,
		ToolsConfig: compose.ToolsNodeConfig{
			Tools: []einotool.BaseTool{tool},
		},
		StreamToolCallChecker: scanAllStreamForToolCall,
		MaxStep:               4,
	})
	if err != nil {
		t.Fatalf("react.NewAgent: %v", err)
	}

	stream, err := agent.Stream(t.Context(), []*schema.Message{schema.UserMessage("calculate")})
	if err != nil {
		t.Fatalf("agent.Stream: %v", err)
	}
	defer stream.Close()

	var chunks []*schema.Message
	for {
		chunk, recvErr := stream.Recv()
		if recvErr == io.EOF {
			break
		}
		if recvErr != nil {
			t.Fatalf("stream.Recv: %v", recvErr)
		}
		if chunk != nil {
			chunks = append(chunks, chunk)
		}
	}
	if mdl.turn < 2 {
		t.Fatalf("model turns = %d, want a second turn after tool execution", mdl.turn)
	}
	if len(mdl.boundTools) != 1 || mdl.boundTools[0].Name != "execute_code" {
		t.Fatalf("bound tools = %#v, want execute_code", mdl.boundTools)
	}
	if got := tool.calls.Load(); got != 1 {
		t.Fatalf("tool invocations = %d, want exactly 1", got)
	}
	final, err := schema.ConcatMessages(chunks)
	if err != nil {
		t.Fatalf("schema.ConcatMessages: %v", err)
	}
	if final.Content != "2" {
		t.Fatalf("final content = %q, want 2", final.Content)
	}
}

// slowThinkingModel streams a few reasoning chunks (each delayed) before a
// tool call, then answers directly on the second turn. It is used to prove
// that thinking deltas reach the agent message emitter while agent.Stream is
// still blocked inside the stream-tool-call checker.
type slowThinkingModel struct {
	turn int
}

func (m *slowThinkingModel) WithTools(_ []*schema.ToolInfo) (model.ToolCallingChatModel, error) {
	return m, nil
}

func (m *slowThinkingModel) Generate(_ context.Context, _ []*schema.Message, _ ...model.Option) (*schema.Message, error) {
	m.turn++
	return &schema.Message{Role: schema.Assistant, Content: "2"}, nil
}

func (m *slowThinkingModel) Stream(_ context.Context, _ []*schema.Message, _ ...model.Option) (*schema.StreamReader[*schema.Message], error) {
	m.turn++
	if m.turn == 1 {
		sr, sw := schema.Pipe[*schema.Message](1)
		go func() {
			defer sw.Close()
			for _, chunk := range []*schema.Message{
				{Role: schema.Assistant, ReasoningContent: "thinking one"},
				{Role: schema.Assistant, ReasoningContent: "thinking two"},
				{Role: schema.Assistant, ReasoningContent: "thinking three"},
				{
					Role: schema.Assistant,
					ToolCalls: []schema.ToolCall{{
						ID:   "call-1",
						Type: "function",
						Function: schema.FunctionCall{
							Name:      "execute_code",
							Arguments: `{"lang":"python","script":"def main(): return 2"}`,
						},
					}},
				},
			} {
				time.Sleep(30 * time.Millisecond)
				if sw.Send(chunk, nil) {
					return
				}
			}
		}()
		return sr, nil
	}
	return schema.StreamReaderFromArray([]*schema.Message{{Role: schema.Assistant, Content: "2"}}), nil
}

// TestReactCheckerStreamsThinkingBeforeAgentReturns pins the fix for the
// stream realtime regression: the stream-tool-call checker drains the whole
// round synchronously inside the graph main loop, so agent.Stream cannot
// return until the model finishes. The collector (emitAgentModelStreams)
// must therefore be started before agent.Stream and deliver the first
// thinking delta while the model is still streaming.
func TestReactCheckerStreamsThinkingBeforeAgentReturns(t *testing.T) {
	mdl := &slowThinkingModel{}
	tool := &passthroughTool{name: "execute_code"}
	agent, err := react.NewAgent(t.Context(), &react.AgentConfig{
		ToolCallingModel: mdl,
		ToolsConfig: compose.ToolsNodeConfig{
			Tools: []einotool.BaseTool{tool},
		},
		StreamToolCallChecker: scanAllStreamForToolCall,
		MaxStep:               4,
	})
	if err != nil {
		t.Fatalf("react.NewAgent: %v", err)
	}

	thinkingSeen := make(chan struct{}, 1)
	ctx := runtime.WithAgentMessageEmitter(t.Context(), func(content, thinking string) {
		if thinking != "" {
			select {
			case thinkingSeen <- struct{}{}:
			default:
			}
		}
	})

	opt, future := react.WithMessageFuture()
	emitDone := emitAgentModelStreams(ctx, future, false, false)

	streamCh := make(chan *schema.StreamReader[*schema.Message], 1)
	errCh := make(chan error, 1)
	go func() {
		s, streamErr := agent.Stream(ctx, []*schema.Message{schema.UserMessage("calculate")}, opt)
		if streamErr != nil {
			errCh <- streamErr
			return
		}
		streamCh <- s
	}()

	select {
	case <-thinkingSeen:
		// First thinking delta arrived while the model is still streaming.
	case <-streamCh:
		t.Fatal("agent.Stream returned before any thinking delta was emitted")
	case <-errCh:
		t.Fatal("agent.Stream errored before any thinking delta was emitted")
	case <-time.After(10 * time.Second):
		t.Fatal("timed out waiting for a thinking delta")
	}

	var stream *schema.StreamReader[*schema.Message]
	select {
	case stream = <-streamCh:
	case err := <-errCh:
		t.Fatalf("agent.Stream: %v", err)
	case <-time.After(10 * time.Second):
		t.Fatal("agent.Stream did not return")
	}
	defer stream.Close()
	for {
		if _, recvErr := stream.Recv(); recvErr == io.EOF {
			break
		}
	}
	if got := tool.calls.Load(); got != 1 {
		t.Fatalf("tool invocations = %d, want exactly 1", got)
	}
	<-emitDone
}

func TestAgent_EmitsThinking(t *testing.T) {
	withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
		return &schema.Message{
			Role:             schema.Assistant,
			Content:          "final answer",
			ReasoningContent: "model reasoning",
		}, nil
	})

	c := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 1})
	out, err := c.Invoke(t.Context(), nil, map[string]any{
		"user_prompt": "hello",
	})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if got, want := out["content"], "final answer"; got != want {
		t.Errorf("content=%v, want %v", got, want)
	}
	if got, want := out["thinking"], "model reasoning"; got != want {
		t.Errorf("thinking=%v, want %v", got, want)
	}
}

func TestAgent_MessageEmissionIsScopedPerInvocation(t *testing.T) {
	responses := []string{"first answer", "second answer"}
	withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
		if len(responses) == 0 {
			t.Fatal("agent runner called too many times")
		}
		content := responses[0]
		responses = responses[1:]
		return &schema.Message{Role: schema.Assistant, Content: content}, nil
	})

	state := runtime.NewCanvasState("run-1", "task-1")
	ctx := runtime.WithState(t.Context(), state)
	var contents []string
	ctx = runtime.WithAgentMessageEmitterControl(ctx,
		func(contentDelta, _ string) {
			if contentDelta != "" {
				contents = append(contents, contentDelta)
			}
		},
		func() bool { return false },
		func() {},
	)

	first := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 1})
	if _, err := first.Invoke(ctx, nil, map[string]any{"user_prompt": "first"}); err != nil {
		t.Fatalf("first Invoke: %v", err)
	}
	second := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 1})
	if _, err := second.Invoke(ctx, nil, map[string]any{"user_prompt": "second"}); err != nil {
		t.Fatalf("second Invoke: %v", err)
	}

	if got, want := strings.Join(contents, "|"), "first answer|second answer"; got != want {
		t.Fatalf("emitted contents = %q, want %q", got, want)
	}
}

func TestAgent_DefersExecutionForDownstreamMessage(t *testing.T) {
	calls := 0
	withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
		calls++
		return &schema.Message{Role: schema.Assistant, Content: "lazy answer"}, nil
	})

	ctx := runtime.WithComponentExecutionOptions(t.Context(), runtime.ComponentExecutionOptions{
		DeferAgentToMessage: true,
	})
	ctx = runtime.WithAgentMessageEmitter(ctx, func(string, string) {})
	agent := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 1})
	out, err := agent.Invoke(ctx, nil, map[string]any{"user_prompt": "hello"})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if calls != 0 {
		t.Fatalf("runner calls=%d before Message consumed stream, want 0", calls)
	}
	deferred, ok := out["content"].(*runtime.DeferredStream)
	if !ok || deferred == nil {
		t.Fatalf("content=%T, want *runtime.DeferredStream", out["content"])
	}
	var got strings.Builder
	final, err := deferred.Open(ctx, func(contentDelta, _ string) {
		got.WriteString(contentDelta)
	})
	if err != nil {
		t.Fatalf("Open: %v", err)
	}
	if calls != 1 || got.String() != "lazy answer" {
		t.Fatalf("calls=%d streamed=%q, want 1 / %q", calls, got.String(), "lazy answer")
	}
	if final["content"] != "lazy answer" {
		t.Fatalf("final content=%v, want lazy answer", final["content"])
	}
}

func TestAgent_DeferredStreamAppliesFreshTimeout(t *testing.T) {
	withAgentRunner(t, func(ctx context.Context, _ AgentParam) (*schema.Message, error) {
		if _, ok := ctx.Deadline(); !ok {
			t.Fatal("deferred Agent runner context has no deadline")
		}
		return &schema.Message{Role: schema.Assistant, Content: "answer"}, nil
	})

	ctx := runtime.WithComponentExecutionOptions(t.Context(), runtime.ComponentExecutionOptions{
		DeferAgentToMessage: true,
	})
	out, err := NewAgentComponent(AgentParam{ModelID: "stub"}).Invoke(ctx, nil, map[string]any{"user_prompt": "hello"})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	deferred, ok := out["content"].(*runtime.DeferredStream)
	if !ok || deferred == nil {
		t.Fatalf("content=%T, want *runtime.DeferredStream", out["content"])
	}
	if _, err := deferred.Open(t.Context(), func(string, string) {}); err != nil {
		t.Fatalf("Open: %v", err)
	}
}

func TestAgent_DeferredStreamDoesNotAppendFinalAnswerAfterDeltas(t *testing.T) {
	withAgentRunner(t, func(ctx context.Context, _ AgentParam) (*schema.Message, error) {
		runtime.EmitAgentMessage(ctx, "lazy ", "")
		runtime.EmitAgentMessage(ctx, "answer", "")
		return &schema.Message{Role: schema.Assistant, Content: "lazy answer"}, nil
	})

	ctx := runtime.WithComponentExecutionOptions(t.Context(), runtime.ComponentExecutionOptions{
		DeferAgentToMessage: true,
	})
	ctx = runtime.WithAgentMessageEmitter(ctx, func(string, string) {})
	out, err := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 1}).Invoke(ctx, nil, map[string]any{
		"user_prompt": "hello",
	})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	deferred, ok := out["content"].(*runtime.DeferredStream)
	if !ok || deferred == nil {
		t.Fatalf("content=%T, want *runtime.DeferredStream", out["content"])
	}

	var streamed strings.Builder
	final, err := deferred.Open(ctx, func(contentDelta, _ string) {
		streamed.WriteString(contentDelta)
	})
	if err != nil {
		t.Fatalf("Open: %v", err)
	}
	if got, want := streamed.String(), "lazy answer"; got != want {
		t.Fatalf("streamed=%q, want %q", got, want)
	}
	if got, want := final["content"], "lazy answer"; got != want {
		t.Fatalf("final content=%v, want %v", got, want)
	}
}

func TestAgent_SuppressesVisibleEventsWithoutMessageDownstream(t *testing.T) {
	withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
		return &schema.Message{Role: schema.Assistant, Content: "timeline answer"}, nil
	})
	var emitted []string
	ctx := runtime.WithAgentMessageEmitter(t.Context(), func(contentDelta, _ string) {
		if contentDelta != "" {
			emitted = append(emitted, contentDelta)
		}
	})
	ctx = runtime.WithComponentExecutionOptions(ctx, runtime.ComponentExecutionOptions{
		SuppressAgentMessageEvents: true,
	})
	if _, err := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 1}).Invoke(ctx, nil, map[string]any{
		"user_prompt": "hello",
	}); err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if len(emitted) != 0 {
		t.Fatalf("visible events=%#v, want none", emitted)
	}
	if !runtime.AgentMessageEventsSuppressed(ctx) {
		t.Fatal("AgentMessageEventsSuppressed=false, want true")
	}
}

func TestAgent_ForwardsThinkingParam(t *testing.T) {
	var gotThinking string
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		gotThinking = p.Thinking
		return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
	})

	cmp, err := New("Agent", map[string]any{
		"model_id":    "stub",
		"user_prompt": "hello",
		"thinking":    "enabled",
	})
	if err != nil {
		t.Fatalf("New(Agent): %v", err)
	}
	if _, err = cmp.Invoke(t.Context(), nil, nil); err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if gotThinking != "enabled" {
		t.Fatalf("runner thinking = %q, want enabled", gotThinking)
	}
}

func TestAgent_ResolvesUserPromptFromCanvasState(t *testing.T) {
	var gotPrompt string
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		gotPrompt = p.UserPrompt
		return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
	})

	state := runtime.NewCanvasState("run-1", "task-1")
	state.Sys["query"] = "what is marigold"
	ctx := runtime.WithState(t.Context(), state)

	c := NewAgentComponent(AgentParam{
		ModelID:    "stub",
		APIKey:     "test-key",
		UserPrompt: "Question: {sys.query}",
		MaxRounds:  1,
	})
	if _, err := c.Invoke(ctx, nil, nil); err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if gotPrompt != "Question: what is marigold" {
		t.Fatalf("runner prompt = %q, want resolved sys.query", gotPrompt)
	}
}

func TestAgent_RejectsUnresolvedPromptReferences(t *testing.T) {
	tests := []string{"missing@value", "sys.missing", "env.missing", "item", "index"}
	for _, ref := range tests {
		t.Run(ref, func(t *testing.T) {
			called := false
			withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
				called = true
				return &schema.Message{Role: schema.Assistant, Content: "unexpected"}, nil
			})

			state := runtime.NewCanvasState("run-1", "task-1")
			ctx := runtime.WithState(t.Context(), state)
			c := NewAgentComponent(AgentParam{ModelID: "stub", UserPrompt: "value {{" + ref + "}}"})
			_, err := c.Invoke(ctx, nil, nil)
			if err == nil || err.Error() != "Can't find variable: '"+ref+"'" {
				t.Fatalf("Invoke error = %v, want missing-variable error", err)
			}
			if called {
				t.Fatal("agent runner called after prompt resolution failed")
			}
		})
	}
}

func TestAgent_AllowsEmptyPromptReferenceValues(t *testing.T) {
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		if p.UserPrompt != "value " {
			return nil, fmt.Errorf("resolved prompt = %q, want %q", p.UserPrompt, "value ")
		}
		return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
	})

	state := runtime.NewCanvasState("run-1", "task-1")
	state.SetVar("component", "value", "")
	state.Sys["empty"] = ""
	state.Env["empty"] = ""
	state.Globals["__item__"] = ""
	state.Globals["__index__"] = ""
	for _, ref := range []string{"component@value", "sys.empty", "env.empty", "item", "index"} {
		c := NewAgentComponent(AgentParam{ModelID: "stub", UserPrompt: "value {{" + ref + "}}"})
		if _, err := c.Invoke(runtime.WithState(t.Context(), state), nil, nil); err != nil {
			t.Fatalf("Invoke(%q): %v", ref, err)
		}
	}
}

func TestAgent_UsesPromptsListForSysQuery(t *testing.T) {
	var gotPrompt string
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		gotPrompt = p.UserPrompt
		return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
	})

	cmp, err := New("Agent", map[string]any{
		"model_id":    "stub",
		"api_key":     "test-key",
		"sys_prompt":  "act as assistant",
		"user_prompt": "This is the order you need to send to the agent.",
		"prompts": []any{
			map[string]any{"role": "user", "content": "{sys.query}"},
		},
	})
	if err != nil {
		t.Fatalf("New(Agent): %v", err)
	}

	state := runtime.NewCanvasState("run-1", "task-1")
	state.Sys["query"] = "用户真正的问题"
	ctx := runtime.WithState(t.Context(), state)

	if _, err = cmp.Invoke(ctx, nil, nil); err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if gotPrompt != "用户真正的问题" {
		t.Fatalf("runner prompt = %q, want sys.query from prompts list", gotPrompt)
	}
}

func TestAgent_NewTreatsSchemaDefaultUserPromptAsSysQueryPlaceholder(t *testing.T) {
	var gotPrompt string
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		gotPrompt = p.UserPrompt
		return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
	})

	cmp, err := New("Agent", map[string]any{
		"model_id":    "stub",
		"api_key":     "test-key",
		"user_prompt": agentUserPromptSchemaDefault,
	})
	if err != nil {
		t.Fatalf("New(Agent): %v", err)
	}

	state := runtime.NewCanvasState("run-1", "task-1")
	state.Sys["query"] = "用户真正的问题"
	ctx := runtime.WithState(t.Context(), state)

	if _, err = cmp.Invoke(ctx, nil, nil); err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if gotPrompt != "用户真正的问题" {
		t.Fatalf("runner prompt = %q, want sys.query placeholder resolved", gotPrompt)
	}
}

func TestAgent_EmptyConfiguredUserPromptDoesNotFallbackToSysQuery(t *testing.T) {
	var gotSystemPrompt, gotUserPrompt string
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		gotSystemPrompt = p.SystemPrompt
		gotUserPrompt = p.UserPrompt
		return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
	})

	cmp, err := New("Agent", map[string]any{
		"model_id":   "stub",
		"api_key":    "test-key",
		"sys_prompt": "User answer: {UserFillUp:TwelveBadgersRescue@key}",
		"prompts": []any{
			map[string]any{"role": "user", "content": ""},
		},
	})
	if err != nil {
		t.Fatalf("New(Agent): %v", err)
	}

	state := runtime.NewCanvasState("run-1", "task-1")
	state.Sys["query"] = "1"
	state.SetVar("UserFillUp:TwelveBadgersRescue", "key", "21")
	ctx := runtime.WithState(t.Context(), state)

	if _, err = cmp.Invoke(ctx, nil, nil); err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if gotSystemPrompt != "User answer: 21" {
		t.Fatalf("runner system prompt = %q, want resolved UserFillUp answer", gotSystemPrompt)
	}
	if gotUserPrompt == "1" {
		t.Fatalf("runner user prompt reused sys.query: %q", gotUserPrompt)
	}
	if gotUserPrompt != gotSystemPrompt {
		t.Fatalf("runner user prompt = %q, want system-only fallback %q", gotUserPrompt, gotSystemPrompt)
	}
}

func TestAgent_FormatsRuntimePromptLikePython(t *testing.T) {
	var gotPrompt string
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		gotPrompt = p.UserPrompt
		return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
	})

	c := NewAgentComponent(AgentParam{
		ModelID:   "stub",
		APIKey:    "test-key",
		MaxRounds: 1,
	})
	if _, err := c.Invoke(t.Context(), nil, map[string]any{
		"user_prompt": "write answer",
		"reasoning":   "selected because it can answer",
		"context":     "known facts",
	}); err != nil {
		t.Fatalf("Invoke: %v", err)
	}

	want := "\nREASONING:\nselected because it can answer\n\nCONTEXT:\nknown facts\n\nQUERY:\nwrite answer\n"
	if gotPrompt != want {
		t.Fatalf("runner prompt = %q, want %q", gotPrompt, want)
	}
}

func TestAgent_ToolCallRound(t *testing.T) {
	var calls int
	withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
		calls++
		return &schema.Message{
			Role:    schema.Assistant,
			Content: "final answer based on tool",
			ToolCalls: []schema.ToolCall{
				{
					ID:   "call_1",
					Type: "function",
					Function: schema.FunctionCall{
						Name:      "search",
						Arguments: `{"q": "ragflow"}`,
					},
				},
			},
		}, nil
	})

	c := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 3})
	out, err := c.Invoke(t.Context(), nil, map[string]any{
		"user_prompt": "find out about ragflow",
	})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if got, want := out["content"], "final answer based on tool"; got != want {
		t.Errorf("content=%v, want %v", got, want)
	}
	toolCalls, ok := out["tool_calls"].([]map[string]any)
	if !ok {
		t.Fatalf("tool_calls missing or wrong type: %T", out["tool_calls"])
	}
	if len(toolCalls) != 1 {
		t.Fatalf("tool_calls=%d, want 1", len(toolCalls))
	}
	if toolCalls[0]["name"] != "search" {
		t.Errorf("tool name=%v, want search", toolCalls[0]["name"])
	}
	if calls != 1 {
		t.Errorf("runner called %d times, want 1", calls)
	}
}

func TestAgent_ExhaustRoundsError(t *testing.T) {
	withAgentRunner(t, func(_ context.Context, _ AgentParam) (*schema.Message, error) {
		return nil, fmt.Errorf("[GraphRunError] %w", compose.ErrExceedMaxSteps)
	})

	c := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 2})
	out, err := c.Invoke(t.Context(), nil, map[string]any{
		"user_prompt": "x",
	})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if got := out["_ERROR"]; got != "**ERROR**: [GraphRunError] exceeds max steps" {
		t.Fatalf("_ERROR = %v, want step-exhaustion error envelope", got)
	}
}

func TestAgent_ToolInvocationsWithRunnerErrors(t *testing.T) {
	for _, tt := range []struct {
		name         string
		runnerErr    error
		wantError    bool
		wantEnvelope bool
	}{
		{name: "max steps", runnerErr: fmt.Errorf("[GraphRunError] %w", compose.ErrExceedMaxSteps), wantEnvelope: true},
		{name: "other failure", runnerErr: errors.New("provider failed"), wantError: true},
	} {
		t.Run(tt.name, func(t *testing.T) {
			withAgentRunner(t, func(ctx context.Context, p AgentParam) (*schema.Message, error) {
				recorder := &toolInvocationRecordingTool{
					InvokableTool: &referenceRecordingFakeTool{out: `{"ok":true}`},
					name:          "search",
					recorder:      p.toolInvocations,
				}
				if _, err := recorder.InvokableRun(ctx, `{"query":"test"}`); err != nil {
					return nil, err
				}
				return nil, tt.runnerErr
			})

			out, err := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 1}).Invoke(t.Context(), nil, map[string]any{"user_prompt": "test"})
			if tt.wantError {
				if err == nil || !errors.Is(err, tt.runnerErr) {
					t.Fatalf("Invoke error = %v, want wrapped %v", err, tt.runnerErr)
				}
			} else if err != nil {
				t.Fatalf("Invoke: %v", err)
			}
			if tt.wantEnvelope {
				if got := out["_ERROR"]; got != "**ERROR**: [GraphRunError] exceeds max steps" {
					t.Fatalf("_ERROR = %v, want step-exhaustion envelope", got)
				}
			} else if _, ok := out["_ERROR"]; ok {
				t.Fatalf("unexpected _ERROR output: %#v", out["_ERROR"])
			}
			if invocations, ok := out["tool_invocations"].([]map[string]any); !ok || len(invocations) != 1 {
				t.Fatalf("tool_invocations = %#v, want one invocation", out["tool_invocations"])
			}
		})
	}
}

func TestAgent_MissingModelID(t *testing.T) {
	c := NewAgentComponent(AgentParam{MaxRounds: 1})
	_, err := c.Invoke(t.Context(), nil, map[string]any{"user_prompt": "x"})
	if err == nil {
		t.Fatal("expected ParamError for missing model_id")
	}
	var pe *ParamError
	if !errors.As(err, &pe) {
		t.Errorf("err type=%T, want *ParamError", err)
	}
}

// TestAgent_Invoke_RespectsParentCancellation: when the parent
// ctx is cancelled, the runner observes it and the error
// propagates through Invoke.
func TestAgent_Invoke_RespectsParentCancellation(t *testing.T) {
	withAgentRunner(t, func(ctx context.Context, _ AgentParam) (*schema.Message, error) {
		// Honor ctx cancellation — real runners do; a stub that
		// ignores ctx would defeat the test's purpose.
		if err := ctx.Err(); err != nil {
			return nil, err
		}
		return &schema.Message{Content: "ok"}, nil
	})
	c := NewAgentComponent(AgentParam{ModelID: "echo", MaxRounds: 1})

	ctx, cancel := context.WithCancel(t.Context())
	cancel() // pre-cancel

	_, err := c.Invoke(ctx, nil, map[string]any{"user_prompt": "hi"})
	if err == nil {
		t.Fatal("expected error from pre-cancelled context")
	}
	if !errors.Is(err, context.Canceled) {
		t.Errorf("expected context.Canceled, got %v", err)
	}
}

func TestAgent_UnknownToolName(t *testing.T) {
	c := NewAgentComponent(AgentParam{
		ModelID:   "stub",
		MaxRounds: 1,
		Tools:     []string{"does_not_exist"},
	})
	_, err := c.Invoke(t.Context(), nil, map[string]any{
		"user_prompt": "x",
	})
	if err == nil {
		t.Fatal("expected error for unknown tool")
	}
	if !strings.Contains(err.Error(), `build tools: agent tool: unsupported tool "does_not_exist"`) {
		t.Fatalf("err = %q, want unsupported tool message", err.Error())
	}
}

func TestAgent_AllRegisteredToolsConfigPassesToRunner(t *testing.T) {
	var captured AgentParam
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		captured = p
		return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
	})

	c := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 1})
	_, err := c.Invoke(t.Context(), nil, map[string]any{
		"user_prompt": "x",
		"tools": []any{
			"akshare", "arxiv", "code_exec", "crawler", "deepl", "duckduckgo",
			"email", "github", "google", "google_scholar", "jin10", "pubmed",
			"qweather", "retrieval", "searxng", "tavily", "tushare", "wencai",
			"wikipedia", "yahoo_finance", "execute_sql",
		},
		"tool_params": map[string]any{
			"execute_sql": map[string]any{
				"db_type":     "mysql",
				"host":        "127.0.0.1",
				"port":        3306,
				"database":    "demo",
				"username":    "u",
				"password":    "p",
				"max_records": 10,
			},
		},
	})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if len(captured.Tools) != 21 {
		t.Fatalf("captured.Tools len = %d, want 21", len(captured.Tools))
	}
	if captured.ToolParams == nil || captured.ToolParams["execute_sql"] == nil {
		t.Fatalf("captured.ToolParams missing execute_sql: %#v", captured.ToolParams)
	}
}

func TestAgent_AcceptsCanvasToolObjects(t *testing.T) {
	var captured AgentParam
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		captured = p
		return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
	})

	c := NewAgentComponent(AgentParam{ModelID: "stub", MaxRounds: 1})
	_, err := c.Invoke(t.Context(), nil, map[string]any{
		"user_prompt": "x",
		"tools": []any{
			map[string]any{
				"component_name": "Retrieval",
				"name":           "Docs Retrieval",
				"params": map[string]any{
					"kb_ids": []any{"kb-1"},
					"top_n":  float64(3),
				},
			},
		},
	})
	if err != nil {
		t.Fatalf("Invoke: %v", err)
	}
	if len(captured.Tools) != 1 || captured.Tools[0] != "Retrieval" {
		t.Fatalf("captured.Tools = %#v, want [Retrieval]", captured.Tools)
	}
	params := captured.ToolParams["retrieval"]
	if params == nil {
		t.Fatalf("captured.ToolParams missing retrieval: %#v", captured.ToolParams)
	}
	ids, ok := params["kb_ids"].([]any)
	if !ok || len(ids) != 1 || ids[0] != "kb-1" {
		t.Fatalf("retrieval kb_ids = %#v, want [kb-1]", params["kb_ids"])
	}
}

func TestAgent_NewAcceptsCanvasToolObjects(t *testing.T) {
	cmp, err := New("Agent", map[string]any{
		"model_id":    "stub",
		"user_prompt": "x",
		"tools": []any{
			map[string]any{
				"component_name": "Retrieval",
				"params": map[string]any{
					"dataset_ids": []any{"kb-1"},
				},
			},
		},
	})
	if err != nil {
		t.Fatalf("New(Agent): %v", err)
	}
	agent, ok := cmp.(*AgentComponent)
	if !ok {
		t.Fatalf("New(Agent) returned %T, want *AgentComponent", cmp)
	}
	if len(agent.param.Tools) != 1 || agent.param.Tools[0] != "Retrieval" {
		t.Fatalf("agent.param.Tools = %#v, want [Retrieval]", agent.param.Tools)
	}
	if agent.param.ToolParams["retrieval"] == nil {
		t.Fatalf("agent.param.ToolParams missing retrieval: %#v", agent.param.ToolParams)
	}
	if _, err := buildAgentTools(t.Context(), agent.param); err != nil {
		t.Fatalf("buildAgentTools: %v", err)
	}
}

func TestAgent_NewAcceptsCodeExecCanvasToolObject(t *testing.T) {
	cmp, err := New("Agent", map[string]any{
		"model_id":    "stub",
		"user_prompt": "x",
		"tools": []any{
			map[string]any{
				"component_name": "CodeExec",
				"params":         map[string]any{},
			},
		},
	})
	if err != nil {
		t.Fatalf("New(Agent): %v", err)
	}
	agent, ok := cmp.(*AgentComponent)
	if !ok {
		t.Fatalf("New(Agent) returned %T, want *AgentComponent", cmp)
	}
	if len(agent.param.Tools) != 1 || agent.param.Tools[0] != "CodeExec" {
		t.Fatalf("agent.param.Tools = %#v, want [CodeExec]", agent.param.Tools)
	}
	tools, err := buildAgentTools(t.Context(), agent.param)
	if err != nil {
		t.Fatalf("buildAgentTools: %v", err)
	}
	if len(tools) != 1 {
		t.Fatalf("len(tools) = %d, want 1", len(tools))
	}
	info, err := tools[0].Info(t.Context())
	if err != nil {
		t.Fatalf("CodeExec tool Info: %v", err)
	}
	if info.Name != "execute_code" {
		t.Errorf("CodeExec tool Info().Name = %q, want execute_code", info.Name)
	}
}

type fakeToolCallingChatModel struct {
	tools []*schema.ToolInfo
}

func (m *fakeToolCallingChatModel) Generate(_ context.Context, _ []*schema.Message, _ ...model.Option) (*schema.Message, error) {
	return &schema.Message{Role: schema.Assistant, Content: "ok"}, nil
}

func (m *fakeToolCallingChatModel) Stream(_ context.Context, _ []*schema.Message, _ ...model.Option) (*schema.StreamReader[*schema.Message], error) {
	sr, sw := schema.Pipe[*schema.Message](1)
	go func() {
		defer sw.Close()
		_ = sw.Send(&schema.Message{Role: schema.Assistant, Content: "ok"}, io.EOF)
	}()
	return sr, nil
}

func (m *fakeToolCallingChatModel) WithTools(tools []*schema.ToolInfo) (model.ToolCallingChatModel, error) {
	cp := *m
	cp.tools = append([]*schema.ToolInfo(nil), tools...)
	return &cp, nil
}

func TestAgent_CanCreateReactAgentWithAllRegisteredTools(t *testing.T) {
	p := AgentParam{
		Tools: []string{
			"akshare", "arxiv", "code_exec", "crawler", "deepl", "duckduckgo",
			"email", "github", "google", "google_scholar", "jin10", "pubmed",
			"qweather", "retrieval", "searxng", "tavily", "tushare", "wencai",
			"wikipedia", "yahoo_finance", "execute_sql",
		},
		ToolParams: map[string]map[string]any{
			"execute_sql": {
				"db_type":     "mysql",
				"host":        "127.0.0.1",
				"port":        3306,
				"database":    "demo",
				"username":    "u",
				"password":    "p",
				"max_records": 10,
			},
		},
		MaxRounds: 1,
	}
	tools, err := buildAgentTools(t.Context(), p)
	if err != nil {
		t.Fatalf("buildAgentTools: %v", err)
	}
	if len(tools) != len(p.Tools) {
		t.Fatalf("len(tools) = %d, want %d", len(tools), len(p.Tools))
	}
	_, err = react.NewAgent(t.Context(), &react.AgentConfig{
		ToolCallingModel: &fakeToolCallingChatModel{},
		ToolsConfig: compose.ToolsNodeConfig{
			Tools: tools,
		},
		MaxStep: 1,
	})
	if err != nil {
		t.Fatalf("react.NewAgent(all tools): %v", err)
	}
}

func TestAgent_Registered(t *testing.T) {
	c, err := New("Agent", map[string]any{"model_id": "stub", "user_prompt": "x"})
	if err != nil {
		t.Fatalf("New(Agent): %v", err)
	}
	if c.Name() != "Agent" {
		t.Errorf("Name()=%q, want Agent", c.Name())
	}
}

func TestAgent_CanvasSubAgentToolBuildsDynamicTool(t *testing.T) {
	c, err := New("Agent", map[string]any{
		"model_id":    "stub",
		"user_prompt": "parent prompt",
		"tools": []any{
			map[string]any{
				"component_name": "Agent",
				"id":             "child-node",
				"name":           "NewPumasLick",
				"params": map[string]any{
					"model_id":    "stub",
					"description": "child agent description",
					"prompts": []any{
						map[string]any{"role": "user", "content": "child prompt"},
					},
				},
			},
		},
	})
	if err != nil {
		t.Fatalf("New(Agent): %v", err)
	}
	agent, ok := c.(*AgentComponent)
	if !ok {
		t.Fatalf("New(Agent) returned %T, want *AgentComponent", c)
	}
	if len(agent.param.Tools) != 0 {
		t.Fatalf("regular tools = %v, want none", agent.param.Tools)
	}
	if len(agent.param.SubAgents) != 1 {
		t.Fatalf("sub agents = %d, want 1", len(agent.param.SubAgents))
	}
	ctx := t.Context()

	tools, err := buildAgentTools(ctx, agent.param)
	if err != nil {
		t.Fatalf("buildAgentTools: %v", err)
	}
	if len(tools) != 1 {
		t.Fatalf("len(tools) = %d, want 1", len(tools))
	}
	info, err := tools[0].Info(ctx)
	if err != nil {
		t.Fatalf("tool.Info: %v", err)
	}
	if info.Name != "NewPumasLick" {
		t.Fatalf("tool name = %q, want NewPumasLick", info.Name)
	}
	if info.Desc != "child agent description" {
		t.Fatalf("tool desc = %q, want child agent description", info.Desc)
	}
}

func TestAgent_CanvasSubAgentToolNamesAreUniqueAfterNormalization(t *testing.T) {
	c, err := New("Agent", map[string]any{
		"model_id":    "stub",
		"user_prompt": "parent prompt",
		"tools": []any{
			map[string]any{
				"component_name": "Agent",
				"name":           "你好",
				"params": map[string]any{
					"model_id":    "stub",
					"user_prompt": "child one",
				},
			},
			map[string]any{
				"component_name": "Agent",
				"name":           "世界",
				"params": map[string]any{
					"model_id":    "stub",
					"user_prompt": "child two",
				},
			},
		},
	})
	if err != nil {
		t.Fatalf("New(Agent): %v", err)
	}
	agent, ok := c.(*AgentComponent)
	if !ok {
		t.Fatalf("New(Agent) returned %T, want *AgentComponent", c)
	}

	tools, err := buildAgentTools(t.Context(), agent.param)
	if err != nil {
		t.Fatalf("buildAgentTools: %v", err)
	}
	if len(tools) != 2 {
		t.Fatalf("len(tools) = %d, want 2", len(tools))
	}
	var names []string
	for _, tool := range tools {
		info, err := tool.Info(t.Context())
		if err != nil {
			t.Fatalf("tool.Info: %v", err)
		}
		names = append(names, info.Name)
	}
	if got, want := strings.Join(names, ","), "agent,agent_2"; got != want {
		t.Fatalf("tool names = %q, want %q", got, want)
	}
}

func TestAgent_SubAgentToolInvokableRunCallsChildAgent(t *testing.T) {
	var got AgentParam
	withAgentRunner(t, func(_ context.Context, p AgentParam) (*schema.Message, error) {
		got = p
		return &schema.Message{Role: schema.Assistant, Content: "child answer"}, nil
	})

	tool := &subAgentTool{spec: SubAgentTool{
		Name: "Child Agent",
		Param: AgentParam{
			ModelID:    "stub",
			UserPrompt: "default child prompt",
			MaxRounds:  1,
		},
	}}

	out, err := tool.InvokableRun(t.Context(), `{"user_prompt":"ask child","reasoning":"because","context":"facts"}`)
	if err != nil {
		t.Fatalf("InvokableRun: %v", err)
	}
	if out != "child answer" {
		t.Fatalf("InvokableRun output = %q, want child answer", out)
	}
	if !strings.Contains(got.UserPrompt, "REASONING:\nbecause") {
		t.Fatalf("UserPrompt = %q, want reasoning included", got.UserPrompt)
	}
	if !strings.Contains(got.UserPrompt, "CONTEXT:\nfacts") {
		t.Fatalf("UserPrompt = %q, want context included", got.UserPrompt)
	}
	if !strings.Contains(got.UserPrompt, "QUERY:\nask child") {
		t.Fatalf("UserPrompt = %q, want query included", got.UserPrompt)
	}
}

// exhaustStepsModel is a scripted ToolCallingChatModel that emits a
// tool_call on every Generate and never returns final content. It
// is the input driver for TestAgent_ReActExhaustsSteps, which needs
// the eino ReAct loop to hit its MaxStep ceiling.
type exhaustStepsModel struct {
	turn       int
	rounds     [][]*schema.Message
	boundTools []*schema.ToolInfo
	toolName   string
	toolArgs   string
}

func (m *exhaustStepsModel) WithTools(tools []*schema.ToolInfo) (model.ToolCallingChatModel, error) {
	m.boundTools = tools
	return m, nil
}

func (m *exhaustStepsModel) Generate(_ context.Context, in []*schema.Message, _ ...model.Option) (*schema.Message, error) {
	cp := make([]*schema.Message, len(in))
	copy(cp, in)
	m.rounds = append(m.rounds, cp)
	m.turn++
	return &schema.Message{
		Role: schema.Assistant,
		ToolCalls: []schema.ToolCall{{
			ID:   fmt.Sprintf("call_%d", m.turn),
			Type: "function",
			Function: schema.FunctionCall{
				Name:      m.toolName,
				Arguments: m.toolArgs,
			},
		}},
	}, nil
}

func (m *exhaustStepsModel) Stream(_ context.Context, _ []*schema.Message, _ ...model.Option) (*schema.StreamReader[*schema.Message], error) {
	sr, sw := schema.Pipe[*schema.Message](1)
	sw.Close()
	return sr, nil
}

// TestAgent_ReActExhaustsSteps drives a real react.NewAgent whose
// scripted model always returns a tool_call and never returns final
// content. With MaxStep: 2 the loop must terminate with an error
// from eino's MaxStep guard. This is the eino error-path counterpart
// to TestExeSQL_RealReactAgent_ExecutesTool: the latter proves the
// happy path (model returns tool_call, framework runs tool, model
// returns final); this one proves the loop guard terminates even
// when the model never produces a final answer.
//
// Earlier versions also asserted mock.ExpectQuery("SELECT 1") to
// pin the tool-call count, but that assumption is fragile to eino
// version changes (different eino builds invoke the tool a
// different number of times before the MaxStep guard fires).
// The MaxStep guard itself — the thing we actually care about —
// is asserted by the non-nil err return above. PR review round 8
// (CI red): the test was failing on every CI run with "remaining
// expectation" against the SELECT 1 query because eino's internal
// counter for "is this the MaxStep iteration?" varies between
// releases. Stage ExpectPing only.
func TestAgent_ReActExhaustsSteps(t *testing.T) {
	t.Parallel()

	// Real ExeSQLTool with sqlmock. We stage ExpectPing only —
	// the optional Query expectation was removed because eino's
	// MaxStep-guard iteration count is an implementation detail
	// we cannot pin across eino versions.
	db, mock, err := sqlmock.New()
	if err != nil {
		t.Fatalf("sqlmock.New: %v", err)
	}
	defer db.Close()
	mock.ExpectPing()

	// Default sql.Open would try to connect to a real MySQL; the
	// dialer stub makes the tool talk to sqlmock instead.
	dialer := func(_, _ string) (*sql.DB, error) { return db, nil }
	// BuildByName goes through the public registry — the same path
	// AgentComponent.buildAgentTools takes. This proves the agent's
	// own wiring (ToolsConfig -> real BaseTool) works under the
	// MaxStep guard, not a backdoor constructor.
	built, err := agenttool.BuildByName("execute_sql", map[string]any{
		"db_type":     "mysql",
		"host":        "127.0.0.1",
		"port":        3306,
		"database":    "demo",
		"username":    "u",
		"password":    "p",
		"max_records": 10,
	})
	if err != nil {
		t.Fatalf("agenttool.BuildByName(execute_sql): %v", err)
	}
	exeSQLTool, ok := built.(*agenttool.ExeSQLTool)
	if !ok {
		t.Fatalf("BuildByName(execute_sql) returned %T, want *ExeSQLTool", built)
	}
	realTool := exeSQLTool.WithExeSQLDialer(dialer)

	mdl := &exhaustStepsModel{
		toolName: "execute_sql",
		toolArgs: `{"sql": "SELECT 1"}`,
	}

	agent, err := react.NewAgent(t.Context(), &react.AgentConfig{
		ToolCallingModel: mdl,
		ToolsConfig: compose.ToolsNodeConfig{
			Tools: []einotool.BaseTool{realTool},
		},
		MaxStep: 2,
	})
	if err != nil {
		t.Fatalf("react.NewAgent: %v", err)
	}

	out, err := agent.Generate(t.Context(), []*schema.Message{
		schema.UserMessage("loop forever"),
	})
	if err == nil {
		t.Fatalf("agent.Generate returned no error; out=%+v — expected MaxStep exhaustion", out)
	}
	if mdl.turn < 1 {
		t.Errorf("model.Generate called %d times, want >= 1 (the loop should have invoked it before giving up)", mdl.turn)
	}
	if len(mdl.boundTools) != 1 || mdl.boundTools[0].Name != "execute_sql" {
		names := make([]string, 0, len(mdl.boundTools))
		for _, ti := range mdl.boundTools {
			names = append(names, ti.Name)
		}
		t.Errorf("tools bound to model = %v, want [execute_sql]", names)
	}
	if err := mock.ExpectationsWereMet(); err != nil {
		t.Errorf("sqlmock expectations: %v", err)
	}
}

func TestAgentDisabledMaxTokens(t *testing.T) {
	p := mergeAgentParam(AgentParam{}, map[string]any{"max_tokens": 256, "maxTokensEnabled": false})
	if p.MaxTokens != nil {
		t.Fatalf("disabled max_tokens still applied: %d", *p.MaxTokens)
	}
	for _, inputs := range []map[string]any{{"max_tokens": 256}, {"max_tokens": 256, "maxTokensEnabled": true}} {
		p = mergeAgentParam(AgentParam{}, inputs)
		if p.MaxTokens == nil || *p.MaxTokens != 256 {
			t.Fatal("enabled or unflagged max_tokens lost")
		}
	}
}

func TestAgentDisabledTemperatureAndTopP(t *testing.T) {
	p := mergeAgentParam(AgentParam{}, map[string]any{
		"temperature": 0.2, "temperatureEnabled": false,
		"top_p": 0.75, "topPEnabled": false,
	})
	if p.Temperature != nil {
		t.Fatalf("disabled temperature still applied: %v", *p.Temperature)
	}
	if p.TopP != nil {
		t.Fatalf("disabled top_p still applied: %v", *p.TopP)
	}
	for _, inputs := range []map[string]any{
		{"temperature": 0.2, "top_p": 0.75},
		{"temperature": 0.2, "temperatureEnabled": true, "top_p": 0.75, "topPEnabled": true},
	} {
		p = mergeAgentParam(AgentParam{}, inputs)
		if p.Temperature == nil || *p.Temperature != 0.2 || p.TopP == nil || *p.TopP != 0.75 {
			t.Fatal("enabled or unflagged temperature/top_p lost")
		}
	}
}

func TestAgent_MultipleRetrievalToolsUseFunctionName(t *testing.T) {
	p := AgentParam{
		Tools: []string{"search_archa_metodika", "search_archa_data"},
		ToolParams: map[string]map[string]any{
			"search_archa_metodika": {
				"component_name": "Retrieval",
				"function_name":  "search_archa_metodika",
				"description":    "Vyhľadávanie v metodike.",
				"kb_ids":         []any{"kb-metodika"},
				"top_n":          float64(10),
			},
			"search_archa_data": {
				"component_name": "Retrieval",
				"function_name":  "search_archa_data",
				"description":    "Vyhľadávanie v projektovej dokumentácii.",
				"kb_ids":         []any{"kb-data"},
				"top_n":          float64(25),
			},
		},
		MaxRounds: 1,
	}
	tools, err := buildAgentTools(t.Context(), p)
	if err != nil {
		t.Fatalf("buildAgentTools: %v", err)
	}
	if len(tools) != 2 {
		t.Fatalf("len(tools) = %d, want 2", len(tools))
	}
	names := make(map[string]bool)
	for _, tool := range tools {
		info, err := tool.Info(t.Context())
		if err != nil {
			t.Fatalf("tool.Info: %v", err)
		}
		names[info.Name] = true
	}
	if !names["search_archa_metodika"] || !names["search_archa_data"] {
		t.Fatalf("expected distinct retrieval tool names, got %v", names)
	}
}

type fakeAgentRetrievalService struct {
	chunks []agenttool.RetrievalChunk
}

func (f *fakeAgentRetrievalService) Search(ctx context.Context, db *gorm.DB, req agenttool.RetrievalRequest) ([]agenttool.RetrievalChunk, error) {
	return f.chunks, nil
}

func TestAgent_AnthropicReActToolCallLoop(t *testing.T) {
	t.Setenv(common.EnvAllowAnyHost, "true")

	fakeRetrieval := &fakeAgentRetrievalService{
		chunks: []agenttool.RetrievalChunk{
			{ID: "c1", Content: "RAGFlow is an open-source RAG engine based on deep document understanding."},
		},
	}
	prevSvc := agenttool.GetRetrievalService()
	agenttool.SetRetrievalService(fakeRetrieval)
	defer agenttool.SetRetrievalService(prevSvc)

	if err := models.InitProviderManager("../../../conf/models"); err != nil {
		t.Fatal(err)
	}

	turn := 0
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		turn++
		body, _ := io.ReadAll(r.Body)

		if turn == 1 {
			var req map[string]any
			if err := json.Unmarshal(body, &req); err != nil {
				t.Errorf("turn 1: unmarshal request body: %v", err)
			}
			tools, _ := req["tools"].([]any)
			if len(tools) == 0 {
				t.Errorf("turn 1: expected tools in request, got none")
			} else {
				t0, _ := tools[0].(map[string]any)
				if t0["name"] != "search_my_dateset" {
					t.Errorf("turn 1: expected tool name search_my_dateset, got %v", t0["name"])
				}
				schema, _ := t0["input_schema"].(map[string]any)
				if schema == nil || schema["type"] != "object" {
					t.Errorf("turn 1: expected object input_schema, got %#v", t0["input_schema"])
				}
				props, _ := schema["properties"].(map[string]any)
				if props == nil || props["query"] == nil {
					t.Errorf("turn 1: expected query property in input_schema, got %#v", schema["properties"])
				}
			}

			// First turn (non-streaming): model decides to call tool
			w.Header().Set("Content-Type", "application/json")
			w.WriteHeader(http.StatusOK)
			_, _ = w.Write([]byte(`{
				"id": "msg_001",
				"type": "message",
				"role": "assistant",
				"content": [
					{
						"type": "tool_use",
						"id": "toolu_01",
						"name": "search_my_dateset",
						"input": {"query": "ragflow 是什么"}
					}
				],
				"stop_reason": "tool_use",
				"usage": {"input_tokens": 50, "output_tokens": 20}
			}`))
			return
		}

		if turn == 2 {
			if !strings.Contains(string(body), "RAGFlow is an open-source RAG engine based on deep document understanding.") {
				t.Errorf("turn 2: expected retrieval chunk in request body, got %s", string(body))
			}
		}

		// Second turn (streaming): model answers with final text
		w.Header().Set("Content-Type", "text/event-stream")
		w.WriteHeader(http.StatusOK)
		flusher, _ := w.(http.Flusher)

		events := []string{
			`event: message_start` + "\n" + `data: {"type": "message_start", "message": {"id": "msg_002", "type": "message", "role": "assistant", "content": [], "model": "qwen3.5-27b", "usage": {"input_tokens": 80, "output_tokens": 1}}}` + "\n\n",
			`event: content_block_start` + "\n" + `data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}` + "\n\n",
			`event: content_block_delta` + "\n" + `data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "RAGFlow 是一款基于深度文档理解的开源 RAG 引擎。"}}` + "\n\n",
			`event: content_block_stop` + "\n" + `data: {"type": "content_block_stop", "index": 0}` + "\n\n",
			`event: message_delta` + "\n" + `data: {"type": "message_delta", "delta": {"stop_reason": "end_turn"}, "usage": {"output_tokens": 30}}` + "\n\n",
			`event: message_stop` + "\n" + `data: {"type": "message_stop"}` + "\n\n",
		}
		for _, e := range events {
			_, _ = w.Write([]byte(e))
			if flusher != nil {
				flusher.Flush()
			}
		}
	}))
	defer srv.Close()

	rawJSON := `{
		"llm_id": "qwen3.5-27b",
		"driver": "Anthropic",
		"api_key": "test-key",
		"base_url": "` + srv.URL + `",
		"max_rounds": 5,
		"sys_prompt": "You are a test assistant.",
		"prompts": [
			{"role": "user", "content": "The user query is ragflow 是什么"}
		],
		"tools": [
			{
				"component_name": "Retrieval",
				"name": "Retrieval",
				"params": {
					"dataset_ids": ["8d4eec40b50548cab31d4985bd807e23"]
				}
			}
		]
	}`

	var params map[string]any
	if err := json.Unmarshal([]byte(rawJSON), &params); err != nil {
		t.Fatalf("unmarshal: %v", err)
	}

	p := agentParamFromMap(params)
	msg, err := runEinoReActAgent(context.Background(), p)
	if err != nil {
		t.Fatalf("runEinoReActAgent failed: %v", err)
	}
	if msg.Content != "RAGFlow 是一款基于深度文档理解的开源 RAG 引擎。" {
		t.Fatalf("unexpected content: %s", msg.Content)
	}
}