ai 7.0.153 → 7.0.154

package/docs/02-getting-started/02-nextjs-app-router.mdx

@@ -27,8 +27,8 @@ Start by creating a new Next.js application. This command will create a new dire
 <div className="mb-4">
   <Note>
     Be sure to select yes when prompted to use the App Router and Tailwind CSS.
-    If you are looking for the Next.js Pages Router quickstart guide, you can
-    find it [here](/docs/getting-started/nextjs-pages-router).
+    If you are adding the AI SDK to an existing Pages Router application, follow
+    the [Pages Router guide](/docs/getting-started/nextjs-pages-router).
   </Note>
 </div>
 

package/docs/02-getting-started/08-angular.mdx

@@ -0,0 +1,327 @@
+---
+title: Angular
+description: Learn how to build your first agent with the AI SDK and Angular.
+---
+
+# Angular Quickstart
+
+The AI SDK is a powerful TypeScript library designed to help developers build AI-powered applications.
+
+In this quickstart tutorial, you'll build a simple agent with a streaming chat user interface using Angular and an Express backend. Along the way, you'll learn key concepts and techniques that are fundamental to using the AI SDK in your own projects.
+
+If you are unfamiliar with the concepts of [Prompt Engineering](/docs/advanced/prompt-engineering) and [HTTP Streaming](/docs/foundations/streaming), you can optionally read these documents first.
+
+## Prerequisites
+
+To follow this quickstart, you'll need:
+
+- Node.js 24.15+ (or another [version supported by Angular](https://angular.dev/reference/versions)) and pnpm installed on your local development machine.
+- A [Vercel AI Gateway](https://vercel.com/ai-gateway) API key.
+
+If you haven't obtained your Vercel AI Gateway API key, you can do so by [signing up](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai&title=Go+to+AI+Gateway) on the Vercel website.
+
+## Set Up Your Application
+
+Create a new Angular application using the Angular CLI:
+
+<Snippet text="pnpm dlx @angular/cli@latest new my-ai-app --defaults --ssr=false --package-manager=pnpm" />
+
+This creates a standalone Angular application. This guide uses client-side rendering, with a separate Express server for the chat API.
+
+Navigate to the newly created directory:
+
+<Snippet text="cd my-ai-app" />
+
+### Install Dependencies
+
+Install `ai` and `@ai-sdk/angular`, the AI package and AI SDK's Angular bindings. You'll also install `express` for the backend, `dotenv` to load environment variables, and `zod` to define tool inputs.
+
+<InstallPackages packages="ai @ai-sdk/angular express dotenv zod" />
+
+Install the TypeScript runner and server type definitions:
+
+<InstallPackages packages="tsx @types/express @types/node" dev />
+
+<Note>
+  This guide uses the Vercel AI Gateway provider, which ships with the `ai`
+  package. You can access hundreds of models with one API key, or switch to
+  another [AI SDK provider](/providers/ai-sdk-providers).
+</Note>
+
+### Configure Your AI Gateway API Key
+
+Create a `.env` file in your project root:
+
+```env filename=".env"
+AI_GATEWAY_API_KEY=xxxxxxxxx
+```
+
+Replace `xxxxxxxxx` with your actual Vercel AI Gateway API key. The Express server loads this file using `dotenv`, and the AI SDK's Gateway provider reads `AI_GATEWAY_API_KEY` automatically. Keep the API key on the server and add `.env` to `.gitignore`.
+
+## Create an API Route
+
+Create `server.ts` in your project root and add the following code:
+
+```ts filename="server.ts"
+import {
+  streamText,
+  type UIMessage,
+  convertToModelMessages,
+  pipeUIMessageStreamToResponse,
+  toUIMessageStream,
+} from 'ai';
+__PROVIDER_IMPORT__;
+import 'dotenv/config';
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+app.post('/api/chat', async (req, res) => {
+  const { messages }: { messages: UIMessage[] } = req.body;
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+  });
+
+  await pipeUIMessageStreamToResponse({
+    response: res,
+    stream: toUIMessageStream({ stream: result.stream }),
+  });
+});
+
+app.listen(3000, '127.0.0.1', () => {
+  console.log('Chat API listening on http://127.0.0.1:3000');
+});
+```
+
+The server listens on `127.0.0.1` to keep the development API local to your machine. This creates a `POST /api/chat` endpoint. Let's take a look at what happens when it receives a request:
+
+1. `express.json()` parses the request body, which contains the conversation's `UIMessage` objects.
+2. [`convertToModelMessages`](/docs/reference/ai-sdk-ui/convert-to-model-messages) converts those UI messages to the format expected by the model.
+3. [`streamText`](/docs/reference/ai-sdk-core/stream-text) calls the model through AI Gateway.
+4. `toUIMessageStream` converts the model's output to the UI message stream format, and `pipeUIMessageStreamToResponse` writes it to the Express response as server-sent events.
+
+### Configure the Development Proxy
+
+Create `proxy.conf.json` in your project root:
+
+```json filename="proxy.conf.json"
+{
+  "/api/**": {
+    "target": "http://127.0.0.1:3000"
+  }
+}
+```
+
+When you start Angular with this proxy configuration, requests to `/api/chat` are forwarded to the Express server. The browser can use the relative `/api/chat` URL, which is also the default endpoint for the AI SDK's `Chat` class.
+
+<Note>
+  This proxy is for local development. When deploying, route `/api/chat` to your
+  backend, or configure a different API URL using
+  [`DefaultChatTransport`](/docs/ai-sdk-ui/transport).
+</Note>
+
+## Choosing a Provider
+
+The AI SDK supports dozens of model providers through [first-party](/providers/ai-sdk-providers), [OpenAI-compatible](/providers/openai-compatible-providers), and [community](/providers/community-providers) packages.
+
+This quickstart uses the [Vercel AI Gateway](https://vercel.com/ai-gateway) provider, which is the default [global provider](/docs/ai-sdk-core/provider-management#global-provider-configuration). You can select a model using a string in your server's configuration:
+
+```ts
+model: __MODEL__;
+```
+
+To use a provider directly, install its package and create a provider instance. Learn more about [provider management](/docs/ai-sdk-core/provider-management#global-provider-configuration).
+
+## Wire Up the UI
+
+The `@ai-sdk/angular` package provides a `Chat` class that manages messages, streams responses, and exposes the current request status. Its state is backed by Angular signals, so the template updates as new content arrives.
+
+Replace `src/app/app.ts` with the following component:
+
+```ts filename="src/app/app.ts"
+import { JsonPipe } from '@angular/common';
+import { Component, signal } from '@angular/core';
+import { Chat } from '@ai-sdk/angular';
+
+@Component({
+  selector: 'app-root',
+  imports: [JsonPipe],
+  template: `
+    <main>
+      @for (message of chat.messages; track message.id) {
+        <div>
+          <strong>{{ message.role === 'user' ? 'User' : 'AI' }}:</strong>
+          @for (part of message.parts; track $index) {
+            @if (part.type === 'text') {
+              <p style="white-space: pre-wrap">{{ part.text }}</p>
+            } @else if (part.type.startsWith('tool-')) {
+              <pre>{{ part | json }}</pre>
+            }
+          }
+        </div>
+      }
+
+      @if (chat.status === 'submitted') {
+        <p>Waiting for a response...</p>
+      }
+
+      @if (chat.error; as error) {
+        <p role="alert">{{ error.message }}</p>
+      }
+
+      <form (submit)="sendMessage($event)">
+        <label for="message">Your message</label>
+        <input
+          id="message"
+          #messageInput
+          [value]="input()"
+          (input)="input.set(messageInput.value)"
+        />
+        <button
+          type="submit"
+          [disabled]="
+            chat.status === 'submitted' || chat.status === 'streaming'
+          "
+        >
+          Send
+        </button>
+        @if (chat.status === 'submitted' || chat.status === 'streaming') {
+          <button type="button" (click)="chat.stop()">Stop</button>
+        }
+      </form>
+    </main>
+  `,
+})
+export class App {
+  readonly chat = new Chat({});
+  readonly input = signal('');
+
+  sendMessage(event: Event) {
+    event.preventDefault();
+    const text = this.input().trim();
+
+    if (
+      !text ||
+      this.chat.status === 'submitted' ||
+      this.chat.status === 'streaming'
+    ) {
+      return;
+    }
+
+    this.chat.sendMessage({ text });
+    this.input.set('');
+  }
+}
+```
+
+<Note>
+  Older Angular projects may name the root component file `app.component.ts` and
+  its class `AppComponent`. If you are using an existing project, keep its file
+  and class names so the imports in `src/main.ts` continue to work.
+</Note>
+
+The component creates one `Chat` instance and uses its reactive properties:
+
+- `messages` contains the conversation. Each message has a `role` and an ordered array of `parts`.
+- `sendMessage` sends a user message to `/api/chat` and streams the response into `messages`.
+- `status` indicates whether the chat is ready, submitted, streaming, or in an error state.
+- `error` contains the latest request error.
+- `stop` cancels the current response.
+
+Read these properties as `chat.messages`, `chat.status`, and `chat.error`; the `Chat` class manages the underlying signals. The input field uses a separate Angular signal, which is read with `input()`.
+
+The template renders text parts as they arrive and uses Angular's `JsonPipe` to display tool calls and results, which you'll add next.
+
+## Running Your Application
+
+In one terminal, start the Express backend from your project root:
+
+<Snippet text="pnpm exec tsx watch server.ts" />
+
+In a second terminal, start the Angular development server from the same directory:
+
+<Snippet text="pnpm exec ng serve --proxy-config proxy.conf.json" />
+
+Open [http://localhost:4200](http://localhost:4200), enter a message, and watch the response stream into the chat interface.
+
+<Note>
+  If you change `proxy.conf.json`, restart the Angular development server so it
+  picks up the new configuration.
+</Note>
+
+## Enhance Your Chatbot with Tools
+
+[Tools](/docs/ai-sdk-core/tools-and-tool-calling) let a model request actions such as looking up the weather. The server executes the action and returns the result to the model.
+
+Replace `server.ts` with the following code to add a weather tool:
+
+```ts filename="server.ts"
+import {
+  streamText,
+  type UIMessage,
+  convertToModelMessages,
+  pipeUIMessageStreamToResponse,
+  toUIMessageStream,
+  tool,
+  isStepCount,
+} from 'ai';
+__PROVIDER_IMPORT__;
+import 'dotenv/config';
+import express from 'express';
+import * as z4 from 'zod/v4';
+
+const app = express();
+app.use(express.json());
+
+app.post('/api/chat', async (req, res) => {
+  const { messages }: { messages: UIMessage[] } = req.body;
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+    stopWhen: isStepCount(5),
+    tools: {
+      weather: tool({
+        description: 'Get the weather in a location (fahrenheit)',
+        inputSchema: z4.object({
+          location: z4.string().describe('The location to get the weather for'),
+        }),
+        execute: async ({ location }) => {
+          const temperature = Math.round(Math.random() * (90 - 32) + 32);
+          return { location, temperature };
+        },
+      }),
+    },
+  });
+
+  await pipeUIMessageStreamToResponse({
+    response: res,
+    stream: toUIMessageStream({ stream: result.stream }),
+  });
+});
+
+app.listen(3000, '127.0.0.1', () => {
+  console.log('Chat API listening on http://127.0.0.1:3000');
+});
+```
+
+The `weather` tool has a description, an input schema, and an `execute` function. The model uses the description to decide when to call the tool and the schema to generate its input. The server then executes the function and returns its result.
+
+This example returns a simulated temperature. You can replace the function with a call to a weather API to return real data.
+
+### Enabling Multi-Step Tool Calls
+
+By default, a generation stops after one step. Setting `stopWhen: isStepCount(5)` allows the model to continue after receiving a tool result, for up to five steps. It can use the returned weather data to answer the original question.
+
+Ask "What's the weather in San Francisco?" in your chat interface. The template displays the `tool-weather` part as JSON, followed by the model's text response. No frontend changes are required: the `Chat` class already handles tool parts in the UI message stream.
+
+## Where to Go Next
+
+You've built an Angular chat interface that streams responses, calls tools, and uses their results in multi-step generations.
+
+- Explore the [Angular example](https://github.com/vercel/ai/tree/main/examples/angular) for chat, completion, and structured output examples.
+- Learn more about [AI SDK UI](/docs/ai-sdk-ui/overview) and [tools and tool calling](/docs/ai-sdk-core/tools-and-tool-calling).
+- Use the [transport API](/docs/ai-sdk-ui/transport) to connect your Angular frontend to an existing backend.

package/docs/02-getting-started/{03-nextjs-pages-router.mdx → 10-nextjs-pages-router.mdx}

@@ -1,40 +1,32 @@
 ---
 title: Next.js Pages Router
-description: Learn how to build your first agent with the AI SDK and Next.js Pages Router.
+description: Add an agent with a streaming chat interface to an existing Next.js Pages Router application.
 ---
 
-# Next.js Pages Router Quickstart
+# Next.js Pages Router Guide
 
-The AI SDK is a powerful TypeScript library designed to help developers build AI-powered applications.
+This guide shows how to add an agent with a streaming chat user interface to an existing Next.js Pages Router application.
 
-In this quickstart tutorial, you'll build a simple agent with a streaming chat user interface. Along the way, you'll learn key concepts and techniques that are fundamental to using the AI SDK in your own projects.
+<Note>
+  For new applications, we recommend the [Next.js App Router
+  quickstart](/docs/getting-started/nextjs-app-router).
+</Note>
 
 If you are unfamiliar with the concepts of [Prompt Engineering](/docs/advanced/prompt-engineering) and [HTTP Streaming](/docs/foundations/streaming), you can optionally read these documents first.
 
 ## Prerequisites
 
-To follow this quickstart, you'll need:
+To follow this guide, you'll need:
 
+- An existing Next.js 13+ application using the Pages Router.
 - Node.js 22+ and pnpm installed on your local development machine.
 - A [Vercel AI Gateway](https://vercel.com/ai-gateway) API key.
 
 If you haven't obtained your Vercel AI Gateway API key, you can do so by [signing up](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai&title=Go+to+AI+Gateway) on the Vercel website.
 
-## Setup Your Application
-
-Start by creating a new Next.js application. This command will create a new directory named `my-ai-app` and set up a basic Next.js application inside it.
-
-<Note>
-  Be sure to select no when prompted to use the App Router. If you are looking
-  for the Next.js App Router quickstart guide, you can find it
-  [here](/docs/getting-started/nextjs-app-router).
-</Note>
-
-<Snippet text="pnpm create next-app@latest my-ai-app" />
-
-Navigate to the newly created directory:
+## Set Up Your Application
 
-<Snippet text="cd my-ai-app" />
+Open a terminal in the root directory of your existing Next.js Pages Router application.
 
 ### Install dependencies
 
@@ -115,7 +107,7 @@ This Route Handler creates a POST request endpoint at `/api/chat`.
 
 The AI SDK supports dozens of model providers through [first-party](/providers/ai-sdk-providers), [OpenAI-compatible](/providers/openai-compatible-providers), and [community](/providers/community-providers) packages.
 
-This quickstart uses the [Vercel AI Gateway](https://vercel.com/ai-gateway) provider, which is the default [global provider](/docs/ai-sdk-core/provider-management#global-provider-configuration). This means you can access models using a simple string in the model configuration:
+This guide uses the [Vercel AI Gateway](https://vercel.com/ai-gateway) provider, which is the default [global provider](/docs/ai-sdk-core/provider-management#global-provider-configuration). This means you can access models using a simple string in the model configuration:
 
 ```ts
 model: __MODEL__;

package/docs/02-getting-started/index.mdx

@@ -9,6 +9,8 @@ The following guides are intended to provide you with an introduction to some of
 
 <QuickstartFrameworkCards />
 
+[Using an existing Next.js Pages Router app?](/docs/getting-started/nextjs-pages-router)
+
 ## Backend Framework Examples
 
 You can also use [AI SDK Core](/docs/ai-sdk-core/overview) and [AI SDK UI](/docs/ai-sdk-ui/overview) with the following backend frameworks:

package/docs/03-agents/01-overview.mdx

@@ -139,3 +139,4 @@ Agents are flexible and powerful, but non-deterministic. When you need reliable,
 - **[Runtime and Tool Context](/docs/ai-sdk-core/runtime-and-tool-context)** - How to pass shared agent state and per-tool context
 - **[Workflow Patterns](/docs/agents/workflows)** - Structured patterns using core functions for complex workflows
 - **[Loop Control](/docs/agents/loop-control)** - Execution control with stopWhen and prepareStep
+- **[Chat Platforms](/docs/agents/chat-platforms)** - Run agents in Slack, Microsoft Teams, Discord, and more with Chat SDK

package/docs/03-agents/04-loop-control.mdx

@@ -12,6 +12,8 @@ You can control both the execution flow and the settings at each step of the age
 - A tool call needs approval, or
 - A stop condition is met
 
+A [steering message](#steering) that is waiting when the model finishes its answer keeps the loop going for another step.
+
 The AI SDK provides built-in loop control through two parameters: `stopWhen` for defining stopping conditions and `prepareStep` for modifying settings (model, tools, messages, and more) between steps.
 
 ## Stop Conditions
@@ -402,6 +404,121 @@ Unlike `runtimeContext` and `toolsContext`, an experimental sandbox returned fro
 only applies to tool execution in that step. Later steps use the top-level
 `experimental_sandbox` unless they return their own experimental sandbox override.
 
+## Steering
+
+<Note type="warning">Steering is an experimental feature.</Note>
+
+Steering adds a user message to a running loop. Use it when a user sends a correction or a follow-up while the agent is still working. The message is added at the next step boundary, after the current step and its tool calls are done, so running tools are never interrupted.
+
+Create a steering object with `experimental_createSteering()`, pass it with the `experimental_steering` option, and call `steer()` while the loop is running:
+
+```ts
+import { experimental_createSteering, isStepCount, streamText } from 'ai';
+
+const steering = experimental_createSteering();
+
+const result = streamText({
+  model: __MODEL__,
+  tools: { weather },
+  stopWhen: isStepCount(10),
+  prompt: 'What is the weather in Paris?',
+  experimental_steering: steering,
+});
+
+// e.g. when the user sends another message while the agent is running:
+const outcome = await steering.steer('I meant Paris, Texas.');
+```
+
+Steering works the same way with `generateText` and `ToolLoopAgent`, because you create the steering object before the call starts:
+
+```ts
+const steering = experimental_createSteering();
+
+const run = agent.generate({
+  prompt: 'What is the weather in Paris?',
+  experimental_steering: steering,
+});
+
+await steering.steer('I meant Paris, Texas.');
+
+const result = await run;
+```
+
+### How Steering Messages Are Delivered
+
+- Messages are added in the order they are sent. Each message is its own user message.
+- If the model finishes its answer while a message is waiting, the loop continues for another step.
+- Stop conditions still apply. `generateText` and `streamText` stop after one step by default, so set `stopWhen` to steer them. Agents run up to 20 steps by default.
+- Messages that are sent before the loop starts are added to the first step.
+- `prepareStep` and `onStepStart` receive the steering messages as part of `messages`.
+- A steering object can only be used for one call. Create a new one with `experimental_createSteering()` for each call.
+- For agents, steering is supported by `ToolLoopAgent`. `createAgentUIStream` throws when it gets a steering object with another agent.
+
+<Note type="warning">
+  `messages` already contains the steering messages in the right place. If
+  `prepareStep` returns a `messages` override that is rebuilt from other fields,
+  e.g. `initialMessages` and `responseMessages`, the steering messages are
+  dropped and `steer()` reports them as not delivered with the reason
+  `removed-by-prepare-step`. Build overrides from `messages`, or add the
+  steering messages of every step back in order.
+</Note>
+
+```ts
+prepareStep: ({ initialMessages, steps, experimental_steeringMessages }) => ({
+  messages: [
+    ...initialMessages,
+    ...steps.flatMap(step => [
+      ...(step.experimental_steeringMessages ?? []),
+      ...step.response.messages,
+    ]),
+    // steering messages for the current step:
+    ...(experimental_steeringMessages ?? []),
+  ],
+}),
+```
+
+### Handling the Outcome
+
+`steer()` resolves with the outcome of the message and never rejects:
+
+```ts
+const outcome = await steering.steer('I meant Paris, Texas.', {
+  id: messageId,
+});
+
+if (outcome.type === 'delivered') {
+  console.log(`added to step ${outcome.stepNumber}`);
+} else {
+  // the message was not added, e.g. send it as a new message instead:
+  console.log(outcome.reason, outcome.message);
+}
+```
+
+A message is delivered when it is part of the messages that are sent to the model, after `prepareStep`. It is not delivered when the loop ends before the next step boundary, or when `prepareStep` removes it. The `reason` is one of:
+
+- `finished`: the loop ended before the message could be added.
+- `removed-by-prepare-step`: `prepareStep` returned messages without it.
+- `stop-condition`: a stop condition ended the loop.
+- `waiting-for-tool-results`: the loop ended to wait for tool results, e.g. a [tool approval](/docs/agents/tool-approvals).
+- `aborted`: the loop was aborted.
+- `error`: the loop failed.
+
+Pass an `id` to make retries safe. Sending a message again with the same `id` returns the outcome of the first message.
+
+### Saving Steering Messages
+
+Steering messages are not part of `responseMessages`. Each step lists the steering messages that were added to it in `experimental_steeringMessages`, so you can rebuild the full conversation in order:
+
+```ts
+const messages = [
+  ...initialMessages,
+  ...result.steps.flatMap(step => [
+    ...(step.experimental_steeringMessages ?? []),
+    ...step.response.messages,
+  ]),
+];
+```
+
 ## Access Step Information
 
 Both `stopWhen` and `prepareStep` receive detailed information about the current execution:

package/docs/03-agents/06-tool-approvals.mdx

@@ -352,3 +352,4 @@ Every serverless instance that might handle a request needs the same secret, sin
 - Author approval rules as code with [Policy-Based Tool Approvals](/docs/agents/policy-tool-approvals) (`@ai-sdk/policy-opa`).
 - Use `needsApproval` only with [`WorkflowAgent`](/docs/agents/workflow-agent), where approvals suspend and resume durable workflow execution.
 - Subagent tools cannot use `toolApproval`; see [Subagents](/docs/agents/subagents#no-tool-approvals-in-subagents).
+- Chat SDK's `createChatTools` marks its write tools and `getUser` as needing approval. A `toolApproval` rule overrides those defaults; see [Chat Platforms](/docs/agents/chat-platforms#give-the-agent-chat-tools).