AgenticModel User Guide [Beta]

// BaseModel is the generic base model interface parameterized by message type M.
type BaseModel[M any] interface {
    Generate(ctx context.Context, input []M, opts ...Option) (M, error)
    Stream(ctx context.Context, input []M, opts ...Option) (*schema.StreamReader[M], error)
}

// AgenticModel is a type alias for BaseModel specialized with
// *schema.AgenticMessage.
type AgenticModel = BaseModel[*schema.AgenticMessage]

Generate(ctx context.Context, input []*schema.AgenticMessage, opts ...model.Option) (*schema.AgenticMessage, error)

Stream(ctx context.Context, input []*schema.AgenticMessage, opts ...model.Option) (*schema.StreamReader[*schema.AgenticMessage], error)

reader, err := m.Stream(ctx, messages)
if err != nil {
    return err
}
defer reader.Close()

for {
    chunk, err := reader.Recv()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return err
    }
    // handle chunk
}

type AgenticToolChoice struct {
    Type    ToolChoice
    Allowed *AgenticAllowedToolChoice
    Forced  *AgenticForcedToolChoice
}

type AllowedTool struct {
    FunctionName string
    MCPTool      *AllowedMCPTool
    ServerTool   *AllowedServerTool
}

type AgenticRoleType string

const (
    AgenticRoleTypeSystem    AgenticRoleType = "system"
    AgenticRoleTypeUser      AgenticRoleType = "user"
    AgenticRoleTypeAssistant AgenticRoleType = "assistant"
)

type AgenticMessage struct {
    Role          AgenticRoleType
    ContentBlocks []*ContentBlock
    ResponseMeta  *AgenticResponseMeta
    Extra         map[string]any
}

type AgenticResponseMeta struct {
    TokenUsage      *TokenUsage
    OpenAIExtension *openai.ResponseMetaExtension
    GeminiExtension *gemini.ResponseMetaExtension
    ClaudeExtension *claude.ResponseMetaExtension
    Extension       any
}

type ContentBlock struct {
    Type ContentBlockType

    Reasoning *Reasoning

    UserInputText  *UserInputText
    UserInputImage *UserInputImage
    UserInputAudio *UserInputAudio
    UserInputVideo *UserInputVideo
    UserInputFile  *UserInputFile

    AssistantGenText  *AssistantGenText
    AssistantGenImage *AssistantGenImage
    AssistantGenAudio *AssistantGenAudio
    AssistantGenVideo *AssistantGenVideo

    FunctionToolCall   *FunctionToolCall
    FunctionToolResult *FunctionToolResult

    ToolSearchFunctionToolResult *ToolSearchFunctionToolResult

    ServerToolCall   *ServerToolCall
    ServerToolResult *ServerToolResult

    MCPToolCall             *MCPToolCall
    MCPToolResult           *MCPToolResult
    MCPListToolsResult      *MCPListToolsResult
    MCPToolApprovalRequest  *MCPToolApprovalRequest
    MCPToolApprovalResponse *MCPToolApprovalResponse

    StreamingMeta *StreamingMeta
    Extra         map[string]any
}

type Reasoning struct {
    Text      string
    Signature string
}

type UserInputText struct {
    Text string
}

type UserInputImage struct {
    URL        string
    Base64Data string
    MIMEType   string
    Detail     ImageURLDetail
}

type UserInputFile struct {
    URL        string
    Name       string
    Base64Data string
    MIMEType   string
}

type AssistantGenText struct {
    Text            string
    OpenAIExtension *openai.AssistantGenTextExtension
    ClaudeExtension *claude.AssistantGenTextExtension
    Extension       any
}

type FunctionToolCall struct {
    CallID    string
    Name      string
    Arguments string
}

type FunctionToolResult struct {
    CallID  string
    Name    string
    Content []*FunctionToolResultContentBlock
}

type FunctionToolResultContentBlock struct {
    Type  FunctionToolResultContentBlockType
    Text  *UserInputText
    Image *UserInputImage
    Audio *UserInputAudio
    Video *UserInputVideo
    File  *UserInputFile
    Extra  map[string]any
}

type ServerToolCall struct {
    Name      string
    CallID    string
    Arguments any
}

type ServerToolResult struct {
    Name    string
    CallID  string
    Content any
}

type MCPToolCall struct {
    ServerLabel       string
    ApprovalRequestID string
    CallID            string
    Name              string
    Arguments         string
}

type MCPToolResult struct {
    ServerLabel string
    CallID      string
    Name        string
    Content     string
    Error       *MCPToolCallError
}

type MCPToolApprovalRequest struct {
    ID          string
    Name        string
    Arguments   string
    ServerLabel string
}

type MCPToolApprovalResponse struct {
    ApprovalRequestID string
    Approve           bool
    Reason            string
}

msg := schema.SystemAgenticMessage("You are a helpful assistant.")
msg := schema.UserAgenticMessage("Analyze this file.")

block := schema.NewContentBlock(&schema.AssistantGenText{
    Text: "done",
})

chunk := schema.NewContentBlockChunk(
    &schema.AssistantGenText{Text: "partial"},
    &schema.StreamingMeta{Index: 0},
)

input := &schema.AgenticMessage{
    Role: schema.AgenticRoleTypeAssistant,
    ContentBlocks: []*schema.ContentBlock{
        schema.NewContentBlock(&schema.FunctionToolCall{
            CallID:    "call_1",
            Name:      "get_weather",
            Arguments: `{"city":"Beijing"}`,
        }),
    },
}

results, err := toolsNode.Invoke(ctx, input)

&schema.AgenticMessage{
    Role: schema.AgenticRoleTypeUser,
    ContentBlocks: []*schema.ContentBlock{
        schema.NewContentBlock(&schema.FunctionToolResult{
            CallID: "call_1",
            Name:   "get_weather",
            Content: []*schema.FunctionToolResultContentBlock{
                {
                    Type: schema.FunctionToolResultContentBlockTypeText,
                    Text: &schema.UserInputText{Text: "sunny"},
                },
            },
        }),
    },
}

messages := []*schema.AgenticMessage{
    schema.SystemAgenticMessage("You are a concise assistant."),
    schema.UserAgenticMessage("Search recent Go release notes and summarize them."),
}

resp, err := m.Generate(ctx, messages,
    model.WithTools([]*schema.ToolInfo{searchToolInfo}),
    model.WithAgenticToolChoice(&schema.AgenticToolChoice{
        Type: schema.ToolChoiceAllowed,
    }),
)
if err != nil {
    return err
}

for _, block := range resp.ContentBlocks {
    if block.Type == schema.ContentBlockTypeAssistantGenText && block.AssistantGenText != nil {
        fmt.Println(block.AssistantGenText.Text)
    }
}