Options
All option functions for configuring GoAI calls. Options follow the functional options pattern - pass them as variadic arguments to GenerateText, StreamText, GenerateObject, StreamObject, Embed, or EmbedMany.
Import: github.com/zendev-sh/goai
Core Options
WithSystem
Sets the system prompt.
func WithSystem(s string) OptionDefault: empty (no system prompt).
WithPrompt
Sets a shorthand single user message. When set, it is auto-wrapped as a UserMessage and prepended to Messages.
func WithPrompt(s string) OptionDefault: empty.
Use WithPrompt for simple single-turn requests. Use WithMessages for multi-turn conversations.
WithMessages
Sets the conversation history.
func WithMessages(msgs ...provider.Message) OptionDefault: empty. Use with message builders (UserMessage, AssistantMessage, etc.) for multi-turn conversations.
WithPromptCaching
Enables provider-specific prompt caching (e.g., Anthropic's cache_control).
func WithPromptCaching(b bool) OptionDefault: false.
Tool Options
WithTools
Sets the tools available to the model.
func WithTools(tools ...Tool) OptionDefault: no tools. Pass goai.Tool values with Name, Description, InputSchema, and optionally Execute for automatic tool loop execution.
WithMaxSteps
Sets the maximum number of auto tool loop iterations. Step 1 is the initial generation. Each subsequent step executes tool calls and re-generates.
func WithMaxSteps(n int) OptionDefault: 1 (no tool loop - the model generates once and returns, even if it requests tool calls).
Set to 2 or higher to enable automatic tool execution. For example, WithMaxSteps(2) allows: step 1 = model calls tool, step 2 = model uses tool result to generate final answer.
WithToolChoice
Controls how the model selects tools.
func WithToolChoice(tc string) OptionValues:
| Value | Behavior |
|---|---|
"auto" | Model decides whether to use tools (default when tools are present). |
"none" | Model does not use tools. |
"required" | Model must use at least one tool. |
"<tool_name>" | Model must use the specified tool. |
Default: provider-dependent (typically "auto" when tools are present).
Generation Options
WithMaxOutputTokens
Limits the response length in tokens.
func WithMaxOutputTokens(n int) OptionDefault: 0 (provider default).
WithTemperature
Controls randomness. Higher values produce more diverse output.
func WithTemperature(t float64) OptionDefault: nil (provider default, typically around 1.0).
WithTopP
Controls nucleus sampling. Only tokens with cumulative probability up to p are considered.
func WithTopP(p float64) OptionDefault: nil (provider default).
WithStopSequences
Causes generation to stop when any of the specified sequences is encountered.
func WithStopSequences(seqs ...string) OptionDefault: empty (no stop sequences).
Infrastructure Options
WithMaxRetries
Sets the retry count for transient errors (429, 503, 5xx).
func WithMaxRetries(n int) OptionDefault: 2. Retries use exponential backoff. Only retryable errors trigger retry (see Errors).
WithTimeout
Sets the timeout for the entire generation call. For streaming calls, the timeout covers from the initial request until the stream is fully consumed.
func WithTimeout(d time.Duration) OptionDefault: no timeout (relies on the context).
WithHeaders
Sets additional HTTP headers for this request.
func WithHeaders(h map[string]string) OptionDefault: empty. Useful for provider-specific headers (e.g., Azure deployment routing).
WithProviderOptions
Sets provider-specific request parameters that do not map to standard GoAI options.
func WithProviderOptions(opts map[string]any) OptionDefault: empty. Consult provider documentation for supported keys.
Telemetry Hooks
WithOnRequest
Sets a callback invoked before each model API call.
func WithOnRequest(fn func(RequestInfo)) OptionDefault: nil.
WithOnResponse
Sets a callback invoked after each model API call completes (success or failure).
func WithOnResponse(fn func(ResponseInfo)) OptionDefault: nil.
WithOnStepFinish
Sets a callback invoked after each generation step completes, including after tool execution.
func WithOnStepFinish(fn func(StepResult)) OptionDefault: nil. Only relevant when MaxSteps > 1.
WithOnToolCall
Sets a callback invoked after each tool execution.
func WithOnToolCall(fn func(ToolCallInfo)) OptionDefault: nil. Only relevant when tools with Execute are provided and MaxSteps > 1.
Structured Output Options
These options apply to GenerateObject and StreamObject.
WithExplicitSchema
Overrides the auto-generated JSON Schema. When set, SchemaFrom[T]() is not called.
func WithExplicitSchema(schema json.RawMessage) OptionDefault: nil (schema auto-generated from the type parameter T).
WithSchemaName
Sets the schema name sent to providers. Used by OpenAI's json_schema response format.
func WithSchemaName(name string) OptionDefault: "response".
Embedding Options
These options apply to Embed and EmbedMany.
WithMaxParallelCalls
Sets the maximum number of concurrent API calls when EmbedMany auto-chunks a large batch.
func WithMaxParallelCalls(n int) OptionDefault: 4.
WithEmbeddingProviderOptions
Sets provider-specific parameters for embedding requests.
func WithEmbeddingProviderOptions(opts map[string]any) OptionDefault: empty.
Image Options
These options use the separate ImageOption type and apply only to GenerateImage.
WithImagePrompt
Sets the text prompt for image generation.
func WithImagePrompt(prompt string) ImageOptionWithImageCount
Sets the number of images to generate.
func WithImageCount(n int) ImageOptionDefault: 1.
WithImageSize
Sets the image dimensions (e.g., "1024x1024", "512x512").
func WithImageSize(size string) ImageOptionDefault: provider default.
WithAspectRatio
Sets the aspect ratio as an alternative to explicit size (e.g., "16:9", "1:1").
func WithAspectRatio(ratio string) ImageOptionDefault: provider default.
WithImageProviderOptions
Sets provider-specific options for image generation.
func WithImageProviderOptions(opts map[string]any) ImageOptionDefault: empty.