Configuring Call Options

Purpose and Scope

Call options are the agent-level mechanism for passing type-safe runtime inputs into an AI SDK agent call. They solve the problem of agent behavior that needs to vary per request without forcing you to construct a new agent for every user, session, model choice, or tool configuration. In the documented agent API, call options are declared with callOptionsSchema, consumed by prepareCall, and supplied when invoking generate() or stream(). The result is a stable agent definition whose request-specific behavior remains explicit, validated, and visible at the call site.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

Use this pattern when the agent has a consistent role but needs dynamic context. Examples include injecting retrieved documents into instructions, adapting responses to a user's account tier, selecting a faster or more capable model, changing tool configuration based on a location, or applying provider-specific settings for a particular request. The documentation frames call options as an alternative to spreading configuration logic outside the agent. Instead of hidden conditionals near each call site, the agent owns the rule for turning structured options into model, prompt, tool, and provider settings.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

Relevant Source Files

content/docs/03-agents/05-configuring-call-options.mdx - Defines the public documentation page for agent call options, including the purpose, three-step workflow, ToolLoopAgent examples, callOptionsSchema, prepareCall, and runtime options passed to generate().

Core Primitives

A call option is not the same thing as a model setting. A model setting, such as the selected model or provider-specific reasoning controls, is the configuration eventually used to perform a model call. A call option is the typed input that helps decide those settings at runtime. The page's basic example declares a Zod schema with userId and accountType, then uses prepareCall to append account-aware context to the agent instructions. Because the schema is part of the agent definition, the options object becomes required and type-checked when the agent is called.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

prepareCall is the bridge between request input and agent configuration. It receives options and the existing settings, then returns the settings that should apply for that call. The examples preserve existing settings with object spread and then override fields such as instructions, model, or tools. That style matters because it keeps the base agent reusable: the default model, default instructions, and default tools remain the canonical definition, while prepareCall expresses the small, request-specific differences that should be applied just before execution.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

System-to-Code Mapping

Concept	Public API or field	What it controls
Agent definition	`new ToolLoopAgent({...})`	Creates the reusable agent whose behavior can be modified per call.
Runtime input schema	`callOptionsSchema`	Declares the shape of the structured `options` object and enables TypeScript checking.
Configuration hook	`prepareCall`	Converts validated call options into agent settings for this request.
One-shot execution	`agent.generate({...})`	Runs the agent with a prompt and call-specific `options`.
Streaming execution	`agent.stream({...})`	Applies the same options pattern to streaming agent calls.
Dynamic settings	`instructions`, `model`, `tools`	Common fields modified by `prepareCall` in the documented examples.

The documentation presents the workflow in three steps: define the schema, configure with prepareCall, and pass options at runtime. That sequence is the mental model to preserve in application code. The schema defines what callers may influence, prepareCall defines how those inputs influence the agent, and the call site supplies concrete values for one request. Keeping the steps separate makes it easier to review which parts of an agent are user- or session-dependent and which parts are fixed by the developer.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

Execution Flow

A typical request starts with an existing agent instance. The caller provides a prompt plus an options object matching the configured schema. The agent validates and types that object according to callOptionsSchema, then invokes prepareCall before the model interaction is prepared. Inside prepareCall, application logic can add prompt context, switch the model, reconstruct tools with request-scoped parameters, or adjust provider behavior. The returned settings are then used for that call only, so later calls can provide different options without mutating the agent definition.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

For dynamic model selection, the documented example declares a complexity option with values such as simple and complex. The base agent has a default model, but prepareCall chooses openai/gpt-4o-mini for simple questions and openai/o1-mini for more complex reasoning. The important design point is that the call site states the classification, while the agent centralizes what that classification means operationally. That makes routing easier to audit and prevents model selection from being duplicated across controllers, route handlers, or UI actions.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

For dynamic tool configuration, the page shows a news-oriented agent that accepts optional userCity and userRegion values. Its base tools include OpenAI web search, and prepareCall rebuilds that tool with searchContextSize and an approximate userLocation. This is a strong example of why call options are different from ordinary prompts: location changes tool behavior, not just the text sent to the model. The agent can keep a consistent capability set while still tailoring individual tool instances to request-scoped data.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

API Components

The compact API contract for this page is: define callOptionsSchema, implement prepareCall, and call generate() or stream() with options. callOptionsSchema is shown with Zod, including z.object, z.string, z.enum, and optional fields. prepareCall receives an object containing options plus the current settings, commonly destructured as ({ options, ...settings }). The callback returns an object of settings, usually by spreading settings and replacing fields that need to differ for the current request.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

const supportAgent = new ToolLoopAgent({
  model,
  callOptionsSchema: z.object({
    userId: z.string(),
    accountType: z.enum(['free', 'pro', 'enterprise']),
  }),
  instructions: 'You are a helpful customer support agent.',
  prepareCall: ({ options, ...settings }) => ({
    ...settings,
    instructions:
      settings.instructions +
      `\nUser context:\n- Account type: ${options.accountType}\n- User ID: ${options.userId}`,
  }),
});
 
await supportAgent.generate({
  prompt: 'How do I upgrade my account?',
  options: {
    userId: 'user_123',
    accountType: 'free',
  },
});

The examples also imply a useful boundary for application design. Put durable agent behavior in the constructor: the default model, base instructions, and ordinary tools. Put runtime-dependent configuration in call options: user identity, account tier, request complexity, geographic hints, retrieved context identifiers, and provider-tuning choices. Avoid passing arbitrary untyped objects through surrounding application code when they actually determine model or tool behavior. A named schema gives those values a contract, and prepareCall gives them a single place to affect execution.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

Implementation Details and Constraints

Call options are most useful when they are intentionally narrow. If every setting is exposed as a call option, the agent becomes difficult to reason about because each caller can effectively redefine it. The documented examples expose just enough input to make a decision: account tier for prompt adaptation, complexity for model routing, or location fields for web search configuration. That pattern keeps authorization, product policy, and cost controls inside the agent layer rather than scattering them across every caller that invokes generate() or stream().

Sources: content/docs/03-agents/05-configuring-call-options.mdx

Because the options parameter is required and type-checked after a schema is declared, adding call options is an API change for that agent's callers. Treat the schema as part of the agent's public contract within your application. When introducing a new required option, update every generate() and stream() call site. When a value is genuinely optional, model that with the schema, as the local-news example does with optional userCity and userRegion. This keeps TypeScript and runtime validation aligned with the actual behavior you expect.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

Next Steps

After you can configure call options, review loop control and tool-calling behavior so that request-specific settings do not accidentally create unbounded tool loops or unsafe execution paths. If your agent modifies tools per request, connect this page with tool approvals and runtime/tool context so you know which values should be model-visible, tool-visible, or approval-visible. If your agent switches models or provider options dynamically, read the provider options and settings pages next to understand which controls are portable across providers and which are provider-specific.

Sources: content/docs/03-agents/05-configuring-call-options.mdx

Ask a question...