pipeAgentUIStreamToResponse

The pipeAgentUIStreamToResponse function runs an Agent and streams the resulting UI message output directly to a Node.js ServerResponse 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

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, 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

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

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.
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).
Abort Signal Handling: If abortSignal is supplied, streaming is cancelled as soon as the signal is triggered (such as on client disconnect).
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 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.