# Prompts

Prompts are instructions that you give a [large language model (LLM)](https://goaisdk.com/docs/foundations/overview.md#large-language-models) to tell it what to do. It's like when you ask someone for directions; the clearer your question, the better the directions you'll get.

Many LLM providers offer complex interfaces for specifying prompts. They involve different roles and message types. While these interfaces are powerful, they can be hard to use and understand.

In order to simplify prompting, the Go AI SDK supports text, message, and system prompts.

## Text Prompts

Text prompts are strings. They are ideal for simple generation use cases, e.g. repeatedly generating content for variants of the same prompt text.

You can set text prompts using the `Prompt` field available in functions like `ai.StreamText()` or `ai.GenerateObject()`. You can structure the text in any way and inject variables using Go's string formatting.

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    Prompt: "Invent a new holiday and describe its traditions.",
})
```

You can also use string formatting to provide dynamic data to your prompt:

```go
destination := "Paris"
lengthOfStay := 5

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    Prompt: fmt.Sprintf("I am planning a trip to %s for %d days. "+
        "Please suggest the best tourist activities for me to do.", destination, lengthOfStay),
})
```

## System Prompts

System prompts are the initial set of instructions given to models that help guide and constrain the models' behaviors and responses. You can set system prompts using the `System` field. System prompts work with both the `Prompt` and the `Messages` fields.

```go
destination := "Paris"
lengthOfStay := 5

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    System: "You help planning travel itineraries. " +
        "Respond to the users' request with a list " +
        "of the best stops to make in their destination.",
    Prompt: fmt.Sprintf("I am planning a trip to %s for %d days. "+
        "Please suggest the best tourist activities for me to do.", destination, lengthOfStay),
})
```

> **Note:** When you use a message prompt, you can also use system messages instead of a system prompt.

## Message Prompts

A message prompt is a slice of user, assistant, and tool messages. They are great for chat interfaces and more complex, multi-modal prompts. You can use the `Messages` field to set message prompts.

Each message has a `Role` and a `Content` field. The content can either be text (for user and assistant messages), or a slice of relevant parts (data) for that message type.

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

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {Role: types.RoleUser, Content: []types.ContentPart{types.TextContent{Text: "Hi!"}}},
        {Role: types.RoleAssistant, Content: []types.ContentPart{types.TextContent{Text: "Hello, how can I help?"}}},
        {Role: types.RoleUser, Content: []types.ContentPart{types.TextContent{Text: "Where can I buy the best Currywurst in Berlin?"}}},
    },
})
```

Instead of sending text in the `Content` field, you can send a slice of parts that includes a mix of text and other content parts.

> **Warning:** Not all language models support all message and content types. For example, some models might not be capable of handling multi-modal inputs or tool messages. [Learn more about the capabilities of select models](https://goaisdk.com/docs/foundations/providers-and-models.md#model-capabilities).

### User Messages

#### Text Parts

Text content is the most common type of content. It is a string that is passed to the model.

If you only need to send text content in a message, `Content` can be a single-element slice of `TextContent`, but it can also hold multiple content parts.

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role: types.RoleUser,
            Content: []types.ContentPart{
                types.TextContent{
                    Text: "Where can I buy the best Currywurst in Berlin?",
                },
            },
        },
    },
})
```

#### Image Parts

User messages can include image parts. An image can be one of the following:

- Base64-encoded image: `string` with base-64 encoded content or data URL
- Binary image: `[]byte`
- URL: `string` with HTTP(S) URL

##### Example: Binary image ([]byte)

```go
import "os"

imageData, _ := os.ReadFile("./data/comic-cat.png")

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role: types.RoleUser,
            Content: []types.ContentPart{
                types.TextContent{Text: "Describe the image in detail."},
                types.ImageContent{
                    Image:    imageData,
                    MimeType: "image/png",
                },
            },
        },
    },
})
```

##### Example: Base-64 encoded image (string)

```go
imageData, _ := os.ReadFile("./data/comic-cat.png")
base64Image := base64.StdEncoding.EncodeToString(imageData)
decodedImage, _ := base64.StdEncoding.DecodeString(base64Image)

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role: types.RoleUser,
            Content: []types.ContentPart{
                types.TextContent{Text: "Describe the image in detail."},
                types.ImageContent{
                    Image:    decodedImage,
                    MimeType: "image/png",
                },
            },
        },
    },
})
```

##### Example: Image URL (string)

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role: types.RoleUser,
            Content: []types.ContentPart{
                types.TextContent{Text: "Describe the image in detail."},
                types.ImageContent{
                    URL: "https://github.com/vercel/ai/blob/main/examples/ai-core/data/comic-cat.png?raw=true",
                },
            },
        },
    },
})
```

#### File Parts

> **Warning:** Only a few providers and models currently support file parts: Google Generative AI, Google Vertex AI, OpenAI (for `wav` and `mp3` audio with `gpt-4o-audio-preview`), Anthropic, and OpenAI (for `pdf`).

User messages can include file parts. A file can be one of the following:

- Base64-encoded file: `string` with base-64 encoded content or data URL
- Binary data: `[]byte`
- URL: `string` with HTTP(S) URL

You need to specify the MIME type of the file you are sending.

##### Example: PDF file from []byte

```go
import (
    "github.com/digitallysavvy/go-ai/pkg/providers/google"
    "github.com/digitallysavvy/go-ai/pkg/ai"
)

pdfData, _ := os.ReadFile("./data/example.pdf")

model, err := googleProvider.LanguageModel("gemini-1.5-flash")
if err != nil {
    log.Fatal(err)
}

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role: types.RoleUser,
            Content: []types.ContentPart{
                types.TextContent{Text: "What is the file about?"},
                types.FileContent{
                    MediaType: "application/pdf",
                    Data:      pdfData,
                    Filename:  "example.pdf", // optional, not used by all providers
                },
            },
        },
    },
})
```

##### Example: mp3 audio file from []byte

```go
import (
    "github.com/digitallysavvy/go-ai/pkg/providers/openai"
    "github.com/digitallysavvy/go-ai/pkg/ai"
)

audioData, _ := os.ReadFile("./data/galileo.mp3")

model, err := openaiProvider.LanguageModel("gpt-4o-audio-preview")
if err != nil {
    log.Fatal(err)
}

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role: types.RoleUser,
            Content: []types.ContentPart{
                types.TextContent{Text: "What is the audio saying?"},
                types.FileContent{
                    MediaType: "audio/mpeg",
                    Data:      audioData,
                },
            },
        },
    },
})
```

### Assistant Messages

Assistant messages are messages that have a role of `assistant`. They are typically previous responses from the assistant and can contain text, reasoning, and tool call parts.

#### Example: Assistant message with text content

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {Role: types.RoleUser, Content: []types.ContentPart{types.TextContent{Text: "Hi!"}}},
        {Role: types.RoleAssistant, Content: []types.ContentPart{types.TextContent{Text: "Hello, how can I help?"}}},
    },
})
```

#### Example: Assistant message with tool call content

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role:    types.RoleUser,
            Content: []types.ContentPart{types.TextContent{Text: "How many calories are in this block of cheese?"}},
        },
        {
            Role: types.RoleAssistant,
            Content: []types.ContentPart{
                types.ToolCallContent{
                    ToolCallID: "12345",
                    ToolName:   "get-nutrition-data",
                    Arguments: map[string]interface{}{
                        "cheese": "Roquefort",
                    },
                },
            },
        },
    },
})
```

### Tool Messages

> **Note:** [Tools](https://goaisdk.com/docs/foundations/tools.md) (also known as function calling) are programs that you can provide an LLM to extend its built-in functionality. This can be anything from calling an external API to calling functions within your application. Learn more about Tools in [the next section](https://goaisdk.com/docs/foundations/tools.md).

For models that support [tool](https://goaisdk.com/docs/foundations/tools.md) calls, assistant messages can contain tool call parts, and tool messages can contain tool output parts. A single assistant message can call multiple tools, and a single tool message can contain multiple tool results.

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role: types.RoleUser,
            Content: []types.ContentPart{
                types.TextContent{Text: "How many calories are in this block of cheese?"},
                types.ImageContent{Image: imageData, MimeType: "image/jpeg"},
            },
        },
        {
            Role: types.RoleAssistant,
            Content: []types.ContentPart{
                types.ToolCallContent{
                    ToolCallID: "12345",
                    ToolName:   "get-nutrition-data",
                    Arguments: map[string]interface{}{
                        "cheese": "Roquefort",
                    },
                },
                // there could be more tool calls here (parallel calling)
            },
        },
        {
            Role: types.RoleTool,
            Content: []types.ContentPart{
                types.ToolResultContent{
                    ToolCallID: "12345", // needs to match the tool call id
                    ToolName:   "get-nutrition-data",
                    Output: &types.ToolResultOutput{
                        Type: types.ToolResultOutputJSON,
                        Value: map[string]interface{}{
                            "name":     "Cheese, roquefort",
                            "calories": 369,
                            "fat":      31,
                            "protein":  22,
                        },
                    },
                },
                // there could be more tool results here (parallel calling)
            },
        },
    },
})
```

### System Messages

System messages are messages that are sent to the model before the user messages to guide the assistant's behavior. You can alternatively use the `System` field.

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role:    types.RoleSystem,
            Content: []types.ContentPart{types.TextContent{Text: "You help planning travel itineraries."}},
        },
        {
            Role: types.RoleUser,
            Content: []types.ContentPart{types.TextContent{
                Text: "I am planning a trip to Berlin for 3 days. " +
                    "Please suggest the best tourist activities for me to do.",
            }},
        },
    },
})
```

## Provider-Specific Options

Some providers support additional options that can be passed at different levels:

### Function Call Level

Provider options can be passed at the function call level using the `ProviderOptions` field:

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: azureModel,
    ProviderOptions: map[string]interface{}{
        "openai": map[string]interface{}{
            "reasoningEffort": "low",
        },
    },
})
```

### Message Level

For granular control, you can pass `ProviderOptions` to individual messages:

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role:    types.RoleSystem,
            Content: []types.ContentPart{types.TextContent{Text: "Cached system message"}},
            ProviderOptions: map[string]interface{}{
                "anthropic": map[string]interface{}{
                    "cacheControl": map[string]interface{}{
                        "type": "ephemeral",
                    },
                },
            },
        },
    },
})
```

### Message Part Level

Certain provider-specific options require configuration at the message part level:

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model: model,
    Messages: []types.Message{
        {
            Role: types.RoleUser,
            Content: []types.ContentPart{
                types.ImageContent{
                    URL: imageURL,
                    ProviderOptions: map[string]interface{}{
                        "openai": map[string]interface{}{
                            "imageDetail": "low",
                        },
                    },
                },
            },
        },
    },
})
```

## Working with Context

All AI SDK functions in Go accept a `context.Context` as the first parameter. This enables:

- **Cancellation**: Cancel long-running operations
- **Timeouts**: Set deadlines for operations
- **Values**: Pass request-scoped values

```go
// Timeout example
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    Prompt: "Write a long story...",
})
if err != nil {
    if ctx.Err() == context.DeadlineExceeded {
        fmt.Println("Request timed out")
    }
}
```

## Next Steps

- Learn about [Tools](https://goaisdk.com/docs/foundations/tools.md)
- Understand [Streaming](https://goaisdk.com/docs/foundations/streaming.md)
- Explore [Generating Text](https://goaisdk.com/docs/ai-sdk-core/generating-text.md)

## See Also

- [Generating Structured Data](https://goaisdk.com/docs/ai-sdk-core/generating-structured-data.md)
- [Tools and Tool Calling](https://goaisdk.com/docs/ai-sdk-core/tools-and-tool-calling.md)
- [Message Types Reference](https://goaisdk.com/docs/reference/types/messages.md)