feat(@ai-sdk/anthropic): support advisor tool (advisor_20260301)

[pmontp19]

Description

Anthropic released the advisor tool (advisor_20260301), a new server-side tool type that lets a cheaper executor model (Sonnet/Haiku) consult a more capable advisor model (Opus) mid-generation — all within a single /v1/messages request. No orchestration code needed.

This is similar in shape to the existing computer_20250124, bash_20250124, and text_editor_20250124 provider tools already supported by @ai-sdk/anthropic, and should follow the same pattern in anthropic-prepare-tools.ts.

API shape

The advisor is added to the tools array with a dedicated type:

{
  "type": "advisor_20260301",
  "name": "advisor",
  "model": "claude-opus-4-6",
  "max_uses": 3,
  "caching": { "type": "ephemeral", "ttl": "5m" }
}

Parameters:

Parameter	Type	Default	Description
type	string	required	Must be "advisor_20260301"
name	string	required	Must be "advisor"
model	string	required	Advisor model ID (e.g. "claude-opus-4-6")
max_uses	integer	unlimited	Per-request cap on advisor calls
caching	object | null	null	Prompt caching for the advisor's transcript: {"type": "ephemeral", "ttl": "5m" | "1h"}

Beta header required: advisor-tool-2026-03-01

Response content blocks

The advisor introduces two new content block types in the assistant response:

1. server_tool_use with name: "advisor" and empty input: {} — signals the advisor call start.
2. advisor_tool_result — contains one of:
   • { type: "advisor_result", text: "..." } — plaintext advice
   • { type: "advisor_redacted_result", encrypted_content: "..." } — opaque blob (must be round-tripped verbatim)
   • { type: "advisor_tool_result_error", error_code: "max_uses_exceeded" | "overloaded" | ... } — non-fatal error

These blocks must be preserved in message history on subsequent turns. If the advisor tool is removed from tools, all advisor_tool_result blocks must also be stripped from messages to avoid a 400 invalid_request_error.

Usage reporting

Advisor tokens are reported separately in usage.iterations[]:

{
  "usage": {
    "input_tokens": 412,
    "output_tokens": 531,
    "iterations": [
      { "type": "message", "input_tokens": 412, "output_tokens": 89 },
      { "type": "advisor_message", "model": "claude-opus-4-6", "input_tokens": 823, "output_tokens": 1612 },
      { "type": "message", "input_tokens": 1348, "output_tokens": 442 }
    ]
  }
}

Top-level usage reflects executor tokens only. Advisor tokens are billed at the advisor model's rates.

Streaming behavior

The advisor sub-inference does not stream. The executor's stream pauses while the advisor runs. The advisor_tool_result arrives fully formed in a single content_block_start event (no deltas). This is important for streamText() — the stream will pause but should not timeout.

Proposed AI SDK integration

Provider tool definition

Following the existing pattern for anthropic.computer_20250124:

// Usage in streamText()
streamText({
  model: anthropic('claude-sonnet-4-6'),
  tools: {
    advisor: anthropic.tools.advisor({
      model: 'claude-opus-4-6',
      maxUses: 3,
      caching: { type: 'ephemeral', ttl: '5m' },
    }),
    // ... other tools
  },
});

Or alternatively via provider options (simpler, since the advisor has no user-defined schema):

streamText({
  model: anthropic('claude-sonnet-4-6'),
  providerOptions: {
    anthropic: {
      advisor: {
        model: 'claude-opus-4-6',
        maxUses: 3,
      },
    },
  },
});

Implementation scope

1. anthropic-prepare-tools.ts: Add advisor_20260301 case alongside existing provider tool types. Add advisor-tool-2026-03-01 to the betas set.
2. Response parsing: Handle server_tool_use (already exists for other server tools), advisor_tool_result, and advisor_redacted_result content blocks. Map them to appropriate AI SDK message parts so they round-trip correctly through useChat / message history.
3. Usage mapping: Expose usage.iterations[] so consumers can distinguish executor vs. advisor token costs. Currently usage only reports top-level tokens.
4. Streaming: Ensure streamText() tolerates the mid-stream pause without timing out. The content_block_start for advisor_tool_result should be handled like other non-streaming content blocks.

Valid model pairs

Executor	Advisor
claude-haiku-4-5-20251001	claude-opus-4-6
claude-sonnet-4-6	claude-opus-4-6

Benchmark context

• Sonnet + Opus advisor: +2.7pp on SWE-bench Multilingual, -11.9% cost vs Sonnet solo
• Haiku + Opus advisor on BrowseComp: 19.7% -> 41.2% (>2x improvement)

References

• Advisor tool documentation
• Blog post
• Server tools docs

AI SDK Version

• ai: 6.0.91
• @ai-sdk/anthropic: 3.0.68

Code of Conduct

• I agree to follow this project's Code of Conduct