ai 7.0.153 → 7.0.154

package/docs/03-agents/09-chat-platforms.mdx

@@ -0,0 +1,164 @@
+---
+title: Chat Platforms
+description: Run AI SDK agents in Slack, Microsoft Teams, Discord, and other chat platforms with Chat SDK.
+---
+
+# Chat Platforms
+
+[Chat SDK](https://chat-sdk.dev) is a TypeScript SDK for building bots that run on Slack, Microsoft Teams, Google Chat, Discord, Telegram, GitHub, Linear, WhatsApp, and more. You write your bot logic once, and platform adapters handle webhook verification, message parsing, and native formatting for each platform.
+
+Chat SDK works with the AI SDK out of the box:
+
+- `thread.post()` accepts an agent's `fullStream` and streams the reply into the conversation.
+- `toAiMessages` from `chat/ai` converts a thread's messages into AI SDK `ModelMessage[]`.
+- `createChatTools` from `chat/ai` gives an agent tools for reading and acting in the conversation.
+
+This page shows how to connect a [`ToolLoopAgent`](/docs/agents/building-agents) to Slack. The same code works on every platform Chat SDK supports.
+
+## Installation
+
+Install Chat SDK, a platform adapter, and a state adapter. The state adapter stores thread subscriptions and locks. This example uses Slack and Redis:
+
+<InstallPackages packages="ai chat @chat-adapter/slack @chat-adapter/state-redis" />
+
+The Slack adapter reads `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` from the environment, and the Redis state adapter reads `REDIS_URL`. See the [Slack adapter docs](https://chat-sdk.dev/adapters/official/slack) for the Slack app manifest. The examples on this page set `agentView: true` to match a manifest that uses Slack's Agent messaging experience (`agent_view`).
+
+## Create a Bot
+
+Create a `Chat` instance and an agent. When someone mentions the bot, subscribe to the thread and stream the agent's reply into it:
+
+```ts filename="lib/bot.ts"
+import { Chat } from 'chat';
+import { createSlackAdapter } from '@chat-adapter/slack';
+import { createRedisState } from '@chat-adapter/state-redis';
+import { ToolLoopAgent } from 'ai';
+
+export const bot = new Chat({
+  userName: 'mybot',
+  adapters: {
+    slack: createSlackAdapter({ agentView: true }),
+  },
+  state: createRedisState(),
+});
+
+const agent = new ToolLoopAgent({
+  model: 'anthropic/claude-sonnet-5.5',
+  instructions:
+    'You are a helpful assistant in a team chat. Keep replies short.',
+});
+
+bot.onNewMention(async (thread, message) => {
+  await thread.subscribe();
+
+  const result = await agent.stream({
+    prompt: message.text,
+    abortSignal: thread.signal,
+  });
+
+  await thread.post(result.fullStream);
+});
+```
+
+`thread.signal` is aborted when the platform cancels the turn (for example, when a user clicks Slack's stop button), so passing it as `abortSignal` stops generation too.
+
+Then route the platform's webhooks to the bot:
+
+```ts filename="app/api/webhooks/slack/route.ts"
+import { after } from 'next/server';
+import { bot } from '@/lib/bot';
+
+export async function POST(request: Request): Promise<Response> {
+  return bot.webhooks.slack(request, {
+    waitUntil: task => after(() => task),
+  });
+}
+```
+
+`waitUntil` keeps the function running after the webhook responds, so the agent can finish streaming its reply.
+
+### Why `fullStream`?
+
+Pass `fullStream` instead of `textStream`. When an agent calls tools between text steps, `textStream` joins the text from each step without separators. `fullStream` includes `finish-step` events, which Chat SDK uses to add paragraph breaks between steps.
+
+## Use Thread History
+
+After `thread.subscribe()`, later messages in the thread go to `onSubscribedMessage`. Load the thread history and convert it with `toAiMessages` to give the agent the full conversation:
+
+```ts filename="lib/bot.ts"
+import { toAiMessages } from 'chat/ai';
+
+bot.onSubscribedMessage(async thread => {
+  const { messages } = await bot.history.thread.list(thread.id, {
+    limit: 20,
+  });
+
+  const result = await agent.stream({
+    messages: await toAiMessages(messages),
+    abortSignal: thread.signal,
+  });
+
+  await thread.post(result.fullStream);
+});
+```
+
+`toAiMessages` maps the bot's own messages to `assistant` and all others to `user`, sorts them oldest first, and includes supported attachments such as images and text files. Pass `{ includeNames: true }` to prefix each user message with the sender's name in multi-user threads.
+
+## Give the Agent Chat Tools
+
+`createChatTools` returns AI SDK tools that let the agent read and act in the chat: fetch messages, look up channels, post, react, and more. Use a preset to limit the tools to what the agent needs:
+
+```ts filename="lib/bot.ts"
+import { ToolLoopAgent } from 'ai';
+import { createChatTools } from 'chat/ai';
+
+const agent = new ToolLoopAgent({
+  model: 'anthropic/claude-sonnet-5.5',
+  instructions:
+    'You are a helpful assistant in a team chat. You can read messages in the current channel.',
+  tools: createChatTools({ chat: bot, preset: 'reader' }),
+  toolApproval: {
+    getUser: {
+      type: 'denied',
+      reason: 'Profile lookups are disabled for this bot',
+    },
+  },
+});
+```
+
+The presets are `reader` (read-only), `messenger` (read, post, DM, and react), and `moderator` (all tools, including edit and delete).
+
+When a tool runs inside a Chat SDK handler, it is limited to the conversation being handled. This stops the model from reading or posting in other channels the bot can access. See [Limiting what the agent can reach](https://chat-sdk.dev/docs/ai/ai-sdk-tools#limiting-what-the-agent-can-reach) for the `scope` and `strictScope` options.
+
+Chat SDK marks write tools and `getUser` as needing approval by default. A `toolApproval` rule on the agent takes precedence over those defaults, so you can approve or deny calls automatically when your bot has no approval UI. The example above denies `getUser` profile lookups. See [Tool Approvals](/docs/agents/tool-approvals) for all approval options.
+
+## Add More Platforms
+
+Register more adapters to run the same handlers on other platforms:
+
+```ts filename="lib/bot.ts"
+import { Chat } from 'chat';
+import { createSlackAdapter } from '@chat-adapter/slack';
+import { createTeamsAdapter } from '@chat-adapter/teams';
+import { createDiscordAdapter } from '@chat-adapter/discord';
+import { createRedisState } from '@chat-adapter/state-redis';
+
+export const bot = new Chat({
+  userName: 'mybot',
+  adapters: {
+    slack: createSlackAdapter({ agentView: true }),
+    teams: createTeamsAdapter(),
+    discord: createDiscordAdapter(),
+  },
+  state: createRedisState(),
+});
+```
+
+Each adapter gets its own webhook route, such as `bot.webhooks.teams`. Chat SDK normalizes messages and threads across platforms, so your handlers and agent stay the same.
+
+To serve a browser chat from the same bot, use the Chat SDK Web adapter with `useChat`. See [Chat SDK Web Adapter](/docs/ai-sdk-ui/transport#chat-sdk-web-adapter).
+
+## Next Steps
+
+- **[Slackbot Agent Guide](/cookbook/guides/slackbot)** - Build and deploy a Slack agent with tools step by step
+- **[Tool Approvals](/docs/agents/tool-approvals)** - Approve or deny tool calls automatically or with a human in the loop
+- **[Chat SDK documentation](https://chat-sdk.dev/docs)** - Adapters, cards, modals, slash commands, and more

package/docs/03-agents/index.mdx

@@ -68,5 +68,11 @@ The following section shows you how to build agents with the AI SDK - systems wh
         'Run ToolLoopAgent instances in an interactive terminal interface.',
       href: '/docs/agents/terminal-ui',
     },
+    {
+      title: 'Chat Platforms',
+      description:
+        'Run agents in Slack, Microsoft Teams, Discord, and more with Chat SDK.',
+      href: '/docs/agents/chat-platforms',
+    },
   ]}
 />

package/docs/03-ai-sdk-core/60-telemetry.mdx

@@ -319,14 +319,21 @@ context across provider calls and tool executions.
 import { tracingChannel } from 'node:diagnostics_channel';
 import {
   AI_SDK_TELEMETRY_TRACING_CHANNEL,
+  type InferTelemetryEvent,
   type TelemetryTracingChannelMessage,
 } from 'ai';
 
 tracingChannel(AI_SDK_TELEMETRY_TRACING_CHANNEL).subscribe({
   start(message) {
-    const telemetryMessage = message as TelemetryTracingChannelMessage;
-
-    if (telemetryMessage.type === 'onStart') {
+    const telemetryMessage = message as TelemetryTracingChannelMessage<
+      InferTelemetryEvent<unknown>
+    >;
+
+    if (
+      telemetryMessage.type === 'generateText' ||
+      telemetryMessage.type === 'streamText'
+    ) {
+      console.log('AI SDK version:', telemetryMessage.event.aiVersion);
       // Inspect telemetryMessage.event and forward it to your provider.
     }
   },
@@ -431,6 +438,12 @@ export function myIntegration(): Telemetry {
       type: '(event: GenerateTextStepEndEvent) => void | PromiseLike<void>',
       description: 'Called when a step (LLM call) completes.',
     },
+    {
+      name: 'onStepError',
+      type: '(event: GenerateTextStepErrorEvent) => void | PromiseLike<void>',
+      description:
+        'Called when a step that started fails before it produces a step result. Use it to close step-level spans. The call then ends with `onError`.',
+    },
     {
       name: 'onEmbedEnd',
       type: '(event: EmbeddingModelCallEndEvent) => void | PromiseLike<void>',

package/docs/03-ai-sdk-core/65-lifecycle-callbacks.mdx

@@ -299,6 +299,10 @@ A multi-step generation with local tool execution usually runs like this:
 `onLanguageModelCallStart` and `onLanguageModelCallEnd` describe only the model call inside that step.
 This distinction matters when the step includes local tool execution: the step duration can be longer than the model response duration.
 
+When a step that started fails before it produces a step result, `onStepError` is called instead of `onStepEnd`. This happens when the provider call throws or rejects, or when the model stream ends without output. A provider `error` chunk does not fail the step: the step still ends with `onStepEnd` and `finishReason: 'error'`.
+
+Aborts and timeouts end the step differently in each function. In `generateText` and `agent.generate()`, they end the step with `onStepError`. Its `error` is the abort or timeout error, or a provider error that has it as its `cause`. In `streamText` and `agent.stream()`, they end the step with `onAbort`.
+
 ## Runtime and Tool Context
 
 Generation and step lifecycle callbacks receive the full `runtimeContext` and
@@ -403,6 +407,12 @@ const result = await generateText({
       description:
         'Called after each generation step completes. Receives the step result, including usage and performance.',
     },
+    {
+      name: 'onStepError',
+      type: '(event: GenerateTextStepErrorEvent) => void | Promise<void>',
+      description:
+        'Called when a step that started fails before it produces a step result: the provider call throws or rejects, or the model stream ends without output. Receives the `onStepStart` event of the failed step plus `error`. In `generateText`, also called on abort or timeout. In `streamText`, aborts and timeouts call `onAbort` instead.',
+    },
     {
       name: 'onEnd',
       type: '(event: GenerateTextEndEvent) => void | Promise<void>',

package/docs/04-ai-sdk-ui/21-transport.mdx

@@ -271,6 +271,92 @@ WorkflowAgent guide.
 
 For the full API reference, see [`WorkflowChatTransport`](/docs/reference/ai-sdk-workflow/workflow-chat-transport). For server-side endpoint setup, see the [WorkflowAgent guide](/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport).
 
+## Chat SDK Web Adapter
+
+The [Chat SDK](https://chat-sdk.dev) Web adapter (`@chat-adapter/web`) serves a `useChat` endpoint from a Chat SDK bot. It speaks the [UI message stream protocol](/docs/ai-sdk-ui/stream-protocol), so the default transport works without changes. Use it when the same bot also runs on Slack, Microsoft Teams, Discord, or other [chat platforms](/docs/agents/chat-platforms), and you want one set of handlers for all of them.
+
+<InstallPackages packages="ai @ai-sdk/react chat @chat-adapter/web @chat-adapter/state-redis" />
+
+On the server, register the Web adapter and handle messages with `onDirectMessage`. Each browser conversation is a direct message thread:
+
+```ts filename="lib/bot.ts"
+import { Chat } from 'chat';
+import { toAiMessages } from 'chat/ai';
+import { createWebAdapter } from '@chat-adapter/web';
+import { createRedisState } from '@chat-adapter/state-redis';
+import { ToolLoopAgent } from 'ai';
+import { getSession } from './session'; // your app's auth
+
+const agent = new ToolLoopAgent({
+  model: 'anthropic/claude-sonnet-5.5',
+  instructions: 'You are a helpful assistant.',
+});
+
+export const bot = new Chat({
+  userName: 'mybot',
+  adapters: {
+    web: createWebAdapter({
+      userName: 'mybot',
+      // Identify the caller from your app's session. Returning null responds with 401.
+      getUser: async () => {
+        const session = await getSession();
+        return session ? { id: session.userId } : null;
+      },
+    }),
+  },
+  state: createRedisState(),
+});
+
+bot.onDirectMessage(async thread => {
+  const { messages } = await bot.history.thread.list(thread.id, {
+    limit: 20,
+  });
+
+  const result = await agent.stream({
+    messages: await toAiMessages(messages),
+    abortSignal: thread.signal,
+  });
+
+  await thread.post(result.fullStream);
+});
+```
+
+```ts filename="app/api/chat/route.ts"
+import { after } from 'next/server';
+import { bot } from '@/lib/bot';
+
+export async function POST(request: Request): Promise<Response> {
+  return bot.webhooks.web(request, {
+    waitUntil: task => after(() => task),
+  });
+}
+```
+
+On the client, point the default transport at the route:
+
+```tsx filename="app/page.tsx"
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+export default function Chat() {
+  const { messages, sendMessage } = useChat({
+    transport: new DefaultChatTransport({ api: '/api/chat' }),
+  });
+
+  // ... render chat UI
+}
+```
+
+Things to know:
+
+- **Authentication**: browser requests have no platform signature, so `getUser` is the security boundary. Resolve the user from your app's session and return `null` to reject the request.
+- **Conversation history**: the adapter ignores the message history in the request body. It stores each conversation's messages in the state adapter, and `bot.history.thread.list()` reads them back. The chat `id` from `useChat` identifies the conversation.
+- **Stopping**: the adapter honors the request's abort signal, so calling `stop()` in `useChat` stops the handler's stream.
+
+For all options, including the `ag-ui` protocol and `useChat` wrappers for React, Vue, and Svelte, see the [Web adapter docs](https://chat-sdk.dev/adapters/official/web).
+
 ## Building Custom Transports
 
 To understand how to build your own transport, refer to the source code of the default implementation:

package/docs/07-reference/01-ai-sdk-core/01-generate-text.mdx

@@ -658,6 +658,13 @@ To see `generateText` in action, check out [these examples](#examples).
                       description:
                         'The messages that will be sent to the model for the current step. If prepareStep returns a messages override, those messages carry forward to later steps.',
                     },
+                    {
+                      name: 'experimental_steeringMessages',
+                      type: 'Array<UserModelMessage> | undefined',
+                      isOptional: true,
+                      description:
+                        'The user messages that were sent with `experimental_steering` and added to `messages` for the current step. Undefined when the step received no steering messages. `messages` already contains them. If you return a `messages` override that is rebuilt from other fields, add them back together with the steering messages of previous steps from `steps`.',
+                    },
                     {
                       name: 'runtimeContext',
                       type: 'CONTEXT',
@@ -845,6 +852,13 @@ To see `generateText` in action, check out [these examples](#examples).
       description:
         'Experimental sandbox environment that is passed through to `prepareStep`, tool description functions, and tool execution. Tools can access it from their description function options and execution options.',
     },
+    {
+      name: 'experimental_steering',
+      type: 'Experimental_Steering',
+      isOptional: true,
+      description:
+        "Experimental steering object created with `experimental_createSteering()`. Messages sent with `steering.steer()` are added as user messages at the next step boundary, after the current step and its tool calls are done. A waiting message keeps the loop going for another step unless a stop condition is met. `steer()` resolves with `{ type: 'delivered', id, message, stepNumber }` or `{ type: 'not-delivered', id, message, reason }`. See [Steering](/docs/agents/loop-control#steering).",
+    },
     {
       name: 'experimental_download',
       type: '(requestedDownloads: Array<{ url: URL; isUrlSupportedByModel: boolean }>) => Promise<Array<null | { data: Uint8Array; mediaType?: string }>>',
@@ -1999,6 +2013,31 @@ To see `generateText` in action, check out [these examples](#examples).
         },
       ],
     },
+    {
+      name: 'onStepError',
+      type: '(event: GenerateTextStepErrorEvent) => Promise<void> | void',
+      isOptional: true,
+      description:
+        'Callback that is called when a step that started fails before it produces a step result, i.e. when the provider call throws or rejects, or when the call is aborted or times out. `onStepEnd` is not called for such a step. For aborts and timeouts, `error` is the abort or timeout error, or a provider error that has it as its `cause`.',
+      properties: [
+        {
+          type: 'GenerateTextStepErrorEvent',
+          parameters: [
+            {
+              name: '...GenerateTextStepStartEvent',
+              type: 'GenerateTextStepStartEvent',
+              description:
+                'All properties of the `onStepStart` event of the step that failed, such as `callId`, `stepNumber`, `steps`, `messages`, `runtimeContext`, and `toolsContext`.',
+            },
+            {
+              name: 'error',
+              type: 'unknown',
+              description: 'The error that ended the step.',
+            },
+          ],
+        },
+      ],
+    },
     {
       name: 'onStepFinish',
       type: 'GenerateTextOnStepFinishCallback<TOOLS>',
@@ -3226,6 +3265,13 @@ To see `generateText` in action, check out [these examples](#examples).
               description:
                 'Additional provider-specific metadata. They are passed through from the provider to the AI SDK and enable provider-specific results that can be fully encapsulated in the provider.',
             },
+            {
+              name: 'experimental_steeringMessages',
+              type: 'Array<UserModelMessage> | undefined',
+              isOptional: true,
+              description:
+                'The user messages that were sent with `experimental_steering` and added to the input of this step. Undefined when the step received no steering messages.',
+            },
           ],
         },
       ],

package/docs/07-reference/01-ai-sdk-core/02-stream-text.mdx

@@ -715,6 +715,13 @@ retain the content their contracts require.
                       description:
                         'The messages that will be sent to the model for the current step. If prepareStep returns a messages override, those messages carry forward to later steps.',
                     },
+                    {
+                      name: 'experimental_steeringMessages',
+                      type: 'Array<UserModelMessage> | undefined',
+                      isOptional: true,
+                      description:
+                        'The user messages that were sent with `experimental_steering` and added to `messages` for the current step. Undefined when the step received no steering messages. `messages` already contains them. If you return a `messages` override that is rebuilt from other fields, add them back together with the steering messages of previous steps from `steps`.',
+                    },
                     {
                       name: 'runtimeContext',
                       type: 'CONTEXT',
@@ -902,6 +909,13 @@ retain the content their contracts require.
       description:
         'Experimental sandbox environment that is passed through to `prepareStep`, tool description functions, and tool execution. Tools can access it from their description function options and execution options.',
     },
+    {
+      name: 'experimental_steering',
+      type: 'Experimental_Steering',
+      isOptional: true,
+      description:
+        "Experimental steering object created with `experimental_createSteering()`. Messages sent with `steering.steer()` are added as user messages at the next step boundary, after the current step and its tool calls are done. A waiting message keeps the loop going for another step unless a stop condition is met. `steer()` resolves with `{ type: 'delivered', id, message, stepNumber }` or `{ type: 'not-delivered', id, message, reason }`. See [Steering](/docs/agents/loop-control#steering).",
+    },
     {
       name: 'experimental_download',
       type: '(requestedDownloads: Array<{ url: URL; isUrlSupportedByModel: boolean }>) => Promise<Array<null | { data: Uint8Array; mediaType?: string }>>',
@@ -1727,6 +1741,31 @@ retain the content their contracts require.
         },
       ],
     },
+    {
+      name: 'onStepError',
+      type: '(event: GenerateTextStepErrorEvent) => Promise<void> | void',
+      isOptional: true,
+      description:
+        "Callback that is called when a step that started fails before it produces a step result, i.e. when the provider call throws or rejects, or when the model stream ends without output. `onStepEnd` is not called for such a step. A provider `error` chunk does not fail the step: it still ends with `onStepEnd` and `finishReason: 'error'`. Aborts and timeouts end the step with `onAbort` instead.",
+      properties: [
+        {
+          type: 'GenerateTextStepErrorEvent',
+          parameters: [
+            {
+              name: '...GenerateTextStepStartEvent',
+              type: 'GenerateTextStepStartEvent',
+              description:
+                'All properties of the `onStepStart` event of the step that failed, such as `callId`, `stepNumber`, `steps`, `messages`, `runtimeContext`, and `toolsContext`.',
+            },
+            {
+              name: 'error',
+              type: 'unknown',
+              description: 'The error that ended the step.',
+            },
+          ],
+        },
+      ],
+    },
     {
       name: 'onStepFinish',
       type: 'GenerateTextOnStepFinishCallback<TOOLS>',
@@ -3350,6 +3389,13 @@ retain the content their contracts require.
               description:
                 'Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',
             },
+            {
+              name: 'experimental_steeringMessages',
+              type: 'Array<UserModelMessage> | undefined',
+              isOptional: true,
+              description:
+                'The user messages that were sent with `experimental_steering` and added to the input of this step. Undefined when the step received no steering messages.',
+            },
           ],
         },
       ],

package/docs/07-reference/01-ai-sdk-core/16-tool-loop-agent.mdx

@@ -519,6 +519,27 @@ To see `ToolLoopAgent` in action, check out [these examples](#examples).
       description:
         'Callback invoked after each agent step (LLM/tool call) completes. If also specified in `generate()` or `stream()`, both callbacks are called (constructor first).',
     },
+    {
+      name: 'onStepError',
+      type: '(event: GenerateTextStepErrorEvent) => Promise<void> | void',
+      isOptional: true,
+      description:
+        "Callback invoked when an agent step that started fails before it produces a step result, i.e. when the provider call throws or rejects, or when the model stream ends without output. `onStepEnd` is not called for such a step. A provider `error` chunk does not fail the step: it still ends with `onStepEnd` and `finishReason: 'error'`. The event contains all properties of the `onStepStart` event of the step that failed, plus `error`. In `generate()`, aborts and timeouts also end the step here. In `stream()`, they end the step with `onAbort` instead. Only available in the constructor.",
+    },
+    {
+      name: 'onError',
+      type: '(event: { error: unknown }) => Promise<void> | void',
+      isOptional: true,
+      description:
+        'Callback invoked when an error occurs. For `stream()` it receives the errors of the stream, for `generate()` it receives the error before it is thrown. Aborts and timeouts are not reported. When not set, `stream()` logs errors to the console. Only available in the constructor.',
+    },
+    {
+      name: 'onAbort',
+      type: '(event: GenerateTextAbortEvent) => Promise<void> | void',
+      isOptional: true,
+      description:
+        'Callback invoked when `stream()` is aborted or times out. Receives the steps that finished before the abort and the abort reason. `generate()` does not call it: an aborted or timed out `generate()` call rejects, and its step ends with `onStepError`. Only available in the constructor.',
+    },
     {
       name: 'onStepFinish',
       type: 'GenerateTextOnStepFinishCallback',
@@ -742,6 +763,13 @@ const result = await agent.generate({
       description:
         'Experimental sandbox environment that is passed through to `prepareStep`, tool description functions, and tool execution. Tools can access it from their description function options and execution options.',
     },
+    {
+      name: 'experimental_steering',
+      type: 'Experimental_Steering',
+      isOptional: true,
+      description:
+        "Experimental steering object created with `experimental_createSteering()`. Messages sent with `steering.steer()` are added as user messages at the next step boundary, after the current step and its tool calls are done. A waiting message keeps the loop going for another step unless a stop condition is met. `steer()` resolves with `{ type: 'delivered', id, message, stepNumber }` or `{ type: 'not-delivered', id, message, reason }`. See [Steering](/docs/agents/loop-control#steering).",
+    },
     {
       name: 'options',
       type: 'CALL_OPTIONS',
@@ -858,6 +886,13 @@ for await (const chunk of stream.textStream) {
       description:
         'Experimental sandbox environment that is passed through to `prepareStep`, tool description functions, and tool execution. Tools can access it from their description function options and execution options.',
     },
+    {
+      name: 'experimental_steering',
+      type: 'Experimental_Steering',
+      isOptional: true,
+      description:
+        "Experimental steering object created with `experimental_createSteering()`. Messages sent with `steering.steer()` are added as user messages at the next step boundary, after the current step and its tool calls are done. A waiting message keeps the loop going for another step unless a stop condition is met. `steer()` resolves with `{ type: 'delivered', id, message, stepNumber }` or `{ type: 'not-delivered', id, message, reason }`. See [Steering](/docs/agents/loop-control#steering).",
+    },
     {
       name: 'options',
       type: 'CALL_OPTIONS',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.153",
+  "version": "7.0.154",
   "type": "module",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
@@ -42,20 +42,20 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.126",
+    "@ai-sdk/gateway": "4.0.127",
     "@ai-sdk/provider": "4.0.34",
-    "@ai-sdk/provider-utils": "5.0.68"
+    "@ai-sdk/provider-utils": "5.0.69"
   },
   "devDependencies": {
-    "@ai-sdk/amazon-bedrock": "5.0.124",
-    "@ai-sdk/deepseek": "3.0.73",
-    "@ai-sdk/google": "4.0.105",
-    "@ai-sdk/groq": "4.0.70",
-    "@ai-sdk/huggingface": "2.0.78",
-    "@ai-sdk/moonshotai": "3.0.78",
-    "@ai-sdk/openai": "4.0.102",
+    "@ai-sdk/amazon-bedrock": "5.0.125",
+    "@ai-sdk/deepseek": "3.0.74",
+    "@ai-sdk/google": "4.0.106",
+    "@ai-sdk/groq": "4.0.71",
+    "@ai-sdk/huggingface": "2.0.79",
+    "@ai-sdk/moonshotai": "3.0.79",
+    "@ai-sdk/openai": "4.0.103",
     "@ai-sdk/test-server": "2.0.4",
-    "@ai-sdk/xai": "5.0.30",
+    "@ai-sdk/xai": "5.0.31",
     "@edge-runtime/vm": "^5.0.0",
     "@smithy/eventstream-codec": "^4.3.3",
     "@smithy/util-utf8": "^4.3.3",

package/src/agent/create-agent-ui-stream-response.ts

@@ -16,6 +16,7 @@ import {
   createAgentUIStream,
   type AgentUIMessageStreamOptions,
 } from './create-agent-ui-stream';
+import type { Steering } from '../generate-text/steering';
 
 /**
  * Runs the agent and returns a response object with a UI message stream.
@@ -26,6 +27,7 @@ import {
  * @param abortSignal - Abort signal. Optional.
  * @param timeout - Timeout in milliseconds. Optional.
  * @param experimental_sandbox - The sandbox environment that is passed through to tool execution. Optional.
+ * @param experimental_steering - A steering object that adds user messages to the run at the next step boundary. Only supported by `ToolLoopAgent`. Optional.
  * @param options - The options for the agent. Optional.
  * @param experimental_transform - Stream transformations. Optional.
  * @param onStepEnd - Callback that is called when each step ends. Optional.
@@ -70,6 +72,7 @@ export async function createAgentUIStreamResponse<
   abortSignal?: AbortSignal;
   timeout?: TimeoutConfiguration<TOOLS>;
   experimental_sandbox?: SandboxSession;
+  experimental_steering?: Steering;
   options?: CALL_OPTIONS;
   experimental_transform?: Arrayable<StreamTextTransform<TOOLS>>;
 } & UIMessageStreamResponseInit &

package/src/agent/create-agent-ui-stream.ts

@@ -28,7 +28,10 @@ import {
   createAsyncIterableStream,
   type AsyncIterableStream,
 } from '../util/async-iterable-stream';
+import { InvalidArgumentError } from '../error/invalid-argument-error';
+import type { Steering } from '../generate-text/steering';
 import type { Agent } from './agent';
+import { ToolLoopAgent } from './tool-loop-agent';
 
 /**
  * UI stream options with separate generation and UI message step callbacks.
@@ -56,6 +59,7 @@ export type AgentUIMessageStreamOptions<
  * @param abortSignal - The abort signal. Optional.
  * @param timeout - Timeout in milliseconds. Optional.
  * @param experimental_sandbox - The sandbox environment that is passed through to tool execution. Optional.
+ * @param experimental_steering - A steering object that adds user messages to the run at the next step boundary. Only supported by `ToolLoopAgent`. Optional.
  * @param options - The options for the agent.
  * @param experimental_transform - The stream transformations. Optional.
  * @param onStepEnd - Callback that is called when each step ends. Optional.
@@ -83,6 +87,7 @@ export async function createAgentUIStream<
   abortSignal,
   timeout,
   experimental_sandbox: sandbox,
+  experimental_steering: steering,
   experimental_transform,
   onStepEnd,
   onStepFinish,
@@ -101,12 +106,22 @@ export async function createAgentUIStream<
   abortSignal?: AbortSignal;
   timeout?: TimeoutConfiguration<TOOLS>;
   experimental_sandbox?: SandboxSession;
+  experimental_steering?: Steering;
   options?: CALL_OPTIONS;
   experimental_transform?: Arrayable<StreamTextTransform<TOOLS>>;
   // TODO `originalMessages` is part of this for bc, omit in v7
 } & AgentUIMessageStreamOptions<TOOLS, UI_MESSAGE>): Promise<
   AsyncIterableStream<InferUIMessageChunk<UI_MESSAGE>>
 > {
+  // other agents would ignore the steering object and never resolve its messages:
+  if (steering != null && !(agent instanceof ToolLoopAgent)) {
+    throw new InvalidArgumentError({
+      parameter: 'experimental_steering',
+      value: steering,
+      message: 'Steering is only supported by ToolLoopAgent.',
+    });
+  }
+
   const validatedMessages = await validateUIMessagesForAgent<UI_MESSAGE>({
     messages: uiMessages,
     // tools are compatible; the casting is required because the context param is
@@ -130,6 +145,7 @@ export async function createAgentUIStream<
     abortSignal,
     timeout,
     experimental_sandbox: sandbox,
+    experimental_steering: steering,
     experimental_transform,
     onStepEnd: onStepEnd ?? onStepFinish,
   });