Message Types

Types for representing messages in conversations between users, assistants, and tools.

MessageRole

type MessageRole string

const (
    RoleSystem    MessageRole = "system"
    RoleUser      MessageRole = "user"
    RoleAssistant MessageRole = "assistant"
    RoleTool      MessageRole = "tool"
)

Message roles define who is speaking in a conversation:

• RoleSystem: System instructions that guide model behavior
• RoleUser: User input or queries
• RoleAssistant: Model-generated responses
• RoleTool: Tool execution results

Message

type Message struct {
    Role    MessageRole   `json:"role"`
    Content []ContentPart `json:"content"`
    Name    string        `json:"name,omitempty"`
}

Represents a single message in a conversation.

Fields

Field	Type	Description
Role	MessageRole	Role of the message sender
Content	[]ContentPart	Content parts (text, images, tool results)
Name	string	Optional sender name

ContentPart Interface

type ContentPart interface {
    ContentType() string
}

Interface for different types of message content.

TextContent

type TextContent struct {
    Text string `json:"text"`
}

Text content in a message.

ReasoningContent

type ReasoningContent struct {
    Text string `json:"text"`
}

Reasoning or thinking content (for models that expose reasoning, like OpenAI o1).

ImageContent

type ImageContent struct {
    Image    []byte `json:"image"`
    MimeType string `json:"mimeType"`
    URL      string `json:"url,omitempty"`
}

Image content in a message.

FileContent

type FileContent struct {
    FileData         FileData        `json:"fileData,omitempty"`
    Data             []byte          `json:"data,omitempty"`
    MimeType         string          `json:"mimeType,omitempty"`
    MediaType        string          `json:"mediaType,omitempty"`
    Filename         string          `json:"filename,omitempty"`
    URL              string          `json:"url,omitempty"`
    Reference        string          `json:"reference,omitempty"`
    Text             string          `json:"text,omitempty"`
    ProviderOptions  map[string]interface{} `json:"providerOptions,omitempty"`
    ProviderMetadata json.RawMessage `json:"providerMetadata,omitempty"`
}

File attachment in a message.

GeneratedFileContent

type GeneratedFileContent struct {
    MediaType        string          `json:"mediaType"`
    FileData         FileData        `json:"fileData,omitempty"`
    Data             []byte          `json:"data,omitempty"`
    URL              string          `json:"url,omitempty"`
    ProviderOptions  map[string]interface{} `json:"providerOptions,omitempty"`
    ProviderMetadata json.RawMessage `json:"providerMetadata,omitempty"`
}

Generated file output from providers that return files or file URLs. Custom JSON encoding follows the AI SDK file-data shape: the emitted data field is a tagged object with type: "data" and base64 data, or type: "url" and url.

ToolCallContent

type ToolCallContent struct {
    ToolCallID       string          `json:"toolCallId"`
    ToolName         string          `json:"toolName"`
    Title            string          `json:"title,omitempty"`
    Input            string          `json:"input,omitempty"`
    Arguments        map[string]interface{} `json:"arguments,omitempty"`
    ProviderExecuted bool                   `json:"providerExecuted,omitempty"`
    ProviderOptions  map[string]interface{} `json:"providerOptions,omitempty"`
    ProviderMetadata json.RawMessage `json:"providerMetadata,omitempty"`
    ToolMetadata     map[string]interface{} `json:"toolMetadata,omitempty"`
    Dynamic          bool                   `json:"dynamic,omitempty"`
    Invalid          bool                   `json:"invalid,omitempty"`
    Error            interface{}            `json:"error,omitempty"`
    ThoughtSignature string                 `json:"thoughtSignature,omitempty"`
}

Assistant tool-call content preserves ordered model output, including provider-executed, dynamic, invalid, and tool-metadata fields plus Google thoughtSignature metadata for round trips.

Input stores the provider's raw streamed JSON when available, while Arguments stores the decoded Go map used by provider converters and tool execution. JSON serialization follows the TypeScript SDK public shape and emits input; it does not emit the Go-only arguments helper field.

ToolResultContent

type ToolResultContent struct {
    ToolCallID       string                 `json:"toolCallId"`
    ToolName         string                 `json:"toolName"`
    Title            string                 `json:"title,omitempty"`
    Input            map[string]interface{} `json:"input,omitempty"`
    Result           interface{}            `json:"result,omitempty"` // deprecated; use Output
    Error            string                 `json:"error,omitempty"`
    Output           *ToolResultOutput      `json:"output,omitempty"`
    ProviderExecuted bool                   `json:"providerExecuted,omitempty"`
    ProviderOptions  map[string]interface{} `json:"providerOptions,omitempty"`
    ProviderMetadata json.RawMessage        `json:"providerMetadata,omitempty"`
    ToolMetadata     map[string]interface{} `json:"toolMetadata,omitempty"`
    Dynamic          bool                   `json:"dynamic,omitempty"`
    Preliminary      bool                   `json:"preliminary,omitempty"`
}

Tool execution result content mirrors the TypeScript SDK tool-result part. Output content carries ProviderMetadata; when the part is replayed to a provider as a response message, that metadata is converted to provider-facing ProviderOptions.

ToolErrorContent

type ToolErrorContent struct {
    ToolCallID       string                 `json:"toolCallId"`
    ToolName         string                 `json:"toolName"`
    Title            string                 `json:"title,omitempty"`
    Input            map[string]interface{} `json:"input,omitempty"`
    Error            interface{}            `json:"error"`
    ProviderExecuted bool                   `json:"providerExecuted,omitempty"`
    ProviderOptions  map[string]interface{} `json:"providerOptions,omitempty"`
    ProviderMetadata json.RawMessage        `json:"providerMetadata,omitempty"`
    ToolMetadata     map[string]interface{} `json:"toolMetadata,omitempty"`
    Dynamic          bool                   `json:"dynamic,omitempty"`
}

Tool execution error content mirrors the TypeScript SDK tool-error part and follows the same ProviderMetadata to ProviderOptions replay behavior.

ToolApprovalRequestContent

type ToolApprovalRequestContent struct {
    ApprovalID  string   `json:"approvalId"`
    ToolCallID  string   `json:"toolCallId"` // provider replay shape
    ToolCall    ToolCall `json:"toolCall,omitempty"` // public result content shape
    IsAutomatic bool     `json:"isAutomatic,omitempty"`
}

Tool approval request content mirrors the TypeScript SDK split between public result content and replayed provider messages. In GenerateTextResult.Content and StreamTextResult.Content(), JSON contains approvalId, nested toolCall, and optional isAutomatic. In response messages replayed to a provider, JSON contains approvalId, toolCallId, and optional isAutomatic.

ToolApprovalResponseContent

type ToolApprovalResponseContent struct {
    ApprovalID       string   `json:"approvalId"`
    ToolCallID       string   `json:"toolCallId,omitempty"` // internal lookup field
    ToolCall         ToolCall `json:"toolCall,omitempty"` // public result content shape
    Approved         bool     `json:"approved"`
    Reason           string   `json:"reason,omitempty"`
    ProviderExecuted bool     `json:"providerExecuted,omitempty"`
}

Tool approval response content contains approvalId, nested toolCall, approved, optional reason, and optional providerExecuted in public result content. Provider replay strips the nested tool call and sends approvalId, approved, reason, and providerExecuted, matching the TypeScript SDK toResponseMessages behavior.

Prompt

type Prompt struct {
    Messages []Message
    System   string
    Text     string
}

Represents a prompt that can be either a simple string or a list of messages.

Examples

User Message

package main

import (
    "github.com/digitallysavvy/go-ai/pkg/provider/types"
)

func main() {
    message := types.Message{
        Role: types.RoleUser,
        Content: []types.ContentPart{
            types.TextContent{Text: "Hello, how are you?"},
        },
    }
}

Assistant Message

message := types.Message{
    Role: types.RoleAssistant,
    Content: []types.ContentPart{
        types.TextContent{Text: "I'm doing well, thank you!"},
    },
}

Multi-turn Conversation

messages := []types.Message{
    {
        Role: types.RoleUser,
        Content: []types.ContentPart{
            types.TextContent{Text: "What is the capital of France?"},
        },
    },
    {
        Role: types.RoleAssistant,
        Content: []types.ContentPart{
            types.TextContent{Text: "The capital of France is Paris."},
        },
    },
    {
        Role: types.RoleUser,
        Content: []types.ContentPart{
            types.TextContent{Text: "What is its population?"},
        },
    },
}

Message with Image

imageData, _ := os.ReadFile("image.jpg")

message := types.Message{
    Role: types.RoleUser,
    Content: []types.ContentPart{
        types.TextContent{Text: "What's in this image?"},
        types.ImageContent{
            Image:    imageData,
            MimeType: "image/jpeg",
        },
    },
}

Tool Result Message

message := types.Message{
    Role: types.RoleTool,
    Content: []types.ContentPart{
        types.ToolResultContent{
            ToolCallID: "call_abc123",
            ToolName:   "get_weather",
            Result: map[string]interface{}{
                "temperature": 72,
                "condition":   "sunny",
            },
        },
    },
}

Assistant Tool Call Message

message := types.Message{
    Role: types.RoleAssistant,
    Content: []types.ContentPart{
        types.ToolCallContent{
            ToolCallID: "call_abc123",
            ToolName:   "get_weather",
            Input:      `{"location":"Tokyo"}`,
            Arguments: map[string]interface{}{"location": "Tokyo"},
        },
    },
}

System Message

message := types.Message{
    Role: types.RoleSystem,
    Content: []types.ContentPart{
        types.TextContent{
            Text: "You are a helpful assistant that answers questions concisely.",
        },
    },
}

See Also

• Tool Types - Tool-related types
• GenerateText - Using messages for generation