prompt-caching

Prompt caching

`Agent.promptCaching()` generates provider-specific `providerOptions` for Anthropic and OpenAI so callers don't have to hand-write the Vercel AI SDK's raw `cacheControl` / `promptCacheKey` shapes. It layers on top of the existing `providerOptions` escape hatch — nothing here is required, and anything set explicitly (via `.instructions(text, { providerOptions })`, call-level `providerOptions`, or `Tool.providerOptions(...)`) always wins on conflicts.

// Defaults tuned for agent workloads: Anthropic gets a 1h instruction
// breakpoint, OpenAI gets 24h retention plus an auto-generated cache key.
new Agent('assistant').model('anthropic/claude-sonnet-4-5').promptCaching().instructions(LONG_SYSTEM_PROMPT);

// Override a field, or disable a provider entirely.
new Agent('assistant')
  .model('anthropic/claude-sonnet-4-5')
  .promptCaching({ anthropic: { ttl: '5m' } })
  .instructions(LONG_SYSTEM_PROMPT);

new Agent('assistant')
  .model('openai/gpt-5.1')
  .promptCaching({ openai: { promptCacheKey: 'assistant-v1' } })
  .instructions(LONG_SYSTEM_PROMPT);

The n8n Agent JSON config is a mandatory, simplified surface

The richer SDK shape above (OpenAI key/retention overrides) is for direct SDK callers. The n8n Agent product (JSON config / builder UI) exposes `config.promptCaching: { enabled: boolean; anthropic?: { ttl?: '5m' | '1h' } }` and maps it straight to `agent.promptCaching(config.promptCaching)`. Two differences from the general SDK usage worth knowing:

• **Mandatory, not opt-in or opt-out.** For OpenAI and Anthropic agents, the

config is always force-written with `{ enabled: true, ... }` — by the builder agent's write-path normalizer and the model picker — regardless of what the LLM or a prior config said; there is no user-facing way to disable it. Every other provider never gets the field at all. As with the SDK, a missing `promptCaching` field is still just "disabled" at runtime — the mandatory-on behavior lives in the config producers (builder tools, model picker), not in the runtime default.

• **TTL is Anthropic-only and defaults to `1h`.** The Advanced panel renders

a Cache duration dropdown (`5m` / `1h`) only for Anthropic agents; OpenAI has no sub-config or UI (its caching is fully automatic server-side). The TTL is preserved across a switch between Anthropic and another supported provider and back.

Prefix stability (always on, both providers)

Unlike everything else in this doc, this part is not gated by `.promptCaching()` — it's baseline hygiene that keeps the system-instructions prefix byte-stable, which both OpenAI's automatic caching and Anthropic's `cacheControl` breakpoint depend on regardless of whether the SDK feature is enabled.

Tools can attach a `systemInstruction` fragment (`Tool.systemInstruction(...)`) that gets merged into the system prompt. Deferred tools loaded mid-conversation via `load_tool` are a special case: if a newly loaded tool has a `systemInstruction`, merging it into the same cached instructions string the moment it loads would change that string's bytes — a full-prefix cache miss for OpenAI, and an invalidated breakpoint for Anthropic, for the rest of the conversation.

`RuntimeContextBuilder.composeEffectiveInstructions()` avoids this by splitting fragments by stability:

• **Stable** (base tools, the deferred-tool controllers `search_tools` /

`load_tool`, the episodic-recall tool) stay in the cached instructions message — this set never changes for the life of a run.

• **Volatile** (tools loaded via `load_tool` during the conversation) are

routed into the same uncached second system message that observation-log memory uses (see `buildSystemMessages`), not dropped — the model still sees the instruction the moment the tool loads, just outside the cached prefix.

Other prefix-stability hygiene, already true or verified: tool ordering is append-only (`getCurrentTools()` only ever appends), and none of the current built-in `systemInstruction` sources (`delegate_subagent`, `write_todos`, `recall_memory`) interpolate timestamps, run IDs, or other per-request nondeterminism into their text. Hosts can rename the delegate tool and replace its description / system instruction (`createDelegateSubAgentTool({ name, description, systemInstruction })`, mirrored into `write_todos` via `createWriteTodosTool({ delegateToolName })`), but those values are fixed at tool-build time, so the instructions prefix stays byte-stable for the life of a run.

Anthropic: instruction-level cache breakpoint

`.promptCaching()` attaches `providerOptions.anthropic.cacheControl` to the agent's system instructions (`buildSystemMessages()` already splits static instructions from observation-log memory into separate system messages, so the cache breakpoint on instructions survives append-only memory growth).

• **`ttl: '1h'` (default).** Anthropic's default cache TTL is 5 minutes, and

the API silently reverted to that default in early 2026. Agent workloads that pause — HITL tool approval, multi-step tool loops, eval waves — often go longer than 5 minutes between calls, so a `1h` breakpoint fails cheaper than repeatedly missing a `5m` one. `1h` writes cost 2x base input; `5m` writes cost 1.25x. Reads are always ~0.1x.

• **`ttl: '5m'`.** Use this for continuously warm chat loops (steady traffic,

no multi-minute gaps) to avoid the larger `1h` write premium.

• Anthropic requires a minimum prompt length to cache at all (roughly 1,024

tokens for the Sonnet family, 4,096 tokens for Opus 4.5 / Haiku 4.5). Below that, the request still succeeds — it's just never cached.

• Only Anthropic models get this option; it's a no-op for other providers.

Anthropic: runtime breakpoints (conversation history + tools)

On top of the instruction breakpoint above, every model call for an Anthropic agent with `.promptCaching()` enabled adds up to two more breakpoints, applied only to the per-call AI SDK `messages