@ai-sdk/anthropic 3.0.76 → 3.0.77

package/docs/05-anthropic.mdx

@@ -954,6 +954,63 @@ const result = await generateText({
 });
 ```
 
+### Advisor Tool
+
+Anthropic provides a provider-executed advisor tool that lets an executor model consult a stronger advisor model during generation. This is useful for long-running coding, research, and agentic tasks where a stronger model can provide planning or course correction while the main response is generated by a faster or lower-cost model.
+
+You can enable the advisor tool using `anthropic.tools.advisor_20260301`:
+
+```ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { generateText } from 'ai';
+
+const result = await generateText({
+  model: anthropic('claude-sonnet-4-6'),
+  system: 'You have access to an `advisor` tool backed by a stronger reviewer model.'
+  prompt:
+    'Build a concurrent worker pool in Go with graceful shutdown. Outline the design first.',
+  tools: {
+    advisor: anthropic.tools.advisor_20260301({
+      model: 'claude-opus-4-7',
+      maxUses: 3,
+    }),
+  },
+});
+```
+
+<Note>
+  The AI SDK automatically sends the required `advisor-tool-2026-03-01` beta
+  header when you include this tool.
+</Note>
+
+#### Configuration Options
+
+The advisor tool supports the following configuration options:
+
+- **model** _string_
+
+  Required. The advisor model ID, such as `claude-opus-4-7`. The advisor model must be at least as capable as the executor model.
+
+- **maxUses** _number_
+
+  Optional. Maximum number of advisor calls allowed in a single request. Once the executor reaches this cap, further advisor calls return an `advisor_tool_result_error` with `errorCode: 'max_uses_exceeded'`, and the executor continues without further advice.
+
+- **caching** _object_
+
+  Optional. Enables prompt caching for the advisor's own transcript across calls within a conversation. Use `{ type: 'ephemeral', ttl: '5m' | '1h' }`. This is most useful for longer agent loops where you expect at least three advisor calls.
+
+#### How It Works
+
+The advisor tool is provider-executed, so you do not provide an `execute` function. When the executor model calls `advisor`, Anthropic runs a separate server-side inference with the advisor model. The advisor sees the transcript and returns guidance to the executor, which then continues generating within the same request.
+
+The advisor tool input is always empty. Anthropic constructs the advisor's view from the full transcript automatically.
+
+For multi-turn conversations, pass the full assistant content, including advisor tool results, back on subsequent turns. If you remove the advisor tool from a later request, also remove previous advisor tool results from the message history; otherwise the Anthropic API returns an invalid request error.
+
+#### Streaming
+
+Advisor sub-inferences do not stream. When using `streamText`, the executor stream pauses while the advisor runs, then the advisor result arrives as a single tool result before executor output resumes.
+
 ### Tool Search
 
 Anthropic provides provider-defined tool search tools that enable Claude to work with hundreds or thousands of tools by dynamically discovering and loading them on-demand. Instead of loading all tool definitions into the context window upfront, Claude searches your tool catalog and loads only the tools it needs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/anthropic",
-  "version": "3.0.76",
+  "version": "3.0.77",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",

package/src/anthropic-message-metadata.ts

@@ -2,22 +2,72 @@ import type { JSONObject } from '@ai-sdk/provider';
 
 /**
  * Represents a single iteration in the usage breakdown.
- * When compaction occurs, the API returns an iterations array showing
- * usage for each sampling iteration (compaction + message).
+ *
+ * The API returns an iterations array showing usage for each sampling
+ * iteration. Iterations can be:
+ * - `compaction`: a context compaction step (billed at executor rates).
+ * - `message`: an executor sampling iteration (billed at executor rates).
+ * - `advisor_message`: an advisor sub-inference (billed at the advisor
+ *   model's rates; `model` carries the advisor model ID). Advisor token
+ *   usage is NOT rolled into the top-level usage totals because it bills
+ *   at a different rate; inspect this array directly for advisor billing.
  */
-export interface AnthropicUsageIteration {
-  type: 'compaction' | 'message';
+export type AnthropicUsageIteration =
+  | {
+      type: 'compaction' | 'message';
 
-  /**
-   * Number of input tokens consumed in this iteration.
-   */
-  inputTokens: number;
+      /**
+       * Number of input tokens consumed in this iteration.
+       */
+      inputTokens: number;
 
-  /**
-   * Number of output tokens generated in this iteration.
-   */
-  outputTokens: number;
-}
+      /**
+       * Number of output tokens generated in this iteration.
+       */
+      outputTokens: number;
+
+      /**
+       * Number of cache-creation input tokens consumed in this iteration.
+       */
+      cacheCreationInputTokens?: number;
+
+      /**
+       * Number of cache-read input tokens consumed in this iteration.
+       */
+      cacheReadInputTokens?: number;
+    }
+  | {
+      type: 'advisor_message';
+
+      /**
+       * The advisor model that produced this iteration.
+       */
+      model: string;
+
+      /**
+       * Number of input tokens consumed in this iteration.
+       */
+      inputTokens: number;
+
+      /**
+       * Number of output tokens generated in this iteration.
+       */
+      outputTokens: number;
+
+      /**
+       * Number of cache-creation input tokens consumed by this advisor
+       * sub-inference. Nonzero when advisor-side caching is enabled and
+       * the advisor writes a fresh cache entry.
+       */
+      cacheCreationInputTokens?: number;
+
+      /**
+       * Number of cache-read input tokens consumed by this advisor
+       * sub-inference. Nonzero on the second and later advisor calls
+       * when advisor-side caching is enabled.
+       */
+      cacheReadInputTokens?: number;
+    };
 
 export interface AnthropicMessageMetadata {
   usage: JSONObject;

package/src/anthropic-messages-api.ts

@@ -42,6 +42,7 @@ export interface AnthropicAssistantMessage {
     | AnthropicToolSearchToolResultContent
     | AnthropicBashCodeExecutionToolResultContent
     | AnthropicTextEditorCodeExecutionToolResultContent
+    | AnthropicAdvisorToolResultContent
     | AnthropicMcpToolUseContent
     | AnthropicMcpToolResultContent
     | AnthropicCompactionContent
@@ -151,7 +152,9 @@ export interface AnthropicServerToolUseContent {
     | 'text_editor_code_execution'
     // tool search:
     | 'tool_search_tool_regex'
-    | 'tool_search_tool_bm25';
+    | 'tool_search_tool_bm25'
+    // advisor:
+    | 'advisor';
   input: unknown;
   cache_control: AnthropicCacheControl | undefined;
 }
@@ -310,6 +313,30 @@ export interface AnthropicBashCodeExecutionToolResultContent {
   cache_control: AnthropicCacheControl | undefined;
 }
 
+export interface AnthropicAdvisorToolResultContent {
+  type: 'advisor_tool_result';
+  tool_use_id: string;
+  content:
+    | {
+        type: 'advisor_result';
+        text: string;
+      }
+    | {
+        type: 'advisor_redacted_result';
+        encrypted_content: string;
+      }
+    | {
+        type: 'advisor_tool_result_error';
+        /**
+         * Available options: `max_uses_exceeded`, `too_many_requests`,
+         * `overloaded`, `prompt_too_long`, `execution_time_exceeded`,
+         * `unavailable`.
+         */
+        error_code: string;
+      };
+  cache_control: AnthropicCacheControl | undefined;
+}
+
 export interface AnthropicWebFetchToolResultContent {
   type: 'web_fetch_tool_result';
   tool_use_id: string;
@@ -459,6 +486,16 @@ export type AnthropicTool =
   | {
       type: 'tool_search_tool_bm25_20251119';
       name: string;
+    }
+  | {
+      type: 'advisor_20260301';
+      name: 'advisor';
+      model: string;
+      max_uses?: number;
+      caching?: {
+        type: 'ephemeral';
+        ttl: '5m' | '1h';
+      };
     };
 
 export type AnthropicSpeed = 'fast' | 'standard';
@@ -832,6 +869,25 @@ export const anthropicMessagesResponseSchema = lazySchema(() =>
               }),
             ]),
           }),
+          // advisor results for advisor_20260301:
+          z.object({
+            type: z.literal('advisor_tool_result'),
+            tool_use_id: z.string(),
+            content: z.discriminatedUnion('type', [
+              z.object({
+                type: z.literal('advisor_result'),
+                text: z.string(),
+              }),
+              z.object({
+                type: z.literal('advisor_redacted_result'),
+                encrypted_content: z.string(),
+              }),
+              z.object({
+                type: z.literal('advisor_tool_result_error'),
+                error_code: z.string(),
+              }),
+            ]),
+          }),
         ]),
       ),
       stop_reason: z.string().nullish(),
@@ -843,11 +899,23 @@ export const anthropicMessagesResponseSchema = lazySchema(() =>
         cache_read_input_tokens: z.number().nullish(),
         iterations: z
           .array(
-            z.object({
-              type: z.union([z.literal('compaction'), z.literal('message')]),
-              input_tokens: z.number(),
-              output_tokens: z.number(),
-            }),
+            z.union([
+              z.object({
+                type: z.union([z.literal('compaction'), z.literal('message')]),
+                input_tokens: z.number(),
+                output_tokens: z.number(),
+                cache_creation_input_tokens: z.number().nullish(),
+                cache_read_input_tokens: z.number().nullish(),
+              }),
+              z.object({
+                type: z.literal('advisor_message'),
+                model: z.string(),
+                input_tokens: z.number(),
+                output_tokens: z.number(),
+                cache_creation_input_tokens: z.number().nullish(),
+                cache_read_input_tokens: z.number().nullish(),
+              }),
+            ]),
           )
           .nullish(),
       }),
@@ -1190,6 +1258,25 @@ export const anthropicMessagesChunkSchema = lazySchema(() =>
               }),
             ]),
           }),
+          // advisor results for advisor_20260301:
+          z.object({
+            type: z.literal('advisor_tool_result'),
+            tool_use_id: z.string(),
+            content: z.discriminatedUnion('type', [
+              z.object({
+                type: z.literal('advisor_result'),
+                text: z.string(),
+              }),
+              z.object({
+                type: z.literal('advisor_redacted_result'),
+                encrypted_content: z.string(),
+              }),
+              z.object({
+                type: z.literal('advisor_tool_result_error'),
+                error_code: z.string(),
+              }),
+            ]),
+          }),
         ]),
       }),
       z.object({
@@ -1288,11 +1375,26 @@ export const anthropicMessagesChunkSchema = lazySchema(() =>
           cache_read_input_tokens: z.number().nullish(),
           iterations: z
             .array(
-              z.object({
-                type: z.union([z.literal('compaction'), z.literal('message')]),
-                input_tokens: z.number(),
-                output_tokens: z.number(),
-              }),
+              z.union([
+                z.object({
+                  type: z.union([
+                    z.literal('compaction'),
+                    z.literal('message'),
+                  ]),
+                  input_tokens: z.number(),
+                  output_tokens: z.number(),
+                  cache_creation_input_tokens: z.number().nullish(),
+                  cache_read_input_tokens: z.number().nullish(),
+                }),
+                z.object({
+                  type: z.literal('advisor_message'),
+                  model: z.string(),
+                  input_tokens: z.number(),
+                  output_tokens: z.number(),
+                  cache_creation_input_tokens: z.number().nullish(),
+                  cache_read_input_tokens: z.number().nullish(),
+                }),
+              ]),
             )
             .nullish(),
         }),

package/src/anthropic-messages-language-model.ts

@@ -30,7 +30,10 @@ import {
   type Resolvable,
 } from '@ai-sdk/provider-utils';
 import { anthropicFailedResponseHandler } from './anthropic-error';
-import type { AnthropicMessageMetadata } from './anthropic-message-metadata';
+import type {
+  AnthropicMessageMetadata,
+  AnthropicUsageIteration,
+} from './anthropic-message-metadata';
 import {
   anthropicMessagesChunkSchema,
   anthropicMessagesResponseSchema,
@@ -355,6 +358,7 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
         'anthropic.web_fetch_20260209': 'web_fetch',
         'anthropic.tool_search_regex_20251119': 'tool_search_tool_regex',
         'anthropic.tool_search_bm25_20251119': 'tool_search_tool_bm25',
+        'anthropic.advisor_20260301': 'advisor',
       },
     });
 
@@ -1000,6 +1004,14 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
               input: JSON.stringify(part.input),
               providerExecuted: true,
             });
+          } else if (part.name === 'advisor') {
+            content.push({
+              type: 'tool-call',
+              toolCallId: part.id,
+              toolName: toolNameMapping.toCustomToolName('advisor'),
+              input: JSON.stringify(part.input),
+              providerExecuted: true,
+            });
           }
 
           break;
@@ -1218,6 +1230,44 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
           }
           break;
         }
+
+        // advisor results for advisor_20260301:
+        case 'advisor_tool_result': {
+          const advisorToolName = toolNameMapping.toCustomToolName('advisor');
+          if (part.content.type === 'advisor_result') {
+            content.push({
+              type: 'tool-result',
+              toolCallId: part.tool_use_id,
+              toolName: advisorToolName,
+              result: {
+                type: 'advisor_result',
+                text: part.content.text,
+              },
+            });
+          } else if (part.content.type === 'advisor_redacted_result') {
+            content.push({
+              type: 'tool-result',
+              toolCallId: part.tool_use_id,
+              toolName: advisorToolName,
+              result: {
+                type: 'advisor_redacted_result',
+                encryptedContent: part.content.encrypted_content,
+              },
+            });
+          } else {
+            content.push({
+              type: 'tool-result',
+              toolCallId: part.tool_use_id,
+              toolName: advisorToolName,
+              isError: true,
+              result: {
+                type: 'advisor_tool_result_error',
+                errorCode: part.content.error_code,
+              },
+            });
+          }
+          break;
+        }
       }
     }
 
@@ -1247,11 +1297,42 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
           stopSequence: response.stop_sequence ?? null,
 
           iterations: response.usage.iterations
-            ? response.usage.iterations.map(iter => ({
-                type: iter.type,
-                inputTokens: iter.input_tokens,
-                outputTokens: iter.output_tokens,
-              }))
+            ? response.usage.iterations.map(iter =>
+                iter.type === 'advisor_message'
+                  ? ({
+                      type: iter.type,
+                      model: iter.model,
+                      inputTokens: iter.input_tokens,
+                      outputTokens: iter.output_tokens,
+                      ...(iter.cache_creation_input_tokens
+                        ? {
+                            cacheCreationInputTokens:
+                              iter.cache_creation_input_tokens,
+                          }
+                        : {}),
+                      ...(iter.cache_read_input_tokens
+                        ? {
+                            cacheReadInputTokens: iter.cache_read_input_tokens,
+                          }
+                        : {}),
+                    } satisfies AnthropicUsageIteration)
+                  : ({
+                      type: iter.type,
+                      inputTokens: iter.input_tokens,
+                      outputTokens: iter.output_tokens,
+                      ...(iter.cache_creation_input_tokens
+                        ? {
+                            cacheCreationInputTokens:
+                              iter.cache_creation_input_tokens,
+                          }
+                        : {}),
+                      ...(iter.cache_read_input_tokens
+                        ? {
+                            cacheReadInputTokens: iter.cache_read_input_tokens,
+                          }
+                        : {}),
+                    } satisfies AnthropicUsageIteration),
+              )
             : null,
           container: response.container
             ? {
@@ -1379,6 +1460,7 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
       | 'text_editor_code_execution_tool_result'
       | 'bash_code_execution_tool_result'
       | 'tool_search_tool_result'
+      | 'advisor_tool_result'
       | 'mcp_tool_use'
       | 'mcp_tool_result'
       | 'compaction'
@@ -1597,6 +1679,26 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
                       providerToolName: part.name,
                     };
 
+                    controller.enqueue({
+                      type: 'tool-input-start',
+                      id: part.id,
+                      toolName: customToolName,
+                      providerExecuted: true,
+                    });
+                  } else if (part.name === 'advisor') {
+                    const customToolName =
+                      toolNameMapping.toCustomToolName('advisor');
+
+                    contentBlocks[value.index] = {
+                      type: 'tool-call',
+                      toolCallId: part.id,
+                      toolName: customToolName,
+                      input: '{}',
+                      providerExecuted: true,
+                      firstDelta: true,
+                      providerToolName: part.name,
+                    };
+
                     controller.enqueue({
                       type: 'tool-input-start',
                       id: part.id,
@@ -1808,6 +1910,46 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
                   return;
                 }
 
+                // advisor results for advisor_20260301:
+                // arrives fully formed in a single content_block_start (no deltas).
+                case 'advisor_tool_result': {
+                  const advisorToolName =
+                    toolNameMapping.toCustomToolName('advisor');
+                  if (part.content.type === 'advisor_result') {
+                    controller.enqueue({
+                      type: 'tool-result',
+                      toolCallId: part.tool_use_id,
+                      toolName: advisorToolName,
+                      result: {
+                        type: 'advisor_result',
+                        text: part.content.text,
+                      },
+                    });
+                  } else if (part.content.type === 'advisor_redacted_result') {
+                    controller.enqueue({
+                      type: 'tool-result',
+                      toolCallId: part.tool_use_id,
+                      toolName: advisorToolName,
+                      result: {
+                        type: 'advisor_redacted_result',
+                        encryptedContent: part.content.encrypted_content,
+                      },
+                    });
+                  } else {
+                    controller.enqueue({
+                      type: 'tool-result',
+                      toolCallId: part.tool_use_id,
+                      toolName: advisorToolName,
+                      isError: true,
+                      result: {
+                        type: 'advisor_tool_result_error',
+                        errorCode: part.content.error_code,
+                      },
+                    });
+                  }
+                  return;
+                }
+
                 case 'mcp_tool_use': {
                   mcpToolCalls[part.id] = {
                     type: 'tool-call',
@@ -2232,11 +2374,44 @@ export class AnthropicMessagesLanguageModel implements LanguageModelV3 {
                 cacheCreationInputTokens,
                 stopSequence,
                 iterations: usage.iterations
-                  ? usage.iterations.map(iter => ({
-                      type: iter.type,
-                      inputTokens: iter.input_tokens,
-                      outputTokens: iter.output_tokens,
-                    }))
+                  ? usage.iterations.map(iter =>
+                      iter.type === 'advisor_message'
+                        ? ({
+                            type: iter.type,
+                            model: iter.model,
+                            inputTokens: iter.input_tokens,
+                            outputTokens: iter.output_tokens,
+                            ...(iter.cache_creation_input_tokens
+                              ? {
+                                  cacheCreationInputTokens:
+                                    iter.cache_creation_input_tokens,
+                                }
+                              : {}),
+                            ...(iter.cache_read_input_tokens
+                              ? {
+                                  cacheReadInputTokens:
+                                    iter.cache_read_input_tokens,
+                                }
+                              : {}),
+                          } satisfies AnthropicUsageIteration)
+                        : ({
+                            type: iter.type,
+                            inputTokens: iter.input_tokens,
+                            outputTokens: iter.output_tokens,
+                            ...(iter.cache_creation_input_tokens
+                              ? {
+                                  cacheCreationInputTokens:
+                                    iter.cache_creation_input_tokens,
+                                }
+                              : {}),
+                            ...(iter.cache_read_input_tokens
+                              ? {
+                                  cacheReadInputTokens:
+                                    iter.cache_read_input_tokens,
+                                }
+                              : {}),
+                          } satisfies AnthropicUsageIteration),
+                    )
                   : null,
                 container,
                 contextManagement,

package/src/anthropic-prepare-tools.ts

@@ -8,6 +8,7 @@ import type {
   AnthropicToolChoice,
 } from './anthropic-messages-api';
 import { CacheControlValidator } from './get-cache-control';
+import { advisor_20260301ArgsSchema } from './tool/advisor_20260301';
 import { textEditor_20250728ArgsSchema } from './tool/text-editor_20250728';
 import { webSearch_20260209ArgsSchema } from './tool/web-search_20260209';
 import { webSearch_20250305ArgsSchema } from './tool/web-search_20250305';
@@ -349,6 +350,22 @@ export async function prepareTools({
             break;
           }
 
+          case 'anthropic.advisor_20260301': {
+            betas.add('advisor-tool-2026-03-01');
+            const args = await validateTypes({
+              value: tool.args,
+              schema: advisor_20260301ArgsSchema,
+            });
+            anthropicTools.push({
+              type: 'advisor_20260301',
+              name: 'advisor',
+              model: args.model,
+              ...(args.maxUses !== undefined && { max_uses: args.maxUses }),
+              ...(args.caching !== undefined && { caching: args.caching }),
+            });
+            break;
+          }
+
           default: {
             toolWarnings.push({
               type: 'unsupported',

package/src/anthropic-tools.ts

@@ -1,3 +1,4 @@
+import { advisor_20260301 } from './tool/advisor_20260301';
 import { bash_20241022 } from './tool/bash_20241022';
 import { bash_20250124 } from './tool/bash_20250124';
 import { codeExecution_20250522 } from './tool/code-execution_20250522';
@@ -19,6 +20,36 @@ import { webSearch_20260209 } from './tool/web-search_20260209';
 import { webSearch_20250305 } from './tool/web-search_20250305';
 
 export const anthropicTools = {
+  /**
+   * Pairs a faster executor model with a higher-intelligence advisor model
+   * that provides strategic guidance mid-generation.
+   *
+   * The advisor lets a faster, lower-cost executor model consult a
+   * higher-intelligence advisor model server-side. The advisor reads the
+   * executor's full transcript and produces a plan or course correction;
+   * the executor continues with the task, informed by the advice. All of
+   * this happens inside a single `/v1/messages` request.
+   *
+   * Beta header `advisor-tool-2026-03-01` is added automatically when this
+   * tool is included.
+   *
+   * Multi-turn conversations: pass the full assistant content (including
+   * `advisor_tool_result` blocks) back to the API on subsequent turns. If
+   * you omit the advisor tool from `tools` on a follow-up turn while the
+   * message history still contains `advisor_tool_result` blocks, the API
+   * returns a `400 invalid_request_error`.
+   *
+   * Supported executor models: Claude Haiku 4.5, Sonnet 4.6, Opus 4.6,
+   * Opus 4.7. The advisor must be at least as capable as the executor.
+   *
+   * @param model - The advisor model ID (required), e.g. `"claude-opus-4-7"`.
+   * @param maxUses - Maximum advisor calls per request (per-request cap).
+   * @param caching - Enables prompt caching for the advisor's transcript
+   * across calls within a conversation. Worthwhile from ~3 advisor calls
+   * per conversation.
+   */
+  advisor_20260301,
+
   /**
    * The bash tool enables Claude to execute shell commands in a persistent bash session,
    * allowing system operations, script execution, and command-line automation.