Skip to main content

StreamText

Performs streaming text generation where tokens are returned incrementally as they are generated.

Signature​

func StreamText(ctx context.Context, opts StreamTextOptions) (*StreamTextResult, error)

Parameters​

StreamTextOptions​

Model is required, and so is one of Prompt or Messages. Every other field is optional. The table is generated from the source and lists every exported field.

FieldTypeDescription
Modelprovider.LanguageModelModel to use for generation
PromptstringPrompt can be a simple string or a list of messages
Messages[]types.Message
Systemstring
Instructions*stringInstructions is a TypeScript-compatible alias for System. When set, Instructions takes precedence over System.
InstructionMessages[]types.MessageInstructionMessages supplies the instructions as system messages (TS instructions: SystemModelMessage | SystemModelMessage[]), preserving per-message ProviderOptions. When non-empty it takes precedence over Instructions and System. Every message must have the system role.
AllowSystemMessagesboolAllowSystemMessages permits system-role messages in Messages. Defaults to false; use System for system instructions unless you are intentionally passing provider-native system messages.
AllowSystemInMessagesboolAllowSystemInMessages is a TypeScript-compatible alias for AllowSystemMessages. Either field enables system-role messages.
Temperature*float64Generation parameters
MaxTokens*int
TopP*float64
TopK*int
FrequencyPenalty*float64
PresencePenalty*float64
StopSequences[]string
Seed*int
Headersmap[string]string
Tools[]types.ToolTools available for the model to call
ToolChoicetypes.ToolChoice
ToolOrder[]string
ActiveTools[]string
ExperimentalToolCallersExperimentalToolCallersExperimentalToolCallers configures which tools may call which other tools (programmatic tool calling / code mode), and which tools stay hidden from the model until discovered via ai.ToolSearch. Mirrors the TypeScript SDK's experimental_toolCallers.
ToolApprovaltypes.ToolApprovalConfigToolApproval configures approval handling for tool execution.
ExperimentalToolApprovalSecret[]byteExperimentalToolApprovalSecret signs server-issued approval requests so resumed approval responses can be verified before execution.
MaxSteps*intMaxSteps is a convenience shorthand for StopWhen{StepCountIs(N)}. Deprecated: use StopWhen with StepCountIs instead. If StopWhen is set, MaxSteps is ignored.
StopWhen[]StopConditionStopWhen defines conditions that terminate the tool-calling loop. Conditions are evaluated OR -- first non-empty string stops the loop.
ResponseFormat*provider.ResponseFormatResponse format (for structured output) Deprecated: Use Output instead.
Outputinterface{}Output specifies how to handle and parse model output during streaming. Use TextOutput(), ObjectOutput(), ArrayOutput(), ChoiceOutput(), or JSONOutput(). When set, the model is called with the appropriate ResponseFormat and PartialOutput() is updated after each text chunk via ParsePartialOutput. If nil, defaults to plain text streaming.
Timeout*TimeoutConfigTimeout provides granular timeout controls Supports total timeout, per-step timeout, and per-chunk timeout
ExperimentalRetention*types.RetentionSettingsExperimentalRetention controls what data is retained from LLM requests/responses. Useful for reducing memory consumption with images or large contexts. Default (nil) retains everything for backwards compatibility.
Include*IncludeOptionsInclude controls which large request/response details are retained in step results and whether raw provider chunks are requested. Defaults match the TypeScript SDK.
ExperimentalInclude*IncludeOptionsExperimentalInclude is a deprecated alias for Include.
IncludeRawChunksboolIncludeRawChunks is a deprecated alias for Include.RawChunks.
Reasoning*types.ReasoningLevelReasoning controls how much thinking effort the model applies. nil means unset (use provider default). Set to types.ReasoningDefault to explicitly omit from the API request.
SendReasoning*boolSendReasoning controls whether reasoning/thinking boundary chunks are exposed to OnChunk. nil and false suppress reasoning-start/end, matching the TypeScript SDK default.
ProviderOptionsmap[string]interface{}ProviderOptions allows passing provider-specific options
MaxRetries*intMaxRetries controls transient provider call retries. For Gateway models, nil uses the TypeScript SDK default of 2 retries; set to 0 to disable.
ExperimentalSandboxinterface{}ExperimentalSandbox is passed through to tool execution. PrepareStep can override it for an individual step.
RepairToolCallToolCallRepairFunctionRepairToolCall attempts to repair tool calls that fail to parse because the tool does not exist or its input is invalid. When it returns a call, the repaired call is parsed again; (nil, nil) keeps the call invalid.
ExperimentalRepairToolCallToolCallRepairFunctionExperimentalRepairToolCall is a deprecated alias for RepairToolCall. Deprecated: use RepairToolCall.
OnLanguageModelCallStartOnLanguageModelCallStartCallbackOnLanguageModelCallStart is called immediately before each provider model call begins.
ExperimentalOnLanguageModelCallStartOnLanguageModelCallStartCallbackExperimentalOnLanguageModelCallStart is a deprecated alias for OnLanguageModelCallStart. Deprecated: use OnLanguageModelCallStart.
OnLanguageModelCallEndOnLanguageModelCallEndCallbackOnLanguageModelCallEnd is called after each provider model response is normalized and parsed, before client-side tool execution.
ExperimentalOnLanguageModelCallEndOnLanguageModelCallEndCallbackExperimentalOnLanguageModelCallEnd is a deprecated alias for OnLanguageModelCallEnd. Deprecated: use OnLanguageModelCallEnd.
ExperimentalRefineToolInputmap[string]ToolInputRefinerExperimentalRefineToolInput refines parsed tool inputs by tool name before approval, callbacks, telemetry, execution, and response messages.
ExperimentalDownloadDownloadFunctionExperimentalDownload downloads remote file URLs that need inline data before sending tool-result messages back to the model. Defaults to DefaultDownload, matching the TypeScript SDK's default download behavior.
RuntimeContextinterface{}RuntimeContext is user-defined context that flows through callbacks. It is passed as-is to all structured event callbacks.
SensitiveRuntimeContextboolSensitiveRuntimeContext omits runtime context from telemetry payloads.
ToolsContextmap[string]interface{}ToolsContext is the per-tool context map passed to approval and execution hooks.
ExperimentalContextinterface{}ExperimentalContext is a deprecated alias for RuntimeContext.
PrepareStepfunc(ctx context.Context, step PrepareStepOptions) PrepareStepOptionsPrepareStep is called before each model step.
Telemetry*TelemetrySettingsTelemetry configures observability for this operation. When both Telemetry and ExperimentalTelemetry are set, Telemetry wins.
ExperimentalTelemetry*TelemetrySettingsTelemetry configuration for observability. Deprecated: use Telemetry.
Internal*InternalOptionsInternal contains test-only ID generators matching the TypeScript _internal option.
OnChunkfunc(chunk provider.StreamChunk)Callbacks
InitialStreamChunks[]provider.StreamChunkInitialStreamChunks are emitted before the provider stream. Higher-level adapters use this for work resolved before the next model step while preserving stream event ordering.
OnEndfunc(result *StreamTextResult)OnEnd is called when the stream is fully consumed, with the full *StreamTextResult (Text(), Usage(), ToolCalls(), etc. give the same data TS's onEnd event carries). This is a Go-only convenience signature that predates OnEndEvent below; it is NOT the same field as GenerateTextOptions.OnEnd (whose signature is func(ctx, *GenerateTextResult, userContext) — StreamText's per-step and per-call analogues of that tuple shape are OnStepEnd below and OnEndEvent/OnFinishEvent, since a StreamTextResult is a different Go type from a GenerateTextResult and can't share that field's type). For code that wants the same shared, TS-parity event struct that GenerateText/Agent use, prefer OnEndEvent.
OnFinishfunc(result *StreamTextResult)OnFinish is called when the stream is fully consumed. Deprecated: use OnEnd.
OnStepEndfunc(ctx context.Context, step types.StepResult, userContext interface{})OnStepEnd is called after each step completes, mirroring GenerateTextOptions.OnStepEnd exactly (same func type, since types.StepResult — unlike *GenerateTextResult/*StreamTextResult — is shared between generate and stream). TS shares one onStepEnd callback type between generateText and streamText; this is the Go equivalent.
OnStepFinishfunc(ctx context.Context, step types.StepResult, userContext interface{})OnStepFinish is called after each step completes. Deprecated: use OnStepEnd.
OnStartfunc(ctx context.Context, e OnStartEvent)OnStart is called once, before streaming begins.
OnStepStartfunc(ctx context.Context, e OnStepStartEvent)OnStepStart is called at the beginning of each LLM step.
OnToolExecutionStartfunc(ctx context.Context, e OnToolCallStartEvent)OnToolExecutionStart is called just before each tool's Execute function runs.
OnToolExecutionEndfunc(ctx context.Context, e OnToolCallFinishEvent)OnToolExecutionEnd is called after each tool's Execute function returns.
OnToolCallStartfunc(ctx context.Context, e OnToolCallStartEvent)Deprecated: use OnToolExecutionStart.
OnToolCallFinishfunc(ctx context.Context, e OnToolCallFinishEvent)Deprecated: use OnToolExecutionEnd.
OnStepEndEventfunc(ctx context.Context, e OnStepFinishEvent)OnStepEndEvent is called at the end of each LLM step.
OnStepFinishEventfunc(ctx context.Context, e OnStepFinishEvent)OnStepFinishEvent is called at the end of each LLM step. Deprecated: use OnStepEndEvent.
OnEndEventfunc(ctx context.Context, e OnFinishEvent)OnEndEvent is called once when the stream fully completes.
OnFinishEventfunc(ctx context.Context, e OnFinishEvent)OnFinishEvent is called once when the stream fully completes. Deprecated: use OnEndEvent.
OnErrorfunc(ctx context.Context, err error)OnError is called when an error chunk is received from the provider during streaming. Mirrors the TypeScript SDK's onError callback. Unlike a fatal stream error (which surfaces via TextStream.Err()), error chunks are non-fatal stream events that can be observed and logged without aborting the stream. If nil, error chunks are silently forwarded to OnChunk.
StreamRetries*intStreamRetries is the maximum number of automatic retries for ANY provider error chunk received after streaming has already started (a mid-stream error chunk). Matching TS (stream-text.ts's automaticStreamRetryCount < streamRetries), this budget is consulted unconditionally — it does not check whether the normalized providererrors.StreamProviderError considers itself retryable; that classification is informational, for OnError/ OnErrorRetry to build their own heuristics on. nil (the option omitted entirely) disables ALL stream retry behavior, both automatic and OnErrorRetry-directed, and preserves pre-streamRetries incremental chunk delivery for existing OnError observers (TS: "Omit this option to disable all stream retry behavior and preserve incremental tool streaming for existing onError observers"). An explicit 0 disables automatic retries but still allows OnErrorRetry to request one retry (TS canRetryStreamViaOnError = streamRetries !== undefined && onErrorArg != null). A negative value is rejected synchronously by StreamText (TS "streamRetries must be >= 0"). A ToolChoiceViolationError is never retried, automatically or via OnErrorRetry (TS stream-text.ts isToolChoiceViolation check). Audit row 802af1e / WG8.
OnErrorRetryfunc(ctx context.Context, event StreamTextOnErrorRetryEvent) boolOnErrorRetry is called for a mid-stream provider error (after OnError) and, if StreamRetries permits a retry, may request one by returning true. It is consulted only when StreamRetries was explicitly set (even to 0) and no automatic retry applies (StreamRetries exhausted), and is honored at most once per streamText call, matching TS's StreamTextOnErrorRetryCallback semantics.
OnAbortfunc(ctx context.Context, steps []types.StepResult)OnAbort is called when streaming is aborted by context cancellation or deadline before normal completion. Deprecated: use OnAbortEvent, which also carries the call ID and abort reason.
OnAbortEventOnAbortCallbackOnAbortEvent is called when streaming is aborted by context cancellation or deadline before normal completion, with a GenerateTextAbortEvent carrying the call ID, completed steps, and abort reason. Takes precedence over the deprecated OnAbort.
ExperimentalTransform[]StreamTransformFuncExperimentalTransform is an ordered list of transform functions applied to each stream chunk after provider emission but before forwarding to OnChunk. Each function receives a chunk and returns zero or more replacement chunks. Returning nil or an empty slice drops the chunk. Transforms are applied in order; each transform receives the output of the previous one. Mirrors the TypeScript SDK's experimental_transform option.

Return Value​

StreamTextResult​

The result provides methods to consume the stream:

MethodReturnsDescription
Stream()provider.TextStreamUnderlying text stream
FullStream()provider.TextStreamEvery chunk type, including lifecycle chunks (see below)
Text()stringAccumulated text so far
FinishReason()types.FinishReasonFinish reason (after stream ends)
Usage()types.UsageUsage info (after stream ends)
ContextManagement()interfaceContext management info
Err()errorError that occurred during streaming
Close()errorClose the stream
ReadAll()(string, error)Read all chunks and return complete text
Chunks()<-chan provider.StreamChunkChannel of chunks
Steps()[]types.StepResultCompleted steps, including per-step Performance statistics
FinalStep()types.StepResultLast completed step with StepTimeMs, ResponseTimeMs, ToolExecutionMs, EffectiveOutputTokensPerSecond, EffectiveTotalTokensPerSecond, and streaming throughput fields
Content()[]types.ContentPartOrdered generated content from all completed steps

Examples​

Basic Streaming​

package main

import (
"context"
"fmt"
"io"
"log"

"github.com/digitallysavvy/go-ai/pkg/ai"
"github.com/digitallysavvy/go-ai/pkg/provider"
"github.com/digitallysavvy/go-ai/pkg/providers/openai"
)

func main() {
p := openai.New(openai.Config{
APIKey: "your-api-key",
})
model, err := p.LanguageModel("gpt-6-astra")
if err != nil {
log.Fatal(err)
}

// Start streaming
result, err := ai.StreamText(context.Background(), ai.StreamTextOptions{
Model: model,
Prompt: "Write a story about a robot",
})
if err != nil {
log.Fatal(err)
}
defer result.Close()

// Read chunks manually
for {
chunk, err := result.Stream().Next()
if err == io.EOF {
break
}
if err != nil {
log.Fatal(err)
}

if chunk.Type == provider.ChunkTypeText {
fmt.Print(chunk.Text)
}
}

fmt.Printf("\n\nTotal tokens: %d\n", result.Usage().GetTotalTokens())
}

Using Callbacks​

result, err := ai.StreamText(ctx, ai.StreamTextOptions{
Model: model,
Prompt: "Explain machine learning",
OnChunk: func(chunk provider.StreamChunk) {
if chunk.Type == provider.ChunkTypeText {
fmt.Print(chunk.Text)
}
},
OnFinish: func(result *ai.StreamTextResult) {
fmt.Printf("\n\nDone! Tokens: %d\n", result.Usage().GetTotalTokens())
},
})
if err != nil {
log.Fatal(err)
}

Using ReadAll​

result, err := ai.StreamText(ctx, ai.StreamTextOptions{
Model: model,
Prompt: "Write a poem about nature",
})
if err != nil {
log.Fatal(err)
}
defer result.Close()

// Read all at once
text, err := result.ReadAll()
if err != nil {
log.Fatal(err)
}

fmt.Println(text)
fmt.Printf("Tokens: %d\n", result.Usage().GetTotalTokens())

Using Channel-based Consumption​

result, err := ai.StreamText(ctx, ai.StreamTextOptions{
Model: model,
Prompt: "Describe quantum physics",
})
if err != nil {
log.Fatal(err)
}
defer result.Close()

// Consume chunks from channel
for chunk := range result.Chunks() {
if chunk.Type == provider.ChunkTypeText {
fmt.Print(chunk.Text)
}
}

fmt.Printf("\n\nFinish reason: %s\n", result.FinishReason())

With Per-Chunk Timeout​

perChunk := 5 * time.Second
timeout := &ai.TimeoutConfig{
PerChunk: &perChunk,
}

result, err := ai.StreamText(ctx, ai.StreamTextOptions{
Model: model,
Prompt: "Write a long essay",
Timeout: timeout,
})
if err != nil {
log.Fatal(err)
}
defer result.Close()

text, err := result.ReadAll()
if err != nil {
if strings.Contains(err.Error(), "chunk timeout") {
log.Println("Stream timed out waiting for chunk")
} else {
log.Fatal(err)
}
}

Full Stream Lifecycle​

FullStream() (and OnChunk) receive every chunk the call produces, including lifecycle chunks that bracket the call and each step:

  • provider.ChunkTypeStart opens the stream — emitted exactly once, before the first step's provider chunks.
  • provider.ChunkTypeStartStep / provider.ChunkTypeFinishStep bracket each step. ChunkTypeFinishStep carries that step's request, response, usage, finish reason, and provider metadata.
  • provider.ChunkTypeFinish closes the call — emitted exactly once, after the last step, carrying total usage across all steps.

This differs from earlier SDK versions, where ChunkTypeFinish was forwarded once per step. Code that used to detect step boundaries by watching for ChunkTypeFinish must switch to ChunkTypeFinishStep; only the very last ChunkTypeFinish in a multi-step run signals the whole call is done.

for chunk := range result.Chunks() {
switch chunk.Type {
case provider.ChunkTypeStart:
fmt.Println("stream started")
case provider.ChunkTypeStartStep:
fmt.Println("step started")
case provider.ChunkTypeText:
fmt.Print(chunk.Text)
case provider.ChunkTypeFinishStep:
fmt.Printf("\nstep finished: %s\n", chunk.FinishReason)
case provider.ChunkTypeFinish:
fmt.Printf("call finished, total usage: %d tokens\n", chunk.Usage.GetTotalTokens())
}
}

Error Handling​

result, err := ai.StreamText(ctx, opts)
if err != nil {
log.Fatal("Failed to start stream:", err)
}
defer result.Close()

for {
chunk, err := result.Stream().Next()
if err == io.EOF {
break
}
if err != nil {
if strings.Contains(err.Error(), "chunk timeout") {
log.Println("Chunk timeout, continuing...")
continue
}
log.Fatal("Stream error:", err)
}

// Process chunk
fmt.Print(chunk.Text)
}

// Check for errors during streaming
if result.Err() != nil {
log.Println("Error during streaming:", result.Err())
}

Tool approval signing​

ExperimentalToolApprovalSecret is a byte slice. When it is set, the SDK signs every approval request it issues with HMAC-SHA256 and verifies the signature on the approval response before it runs the tool. A client that edits the tool name, the tool call ID or the tool input between the request and the response fails verification. When it is nil, requests are not signed and responses are not verified. The signing functions are ai.SignToolApproval and ai.VerifyToolApprovalSignature; see Tool approval helpers.

See Also​