@assistant-ui/react-data-stream

Hooks for connecting to data stream protocol endpoints and Assistant Cloud.

Data Stream protocol integration for assistant-ui.

API Reference

`useDataStreamRuntime`

Create a runtime that connects to a data stream protocol endpoint.

import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const runtime = useDataStreamRuntime({
    api: "/api/chat",
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};

api?: string

The API endpoint URL for the data stream protocol.

onResponse?: (response: Response) => void | Promise<void>

Optional callback called when a response is received.

onFinish?: (message: ThreadMessage) => void

Optional callback called when a message is finished.

onError?: (error: Error) => void

Optional callback called when an error occurs.

onCancel?: () => void

Optional callback called when a request is cancelled.

credentials?: RequestCredentials

Optional credentials mode for the fetch request.

headers?: Record<string, string> | Headers | (() => Promise<Record<string, string> | Headers>)

Optional headers to include in the request.

body?: object

Optional additional body parameters to include in the request.

sendExtraMessageFields?: boolean

Whether to include extra message fields like IDs in the request.

`useCloudRuntime`

Create a runtime that connects to Assistant Cloud using the data stream protocol.

import { useCloudRuntime } from "@assistant-ui/react-data-stream";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const runtime = useCloudRuntime({
    cloud: assistantCloud,
    assistantId: "my-assistant-id",
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};

cloud?: AssistantCloud

The Assistant Cloud instance.

assistantId?: string

The ID of the assistant to connect to.

onResponse?: (response: Response) => void | Promise<void>

Optional callback called when a response is received.

onFinish?: (message: ThreadMessage) => void

Optional callback called when a message is finished.

onError?: (error: Error) => void

Optional callback called when an error occurs.

onCancel?: () => void

Optional callback called when a request is cancelled.

credentials?: RequestCredentials

Optional credentials mode for the fetch request.

headers?: Record<string, string> | Headers | (() => Promise<Record<string, string> | Headers>)

Optional headers to include in the request.

body?: object

Optional additional body parameters to include in the request.

sendExtraMessageFields?: boolean

Whether to include extra message fields like IDs in the request.

`toLanguageModelMessages`

Convert assistant-ui messages to AI SDK's LanguageModelV2Message format.

For custom integrations, consider using toGenericMessages from assistant-stream instead. This function is specific to the AI SDK format.

import { toLanguageModelMessages } from "@assistant-ui/react-data-stream";

const languageModelMessages = toLanguageModelMessages(messages, {
  unstable_includeId: true,
});

messages?: readonly ThreadMessage[]

The messages to convert.

options?: { unstable_includeId?: boolean }

Optional conversion options.

{ unstable_includeId?: boolean }

unstable_includeId?: boolean

Whether to include message IDs in the converted messages.

Framework-Agnostic Utilities

For custom integrations that don't use the AI SDK, use these utilities from assistant-stream:

`toGenericMessages`

Convert thread messages to a framework-agnostic format.

import { toGenericMessages } from "assistant-stream";

const genericMessages = toGenericMessages(messages);

Returns an array of GenericMessage which can be one of:

{ role: "system"; content: string }
{ role: "user"; content: (GenericTextPart | GenericFilePart)[] }
{ role: "assistant"; content: (GenericTextPart | GenericToolCallPart)[] }
{ role: "tool"; content: GenericToolResultPart[] }

`toToolsJSONSchema`

Convert tool definitions to JSON Schema format.

import { toToolsJSONSchema } from "assistant-stream";

const toolSchemas = toToolsJSONSchema(tools);
// Returns: Record<string, { description?: string; parameters: JSONSchema7 }>

By default, filters out disabled tools and backend-only tools. Use the filter option to customize:

const allTools = toToolsJSONSchema(tools, {
  filter: () => true, // Include all tools
});