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

agent:

Agent

uiMessages:

unknown[]

abortSignal:

AbortSignal

timeout:

number | { totalMs?: number }

experimental_sandbox:

Experimental_SandboxSession

options:

CALL_OPTIONS

experimental_transform:

StreamTextTransform | StreamTextTransform[]

onStepEnd:

GenerateTextOnStepEndCallback

onStepFinish:

GenerateTextOnStepFinishCallback

...UIMessageStreamResponseInit & UIMessageStreamOptions:

object

Returns

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

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

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