# Message Types

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

## MessageRole

```go
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

```go
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

```go
type ContentPart interface {
    ContentType() string
}
```

Interface for different types of message content.

## TextContent

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

Text content in a message.

## ReasoningContent

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

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

## ImageContent

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

Image content in a message.

## FileContent

```go
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

```go
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

```go
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

```go
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

```go
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

```go
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

```go
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

```go
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

```go
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

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

### Multi-turn Conversation

```go
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

```go
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

```go
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

```go
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

```go
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](https://goaisdk.com/docs/reference/types/tools.md) - Tool-related types
- [GenerateText](https://goaisdk.com/docs/reference/ai/generate-text.md) - Using messages for generation