useXChatConversation Data
useXChat
Conversation Data
Data management for single conversations.
Importimport { useXChat } from "@ant-design/x-sdk"; |
Sourcex-sdk/src/x-chat |
Docs |
Versionsupported since 2.0.0 |
Ant Design XImportimport { useXChat } from "@ant-design/x-sdk"; |
Sourcex-sdk/src/x-chat |
Docs |
Versionsupported since 2.0.0 |
Manage conversation data through Agent and produce data for page rendering.
type useXChat<ChatMessage extends SimpleType = object,ParsedMessage extends SimpleType = ChatMessage,Input = RequestParams<ChatMessage>,Output = SSEOutput,> = (config: XChatConfig<ChatMessage, ParsedMessage, Input, Output>) => XChatConfigReturnType;
AgentProvider uses the same Hook. The overload infers input, Chunk, and structured state types:
const { messages, agentState, onRequest, abort, isRequesting } = useXChat({ provider });
See Agent Provider for the complete contract and implementation guide.
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| ChatMessage | Message data type, defines the structure of chat messages | object | object | - |
| ParsedMessage | Parsed message type, message format for component consumption | ChatMessage | ChatMessage | - |
| Input | Request parameter type, defines the structure of request parameters | RequestParams<ChatMessage> | RequestParams<ChatMessage> | - |
| Output | Response data type, defines the format of received response data | SSEOutput | SSEOutput | - |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| provider | The only data entry. Use AbstractChatProvider for regular chat and AgentProvider for structured Agent streams. See Chat Provider and Agent Provider | AbstractChatProvider<ChatMessage, Input, Output> | AgentProvider<Input, Request, Chunk, Context> | - | - |
| conversationKey | Session unique identifier (globally unique), used to distinguish different sessions | string | Symbol('ConversationKey') | - |
| defaultMessages | Default display messages | MessageInfo<ChatMessage>[] | (info: { conversationKey?: string }) => MessageInfo<ChatMessage>[] | (info: { conversationKey?: string }) => Promise<MessageInfo<ChatMessage>[]> | - | - |
| parser | Converts ChatMessage into ParsedMessage for consumption. When not set, ChatMessage is consumed directly. Supports converting one ChatMessage into multiple ParsedMessages | (message: ChatMessage) => BubbleMessage | BubbleMessage[] | - | - |
| requestFallback | Fallback message for failed requests. When not provided, no message will be displayed | ChatMessage | (requestParams: Partial<Input>,info: { error: Error; errorInfo: any; messages: ChatMessage[], messageInfo: MessageInfo<ChatMessage> }) => ChatMessage|Promise<ChatMessage> | - | - |
| requestPlaceholder | Placeholder message during requests. When not provided, no message will be displayed | ChatMessage | (requestParams: Partial<Input>, info: { messages: Message[] }) => ChatMessage | Promise<Message> | - | - |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| abort | Cancel request | () => void | - | - |
| isRequesting | Whether a request is in progress | boolean | - | - |
| isDefaultMessagesRequesting | Whether the default message list is requesting | boolean | false | 2.2.0 |
| messages | Current managed message list content | MessageInfo<ChatMessage>[] | - | - |
| parsedMessages | Content translated through parser | MessageInfo<ParsedMessages>[] | - | - |
| onReload | Regenerate, will send request to backend and update the message with new returned data | (id: string | number, requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void | - | - |
| onRequest | Add a Message and trigger request | (requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void | - | - |
| setMessages | Directly modify messages without triggering requests | (messages: Partial<MessageInfo<ChatMessage>>[]) => void | - | - |
| setMessage | Directly modify a single message without triggering requests | (id: string | number, info: Partial<MessageInfo<ChatMessage>>) => void | - | - |
| removeMessage | Deleting a single message will not trigger a request | (id: string | number) => boolean | - | - |
| queueRequest | Will add the request to a queue, waiting for the conversationKey to be initialized before sending | (conversationKey: string | symbol, requestParams: Partial<Input>, opts?: { extraInfo: AnyObject }) => void | - | - |
| agentState | Complete structured state in AgentProvider mode; undefined in regular ChatProvider mode | AgentState | undefined | undefined | - |
AgentProvider mode accepts only provider, conversationKey, defaultMessages, and parser. requestPlaceholder and requestFallback belong to regular ChatProvider. Requesting, failure, and cancellation state in an Agent run are driven by standard events.
messages remains compatible with existing message components and contains AgentMessageState. Non-message data such as reasoning, tools, approvals, tasks, and artifacts is available from agentState.
setMessages, setMessage, and removeMessage only affect the compatibility message layer and do not directly mutate agentState. In AgentProvider mode, onReload starts a new Run.
interface MessageInfo<ChatMessage> {id: number | string;message: ChatMessage;status: MessageStatus;extraInfo?: AnyObject;}
type MessageStatus = 'local' | 'loading' | 'updating' | 'success' | 'error' | 'abort';
Use OpenAIChatProvider to integrate models with OpenAI data format, enabling message sending, data processing, and message termination.
Use DeepSeekChatProvider to integrate thinking models, enabling message sending, data processing, and message termination.
Connect local Runtime events to useXChat through a generic AgentProvider and render reasoning, tools, tasks, and artifacts directly inside chat bubbles. Start from a sample task, switch between successful and failed runs, or cancel an active run.
You can use defaultMessages to set historical messages.
Set defaultMessages as an asynchronous method to load historical messages during initialization.
You can use defaultMessages to set system prompts.
When working with Chat Provider, the XRequest callback can obtain the assembled Chat Message data.
Custom XRequest.fetch.
When using SDKs (such as openai-node, @openrouter/ai-sdk-provider) to request models or agents, you need to use the built-in Provider to handle data and customize the Request. Please refer to this example. Note: This example only demonstrates the logic for integrating openai using X SDK as a reference, and does not process model data. You need to fill in the correct apiKey for data debugging.
Integrate useXConversations and queueRequest to implement intelligent request queuing based on sessionId, ensuring messages are sent orderly by conversation and context remains accurate in multi-conversation scenarios.
Search and create a brief
Produce structured findings
