prompt-caching

Prompt caching

`Agent.promptCaching()` generates provider-specific `providerOptions` for Anthropic, Claude on OpenRouter and Vertex, and OpenAI. Callers do not have to write the AI SDK's raw `cacheControl` / `promptCacheKey` shapes. It uses 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 passes explicit settings to `agent.promptCaching(config.promptCaching)`.

• **Mandatory in the builder.** For OpenAI, Anthropic, and Claude on OpenRouter

or Vertex, 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. Other models do not get the field.

• **Existing routed Claude agents get the default on their next run.** When a

saved `openrouter/anthropic/claude-*` or `google-vertex/claude-*` agent has no cache config, the JSON loader supplies `{ enabled: true }`. This does not change the saved config. Explicit settings, including `enabled: false`, pass through unchanged. Standalone SDK use stays opt-in.

• **Claude cache duration defaults to `1h`.** The Advanced panel renders

a Cache duration dropdown (`5m` / `1h`) for Anthropic and routed Claude agents. OpenAI has no sub-config or UI (its caching is fully automatic server-side). The TTL is preserved when switching between the supported Claude routes.

Native tool deferral

`Agent.nativeToolDeferral({ eagerToolNames })` uses native tool search for eligible model versions on direct OpenAI and Anthropic endpoints. n8n enables this policy during agent reconstruction. It has no Agent Builder setting.

new Agent('assistant')
  .model('openai/gpt-5.4')
  .nativeToolDeferral({ eagerToolNames: ['workspace_read_file', 'load_skill'] })
  .promptCaching();

The runtime sends the complete authorized catalog on each request. Native tool search controls which local definitions enter the model context. Discovery does not change the catalog, tool order, instructions, or execution handlers. Provider-native tools stay eager. Local tools with explicit cache markers or `deferLoading: false` also stay eager.

Providers register deferral through the runtime model registry. Each implementation supplies `supports` and `prepareTools`. The [OpenAI](../src/runtime/model/native-tool-deferral/openai.ts) and [Anthropic](../src/runtime/model/native-tool-deferral/anthropic.ts) implementations define model support, allowed endpoints, and search setup. The [shared code](../src/runtime/model/native-tool-deferral.ts) resolves and checks endpoints, finds configured provider tools, selects eager tools, applies the fallback, and adapts provider schemas.

The runtime uses numeric version rules instead of a model allowlist:

• OpenAI Responses uses hosted `tool_search` for GPT-5.4 and later versions.

GPT-5.4 Nano stays eager, including its dated snapshots. See the [tool search guide](https://developers.openai.com/api/docs/guides/tools-tool-search) and the [Nano model page](https://developers.openai.com/api/docs/models/gpt-5.4-nano).

• Anthropic Messages uses native BM25 tool search for Claude 4.5 and later

versions. The rule accepts model families that use the `claude-<family>-<major>[-<minor>]` format, including dated snapshots. See the [model compatibility table](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#model-compatibility).

Later versions in these formats qualify without a catalog update. For Claude, this is a forward compatibility policy based on the current table. The provider does not guarantee support for every future model.

The runtime checks the model version, API route, and effective endpoint before the request. Older versions, excluded variants, unknown model ID formats, other providers, Chat Completions, and custom endpoints use the complete eager catalog. Gateway credits also stays eager. When native search is not available, or the agent sets `.toolDeferral({ mode: 'tool-catalog' })`, deferred tools go behind the tool catalog: the prompt lists their names, and the model uses `find_tools` and `call_tool`.

Discovered definitions stay at their original history positions. OpenAI appends search results to the conversation. Anthropic expands tool references in the conversation. The runtime does not move discovered tools into the eager prefix. Call and result provider options are stored separately. This preserves the separate OpenAI search-result item ID through memory and approval checkpoints. The catalog carries the registered search tool name into prompt preparation. When the catalog changes, the runtime uses that name to remove unavailable Anthropic tool references from search results in the outgoing prompt. It also omits failed Anthropic search calls and their results from that prompt. Stored messages keep the original searc