---
title: pipeAgentUIStreamToResponse
description: API Reference for the pipeAgentUIStreamToResponse utility.
url: "https://ai-sdk.dev/docs/reference/ai-sdk-core/pipe-agent-ui-stream-to-response"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

The `pipeAgentUIStreamToResponse` function runs an [Agent](/docs/reference/ai-sdk-core/agent) and streams the resulting UI message output directly to a Node.js [`ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse) object. This is ideal for building real-time streaming API endpoints (for chat, tool use, etc.) in Node.js-based frameworks like Express, Hono, or custom Node servers.

## Import

```
import { pipeAgentUIStreamToResponse } from "ai"
```

## Usage

```ts
import { pipeAgentUIStreamToResponse } from 'ai';
import { MyAgent } from './agent';

export async function handler(req, res) {
  const { messages } = JSON.parse(req.body);

  await pipeAgentUIStreamToResponse({
    response: res, // Node.js ServerResponse
    agent: MyAgent,
    uiMessages: messages, // Required: array of input UI messages
    // abortSignal: optional AbortSignal for cancellation
    // experimental_sandbox: optional experimental sandbox passed through to tool execution
    // status: 200,
    // headers: { ... },
    // ...other optional UI message stream options
  });
}
```

## Parameters

- `response` (`ServerResponse`): The Node.js ServerResponse object to pipe UI message stream output into.
- `agent` (`Agent`): An agent instance implementing \`.stream(\{ prompt, ... })\` and defining a \`tools\` property.
- `uiMessages` (`unknown[]`): Array of input UI messages sent to the agent (such as user/assistant message objects).
- `convertDataPart` (`(part: DataUIPart) => TextPart | FilePart | undefined`): Converts custom UI data parts into text or file parts for the model. Data parts are ignored when this callback is omitted or returns undefined.
- `abortSignal` (`AbortSignal`): Optional abort signal to cancel streaming (e.g., on client disconnect). Supply an \[\`AbortSignal\`]\(https\://developer.mozilla.org/en-US/docs/Web/API/AbortSignal), for example from an \`AbortController\`.
- `timeout` (`number | { totalMs?: number }`): Timeout in milliseconds. Can be specified as a number or as an object with a totalMs property. The call will be aborted if it takes longer than the specified timeout. Can be used alongside abortSignal.
- `experimental_sandbox` (`Experimental_SandboxSession`): Optional experimental sandbox environment that is passed through to tool execution. Tools can access it from their execution context.
- `options` (`CALL_OPTIONS`): Optional agent call options, for agents configured with generic parameter \`CALL\_OPTIONS\`.
- `experimental_transform` (`StreamTextTransform | StreamTextTransform[]`): Optional stream text transformation(s) applied to agent output.
- `onStepEnd` (`GenerateTextOnStepEndCallback`): Callback invoked after each agent step (LLM/tool call) completes. Useful for tracking token usage, per-step performance, or logging intermediate steps.
- `onStepFinish` (`GenerateTextOnStepFinishCallback`): Deprecated. Use \`onStepEnd\` instead. This alias is only used as a fallback when \`onStepEnd\` is not provided.
- `onUIMessageStepEnd` (`UIMessageStreamOnStepEndCallback`): Callback invoked after each UI message step is assembled. It receives \`messages\`, \`isContinuation\`, and the accumulated \`responseMessage\` for intermediate persistence.
- `...UIMessageStreamResponseInit & AgentUIMessageStreamOptions` (`object`): Options for streaming headers, status, SSE stream config, and additional UI message stream control.

## Returns

A `Promise<void>`. The function completes when the UI message stream has been fully sent to the provided ServerResponse.

Use `onUIMessageStepEnd` to persist the accumulated UI response after every agent step. It is awaited before the corresponding `finish-step` chunk is piped. Use idempotent writes and protect model output, reasoning, tool inputs, and tool outputs as sensitive conversation data. Use the existing `onStepEnd` callback when you need low-level generation usage, finish reasons, or raw step details instead.

## Example: Express Route Handler

```ts
import { pipeAgentUIStreamToResponse } from 'ai';
import { openaiWebSearchAgent } from './openai-web-search-agent';

app.post('/chat', async (req, res) => {
  // Use req.body.messages as input UI messages
  await pipeAgentUIStreamToResponse({
    response: res,
    agent: openaiWebSearchAgent,
    uiMessages: req.body.messages,
    // experimental_sandbox, // optional
    // abortSignal: yourController.signal
    // status: 200,
    // headers: { ... },
    // ...more options
  });
});
```

## How It Works

1. **Runs the Agent:** Calls the agent’s `.stream` method with the provided UI messages and options, converting them into model messages as needed and passing through options such as `experimental_sandbox`.
2. **Streams UI Message Output:** Pipes the agent output as a UI message stream to the `ServerResponse`, sending data via streaming HTTP responses (including appropriate headers).
3. **Abort Signal Handling:** If `abortSignal` is supplied, streaming is cancelled as soon as the signal is triggered (such as on client disconnect).
4. **No Response Return:** Unlike Edge/serverless APIs that return a `Response`, this function writes bytes directly to the ServerResponse and does not return a response object.

## Notes

- **Abort Handling:** For best robustness, use an `AbortSignal` (for example, wired to Express/Hono client disconnects) to ensure quick cancellation of agent computation and streaming.
- **Node.js Only:** Only works with Node.js [ServerResponse](https://nodejs.org/api/http.html#class-httpserverresponse) objects (e.g., in Express, Hono’s node adapter, etc.), not Edge/serverless/web Response APIs.
- **Streaming Support:** Make sure your client (and any proxies) correctly support streaming HTTP responses for full effect.
- **Parameter Names:** The property for input messages is `uiMessages` (not `messages`) for consistency with SDK agent utilities.
- Pass `experimental_sandbox` when your agent tools need an experimental sandbox environment during execution.

## See Also

- [`createAgentUIStreamResponse`](/docs/reference/ai-sdk-core/create-agent-ui-stream-response)
- [`Agent`](/docs/reference/ai-sdk-core/agent)
- [`UIMessage`](/docs/reference/ai-sdk-core/ui-message)

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)