feat: define AgenticMessage

components/model/agentic_callback_extra.go

@@ -0,0 +1,94 @@
+/*
+ * Copyright 2026 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 model
+
+import (
+	"github.com/cloudwego/eino/callbacks"
+	"github.com/cloudwego/eino/schema"
+)
+
+// AgenticConfig is the config for the agentic model.
+type AgenticConfig struct {
+	// Model is the model name.
+	Model string
+	// MaxTokens is the max number of output tokens, if reached the max tokens, the model will stop generating.
+	MaxTokens int
+	// Temperature is the temperature, which controls the randomness of the agentic model.
+	Temperature float32
+	// TopP is the top p, which controls the diversity of the agentic model.
+	TopP float32
+}
+
+// AgenticCallbackInput is the input for the agentic model callback.
+type AgenticCallbackInput struct {
+	// Messages is the agentic messages to be sent to the agentic model.
+	Messages []*schema.AgenticMessage
+	// Tools is the tools to be used in the agentic model.
+	Tools []*schema.ToolInfo
+	// Config is the config for the agentic model.
+	Config *AgenticConfig
+	// Extra is the extra information for the callback.
+	Extra map[string]any
+}
+
+// AgenticCallbackOutput is the output for the agentic model callback.
+type AgenticCallbackOutput struct {
+	// Message is the agentic message generated by the agentic model.
+	Message *schema.AgenticMessage
+	// Config is the config for the agentic model.
+	Config *AgenticConfig
+	// TokenUsage is the token usage of this request.
+	TokenUsage *TokenUsage
+	// Extra is the extra information for the callback.
+	Extra map[string]any
+}
+
+// ConvAgenticCallbackInput converts the callback input to the agentic model callback input.
+func ConvAgenticCallbackInput(src callbacks.CallbackInput) *AgenticCallbackInput {
+	switch t := src.(type) {
+	case *AgenticCallbackInput:
+		// when callback is triggered within component implementation,
+		// the input is usually already a typed *model.AgenticCallbackInput
+		return t
+	case []*schema.AgenticMessage:
+		// when callback is injected by graph node, not the component implementation itself,
+		// the input is the input of Agentic Model interface, which is []*schema.AgenticMessage
+		return &AgenticCallbackInput{
+			Messages: t,
+		}
+	default:
+		return nil
+	}
+}
+
+// ConvAgenticCallbackOutput converts the callback output to the agentic model callback output.
+func ConvAgenticCallbackOutput(src callbacks.CallbackOutput) *AgenticCallbackOutput {
+	switch t := src.(type) {
+	case *AgenticCallbackOutput:
+		// when callback is triggered within component implementation,
+		// the output is usually already a typed *model.AgenticCallbackOutput
+		return t
+	case *schema.AgenticMessage:
+		// when callback is injected by graph node, not the component implementation itself,
+		// the output is the output of Agentic Model interface, which is *schema.AgenticMessage
+		return &AgenticCallbackOutput{
+			Message: t,
+		}
+	default:
+		return nil
+	}
+}

components/model/agentic_callback_extra_test.go

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2026 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 model
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/cloudwego/eino/schema"
+)
+
+func TestConvAgenticModel(t *testing.T) {
+	assert.NotNil(t, ConvAgenticCallbackInput(&AgenticCallbackInput{}))
+	assert.NotNil(t, ConvAgenticCallbackInput([]*schema.AgenticMessage{}))
+	assert.Nil(t, ConvAgenticCallbackInput("asd"))
+
+	assert.NotNil(t, ConvAgenticCallbackOutput(&AgenticCallbackOutput{}))
+	assert.NotNil(t, ConvAgenticCallbackOutput(&schema.AgenticMessage{}))
+	assert.Nil(t, ConvAgenticCallbackOutput("asd"))
+}

components/model/interface.go

@@ -89,3 +89,15 @@ type ToolCallingChatModel interface {
 	// This method does not modify the current instance, making it safer for concurrent use.
 	WithTools(tools []*schema.ToolInfo) (ToolCallingChatModel, error)
 }
+
+// AgenticModel defines the interface for agentic models that support AgenticMessage.
+// It provides methods for generating complete and streaming outputs, and supports
+// tool calling via the WithTools method.
+type AgenticModel interface {
+	Generate(ctx context.Context, input []*schema.AgenticMessage, opts ...Option) (*schema.AgenticMessage, error)
+	Stream(ctx context.Context, input []*schema.AgenticMessage, opts ...Option) (*schema.StreamReader[*schema.AgenticMessage], error)
+
+	// WithTools returns a new Model instance with the specified tools bound.
+	// This method does not modify the current instance, making it safer for concurrent use.
+	WithTools(tools []*schema.ToolInfo) (AgenticModel, error)
+}

components/model/option.go

@@ -22,21 +22,29 @@ import "github.com/cloudwego/eino/schema"
 type Options struct {
 	// Temperature is the temperature for the model, which controls the randomness of the model.
 	Temperature *float32
-	// MaxTokens is the max number of tokens, if reached the max tokens, the model will stop generating, and mostly return an finish reason of "length".
-	MaxTokens *int
 	// Model is the model name.
 	Model *string
 	// TopP is the top p for the model, which controls the diversity of the model.
 	TopP *float32
-	// Stop is the stop words for the model, which controls the stopping condition of the model.
-	Stop []string
 	// Tools is a list of tools the model may call.
 	Tools []*schema.ToolInfo
+	// MaxTokens is the max number of tokens, if reached the max tokens, the model will stop generating, and mostly return a finish reason of "length".
+	MaxTokens *int
+	// Stop is the stop words for the model, which controls the stopping condition of the model.
+	Stop []string
+
+	// Options only available for chat model.
+
 	// ToolChoice controls which tool is called by the model.
 	ToolChoice *schema.ToolChoice
 	// AllowedToolNames specifies a list of tool names that the model is allowed to call.
 	// This allows for constraining the model to a specific subset of the available tools.
 	AllowedToolNames []string
+
+	// Options only available for agentic model.
+
+	// AgenticToolChoice controls how the agentic model calls tools.
+	AgenticToolChoice *schema.AgenticToolChoice
 }
 
 // Option is a call-time option for a ChatModel. Options are immutable and
@@ -108,6 +116,7 @@ func WithTools(tools []*schema.ToolInfo) Option {
 
 // WithToolChoice sets the tool choice for the model. It also allows for providing a list of
 // tool names to constrain the model to a specific subset of the available tools.
+// Only available for ChatModel.
 func WithToolChoice(toolChoice schema.ToolChoice, allowedToolNames ...string) Option {
 	return Option{
 		apply: func(opts *Options) {
@@ -117,6 +126,17 @@ func WithToolChoice(toolChoice schema.ToolChoice, allowedToolNames ...string) Op
 	}
 }
 
+// WithAgenticToolChoice is the option to set tool choice for the agentic model.
+// Only available for AgenticModel.
+func WithAgenticToolChoice(toolChoice *schema.AgenticToolChoice) Option {
+	return Option{
+		apply: func(opts *Options) {
+			opts.AgenticToolChoice = toolChoice
+		},
+	}
+}
+
+// WrapImplSpecificOptFn is the option to wrap the implementation specific option function.
 // WrapImplSpecificOptFn wraps an implementation-specific option function into
 // an [Option] so it can be passed alongside standard options.
 //

components/model/option_test.go

@@ -82,6 +82,29 @@ func TestOptions(t *testing.T) {
 		convey.So(opts.Tools, convey.ShouldNotBeNil)
 		convey.So(len(opts.Tools), convey.ShouldEqual, 0)
 	})
+
+	convey.Convey("test agentic tool choice option", t, func() {
+		var (
+			toolChoice   = schema.ToolChoiceForced
+			allowedTools = []*schema.AllowedTool{
+				{FunctionName: "agentic_tool"},
+			}
+		)
+		opts := GetCommonOptions(
+			nil,
+			WithAgenticToolChoice(&schema.AgenticToolChoice{
+				Type: toolChoice,
+				Forced: &schema.AgenticForcedToolChoice{
+					Tools: allowedTools,
+				},
+			}),
+		)
+
+		convey.So(opts.AgenticToolChoice, convey.ShouldNotBeNil)
+		convey.So(opts.AgenticToolChoice.Type, convey.ShouldEqual, toolChoice)
+		convey.So(opts.AgenticToolChoice.Forced, convey.ShouldNotBeNil)
+		convey.So(opts.AgenticToolChoice.Forced.Tools, convey.ShouldResemble, allowedTools)
+	})
 }
 
 type implOption struct {

components/prompt/agentic_callback_extra.go

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2026 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 prompt
+
+import (
+	"github.com/cloudwego/eino/callbacks"
+	"github.com/cloudwego/eino/schema"
+)
+
+// AgenticCallbackInput is the input for the callback.
+type AgenticCallbackInput struct {
+	// Variables is the variables for the callback.
+	Variables map[string]any
+	// Templates is the agentic templates for the callback.
+	Templates []schema.AgenticMessagesTemplate
+	// Extra is the extra information for the callback.
+	Extra map[string]any
+}
+
+// AgenticCallbackOutput is the output for the callback.
+type AgenticCallbackOutput struct {
+	// Result is the agentic result for the callback.
+	Result []*schema.AgenticMessage
+	// Templates is the agentic templates for the callback.
+	Templates []schema.AgenticMessagesTemplate
+	// Extra is the extra information for the callback.
+	Extra map[string]any
+}
+
+// ConvAgenticCallbackInput converts the callback input to the agentic prompt callback input.
+func ConvAgenticCallbackInput(src callbacks.CallbackInput) *AgenticCallbackInput {
+	switch t := src.(type) {
+	case *AgenticCallbackInput:
+		return t
+	case map[string]any:
+		return &AgenticCallbackInput{
+			Variables: t,
+		}
+	default:
+		return nil
+	}
+}
+
+// ConvAgenticCallbackOutput converts the callback output to the agentic prompt callback output.
+func ConvAgenticCallbackOutput(src callbacks.CallbackOutput) *AgenticCallbackOutput {
+	switch t := src.(type) {
+	case *AgenticCallbackOutput:
+		return t
+	case []*schema.AgenticMessage:
+		return &AgenticCallbackOutput{
+			Result: t,
+		}
+	default:
+		return nil
+	}
+}

components/prompt/agentic_callback_extra_test.go

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2026 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 prompt
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/cloudwego/eino/schema"
+)
+
+func TestConvAgenticPrompt(t *testing.T) {
+	assert.NotNil(t, ConvAgenticCallbackInput(&AgenticCallbackInput{
+		Variables: map[string]any{},
+		Templates: []schema.AgenticMessagesTemplate{
+			&schema.AgenticMessage{},
+		},
+	}))
+	assert.NotNil(t, ConvAgenticCallbackInput(map[string]any{}))
+	assert.Nil(t, ConvAgenticCallbackInput("asd"))
+
+	assert.NotNil(t, ConvAgenticCallbackOutput(&AgenticCallbackOutput{
+		Result: []*schema.AgenticMessage{
+			{},
+		},
+		Templates: []schema.AgenticMessagesTemplate{
+			&schema.AgenticMessage{},
+		},
+	}))
+	assert.NotNil(t, ConvAgenticCallbackOutput([]*schema.AgenticMessage{}))
+}