/prompt-file-provider-options

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 it a standard AI SDK option (temperature, maxTokens, topP, etc.)?
├─ YES → Top-level config (alongside provider and model)
└─ NO → providerOptions

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          # WRONG: 'effort' is not a standard option

✅ **Correct:**

provider: anthropic
providerOptions:
  anthropic:
    effort: medium

---

❌ **Mistake 2: Nesting `thinking` under provider**

providerOptions:
  anthropic:
    thinking:           # WRONG: thinking is top-level
      type: enabled

✅ **Correct:**

providerOptions:
  thinking:             # Correct: top-level special key
    type: enabled

---

❌ **Mistake 3: Wrong namespace for Vertex Gemini**

provider: vertex
model: gemini-2.0-flash
providerOptions:
  vertex:               # WRONG: Gemini uses 'google' namespace
    useSearchGrounding: true

✅ **Correct:**

provider: vertex
model: gemini-2.0-flash
providerOptions:
  google:               # Correct: Gemini is a Google model
    useSearchGrounding: true

---

❌ **Mistake 4: Confusing standard and provider options**

providerOptions:
  anthropic:
    temperature: 0.7    # WRONG: temperature is standard, goes top-level
    effort: medium

✅ **Correct:**

temperature: 0.7        # Standard: top-level
providerOptions:
  anthropic:
    effort: medium      # Provider-specific: nested

Quick Reference: Common Provider Options

**Anthropic (Claude)**

provider: anthropic
providerOptions:
  anthropic:
    effort: medium      # low | medium | high

**OpenAI**

provider: openai
providerOptions:
  openai:
    maxToolCalls: 1
    reasoningEffort: high

**Vertex with Gemini**

provider: vertex
model: gemini-2.0-flash
providerOptions:
  google:               # Note: 'google', not 'vertex'
    useSearchGrounding: true

**Vertex with Claude**

provider: vertex
model: claude-sonnet-4-20250514@vertex
providerOptions:
  anthropic:            # Note: 'anthropic', not 'vertex'
    effort: medium

**Amazon Bedrock**

provider: bedrock
model: anthropic.claude-sonnet-4-20250514-v1:0
maxTokens: 64000              # Recommended: Bedrock has no client-side defaults
providerOptions:
  bedrock:                    # Note: 'bedrock', not 'anthropic'
    guardrailConfig:
      guardrailIdentifier: my-guardrail
      guardrailVersion: "1"

**Extended Thinking (any provider)**

providerOptions:
  thinking:             # Top-level, not nested
    type: enabled
    budgetTokens: 10000

Why This Structure Exists

AI SDK uses `Record<string, Record<string, JSONValue>>` for `providerOptions` to: 1. **Prevent collisions** - `anthropic.effort` and `openai.reasoningEffort` can coexist 2. **Support multi-provider** - Pass options to multiple providers in one call 3. **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 } } }      # add ttl: 1h for the 1-hour cache

<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**.
• 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+).