createUIMessageStream

The createUIMessageStream function allows you to create a readable stream for UI messages with advanced features like message merging, error handling, and finish callbacks.

Import

import { createUIMessageStream } from "ai"

Example

const existingMessages: UIMessage[] = [
  /* ... */
];

const stream = createUIMessageStream({
  async execute({ writer }) {
    // Start a text message
    // Note: The id must be consistent across text-start, text-delta, and text-end steps
    // This allows the system to correctly identify they belong to the same text block
    writer.write({
      type: 'text-start',
      id: 'example-text',
    });

    // Write a message chunk
    writer.write({
      type: 'text-delta',
      id: 'example-text',
      delta: 'Hello',
    });

    // End the text message
    writer.write({
      type: 'text-end',
      id: 'example-text',
    });

    // Merge another stream from streamText
    const result = streamText({
      model: "anthropic/claude-sonnet-5.5",
      prompt: 'Write a haiku about AI',
    });

    writer.merge(
      result.toUIMessageStream({
        onFinish: ({ outcome }) => {
          // The composer decides that the model stream outcome is also the
          // aggregate stream outcome.
          writer.setOutcome(outcome);
        },
      }),
    );
  },
  onError: error => `Custom error: ${error.message}`,
  originalMessages: existingMessages,
  onFinish: ({ messages, isContinuation, outcome, responseMessage }) => {
    console.log('Stream finished with messages:', messages);
    console.log('Stream outcome:', outcome.status);
  },
});

setOutcome records the composer's policy without writing a chunk or closing the stream. The first outcome declared through setOutcome is retained, but a fatal execution, merge, error-handling, or downstream processing failure makes the final onFinish outcome failed. Individual error chunks do not change the outcome by themselves. When merging multiple child streams, aggregate their outcomes and call setOutcome once.

API Signature

Parameters

execute:

(options: { writer: UIMessageStreamWriterWithOutcome }) => Promise<void> | void

A function that receives a writer instance and can use it to write UI message chunks to the stream.

UIMessageStreamWriterWithOutcome

write:

(part: UIMessageChunk) => void

Writes a UI message chunk to the stream.

merge:

(stream: ReadableStream<UIMessageChunk>) => void

Merges the contents of another UI message stream into this stream.

setOutcome:

(outcome: UIMessageStreamOutcome) => void

Declares the operation-level outcome of the composed stream. The first outcome declared through this method is retained, while fatal execution, merge, error-handling, or downstream processing failures override declarations. Supported statuses are 'completed', 'failed', 'aborted', and 'unknown'. Declaring an outcome does not write a chunk or close the stream.