@assistant-ui/cloud-ai-sdk

Assistant Cloud AI SDK hooks for connecting cloud-backed threads, persistence, and chat state to assistant-ui React runtimes.

API Reference

useCloudChat

useCloudChat

options ?: UseCloudChatOptions

id ?: string

A unique identifier for the chat. If not provided, a random one will be generated.

messageMetadataSchema ?: FlexibleSchema<InferUIMessageMetadata<UI_MESSAGE>>

dataPartSchemas ?: UIDataTypesToSchemas<InferUIMessageData<UI_MESSAGE>>

messages ?: UI_MESSAGE[]

generateId ?: IdGenerator

A way to provide a function that is going to be used for ids for messages and the chat. If not provided the default AI SDK `generateId` is used.

transport ?: ChatTransport<UI_MESSAGE>

sendMessages : (options: { /** The type of message submission - either new message or regeneration */ trigger: 'submit-message' | 'regenerate-message'; /** Unique identifier for the chat session */ chatId: string; /** ID of the message to regenerate, or undefined for new messages */ messageId: string | undefined; /** Array of UI messages representing the conversation history */ messages: UI_MESSAGE[]; /** Signal to abort the request if needed */ abortSignal: AbortSignal | undefined; } & ChatRequestOptions) => Promise<ReadableStream<UIMessageChunk>>: Sends messages to the chat API endpoint and returns a streaming response. This method handles both new message submission and message regeneration. It supports real-time streaming of responses through UIMessageChunk events.
reconnectToStream : (options: { /** Unique identifier for the chat session to reconnect to */ chatId: string; } & ChatRequestOptions) => Promise<ReadableStream<UIMessageChunk> | null>: Reconnects to an existing streaming response for the specified chat session. This method is used to resume streaming when a connection is interrupted or when resuming a chat session. It's particularly useful for maintaining continuity in long-running conversations or recovering from network issues.

onError ?: ChatOnErrorCallback

Callback function to be called when an error is encountered.

onToolCall ?: ChatOnToolCallCallback<UI_MESSAGE>

Optional callback function that is invoked when a tool call is received. Intended for automatic client-side tool execution. You can optionally return a result for the tool call, either synchronously or asynchronously.

onFinish ?: ChatOnFinishCallback<UI_MESSAGE>

Function that is called when the assistant response has finished streaming.

onData ?: ChatOnDataCallback<UI_MESSAGE>

Optional callback function that is called when a data part is received.

sendAutomaticallyWhen

?: (options: {
        messages: UI_MESSAGE[];
    }) => boolean | PromiseLike<boolean>

When provided, this function will be called when the stream is finished or a tool call is added to determine if the current messages should be resubmitted.

threads ?: UseThreadsResult

cloud : AssistantCloud

threads : AssistantCloudThreads
auth : { tokens: AssistantCloudAuthTokens; }
runs : AssistantCloudRuns
files : AssistantCloudFiles
telemetry : AssistantCloudTelemetryConfig

threads : CloudThread[]

isLoading : boolean

error : Error | null

name : string
message : string
stack ?: string
cause ?: unknown

refresh : () => Promise<boolean>

get : (id: string) => Promise<CloudThread | null>

create : (options?: { externalId?: string }) => Promise<CloudThread | null>

delete : (id: string) => Promise<boolean>

rename : (id: string, title: string) => Promise<boolean>

archive : (id: string) => Promise<boolean>

unarchive : (id: string) => Promise<boolean>

threadId : string | null

selectThread : (id: string | null) => void

generateTitle : (threadId: string) => Promise<string | null>

cloud ?: AssistantCloud

threads : AssistantCloudThreads

messages : AssistantCloudThreadMessages
cloud : AssistantCloudAPI
list : (query?: AssistantCloudThreadsListQuery) => Promise<AssistantCloudThreadsListResponse>
get : (threadId: string) => Promise<CloudThread>
create : (body: AssistantCloudThreadsCreateBody) => Promise<AssistantCloudThreadsCreateResponse>
update : (threadId: string, body: AssistantCloudThreadsUpdateBody) => Promise<void>
delete : (threadId: string) => Promise<void>

auth : __object

tokens : AssistantCloudAuthTokens

runs : AssistantCloudRuns

cloud : AssistantCloudAPI
stream : (body: AssistantCloudRunsStreamBody) => Promise<AssistantStream>
report : (body: AssistantCloudRunReport) => Promise<{ run_id: string; }>

files : AssistantCloudFiles

cloud : AssistantCloudAPI
pdfToImages : (body: PdfToImagesRequestBody) => Promise<PdfToImagesResponse>
generatePresignedUploadUrl : (body: GeneratePresignedUploadUrlRequestBody) => Promise<GeneratePresignedUploadUrlResponse>

telemetry : AssistantCloudTelemetryConfig

enabled ?: boolean
beforeReport ?: ( report: AssistantCloudRunReport, ) => AssistantCloudRunReport | null: Called before each telemetry report is sent. Return a modified report to enrich it (e.g. add `model_id`), or return `null` to skip the report.

onSyncError ?: (error: Error) => void

useThreads

useThreads

options : UseThreadsOptions