@ai-sdk/anthropic does not add advanced-tool-use beta for tool search / deferLoading

[DaisukeYoda]

Description

When using the Anthropic provider with toolSearchRegex_20251119() and tools marked with providerOptions: { anthropic: { deferLoading: true } }, the SDK serializes Anthropic advanced tool-use fields into the request body but does not include the required advanced-tool-use-2025-11-20 beta header.

Anthropic rejects these requests unless users manually add the beta via providerOptions.anthropic.anthropicBeta.

Reproduction

import { createAnthropic } from "@ai-sdk/anthropic";
import { generateText, tool } from "ai";
import { z } from "zod";

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

await generateText({
  model: anthropic("claude-sonnet-4-6"),
  prompt: "hello",
  tools: {
    tool_search_tool_regex: anthropic.tools.toolSearchRegex_20251119(),
    sample: tool({
      description: "sample tool",
      inputSchema: z.object({}),
      providerOptions: {
        anthropic: { deferLoading: true },
      },
      execute: async () => ({ ok: true }),
    }),
  },
});

Expected behavior

The Anthropic provider should automatically include:

anthropic-beta: advanced-tool-use-2025-11-20

when using toolSearchRegex_20251119(), toolSearchBm25_20251119(), or deferLoading, similar to how other Anthropic beta-gated tools/options add their required beta headers automatically.

Actual behavior

The provider sends tool_search_tool_regex_20251119 and defer_loading in the request body, but does not add advanced-tool-use-2025-11-20 to anthropic-beta.

With @ai-sdk/anthropic@3.0.85 and ai@6.0.207, intercepting the request with a fake fetch produced this header:

{
  "anthropic-beta": "structured-outputs-2025-11-13",
  "anthropic-version": "2023-06-01",
  "content-type": "application/json"
}

A manual workaround is required:

providerOptions: {
  anthropic: {
    anthropicBeta: ["advanced-tool-use-2025-11-20"],
  },
}

Versions

• @ai-sdk/anthropic: 3.0.85
• ai: 6.0.207
• Runtime used for verification: bun@1.3.13

Notes

This looks like a provider implementation bug rather than a feature request because the SDK exposes the beta-gated API surface and serializes the corresponding request body fields, but omits the required beta header.

[Aayush-engineer]

Hi, I'd like to work on this fix.
I'll look at how other beta headers are auto-added
and apply the same pattern for advanced-tool-use-2025-11-20.
Will open a PR shortly.

[Aayush-engineer]

Hi @lgrammel @gr2m, I've opened a PR for this fix.

The issue was that anthropic-prepare-tools.ts was serializing the correct
request body fields for toolSearchRegex_20251119, toolSearchBm25_20251119,
and deferLoading, but missing the required advanced-tool-use-2025-11-20
beta header for all three cases.

Fix adds betas.add('advanced-tool-use-2025-11-20') in:

• tool_search_regex_20251119 case
• tool_search_bm25_20251119 case
• Function tool condition when deferLoading != null

All 434 tests pass with updated snapshots.

PR: #16246

[aayush-kapoor]

i dont think this issue exists anymore - i tried the example in our repo and it works without passing the beta header. i'd recommend updating the ai and @ai-sdk/anthropic versions to the latest stable version

also, there's no mention of the beta header in anthropic docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.

marking as closed. if observed again, please point to where in Anthropic docs they specify it

[lgrammel]

Identify issue type

Identified as Bug
Confidence: Medium

Rationale

This is a concrete provider failure in specified released versions, with reproducible request output and a workaround. The later non-reproduction may indicate the requirement changed or the problem became obsolete, but does not change the original report’s bug nature.

Evidence

• The report reproduces Anthropic rejecting requests that use exposed tool-search/deferLoading fields because the provider omits the claimed required beta header.
• A manual anthropicBeta header is reported to make the same request work.
• A follow-up PR identified missing beta registration for all three affected cases and added it with passing tests.
• A later commenter could not reproduce on newer versions and questioned whether Anthropic still requires the header.