Everything the SDK reads is passed in. There is no global registry, no init
hook and no ambient default — a run is configured by the RunOptions you hand
it and the agent it is given, which is what makes two differently-configured
runs safe to execute concurrently in one process.
This page covers the knobs that are not about a single capability: API keys and clients, logging, and the environment variables that exist. For a capability’s own options see its page.
The SDK never reads global state behind your back: model access is configured per run via a ModelProvider (or per agent via ModelImpl).
The OpenAI provider reads OPENAI_API_KEY from the environment by default, and accepts any openai-go request option:
import (
"github.com/openai/openai-go/v3/option"
"github.com/zzir/agents-go/models/openai"
)
// Default: key from OPENAI_API_KEY.
provider := openai.NewProvider()
// Explicit key, custom base URL (e.g. a gateway or compatible endpoint):
provider = openai.NewProvider(
option.WithAPIKey("sk-..."),
option.WithBaseURL("https://my-gateway.example.com/v1"),
)
Every agent in a run resolves its model through the provider passed in RunOptions:
res, err := agents.RunSync(ctx, agent, input, agents.RunOptions{Model: agents.ModelOptions{Provider: provider}})
There is no built-in default model: an agent that sets no Agent.Model fails with a UserError unless the provider was given a default. Configure one for all agents with:
provider := openai.NewProvider().WithDefaultModel("gpt-4o-mini")
Or pin a model per agent:
agent := &agents.Agent{Name: "fast", Model: "gpt-4o-mini"}
ModelSettings carries optional parameters (temperature, tool_choice, max tokens, reasoning effort, …). All fields use pointers or zero-value-means-unset semantics so the provider default applies unless you set them; use agents.Ptr for pointer fields.
agent.ModelSettings = &agents.ModelSettings{
Temperature: agents.Ptr(0.2),
MaxTokens: agents.Ptr(int64(1024)),
}
A run-level override merges over each agent’s own settings:
res, err := agents.RunSync(ctx, agent, input, agents.RunOptions{
Model: agents.ModelOptions{Provider: provider, Settings: &agents.ModelSettings{Temperature: agents.Ptr(0.0)}},
})
See Models for the full field list.
Tracing is opt-in: build a *tracing.Tracer and pass it in RunOptions.Observe.Tracer. Without one, tracing code paths are no-ops. See Tracing.
The SDK is silent by default and never writes to slog.Default(); opt in to its structured logging with RunOptions.Log — see Logging. Failures surface as Go errors with typed wrappers (*agents.MaxTurnsError, *agents.ModelBehaviorError, guardrail tripwire errors, …) that you can match with errors.As; a failed run’s partial state rides on *agents.RunError. See Results.