feat(agent): support abortSignal in createAgentUIStream (#10518)

## Background

`abortSignal` has been added to `AgentCallParameters` but was not
exposed in the agent UI stream helpers.

## Summary

Forward `abortSignal`.

Author: lgrammel

.changeset/old-drinks-prove.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat(agent): support abortSignal in createAgentUIStream

content/docs/07-reference/01-ai-sdk-core/17-create-agent-ui-stream.mdx

@@ -22,10 +22,14 @@ const agent = new ToolLoopAgent({
   tools: { weather: weatherTool, calculator: calculatorTool },
 });
 
-export async function* streamAgent(messages: unknown[]) {
+export async function* streamAgent(
+  messages: unknown[],
+  abortSignal?: AbortSignal,
+) {
   const stream = await createAgentUIStream({
     agent,
     messages,
+    abortSignal,
     // ...other options
   });
 
@@ -53,6 +57,13 @@ export async function* streamAgent(messages: unknown[]) {
       description:
         'Array of input UI messages sent to the agent (e.g., from user/assistant).',
     },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isRequired: false,
+      description:
+        'Optional abort signal to cancel the agent streaming, e.g., in response to client disconnection.',
+    },
     {
       name: '...options',
       type: 'UIMessageStreamOptions',
@@ -72,30 +83,36 @@ A `Promise<AsyncIterableStream<UIMessageChunk>>`, where each yielded value is a
 ```ts
 import { createAgentUIStream } from 'ai';
 
+const controller = new AbortController();
+
 const stream = await createAgentUIStream({
   agent,
   messages: [{ role: 'user', content: 'What is the weather in SF today?' }],
+  abortSignal: controller.signal,
   sendStart: true,
 });
 
 for await (const chunk of stream) {
   // Process each UI message chunk (e.g., send to client)
   console.log(chunk);
 }
+
+// Call controller.abort() to stop streaming early if needed.
 ```
 
 ## How It Works
 
 1. **Message Validation:** The incoming array of `messages` is validated and normalized according to the agent's tools and requirements. Invalid messages will cause an error.
 2. **Model Message Conversion:** The validated UI messages are converted into the model message format the agent expects.
-3. **Agent Streaming:** The agent's `.stream({ prompt })` method is invoked to produce a low-level result stream.
+3. **Agent Streaming:** The agent's `.stream({ prompt, abortSignal })` method is invoked to produce a low-level result stream. If an `abortSignal` is provided and triggered, streaming will be canceled promptly.
 4. **UI Message Stream:** That result stream is exposed as a streaming async iterable of UI message chunks.
 
 ## Notes
 
 - The agent **must** define its `tools` and a `.stream({ prompt })` method.
 - This utility returns an async iterator for full streaming flexibility. To produce an HTTP response, see [`createAgentUIStreamResponse`](/docs/reference/ai-sdk-core/create-agent-ui-stream-response) or [`pipeAgentUIStreamToResponse`](/docs/reference/ai-sdk-core/pipe-agent-ui-stream-to-response).
 - You can provide UI message stream options (see [`UIMessageStreamOptions`](/docs/reference/ai-sdk-core/ui-message-stream-options)) for fine-grained control over the output.
+- To cancel a streaming agent operation, supply an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) via the `abortSignal` option.
 
 ## See Also
 

content/docs/07-reference/01-ai-sdk-core/18-create-agent-ui-stream-response.mdx

@@ -25,14 +25,18 @@ const agent = new ToolLoopAgent({
   tools: { weather: weatherTool, calculator: calculatorTool },
 });
 
+// Typical usage with streaming options
 export async function POST(request: Request) {
   const { messages } = await request.json();
 
-  // Stream agent response as an HTTP Response with UI messages
+  // Optional: Use abortSignal for cancellation support (client-side disconnects)
+  const abortController = new AbortController();
+
   return createAgentUIStreamResponse({
     agent,
     messages,
-    // ...other optional streaming options
+    abortSignal: abortController.signal, // optional
+    // ...other UIMessageStreamOptions like sendSources, includeUsage, experimental_transform, etc.
   });
 }
 ```
@@ -55,12 +59,19 @@ export async function POST(request: Request) {
       description:
         'Array of input UI messages sent to the agent (typically user and assistant message objects).',
     },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isRequired: false,
+      description:
+        'Optional abort signal to cancel streaming, e.g., when client disconnects. Useful for long-running or cancelable requests.',
+    },
     {
       name: '...options',
       type: 'UIMessageStreamOptions',
       isRequired: false,
       description:
-        'Additional options for customizing UI message streaming. For example, controlling source inclusion or stream behavior.',
+        'Additional UI message streaming options, such as `sendSources`, `includeUsage`, `experimental_transform`, etc. See [`UIMessageStreamOptions`](/docs/reference/ai-sdk-core/ui-message-stream-options) for details.',
     },
   ]}
 />
@@ -82,6 +93,8 @@ export async function POST(request: Request) {
     agent: MyCustomAgent,
     messages,
     sendSources: true, // optionally include sources in the UI message stream
+    includeUsage: true, // include token usage details if enabled by the agent
+    // Optionally, provide abortSignal for cancellation and other stream options
   });
 }
 ```
@@ -99,7 +112,7 @@ Under the hood, this function uses the internal `createAgentUIStream` utility an
 
 - The agent **must** define its `tools` and implement `.stream({ prompt })`.
 - **Do not use in the browser**; call this from backend/API/server code only.
-- You can provide additional UI message streaming options (see [`UIMessageStreamOptions`](/docs/reference/ai-sdk-core/ui-message-stream-options)) to customize the response.
+- You can provide additional UI message streaming options (see [`UIMessageStreamOptions`](/docs/reference/ai-sdk-core/ui-message-stream-options)) to customize the response, including experimental stream transforms.
 - The returned `Response` leverages [Readable Streams](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream). Make sure your client or framework can consume streamed HTTP responses.
 
 ## See Also

content/docs/07-reference/01-ai-sdk-core/18-pipe-agent-ui-stream-to-response.mdx

@@ -23,10 +23,14 @@ import { MyCustomAgent } from './agent';
 export async function handler(req, res) {
   const { messages } = JSON.parse(req.body);
 
+  // Optional: Use abortSignal for request cancellation support
+  const abortController = new AbortController();
+
   await pipeAgentUIStreamToResponse({
     response: res, // Node.js ServerResponse
     agent: MyCustomAgent,
     messages,
+    abortSignal: abortController.signal, // optional, see notes
     // ...other optional streaming options
   });
 }
@@ -57,6 +61,13 @@ export async function handler(req, res) {
       description:
         'Array of input UI messages sent to the agent (typically user and assistant message objects).',
     },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isRequired: false,
+      description:
+        'Optional abort signal to cancel streaming (e.g., when the client disconnects). Useful for enabling cancellation of long-running or streaming agent responses. Provide an instance of [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) (for example, from an `AbortController`).',
+    },
     {
       name: '...options',
       type: 'UIMessageStreamResponseInit & UIMessageStreamOptions',
@@ -77,14 +88,18 @@ A `Promise<void>`. This function returns a promise that resolves when piping the
 import { pipeAgentUIStreamToResponse } from 'ai';
 import { openaiWebSearchAgent } from './openai-web-search-agent';
 
-// Hono/Express handler signature
 app.post('/chat', async (req, res) => {
   const { messages } = await getJsonBody(req);
 
+  // Optionally use abortSignal for cancellation on disconnect, etc.
+  const abortController = new AbortController();
+  // e.g., tie abortController to request lifecycle/disconnect detection as needed
+
   await pipeAgentUIStreamToResponse({
     response: res,
     agent: openaiWebSearchAgent,
     messages,
+    abortSignal: abortController.signal, // optional
     // status: 200,
     // headers: { 'X-Custom': 'foo' },
     // ...additional streaming options
@@ -95,10 +110,12 @@ app.post('/chat', async (req, res) => {
 ## How It Works
 
 1. **Streams Output:** The function creates a UI message stream from the agent and efficiently pipes it to the provided Node.js `ServerResponse`, setting appropriate HTTP headers (including content type and streaming-friendly headers) and status.
-2. **No Response Object:** Unlike serverless `Response`-returning APIs, this function does _not_ return a Response object. It writes streaming bytes directly to the Node.js response. This is more memory- and latency-efficient for Node.js server frameworks.
+2. **Abort Support:** If you provide an `abortSignal`, you can cancel the streaming response (for example, when a client disconnects or a timeout occurs), improving resource usage and responsiveness.
+3. **No Response Object:** Unlike serverless `Response`-returning APIs, this function does _not_ return a Response object. It writes streaming bytes directly to the Node.js response. This is more memory- and latency-efficient for Node.js server frameworks.
 
 ## Notes
 
+- **abortSignal for Cancellation:** Use `abortSignal` to stop agent and stream processing early, improving robustness for long-running connections. In frameworks like Express or Hono, tie this to your server's disconnect or timeout events when possible.
 - **Only for Node.js:** This function is intended for use in Node.js environments with access to `ServerResponse` objects, not for Edge/serverless/server-side frameworks using web `Response` objects.
 - **Streaming Support:** Ensure your client and reverse proxy/server infrastructure support streaming HTTP responses.
 - Supports both Hono (`@hono/node-server`), Express, and similar Node.js frameworks.

packages/ai/src/agent/create-agent-ui-stream-response.ts

@@ -29,6 +29,7 @@ export async function createAgentUIStreamResponse<
 }: {
   agent: Agent<CALL_OPTIONS, TOOLS, OUTPUT>;
   messages: unknown[];
+  abortSignal?: AbortSignal;
   options?: CALL_OPTIONS;
   experimental_transform?:
     | StreamTextTransform<TOOLS>

packages/ai/src/agent/create-agent-ui-stream.ts

@@ -13,6 +13,9 @@ import { Agent } from './agent';
  *
  * @param agent - The agent to run.
  * @param messages - The input UI messages.
+ * @param abortSignal - The abort signal. Optional.
+ * @param options - The options for the agent.
+ * @param experimental_transform - The stream transformations. Optional.
  *
  * @returns The UI message stream.
  */
@@ -25,11 +28,13 @@ export async function createAgentUIStream<
   agent,
   messages,
   options,
+  abortSignal,
   experimental_transform,
   ...uiMessageStreamOptions
 }: {
   agent: Agent<CALL_OPTIONS, TOOLS, OUTPUT>;
   messages: unknown[];
+  abortSignal?: AbortSignal;
   options?: CALL_OPTIONS;
   experimental_transform?:
     | StreamTextTransform<TOOLS>
@@ -55,6 +60,7 @@ export async function createAgentUIStream<
   const result = await agent.stream({
     prompt: modelMessages,
     options: options as CALL_OPTIONS,
+    abortSignal,
     experimental_transform,
   });
 

packages/ai/src/agent/pipe-agent-ui-stream-to-response.ts

@@ -30,6 +30,7 @@ export async function pipeAgentUIStreamToResponse<
   response: ServerResponse;
   agent: Agent<CALL_OPTIONS, TOOLS, OUTPUT>;
   messages: unknown[];
+  abortSignal?: AbortSignal;
   options?: CALL_OPTIONS;
   experimental_transform?:
     | StreamTextTransform<TOOLS>