feat: add more AgentOption for react agent and a converter function to compose.Option

Change-Id: I3a069cd40b5fff9d701b35c4f1d383c303e2387f

Author: shentongmartin

_typos.toml

@@ -6,6 +6,7 @@ Invokable = "Invokable"
 invokable = "invokable"
 InvokableLambda = "InvokableLambda"
 InvokableRun = "InvokableRun"
+typ = "typ"
 
 [files]
 extend-exclude = ["go.mod", "go.sum", "check_branch_name.sh"]

components/tool/option.go

@@ -17,8 +17,8 @@
 package tool
 
 // Option defines call option for InvokableTool or StreamableTool component, which is part of component interface signature.
-// Each tool implementation could define its own options struct and option funcs within its own package,
-// then wrap the impl specific option funcs into this type, before passing to InvokableRun or StreamableRun.
+// Each tool implementation could define its own options struct and option functions within its own package,
+// then wrap the impl specific option functions into this type, before passing to InvokableRun or StreamableRun.
 type Option struct {
 	implSpecificOptFn any
 }

compose/graph_call_options.go

@@ -80,6 +80,24 @@ func (o Option) DesignateNodeWithPath(path ...*NodePath) Option {
 	return o
 }
 
+// DesignateNodePrependPath prepends the prefix to the path of the node(s) to which the option will be applied to.
+// Useful when you already have an Option designated to a graph's node, and now you want to add this graph as a subgraph.
+// e.g.
+// Your subgraph has a Node with key "A", and your subgraph's NodeKey is "sub_graph", you can specify option to A using:
+//
+// option := WithCallbacks(...).DesignateNode("A").DesignateNodePrependPath("sub_graph")
+// Note: as an End User, you probably don't need to use this method, as DesignateNodeWithPath will be sufficient in most use cases.
+// Note: as a Flow author, if you define your own Option type, and at the same time your flow can be exported to graph and added as GraphNode,
+// you can use this method to prepend your Option's designated path with the GraphNode's path.
+func (o Option) DesignateNodePrependPath(prefix *NodePath) Option {
+	for i := range o.paths {
+		p := o.paths[i]
+		p.path = append(prefix.path, p.path...)
+	}
+
+	return o
+}
+
 // WithEmbeddingOption is a functional option type for embedding component.
 // e.g.
 //

flow/agent/agent_option.go

@@ -19,14 +19,14 @@ package agent
 import "github.com/cloudwego/eino/compose"
 
 // AgentOption is the common option type for various agent and multi-agent implementations.
-// For options intended to use with underlying graph or components, use WithComposeOptions to specify.
 // For options intended to use with particular agent/multi-agent implementations, use WrapImplSpecificOptFn to specify.
 type AgentOption struct {
 	implSpecificOptFn any
 	composeOptions    []compose.Option
 }
 
 // GetComposeOptions returns all compose options from the given agent options.
+// Deprecated
 func GetComposeOptions(opts ...AgentOption) []compose.Option {
 	var result []compose.Option
 	for _, opt := range opts {
@@ -37,6 +37,7 @@ func GetComposeOptions(opts ...AgentOption) []compose.Option {
 }
 
 // WithComposeOptions returns an agent option that specifies compose options.
+// Deprecated: use option functions defined by each agent flow implementation instead.
 func WithComposeOptions(opts ...compose.Option) AgentOption {
 	return AgentOption{
 		composeOptions: opts,

flow/agent/multiagent/host/callback.go

@@ -39,6 +39,7 @@ type HandOffInfo struct {
 }
 
 // ConvertCallbackHandlers converts []host.MultiAgentCallback to callbacks.Handler.
+// Deprecated: use ConvertOptions to convert agent.AgentOption to compose.Option when adding MultiAgent's Graph to another Graph.
 func ConvertCallbackHandlers(handlers ...MultiAgentCallback) callbacks.Handler {
 	onChatModelEnd := func(ctx context.Context, info *callbacks.RunInfo, output *model.CallbackOutput) context.Context {
 		if output == nil || info == nil {
@@ -121,5 +122,76 @@ func convertCallbacks(opts ...agent.AgentOption) callbacks.Handler {
 	}
 
 	handlers := agentOptions.agentCallbacks
-	return ConvertCallbackHandlers(handlers...)
+
+	onChatModelEnd := func(ctx context.Context, info *callbacks.RunInfo, output *model.CallbackOutput) context.Context {
+		if output == nil || info == nil {
+			return ctx
+		}
+
+		msg := output.Message
+		if msg == nil || msg.Role != schema.Assistant || len(msg.ToolCalls) == 0 {
+			return ctx
+		}
+
+		agentName := msg.ToolCalls[0].Function.Name
+		argument := msg.ToolCalls[0].Function.Arguments
+
+		for _, cb := range handlers {
+			ctx = cb.OnHandOff(ctx, &HandOffInfo{
+				ToAgentName: agentName,
+				Argument:    argument,
+			})
+		}
+
+		return ctx
+	}
+
+	onChatModelEndWithStreamOutput := func(ctx context.Context, info *callbacks.RunInfo, output *schema.StreamReader[*model.CallbackOutput]) context.Context {
+		if output == nil || info == nil {
+			return ctx
+		}
+
+		defer output.Close()
+
+		var msgs []*schema.Message
+		for {
+			oneOutput, err := output.Recv()
+			if err == io.EOF {
+				break
+			}
+			if err != nil {
+				return ctx
+			}
+
+			msg := oneOutput.Message
+			if msg == nil {
+				continue
+			}
+
+			msgs = append(msgs, msg)
+		}
+
+		msg, err := schema.ConcatMessages(msgs)
+		if err != nil {
+			return ctx
+		}
+
+		if msg.Role != schema.Assistant || len(msg.ToolCalls) == 0 {
+			return ctx
+		}
+
+		for _, cb := range handlers {
+			ctx = cb.OnHandOff(ctx, &HandOffInfo{
+				ToAgentName: msg.ToolCalls[0].Function.Name,
+				Argument:    msg.ToolCalls[0].Function.Arguments,
+			})
+		}
+
+		return ctx
+	}
+
+	return template.NewHandlerHelper().ChatModel(&template.ModelCallbackHandler{
+		OnEnd:                 onChatModelEnd,
+		OnEndWithStreamOutput: onChatModelEndWithStreamOutput,
+	}).Handler()
 }

flow/agent/multiagent/host/compose_test.go

@@ -24,12 +24,15 @@ import (
 	"github.com/stretchr/testify/assert"
 	"go.uber.org/mock/gomock"
 
+	"github.com/cloudwego/eino/callbacks"
+	chatmodel "github.com/cloudwego/eino/components/model"
 	"github.com/cloudwego/eino/components/prompt"
 	"github.com/cloudwego/eino/compose"
 	"github.com/cloudwego/eino/flow/agent"
 	"github.com/cloudwego/eino/internal/generic"
 	"github.com/cloudwego/eino/internal/mock/components/model"
 	"github.com/cloudwego/eino/schema"
+	template "github.com/cloudwego/eino/utils/callbacks"
 )
 
 func TestHostMultiAgent(t *testing.T) {
@@ -48,6 +51,14 @@ func TestHostMultiAgent(t *testing.T) {
 
 	specialist2 := &Specialist{
 		Invokable: func(ctx context.Context, input []*schema.Message, opts ...agent.AgentOption) (*schema.Message, error) {
+			agentOpts := agent.GetImplSpecificOptions(&specialist2Options{}, opts...)
+			if agentOpts.mockOutput != nil {
+				return &schema.Message{
+					Role:    schema.Assistant,
+					Content: *agentOpts.mockOutput,
+				}, nil
+			}
+
 			return &schema.Message{
 				Role:    schema.Assistant,
 				Content: "specialist2 invoke answer",
@@ -92,11 +103,18 @@ func TestHostMultiAgent(t *testing.T) {
 			Content: "direct answer",
 		}
 
-		mockHostLLM.EXPECT().Generate(gomock.Any(), gomock.Any()).Return(directAnswerMsg, nil).Times(1)
+		mockHostLLM.EXPECT().Generate(gomock.Any(), gomock.Any(), gomock.Any()).
+			DoAndReturn(func(_ context.Context, input []*schema.Message, opts ...chatmodel.Option) (*schema.Message, error) {
+				modelOpts := chatmodel.GetCommonOptions(&chatmodel.Options{}, opts...)
+				assert.Equal(t, *modelOpts.Temperature, float32(0.7))
+				return directAnswerMsg, nil
+			}).
+			Times(1)
 
 		mockCallback := &mockAgentCallback{}
 
-		out, err := hostMA.Generate(ctx, nil, WithAgentCallbacks(mockCallback))
+		out, err := hostMA.Generate(ctx, nil, WithAgentCallbacks(mockCallback),
+			WithAgentModelOptions(hostMA.HostNodeKey(), chatmodel.WithTemperature(0.7)))
 		assert.NoError(t, err)
 		assert.Equal(t, "direct answer", out.Content)
 		assert.Empty(t, mockCallback.infos)
@@ -164,11 +182,18 @@ func TestHostMultiAgent(t *testing.T) {
 		}
 
 		mockHostLLM.EXPECT().Generate(gomock.Any(), gomock.Any()).Return(handOffMsg, nil).Times(1)
-		mockSpecialistLLM1.EXPECT().Generate(gomock.Any(), gomock.Any()).Return(specialistMsg, nil).Times(1)
+		mockSpecialistLLM1.EXPECT().Generate(gomock.Any(), gomock.Any(), gomock.Any()).
+			DoAndReturn(func(_ context.Context, input []*schema.Message, opts ...chatmodel.Option) (*schema.Message, error) {
+				modelOpts := chatmodel.GetCommonOptions(&chatmodel.Options{}, opts...)
+				assert.Equal(t, *modelOpts.Temperature, float32(0.7))
+				return specialistMsg, nil
+			}).
+			Times(1)
 
 		mockCallback := &mockAgentCallback{}
 
-		out, err := hostMA.Generate(ctx, nil, WithAgentCallbacks(mockCallback))
+		out, err := hostMA.Generate(ctx, nil, WithAgentCallbacks(mockCallback),
+			WithAgentModelOptions(specialist1.Name, chatmodel.WithTemperature(0.7)))
 		assert.NoError(t, err)
 		assert.Equal(t, "specialist 1 answer", out.Content)
 		assert.Equal(t, []*HandOffInfo{
@@ -379,16 +404,41 @@ func TestHostMultiAgent(t *testing.T) {
 			},
 		}
 
-		specialistMsg := &schema.Message{
+		specialist1Msg := &schema.Message{
 			Role:    schema.Assistant,
 			Content: "Beijing",
 		}
 
-		mockHostLLM.EXPECT().Generate(gomock.Any(), gomock.Any()).Return(handOffMsg, nil).Times(1)
-		mockSpecialistLLM1.EXPECT().Generate(gomock.Any(), gomock.Any()).Return(specialistMsg, nil).Times(1)
+		mockHostLLM.EXPECT().Generate(gomock.Any(), gomock.Any()).Return(handOffMsg, nil).Times(2)
+		mockSpecialistLLM1.EXPECT().Generate(gomock.Any(), gomock.Any(), gomock.Any()).
+			DoAndReturn(func(_ context.Context, input []*schema.Message, opts ...chatmodel.Option) (*schema.Message, error) {
+				modelOpts := chatmodel.GetCommonOptions(&chatmodel.Options{}, opts...)
+				assert.Equal(t, *modelOpts.Temperature, float32(0.7))
+				return specialist1Msg, nil
+			}).
+			Times(1)
 
 		mockCallback := &mockAgentCallback{}
 
+		var hostOutput, specialist1Output, specialist2Output string
+		hostModelCallback := template.NewHandlerHelper().ChatModel(&template.ModelCallbackHandler{
+			OnEnd: func(ctx context.Context, runInfo *callbacks.RunInfo, output *chatmodel.CallbackOutput) context.Context {
+				hostOutput = output.Message.ToolCalls[0].Function.Name
+				return ctx
+			},
+		}).Handler()
+		specialist1ModelCallback := template.NewHandlerHelper().ChatModel(&template.ModelCallbackHandler{
+			OnEnd: func(ctx context.Context, runInfo *callbacks.RunInfo, output *chatmodel.CallbackOutput) context.Context {
+				specialist1Output = output.Message.Content
+				return ctx
+			},
+		}).Handler()
+		specialist2LambdaCallback := template.NewHandlerHelper().Lambda(callbacks.NewHandlerBuilder().OnEndFn(
+			func(ctx context.Context, info *callbacks.RunInfo, output callbacks.CallbackOutput) context.Context {
+				specialist2Output = output.(*schema.Message).Content
+				return ctx
+			}).Build()).Handler()
+
 		hostMA, err := NewMultiAgent(ctx, &MultiAgentConfig{
 			Host: Host{
 				ChatModel: mockHostLLM,
@@ -409,7 +459,14 @@ func TestHostMultiAgent(t *testing.T) {
 			Compile(ctx)
 		assert.NoError(t, err)
 
-		out, err := fullGraph.Invoke(ctx, map[string]any{"country_name": "China"}, compose.WithCallbacks(ConvertCallbackHandlers(mockCallback)).DesignateNodeWithPath(compose.NewNodePath("host_ma_node", hostMA.HostNodeKey())))
+		convertedOptions := ConvertOptions(compose.NewNodePath("host_ma_node"), WithAgentCallbacks(mockCallback),
+			WithAgentModelOptions(specialist1.Name, chatmodel.WithTemperature(0.7)),
+			WithAgentModelCallbacks(hostMA.HostNodeKey(), hostModelCallback),
+			WithAgentModelCallbacks(specialist1.Name, specialist1ModelCallback),
+			WithSpecialistLambdaCallbacks(specialist2.Name, specialist2LambdaCallback),
+			WithSpecialistLambdaOptions(specialist2.Name, withSpecialist2MockOutput("mock_city_name")))
+
+		out, err := fullGraph.Invoke(ctx, map[string]any{"country_name": "China"}, convertedOptions...)
 		assert.NoError(t, err)
 		assert.Equal(t, "Beijing", out.Content)
 		assert.Equal(t, []*HandOffInfo{
@@ -418,6 +475,28 @@ func TestHostMultiAgent(t *testing.T) {
 				Argument:    `{"reason": "specialist 1 is the best"}`,
 			},
 		}, mockCallback.infos)
+		assert.Equal(t, hostOutput, specialist1.Name)
+		assert.Equal(t, specialist1Output, out.Content)
+		assert.Equal(t, specialist2Output, "")
+
+		handOffMsg.ToolCalls[0].Function.Name = specialist2.Name
+		handOffMsg.ToolCalls[0].Function.Arguments = `{"reason": "specialist 2 is even better"}`
+
+		out, err = fullGraph.Invoke(ctx, map[string]any{"country_name": "China"}, convertedOptions...)
+		assert.NoError(t, err)
+		assert.Equal(t, "mock_city_name", out.Content)
+		assert.Equal(t, []*HandOffInfo{
+			{
+				ToAgentName: specialist1.Name,
+				Argument:    `{"reason": "specialist 1 is the best"}`,
+			},
+			{
+				ToAgentName: specialist2.Name,
+				Argument:    `{"reason": "specialist 2 is even better"}`,
+			},
+		}, mockCallback.infos)
+		assert.Equal(t, hostOutput, specialist2.Name)
+		assert.Equal(t, specialist2Output, "mock_city_name")
 	})
 }
 
@@ -429,3 +508,13 @@ func (m *mockAgentCallback) OnHandOff(ctx context.Context, info *HandOffInfo) co
 	m.infos = append(m.infos, info)
 	return ctx
 }
+
+type specialist2Options struct {
+	mockOutput *string
+}
+
+func withSpecialist2MockOutput(mockOutput string) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *specialist2Options) {
+		o.mockOutput = &mockOutput
+	})
+}

flow/agent/multiagent/host/options.go

@@ -16,14 +16,88 @@
 
 package host
 
-import "github.com/cloudwego/eino/flow/agent"
+import (
+	"github.com/cloudwego/eino/callbacks"
+	"github.com/cloudwego/eino/components/model"
+	"github.com/cloudwego/eino/compose"
+	"github.com/cloudwego/eino/flow/agent"
+)
 
 type options struct {
 	agentCallbacks []MultiAgentCallback
+	composeOptions []compose.Option
 }
 
 func WithAgentCallbacks(agentCallbacks ...MultiAgentCallback) agent.AgentOption {
 	return agent.WrapImplSpecificOptFn(func(opts *options) {
 		opts.agentCallbacks = append(opts.agentCallbacks, agentCallbacks...)
 	})
 }
+
+// WithAgentModelOptions returns an agent option that specifies model.Option for the given agent.
+// The given agentName should be the name of the agent in the graph.
+// e.g.
+//
+//	if specifying model.Option for the host agent, use MultiAgent.HostNodeKey() as the agentName.
+//	if specifying model.Option for the specialist agent, use the specialist agent's AgentMeta.Name as the agentName.
+func WithAgentModelOptions(agentName string, opts ...model.Option) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithChatModelOption(opts...).DesignateNode(agentName))
+	})
+}
+
+// WithAgentModelCallbacks returns an agent option that specifies callbacks.Handler for the given agent's ChatModel.
+// The given agentName should be the name of the agent in the graph.
+// e.g.
+//
+//	if specifying model.Option for the host agent, use MultiAgent.HostNodeKey() as the agentName.
+//	if specifying model.Option for the specialist agent, use the specialist agent's AgentMeta.Name as the agentName.
+func WithAgentModelCallbacks(agentName string, cbs ...callbacks.Handler) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithCallbacks(cbs...).DesignateNode(agentName))
+	})
+}
+
+// WithSpecialistLambdaOptions returns an agent option that specifies agent.AgentOption for the given specialist's Lambda.
+// The given specialistName should be the name of the specialist in the graph.
+func WithSpecialistLambdaOptions(specialistName string, opts ...agent.AgentOption) agent.AgentOption {
+	anyOpts := make([]any, len(opts))
+	for i, opt := range opts {
+		anyOpts[i] = opt
+	}
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithLambdaOption(anyOpts...).DesignateNode(specialistName))
+	})
+}
+
+// WithSpecialistLambdaCallbacks returns an agent option that specifies callbacks.Handler for the given specialist's Lambda.
+// The given specialistName should be the name of the specialist in the graph.
+func WithSpecialistLambdaCallbacks(specialistName string, cbs ...callbacks.Handler) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithCallbacks(cbs...).DesignateNode(specialistName))
+	})
+}
+
+// ConvertOptions converts agent options to compose options, and designate them to the Agent sub graph specified by nodePath.
+// Useful when adding MultiAgent's Graph to another Graph.
+// The parameter nodePath is the path to the MultiAgent sub graph within the whole Graph.
+// If nodePath == nil, then MultiAgent's Graph is treated as a stand-alone, top-level Graph.
+func ConvertOptions(nodePath *compose.NodePath, opts ...agent.AgentOption) []compose.Option {
+	composeOpts := agent.GetImplSpecificOptions(&options{}, opts...).composeOptions
+	if nodePath != nil {
+		for i := range composeOpts {
+			composeOpts[i] = composeOpts[i].DesignateNodePrependPath(nodePath)
+		}
+	}
+
+	convertedCallbackHandler := convertCallbacks(opts...)
+	if convertedCallbackHandler != nil {
+		callbackOpt := compose.WithCallbacks(convertedCallbackHandler).DesignateNode(defaultHostNodeKey)
+		if nodePath != nil {
+			return append(composeOpts, callbackOpt.DesignateNodePrependPath(nodePath))
+		}
+		return append(composeOpts, callbackOpt)
+	}
+
+	return composeOpts
+}

flow/agent/multiagent/host/types.go

@@ -38,25 +38,11 @@ type MultiAgent struct {
 }
 
 func (ma *MultiAgent) Generate(ctx context.Context, input []*schema.Message, opts ...agent.AgentOption) (*schema.Message, error) {
-	composeOptions := agent.GetComposeOptions(opts...)
-
-	handler := convertCallbacks(opts...)
-	if handler != nil {
-		composeOptions = append(composeOptions, compose.WithCallbacks(handler).DesignateNode(ma.HostNodeKey()))
-	}
-
-	return ma.runnable.Invoke(ctx, input, composeOptions...)
+	return ma.runnable.Invoke(ctx, input, ConvertOptions(nil, opts...)...)
 }
 
 func (ma *MultiAgent) Stream(ctx context.Context, input []*schema.Message, opts ...agent.AgentOption) (*schema.StreamReader[*schema.Message], error) {
-	composeOptions := agent.GetComposeOptions(opts...)
-
-	handler := convertCallbacks(opts...)
-	if handler != nil {
-		composeOptions = append(composeOptions, compose.WithCallbacks(handler).DesignateNode(ma.HostNodeKey()))
-	}
-
-	return ma.runnable.Stream(ctx, input, composeOptions...)
+	return ma.runnable.Stream(ctx, input, ConvertOptions(nil, opts...)...)
 }
 
 // ExportGraph exports the underlying graph from MultiAgent, along with the []compose.GraphAddNodeOpt to be used when adding this graph to another graph.

flow/agent/react/callback.go

@@ -27,6 +27,8 @@ import (
 //	callback := BuildAgentCallback(modelHandler, toolHandler)
 //	agent, err := react.NewAgent(ctx, &AgentConfig{})
 //	agent.Generate(ctx, input, agent.WithComposeOptions(compose.WithCallbacks(callback)))
+//
+// Deprecated: use WithModelCallbacks and WithToolCallbacks instead.
 func BuildAgentCallback(modelHandler *template.ModelCallbackHandler, toolHandler *template.ToolCallbackHandler) callbacks.Handler {
 	return template.NewHandlerHelper().ChatModel(modelHandler).Tool(toolHandler).Handler()
 }

flow/agent/react/options.go

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2025 CloudWeGo Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package react
+
+import (
+	"github.com/cloudwego/eino/callbacks"
+	"github.com/cloudwego/eino/components/model"
+	"github.com/cloudwego/eino/components/tool"
+	"github.com/cloudwego/eino/compose"
+	"github.com/cloudwego/eino/flow/agent"
+)
+
+type options struct {
+	composeOptions []compose.Option
+}
+
+// WithChatModelOptions returns an agent option that specifies model.Option for the ChatModel node.
+func WithChatModelOptions(opts ...model.Option) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithChatModelOption(opts...))
+	})
+}
+
+// WithToolOptions returns an agent option that specifies tool.Option for the ToolsNode node.
+func WithToolOptions(opts ...tool.Option) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithToolsNodeOption(compose.WithToolOption(opts...)))
+	})
+}
+
+// WithToolList returns an agent option that specifies tool list for the ToolsNode node, overriding default tool list.
+func WithToolList(tool ...tool.BaseTool) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithToolsNodeOption(compose.WithToolList(tool...)))
+	})
+}
+
+// WithRuntimeMaxSteps returns an agent option that specifies max steps for the agent, overriding default configuration.
+func WithRuntimeMaxSteps(maxSteps int) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithRuntimeMaxSteps(maxSteps))
+	})
+}
+
+// WithModelCallbacks returns an agent option that specifies callback handlers for the ChatModel node.
+func WithModelCallbacks(cbs ...callbacks.Handler) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithCallbacks(cbs...).DesignateNode(nodeKeyModel))
+	})
+}
+
+// WithToolCallbacks returns an agent option that specifies callback handlers for the tools executed by ToolsNode node.
+func WithToolCallbacks(cbs ...callbacks.Handler) agent.AgentOption {
+	return agent.WrapImplSpecificOptFn(func(o *options) {
+		o.composeOptions = append(o.composeOptions, compose.WithCallbacks(cbs...).DesignateNode(nodeKeyTools))
+	})
+}
+
+// ConvertOptions converts agent options to compose options, and designate them to the Agent sub graph specified by nodePath.
+// Useful when adding Agent's Graph to another Graph.
+// The parameter nodePath is the path to the Agent sub graph within the whole Graph.
+// If nodePath == nil, then Agent's Graph is treated as a stand-alone, top-level Graph.
+func ConvertOptions(nodePath *compose.NodePath, opts ...agent.AgentOption) []compose.Option {
+	composeOpts := agent.GetImplSpecificOptions(&options{}, opts...).composeOptions
+	if nodePath != nil {
+		for i := range composeOpts {
+			composeOpts[i] = composeOpts[i].DesignateNodePrependPath(nodePath)
+		}
+	}
+
+	return composeOpts
+}

flow/agent/react/react.go

@@ -308,7 +308,7 @@ func getReturnDirectlyToolCallID(input *schema.Message, toolReturnDirectly map[s
 
 // Generate generates a response from the agent.
 func (r *Agent) Generate(ctx context.Context, input []*schema.Message, opts ...agent.AgentOption) (output *schema.Message, err error) {
-	output, err = r.runnable.Invoke(ctx, input, agent.GetComposeOptions(opts...)...)
+	output, err = r.runnable.Invoke(ctx, input, ConvertOptions(nil, opts...)...)
 	if err != nil {
 		return nil, err
 	}
@@ -319,7 +319,7 @@ func (r *Agent) Generate(ctx context.Context, input []*schema.Message, opts ...a
 // Stream calls the agent and returns a stream response.
 func (r *Agent) Stream(ctx context.Context, input []*schema.Message, opts ...agent.AgentOption) (
 	output *schema.StreamReader[*schema.Message], err error) {
-	res, err := r.runnable.Stream(ctx, input, agent.GetComposeOptions(opts...)...)
+	res, err := r.runnable.Stream(ctx, input, ConvertOptions(nil, opts...)...)
 	if err != nil {
 		return nil, err
 	}

flow/agent/react/react_test.go

@@ -28,6 +28,7 @@ import (
 	"github.com/stretchr/testify/assert"
 	"go.uber.org/mock/gomock"
 
+	"github.com/cloudwego/eino/callbacks"
 	"github.com/cloudwego/eino/components/model"
 	"github.com/cloudwego/eino/components/tool"
 	"github.com/cloudwego/eino/compose"
@@ -53,6 +54,11 @@ func TestReact(t *testing.T) {
 	times := 0
 	cm.EXPECT().Generate(gomock.Any(), gomock.Any(), gomock.Any()).
 		DoAndReturn(func(ctx context.Context, input []*schema.Message, opts ...model.Option) (*schema.Message, error) {
+			modelOpts := model.GetCommonOptions(&model.Options{}, opts...)
+			if modelOpts.Temperature == nil || *modelOpts.Temperature != 0.7 {
+				return nil, errors.New("temperature not match")
+			}
+
 			times++
 			if times <= 2 {
 				info, _ := fakeTool.Info(ctx)
@@ -95,13 +101,10 @@ func TestReact(t *testing.T) {
 			Role:    schema.User,
 			Content: "使用 greet tool 持续打招呼，直到得到一个 bye 的回复，打招呼名字按照以下顺序: max、bob、alice、john、marry、joe、ken、lily, 请直接开始!请直接开始!请直接开始!",
 		},
-	}, agent.WithComposeOptions(compose.WithCallbacks(callbackForTest)))
+	}, WithChatModelOptions(model.WithTemperature(0.7)),
+		WithToolOptions(withMockOutput("mock_output")))
 	assert.Nil(t, err)
 
-	if out != nil {
-		t.Log(out.Content)
-	}
-
 	// test return directly
 	times = 0
 	a, err = NewAgent(ctx, &AgentConfig{
@@ -123,12 +126,37 @@ func TestReact(t *testing.T) {
 			Role:    schema.User,
 			Content: "使用 greet tool 持续打招呼，直到得到一个 bye 的回复，打招呼名字按照以下顺序: max、bob、alice、john、marry、joe、ken、lily, 请直接开始!请直接开始!请直接开始!",
 		},
-	}, agent.WithComposeOptions(compose.WithCallbacks(callbackForTest)))
+	}, WithChatModelOptions(model.WithTemperature(0.7)))
 	assert.Nil(t, err)
 
 	if out != nil {
 		t.Log(out.Content)
 	}
+
+	// test max steps
+	times = 0
+	out, err = a.Generate(ctx, []*schema.Message{
+		{
+			Role:    schema.User,
+			Content: "使用 greet tool 持续打招呼，直到得到一个 bye 的回复，打招呼名字按照以下顺序: max、bob、alice、john、marry、joe、ken、lily, 请直接开始!请直接开始!请直接开始!",
+		},
+	}, WithRuntimeMaxSteps(1),
+		WithChatModelOptions(model.WithTemperature(0.7)))
+	assert.ErrorContains(t, err, "max step")
+
+	// test change tools
+	times = 0
+	fakeStreamTool := &fakeStreamToolGreetForTest{
+		tarCount: 20,
+	}
+	out, err = a.Generate(ctx, []*schema.Message{
+		{
+			Role:    schema.User,
+			Content: "使用 greet tool 持续打招呼，直到得到一个 bye 的回复，打招呼名字按照以下顺序: max、bob、alice、john、marry、joe、ken、lily, 请直接开始!请直接开始!请直接开始!",
+		},
+	}, WithChatModelOptions(model.WithTemperature(0.7)),
+		WithToolList(fakeStreamTool))
+	assert.ErrorContains(t, err, "tool greet not found in toolsNode indexes")
 }
 
 func TestReactStream(t *testing.T) {
@@ -224,7 +252,7 @@ func TestReactStream(t *testing.T) {
 			Role:    schema.User,
 			Content: "使用 greet tool 持续打招呼，直到得到一个 bye 的回复，打招呼名字按照以下顺序: max、bob、alice、john、marry、joe、ken、lily, 请直接开始!请直接开始!请直接开始!",
 		},
-	}, agent.WithComposeOptions(compose.WithCallbacks(callbackForTest)))
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -275,7 +303,7 @@ func TestReactStream(t *testing.T) {
 			Role:    schema.User,
 			Content: "使用 greet tool 持续打招呼，直到得到一个 bye 的回复，打招呼名字按照以下顺序: max、bob、alice、john、marry、joe、ken、lily, 请直接开始!请直接开始!请直接开始!",
 		},
-	}, agent.WithComposeOptions(compose.WithCallbacks(callbackForTest)))
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -311,7 +339,7 @@ func TestReactStream(t *testing.T) {
 			Role:    schema.User,
 			Content: "使用 greet tool 持续打招呼，直到得到一个 bye 的回复，打招呼名字按照以下顺序: max、bob、alice、john、marry、joe、ken、lily, 请直接开始!请直接开始!请直接开始!",
 		},
-	}, agent.WithComposeOptions(compose.WithCallbacks(callbackForTest)))
+	})
 	assert.NoError(t, err)
 
 	defer out.Close()
@@ -385,7 +413,7 @@ func TestReactWithModifier(t *testing.T) {
 			Role:    schema.User,
 			Content: "hello",
 		},
-	}, agent.WithComposeOptions(compose.WithCallbacks(callbackForTest)))
+	})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -452,8 +480,7 @@ func TestAgentInGraph(t *testing.T) {
 		r, err := chain.Compile(ctx)
 		assert.Nil(t, err)
 
-		res, err := r.Invoke(ctx, []*schema.Message{{Role: schema.User, Content: "hello"}},
-			compose.WithCallbacks(callbackForTest))
+		res, err := r.Invoke(ctx, []*schema.Message{{Role: schema.User, Content: "hello"}}, compose.WithCallbacks(callbackForTest))
 		assert.Nil(t, err)
 
 		t.Log(res)
@@ -510,16 +537,35 @@ func TestAgentInGraph(t *testing.T) {
 		assert.Nil(t, err)
 
 		chain.
-			AppendGraph(agentGraph, opts...).
+			AppendGraph(agentGraph, append(opts, compose.WithNodeKey("react_agent"))...).
 			AppendLambda(compose.InvokableLambda(func(ctx context.Context, input *schema.Message) (string, error) {
 				t.Log("got agent response: ", input.Content)
 				return input.Content, nil
 			}))
 		r, err := chain.Compile(ctx)
 		assert.Nil(t, err)
 
-		outStream, err := r.Stream(ctx, []*schema.Message{{Role: schema.User, Content: "hello"}},
-			compose.WithCallbacks(callbackForTest))
+		var modelCallbackCnt, toolCallbackCnt int
+		modelCallback := template.NewHandlerHelper().ChatModel(&template.ModelCallbackHandler{
+			OnStart: func(ctx context.Context, runInfo *callbacks.RunInfo, input *model.CallbackInput) context.Context {
+				modelCallbackCnt++
+				return ctx
+			},
+		}).Handler()
+		toolCallback := template.NewHandlerHelper().Tool(&template.ToolCallbackHandler{
+			OnStart: func(ctx context.Context, runInfo *callbacks.RunInfo, input *tool.CallbackInput) context.Context {
+				toolCallbackCnt++
+				return ctx
+			},
+		}).Handler()
+
+		agentOptions := []agent.AgentOption{
+			WithChatModelOptions(model.WithTemperature(0.7)),
+			WithModelCallbacks(modelCallback),
+			WithToolCallbacks(toolCallback),
+		}
+		convertedOptions := ConvertOptions(compose.NewNodePath("react_agent"), agentOptions...)
+		outStream, err := r.Stream(ctx, []*schema.Message{{Role: schema.User, Content: "hello"}}, convertedOptions...)
 		if err != nil {
 			t.Fatal(err)
 		}
@@ -541,8 +587,10 @@ func TestAgentInGraph(t *testing.T) {
 		}
 
 		t.Log(msg)
-	})
 
+		assert.Equal(t, 3, modelCallbackCnt)
+		assert.Equal(t, 2, toolCallbackCnt)
+	})
 }
 
 type fakeStreamToolGreetForTest struct {
@@ -572,6 +620,16 @@ type fakeToolGreetForTest struct {
 	curCount int
 }
 
+type toolOption struct {
+	mockOutput *string
+}
+
+func withMockOutput(output string) tool.Option {
+	return tool.WrapImplSpecificOptFn(func(opt *toolOption) {
+		opt.mockOutput = &output
+	})
+}
+
 func (t *fakeToolGreetForTest) Info(_ context.Context) (*schema.ToolInfo, error) {
 	return &schema.ToolInfo{
 		Name: "greet",
@@ -602,7 +660,12 @@ func (t *fakeStreamToolGreetForTest) Info(_ context.Context) (*schema.ToolInfo,
 	}, nil
 }
 
-func (t *fakeToolGreetForTest) InvokableRun(_ context.Context, argumentsInJSON string, _ ...tool.Option) (string, error) {
+func (t *fakeToolGreetForTest) InvokableRun(_ context.Context, argumentsInJSON string, opts ...tool.Option) (string, error) {
+	toolOpts := tool.GetImplSpecificOptions(&toolOption{}, opts...)
+	if toolOpts.mockOutput != nil {
+		return *toolOpts.mockOutput, nil
+	}
+
 	p := &fakeToolInput{}
 	err := sonic.UnmarshalString(argumentsInJSON, p)
 	if err != nil {