@ai-sdk/anthropic 3.0.122 → 3.0.123

package/docs/05-anthropic.mdx

@@ -1376,13 +1376,16 @@ This sends `tool_reference` blocks to Anthropic, which loads the corresponding d
 
 ### Mid-Conversation System Controls
 
-With `claude-opus-5-5` and `claude-fable-5-1`, a mid-conversation system message
-can be cleared before the next user message with `clearAt: 'next_user_message'`,
-or set the effort for the next turn without invalidating the prompt cache. The provider adds the required
+With `claude-opus-5-5` and `claude-fable-5-1`, use an empty system message to
+change effort from the next user turn. A separate system message containing text
+can provide a turn-scoped reminder with `clearAt: 'next_user_message'`: its text
+applies until the next user message. Keep the reminder after a user turn and
+before an assistant turn, or at the end of the messages array.
+The provider adds the required
 `mid-conversation-system-clear-at-2026-08-21` and
 `mid-conversation-output-config-2026-07-01` beta headers automatically.
 
-```ts highlight="17-25"
+```ts highlight="16-24,29-37"
 import { anthropic } from '@ai-sdk/anthropic';
 import { generateText } from 'ai';
 
@@ -1400,10 +1403,9 @@ const result = await generateText({
     },
     {
       role: 'system',
-      content: 'For the next turn, verify every compatibility claim.',
+      content: '',
       providerOptions: {
         anthropic: {
-          clearAt: 'next_user_message',
           effort: 'high',
         },
       },
@@ -1412,19 +1414,39 @@ const result = await generateText({
       role: 'user',
       content: 'Complete the plan.',
     },
+    {
+      role: 'system',
+      content: 'For this turn, verify every compatibility claim.',
+      providerOptions: {
+        anthropic: {
+          clearAt: 'next_user_message',
+        },
+      },
+    },
   ],
 });
 ```
 
 An effort-only system message can use an empty content array at the API level;
 in an AI SDK prompt, set `content: ''`. The provider serializes it as
-`content: []`.
+`content: []`. These effort-only messages can appear first or later in the
+conversation, including consecutively. The provider preserves their order. The new
+level applies from the next user turn until a later message changes it.
+Initial instruction text is sent in the top-level `system` field.
+
+Consecutive inline system messages are evaluated as a group. If an effort-only
+message is adjacent to a system message containing text, the whole group must
+follow Anthropic's [content placement rules](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations).
+
+Turn-scoped messages with `clearAt` support text only. Put effort updates in a
+separate message, as in the example above.
 
 <Note>
-  `clearAt` and per-message `effort` apply only to mid-conversation system
-  messages. When used on the initial system message, the provider ignores them
-  and emits a warning. Use the top-level `effort` provider option to configure
-  effort for the full request.
+  `clearAt` applies only to mid-conversation system messages. On initial system
+  messages, the provider ignores `clearAt` and effort attached to non-empty
+  content and emits a warning. Use an empty system message for an initial
+  per-message effort setting, or the top-level `effort` provider option to
+  configure effort for the full request.
 </Note>
 
 ### Mid-Conversation Tool Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/anthropic",
-  "version": "3.0.122",
+  "version": "3.0.123",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -36,8 +36,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "3.0.17",
-    "@ai-sdk/provider-utils": "4.0.54"
+    "@ai-sdk/provider": "3.0.18",
+    "@ai-sdk/provider-utils": "4.0.55"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

package/src/anthropic-messages-options.ts

@@ -75,11 +75,10 @@ export const anthropicSystemMessageProviderOptions = z.object({
   clearAt: z.literal('next_user_message').optional(),
 
   /**
-   * Overrides the effort level for the turn following this
-   * mid-conversation system message.
-   *
-   * Requires the `mid-conversation-output-config-2026-07-01` beta,
-   * which is added automatically.
+   * Sets the model effort from the next user turn until a later message
+   * changes it. An effort-only system message with empty content can appear
+   * first. The required `mid-conversation-output-config-2026-07-01` beta is
+   * added automatically.
    */
   effort: z.enum(['low', 'medium', 'high', 'xhigh', 'max']).optional(),
 

package/src/convert-to-anthropic-messages-prompt.ts

@@ -247,14 +247,28 @@ export async function convertToAnthropicMessagesPrompt({
                 'The tool changes have been ignored.',
             });
           }
-          if (hasMidConversationOptions) {
-            warnings.push({
-              type: 'other',
-              message:
-                'clearAt and effort on the initial system message are not supported by Anthropic. ' +
-                'Configure these options on a mid-conversation system message instead. ' +
-                'The options have been ignored.',
-            });
+          // Initial instruction text goes in the top-level system field.
+          // Effort-only messages stay in the messages array.
+          for (const message of systemMessages) {
+            if (
+              message.content.length === 0 &&
+              message.clear_at == null &&
+              message.output_config != null
+            ) {
+              messages.push(message);
+              betas.add('mid-conversation-output-config-2026-07-01');
+            } else if (
+              message.clear_at != null ||
+              message.output_config != null
+            ) {
+              warnings.push({
+                type: 'other',
+                message:
+                  'clearAt and effort on this initial system message are not supported by Anthropic. ' +
+                  'Use a separate effort-only system message with empty content to set effort. ' +
+                  'These options have been ignored.',
+              });
+            }
           }
           system = systemMessages.flatMap(message =>
             message.content.filter(