RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
// 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), ¶ms); 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)
}
}