| name | prompt-file-provider-options |
| description | Guide to the providerOptions structure in .prompt files — decision tree for where an option goes, common mistakes, per-provider quick reference, and Anthropic prompt caching. Use when writing or reviewing .prompt file frontmatter (provider, model, providerOptions, messageOptions). |
Writing .prompt Files: ProviderOptions Guide
When creating .prompt files, understanding the providerOptions structure is critical.
Decision Tree: Where Does This Option Go?
Is the key on the prompt config allowlist (provider, model, temperature, maxTokens, maxSteps, skills, tools, providerOptions, messageOptions, n, maxImagesPerCall, size, aspectRatio, seed)?
├─ YES -> Top-level config
└─ NO -> Nest under providerOptions (unknown top-level keys throw; snake_case aliases like max_tokens fail with a camelCase suggestion)
In providerOptions:
├─ Is it 'thinking' or 'order'? -> Top-level (special AI SDK features)
└─ Is it provider-specific? -> Nested under provider namespace
Common Mistakes to Avoid
❌ Mistake 1: Putting provider options at top-level
provider: anthropic
effort: medium
✅ Correct:
provider: anthropic
providerOptions:
anthropic:
effort: medium
❌ Mistake 2: Nesting thinking under provider
providerOptions:
anthropic:
thinking:
type: enabled
✅ Correct:
providerOptions:
thinking:
type: enabled
❌ Mistake 3: Wrong namespace for Google Vertex Gemini
provider: google-vertex
model: gemini-2.0-flash
providerOptions:
vertex:
useSearchGrounding: true
✅ Correct:
provider: google-vertex
model: gemini-2.0-flash
providerOptions:
google:
useSearchGrounding: true
❌ Mistake 4: Confusing standard and provider options
providerOptions:
anthropic:
temperature: 0.7
effort: medium
✅ Correct:
temperature: 0.7
providerOptions:
anthropic:
effort: medium
❌ Mistake 5: Unknown or snake_case top-level keys
provider: openai
max_tokens: 16000
topP: 0.9
reasoningEffort: medium
✅ Correct:
provider: openai
maxTokens: 16000
providerOptions:
openai:
reasoningEffort: medium
topP: 0.9
Unknown top-level keys throw Invalid prompt file. A snake_case alias of a known field fails with a suggestion (max_tokens -> use maxTokens). Nested providerOptions stays open.
Quick Reference: Common Provider Options
Anthropic (Claude)
provider: anthropic
providerOptions:
anthropic:
effort: medium
OpenAI
provider: openai
providerOptions:
openai:
maxToolCalls: 1
reasoningEffort: high
Google Vertex with Gemini
provider: google-vertex
model: gemini-2.0-flash
providerOptions:
google:
useSearchGrounding: true
Google Vertex with Claude
provider: google-vertex
model: claude-sonnet-4-20250514@vertex
providerOptions:
anthropic:
effort: medium
Amazon Bedrock
provider: amazon-bedrock
model: anthropic.claude-sonnet-4-20250514-v1:0
maxTokens: 64000
providerOptions:
bedrock:
guardrailConfig:
guardrailIdentifier: my-guardrail
guardrailVersion: "1"
Extended Thinking (any provider)
providerOptions:
thinking:
type: enabled
budgetTokens: 10000
Why This Structure Exists
AI SDK uses Record<string, Record<string, JSONValue>> for providerOptions to:
- Prevent collisions -
anthropic.effort and openai.reasoningEffort can coexist
- Support multi-provider - Pass options to multiple providers in one call
- Route correctly - AI SDK extracts each provider's options independently
The nesting is intentional architecture, not redundancy.
Per-Message Caching (Anthropic Prompt Cache)
Anthropic prompt caching is a per-message directive. Mark the block that ends your static prefix and that prefix is cached and reused across calls. Define a cacheControl set in frontmatter messageOptions and attach it to the block with options:
messageOptions:
cached: { anthropic: { cacheControl: { type: ephemeral } } }
<system options="cached">
{{ long static instructions }}
</system>
<user>
{{ per-call input }}
</user>
Each set is a provider-namespaced providerOptions object (same namespace rules as call-level providerOptions); on Vertex with a Claude model use the same anthropic namespace. A block may list multiple sets: options="cached fast".
Rules:
- Attach the set to the last static block, never one containing per-call
{{ variables }} — a breakpoint on changing content rewrites the cache every call and never hits.
- Order blocks static-first, dynamic-last.
- Always give
options a value, such as options="cached"; bare <system options> throws at load.
- Put provider settings such as
ttl inside the named messageOptions set. options is the only supported role-tag attribute, so <system ttl="1h"> throws.
- Every name listed in
options must exist in frontmatter messageOptions.
- Minimum cacheable prefix is model-specific (~1,024 tokens for most Sonnet/Opus; higher for some). Below it, caching is silently skipped — verify via the cost trace (
cachedInputTokens).
- Max 4 cache breakpoints per request.
❌ caching a dynamic block: <user options="cached">{{ topic }}</user> (never hits)
✅ caching the static prefix: <system options="cached">{{ guide }}</system> then <user>{{ topic }}</user>
OpenAI / Azure: caching is automatic for prompts ≥1024 tokens — no messageOptions needed. Tune routing with providerOptions.openai.promptCacheKey (and promptCacheRetention: 24h on GPT-5.1+).
