TDesign React Chat

https://tdesign.tencent.com/react-chat
Admin
TDesign React Chat is a React component library for building AI chat interfaces with support for...
Tokens:48,307
Snippets:325
Trust Score:10
Update:8 months ago
Show doc for...
Tokens:
Raw
### Initialize ChatEngine with useChat Hook

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=api

Demonstrates the basic usage of the useChat Hook to create a chat engine and combine components to build a chat interface. This is the quickest way to get started.

```javascript
import {
  useChat,
  ChatBubble,
  ChatInput,
  ChatWindow,
} from '@tdesign/react-chat-engine';

function MyChatComponent() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    // ... other configurations
  });

  return (
    <ChatWindow>
      {messages.map((msg, index) => (
        <ChatBubble key={index} message={msg} />
      ))}
      <ChatInput value={input} onChange={handleInputChange} onSubmit={handleSubmit} />
    </ChatWindow>
  );
}
```

--------------------------------

### Install TDesign React Chat with pnpm

Source: https://tdesign.tencent.com/react-chat/index

Install the TDesign React Chat component using pnpm. This command adds the package to your project's dependencies.

```bash
pnpm add @tdesign-react/chat
```

--------------------------------

### Full Event Stream Example

Source: https://tdesign.tencent.com/react-chat/agui

An example demonstrating a complete event flow for a travel planning Agent, showcasing the collaboration of various event types.

```APIDOC
## Full Event Stream Example

### Description
This is a complete event stream example for a travel planning Agent, illustrating the interaction of different event types.

### Method
N/A (SSE Stream)

### Endpoint
N/A (SSE Stream)

### Parameters
N/A

### Request Example
```json
// 1. Run start
{
  "type": "RUN_STARTED",
  "threadId": "t1",
  "runId": "r1"
}

// 2. Initial state
{
  "type": "STATE_SNAPSHOT",
  "snapshot": {
    "plan_task": {
      "progress": 0,
      "steps": []
    }
  }
}

// 3. Start of reply
{
  "type": "TEXT_MESSAGE_START",
  "messageId": "m1",
  "role": "assistant"
}
{
  "type": "TEXT_MESSAGE_CONTENT",
  "messageId": "m1",
  "delta": "好的，我来帮您规划行程..."
}
{
  "type": "TEXT_MESSAGE_END",
  "messageId": "m1"
}

// 4. Calling weather tool
{
  "type": "TOOL_CALL_START",
  "toolCallId": "tc1",
  "toolCallName": "get_weather"
}
{
  "type": "TOOL_CALL_ARGS",
  "toolCallId": "tc1",
  "delta": "{\"city\": \"北京\"}"
}
{
  "type": "TOOL_CALL_END",
  "toolCallId": "tc1"
}
{
  "type": "TOOL_CALL_RESULT",
  "toolCallId": "tc1",
  "content": "{\"temp\": 25}"
}

// 5. Updating state progress
{
  "type": "STATE_DELTA",
  "delta": [
    {"op": "replace", "path": "/plan_task/progress", "value": 50}
  ]
}

// 6. Displaying real-time data (Activity)
{
  "type": "ACTIVITY_SNAPSHOT",
  "messageId": "a1",
  "activityType": "stock-chart",
  "content": {
    "title": "相关股票",
    "data": []
  }
}
{
  "type": "ACTIVITY_DELTA",
  "messageId": "a1",
  "activityType": "stock-chart",
  "patch": [
    {"op": "add", "path": "/data/-", "value": {"price": 100}}
  ]
}

// 7. Collecting user preferences (Human-in-the-Loop)
{
  "type": "TOOL_CALL_START",
  "toolCallId": "tc2",
  "toolCallName": "collect_preferences"
}
{
  "type": "TOOL_CALL_ARGS",
  "toolCallId": "tc2",
  "delta": "{\"options\": [\"经济型\", \"舒适型\"]}"
}
{
  "type": "TOOL_CALL_END",
  "toolCallId": "tc2"
}
// Waiting for user response...

// 8. Continuing after user response
{
  "type": "TOOL_CALL_RESULT",
  "toolCallId": "tc2",
  "content": "{\"choice\": \"舒适型\"}"
}

// 9. Final reply
{
  "type": "TEXT_MESSAGE_START",
  "messageId": "m2",
  "role": "assistant"
}
{
  "type": "TEXT_MESSAGE_CONTENT",
  "messageId": "m2",
  "delta": "根据您的偏好，推荐以下行程..."
}
{
  "type": "TEXT_MESSAGE_END",
  "messageId": "m2"
}

// 10. Run finished
{
  "type": "RUN_FINISHED",
  "threadId": "t1",
  "runId": "r1"
}
```

### Response
#### Success Response (200)
N/A (SSE Stream)

#### Response Example
N/A (SSE Stream)
```

--------------------------------

### Install TDesign React Chat with yarn

Source: https://tdesign.tencent.com/react-chat/index

Install the TDesign React Chat component using yarn. This command adds the package to your project's dependencies.

```bash
yarn add @tdesign-react/chat
```

--------------------------------

### Headless Event Bus Example (JavaScript)

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Illustrates the usage of ChatEngine's built-in EventBus for event distribution in headless scenarios. This is useful for logging, cross-component communication, and external system integration.

```javascript
import { ChatEngine } from '@//tdesign/react-chat';

const engine = new ChatEngine();

// Subscribe to an event
engine.on('customEvent', (payload) => {
  console.log('Custom event received:', payload);
});

// Publish an event
engine.emit('customEvent', { message: 'Hello from EventBus!' });

// Example of engine state events
engine.on('engineStateChange', (state) => {
  console.log('Engine state:', state);
});

// Initialize engine
engine.init();

// Send message
engine.sendMessage('Test message');

// Destroy engine
// engine.destroy();
```

--------------------------------

### ChatEngine Event Bus Example

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=api

Demonstrates the built-in EventBus for headless scenarios, useful for logging, cross-component communication, and external system integration. It shows how to initialize the engine, send messages, and view event logs.

```javascript
import {
  useChat,
  ChatEngineEventBus,
} from '@tdesign/react-chat-engine';

const { 
  initEngine,
  sendMessage,
  abortRequest,
  clearMessages,
  destroyEngine,
  onComplete,
  emitCustomEvent,
  getEventHistory
} = useChat();

// Example of initializing and emitting an event
initEngine();
emitCustomEvent('my-custom-event', { detail: 'some data' });

// To view event history:
// const history = getEventHistory();
// console.log(history);
```

--------------------------------

### Install TDesign React Chat with npm

Source: https://tdesign.tencent.com/react-chat/index

Install the TDesign React Chat component using npm. This is the standard way to add the package to your project's dependencies.

```bash
npm install @tdesign-react/chat
```

--------------------------------

### Python FastAPI 实现 Server-Sent Events (SSE)

Source: https://tdesign.tencent.com/react-chat/sse

使用 FastAPI 和 sse-starlette 库创建一个支持 SSE 的流式接口。该接口通过异步生成器每秒发送一个包含计数器的数据对象。支持 GET 和 POST 请求。需要安装 fastapi 和 uvicorn。

```python
import json
import asyncio
from fastapi import FastAPI
from sse_starlette.sse import EventSourceResponse
import uvicorn
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()
app.add_middleware(
    CORSMiddleware,
    allow_origins=['*'], # 设置允许跨域的域名列表，* 代表所有域名
    allow_credentials=True,
    allow_methods=['*'],
    allow_headers=['*'],
)
async def event_generator():
    count = 0
    while True:
        await asyncio.sleep(1)
        count += 1
        data = {"count": count}
        yield json.dumps(data)

@app.get("/events")
async def get_events():
    return EventSourceResponse(event_generator())
@app.post("/events")
async def post_events():
      return EventSourceResponse(event_generator())

if __name__ == '__main__':
    uvicorn.run(app, host='0.0.0.0', port=4000)

```

--------------------------------

### AG-UI Protocol SSE Data Example

Source: https://tdesign.tencent.com/react-chat/index

Example of SSE data format adhering to the AG-UI protocol. This protocol standardizes interaction with AI agents, supporting features like tool calls and status management.

```text
// 符合AG-UI协议的后端接口（/api/agui/chat）返回案例
data: {"type": "RUN_STARTED", "runId": "run_456"}
data: {"type": "TEXT_MESSAGE_CONTENT", "delta": "正在处理您的请求..."}
data: {"type": "TOOL_CALL_START", "toolCallName": "search"}
data: {"type": "TOOL_CALL_RESULT", "content": "查询结果"}
data: {"type": "RUN_FINISHED", "runId": "run_456"}
```

--------------------------------

### Custom Protocol SSE Data Example

Source: https://tdesign.tencent.com/react-chat/index

Example of SSE data format for the custom protocol. The backend service returns data in standard SSE format, which the frontend can parse using the onMessage callback.

```text
// 自定义后端接口（/api/chat）返回案例
data: {"type": "think", "content": "正在分析您的问题..."}
data: {"type": "text", "content": "我是**腾讯云**助手"}
data: {"type": "text", "content": "很高兴为您服务！"}
```

--------------------------------

### AG-UI Backend: Correct Lifecycle Event Output

Source: https://tdesign.tencent.com/react-chat/agui

Demonstrates the correct way to emit AG-UI lifecycle events for an Agent run. It must start with RUN_STARTED and end with either RUN_FINISHED or RUN_ERROR. Intermediate events like TEXT_MESSAGE_* should be correctly sequenced.

```json
// ✅ 正确：完整的生命周期
data: {"type": "RUN_STARTED", "threadId": "thread_1", "runId": "run_1"}
data: {"type": "TEXT_MESSAGE_START", "messageId": "msg_1", "role": "assistant"}
data: {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "你好！"}
data: {"type": "TEXT_MESSAGE_END", "messageId": "msg_1"}
data: {"type": "RUN_FINISHED", "threadId": "thread_1", "runId": "run_1"}

// ❌ 错误：缺少 RUN_STARTED 或 RUN_FINISHED
data: {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "你好！"}
```

--------------------------------

### Control ChatEngine with Instance Methods

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=api

Demonstrates how to use instance methods provided by `useChat` to control component behavior, such as sending messages, managing the conversation, and regenerating responses. These methods offer programmatic control over the chat interface.

```javascript
import {
  useChat,
} from '@tdesign/react-chat-chat-engine';

const { 
  sendMessage,
  sendAIMessage,
  sendSystemMessage,
  setMessages,
  clearMessages,
  regenerateResponse,
  abortRequest,
  fillPrompt,
  getStatus
} = useChat();

// Example usage:
// sendMessage('Hello from user!');
// sendAIMessage('AI response example.');
// setMessages([{ type: 'text', content: { text: 'Initial message' }, role: 'user' }]);
// clearMessages();
// regenerateResponse();
// abortRequest();
// fillPrompt('This is a prompt.');
// const currentStatus = getStatus();
```

--------------------------------

### Control ChatEngine with Instance Methods (React)

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Demonstrates how to use instance methods provided by the useChat hook to control component behavior, such as sending messages, managing history, and regenerating responses. These methods offer programmatic control over the chat engine.

```javascript
import {
  useChat,
  type ChatMessage,
  type UseChatOptions
} from '@//tdesign/react-chat';

const options: UseChatOptions = {};
const { 
  messages,
  sendMessage,
  sendAIResponse,
  sendSystemMessage,
  setMessages,
  clearMessages,
  regenerateResponse,
  abortRequest,
  fillPrompt,
  getStatus
} = useChat(options);

// Example usage:
sendMessage('Hello from instance method!');
regenerateResponse();
abortRequest();
const currentStatus = getStatus();
```

--------------------------------

### Chatbot Instance Methods

Source: https://tdesign.tencent.com/react-chat/components/chatbot_tab=api

Methods available on the Chatbot component instance for managing chat functionality.

```APIDOC
## Chatbot Instance Methods

### Description
Methods available on the Chatbot component instance for managing chat functionality, such as setting messages, sending user or AI messages, and controlling the chat flow.

### Method
Various (void, Promise<void>, void, void, void, void, void, void, void, void)

### Endpoint
N/A (Instance Methods)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "N/A for instance methods"
}
```

### Response
#### Success Response (200)
N/A (Instance Methods)

#### Response Example
```json
{
  "example": "N/A for instance methods"
}
```

### Methods List:

- **setMessages** `(messages: ChatMessagesData[], mode?: 'replace' | 'prepend' | 'append') => void`
  - Description: Batch set messages.

- **sendUserMessage** `(params: ChatRequestParams) => Promise<void>`
  - Description: Send user message, process request parameters and trigger message stream.

- **sendAIMessage** `{ params?: ChatRequestParams; content?: AIMessageContent[]; sendRequest?: boolean }`
  - Description: Send AI message, process request parameters and trigger message stream.

- **sendSystemMessage** `(msg: string) => void`
  - Description: Send system-level notification message, used to display system prompts/warnings.

- **abortChat** `() => Promise<void>`
  - Description: Abort the current ongoing chat request, clean up network connection.

- **addPrompt** `(prompt: string) => void`
  - Description: Add preset prompt to the input box to assist users in quick input.

- **selectFile** `() => void`
  - Description: Trigger file selection dialog for attachment upload function.

- **regenerate** `(keepVersion?: boolean) => Promise<void>`
  - Description: Regenerate the last message, optionally keep the history version.

- **registerMergeStrategy** `(type: T['type'], handler: (chunk: T, existing?: T) => T) => void`
  - Description: Register custom message merge strategy for handling streaming data updates.

- **scrollList** `({ to: 'bottom' | 'top', behavior: 'auto' | 'smooth' }) => void`
  - Description: Controlled scroll to the specified position.
```

--------------------------------

### useChat State Management

Source: https://tdesign.tencent.com/react-chat/components/chat-engine

Hook for managing chat state, providing access to state mapping, current state, and methods to set or get state.

```APIDOC
## useChat State Management

### Description
Provides state management capabilities for chat functionalities.

### Method
`useChat()`

### Returns
- **stateMap** (Record<string, any>) - A mapping of states.
- **currentStateKey** (string | null) - The key of the currently active state.
- **setStateMap** ((stateMap: Record<string, any> | Function) => void) - Function to manually set the state map.
- **getCurrentState** (() => Record<string, any>) - Function to get the complete current state.
- **getStateByKey** ((key: string) => any) - Function to get the state for a specific key.
```

--------------------------------

### Initialize Messages in ChatEngine (React)

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Shows how to set static initial messages or dynamically load historical messages using ChatEngine's configuration. This is useful for pre-populating the chat or loading conversation history.

```javascript
import {
  useChat,
  type ChatMessage,
  type UseChatOptions
} from '@//tdesign/react-chat';

const initialMessages: ChatMessage[] = [
  { id: '1', role: 'user', content: 'Hello!' },
  { id: '2', role: 'assistant', content: 'Hi there!' },
];

const options: UseChatOptions = {
  initialMessages: initialMessages,
  // or for dynamic loading:
  // onRequestHistory: async () => {
  //   const history = await fetch('/api/history');
  //   return history.json();
  // },
};

const { messages, ... } = useChat(options);
```

--------------------------------

### Minimal ChatBot Component Integration

Source: https://tdesign.tencent.com/react-chat/index

Integrate the ChatBot component for a quick setup of a standard chat interface. It requires minimal configuration and provides built-in features like message sending, markdown parsing, and auto-scrolling.

```jsx
import React from 'react';
import { ChatBot } from '@tdesign-react/chat';
import '@tdesign-react/chat/es/style/index.js'; // 少量公共样式

export default function () {
  // 聊天服务配置
  const chatServiceConfig = {
    // 对话服务地址
    endpoint: `https://1257786608-9i9j1kpa67.ap-guangzhou.tencentscf.com/sse/normal`,
    // 开启流式对话传输
    stream: true,
    // 自定义流式数据结构解析
    onMessage: (chunk) => chunk.data,
  };

  return <ChatBot chatServiceConfig={chatServiceConfig} />;
}
```

--------------------------------

### ChatEngine Instance Methods

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Provides methods for interacting with the chat engine, including event handling, message management, and request control.

```APIDOC
## ChatEngine Instance Methods

### Description
Provides methods for interacting with the chat engine, including event handling, message management, and request control.

### EventBus Methods
- **on** (`(event, callback)`) - Subscribes to an event and returns an unsubscribe function.
- **once** (`(event, callback)`) - Subscribes to an event once.
- **off** (`(event, callback?)`) - Unsubscribes from an event.
- **emit** (`(event, payload)`) - Publishes an event.
- **waitFor** (`(event, timeout?)`) - Waits for an event to be triggered.
- **waitForMatch** (`(event, filter, timeout?)`) - Waits for an event with a specific filter.
- **onCustom** (`(eventName, callback)`) - Subscribes to a custom event.
- **emitCustom** (`(eventName, data)`) - Publishes a custom event.
- **getHistory** (`()`) - Retrieves the event history.
- **clear** (`()`) - Clears all subscriptions.
- **destroy** (`()`) - Destroys the event bus.

### Supported Event Types
#### Lifecycle Events
- **ENGINE_INIT** (`engine:init`) - Engine initialization complete.
- **ENGINE_DESTROY** (`engine:destroy`) - Engine destruction.
#### Message Events
- **MESSAGE_CREATE** (`message:create`) - Message creation.
- **MESSAGE_UPDATE** (`message:update`) - Message update.
- **MESSAGE_DELETE** (`message:delete`) - Message deletion.
- **MESSAGE_CLEAR** (`message:clear`) - Message clearing.
- **MESSAGE_STATUS_CHANGE** (`message:status`) - Message status change.
#### Request Events
- **REQUEST_START** (`request:start`) - Request start.
- **REQUEST_STREAM** (`request:stream`) - SSE chunk received.
- **REQUEST_COMPLETE** (`request:complete`) - Request complete.
- **REQUEST_ERROR** (`request:error`) - Request error.
- **REQUEST_ABORT** (`request:abort`) - Request abort.
#### AG-UI Events
- **AGUI_RUN_START** (`agui:run:start`) - AG-UI run start.
- **AGUI_RUN_COMPLETE** (`agui:run:complete`) - AG-UI run complete.
- **AGUI_RUN_ERROR** (`agui:run:error`) - AG-UI run error.
```

--------------------------------

### Why use useAgentToolcall over Custom Rendering

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Comparison between `useAgentToolcall` and custom rendering, highlighting the benefits of `useAgentToolcall`.

```APIDOC
## Why use useAgentToolcall over Custom Rendering

### Description
Compares `useAgentToolcall` with custom rendering approaches, emphasizing the advantages of `useAgentToolcall` in terms of configuration, type safety, state subscription, and portability.

### Comparison Table
| Comparison Item       | useAgentToolcall                               | Custom Rendering                               | Notes                                          |
|-----------------------|------------------------------------------------|------------------------------------------------|------------------------------------------------|
| Configuration Cohesion | ✅ Tool definition, parameters, UI managed centrally | ❌ Scattered across multiple places             |
| Type Safety           | ✅ Full TypeScript support                     | ⚠️ Manual maintenance required                 |
| State Subscription    | ✅ Built-in `subscribeKey` + `agentState`      | ❌ Requires custom implementation              |
| Portability           | ✅ Configurations reusable across projects       | ❌ Coupled with business logic                  |
| Error Boundaries      | ✅ Built-in protection                         | ❌ Requires manual addition                     |
```

--------------------------------

### AG-UI Backend: Streaming Text Message Events

Source: https://tdesign.tencent.com/react-chat/agui

Illustrates how to stream text messages using the AG-UI protocol. Text messages follow the Start → Content → End pattern, with each content part sent as a separate TEXT_MESSAGE_CONTENT event, all associated with the same messageId.

```json
// 流式输出文本
data: {"type": "TEXT_MESSAGE_START", "messageId": "msg_1", "role": "assistant"}
data: {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "我来"}
data: {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "帮你"}
data: {"type": "TEXT_MESSAGE_CONTENT", "messageId": "msg_1", "delta": "分析..."}
data: {"type": "TEXT_MESSAGE_END", "messageId": "msg_1"}
```

--------------------------------

### Tool Calling with AG-UI Protocol (React)

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Demonstrates how to use ChatEngine's core hooks and components for tool calling within the AG-UI protocol. It covers registering tool configurations using `useTools` and rendering tool calls with the `ToolCaller` component.

```javascript
import {
  useChat,
  useTools,
  ToolCaller,
  type ToolConfig,
  type UseChatOptions
} from '@//tdesign/react-chat';

// Define tool configuration
const imageGeneratorTool: ToolConfig = {
  name: 'imageGenerator',
  description: 'Generates an image based on a prompt.',
  parameters: [
    { name: 'prompt', type: 'string', description: 'The description of the image to generate.' },
    { name: 'style', type: 'string', enum: ['realistic', 'cartoon'], description: 'The style of the image.' },
  ],
  uiComponent: ({ parameters, execute }) => (
    <div>
      <input placeholder='Prompt' onChange={(e) => parameters.prompt = e.target.value} />
      <select onChange={(e) => parameters.style = e.target.value}>
        <option value='realistic'>Realistic</option>
        <option value='cartoon'>Cartoon</option>
      </select>
      <button onClick={() => execute(parameters)}>Generate</button>
    </div>
  ),
};

const App = () => {
  const { messages, sendMessage, ... } = useChat({
    requestConfig: {
      enableAGUI: true,
    },
  });

  // Register tools
  useTools([imageGeneratorTool]);

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          {msg.role === 'tool_call' ? (
            <ToolCaller toolCall={msg.toolCall} />
          ) : (
            <div>{msg.content}</div>
          )}
        </div>
      ))}
      {/* Input and send button */}
    </div>
  );
};

export default App;
```

--------------------------------

### ChatEngine Instance Methods for Control

Source: https://tdesign.tencent.com/react-chat/components/chat-engine

Details how to use instance methods obtained from `useChat` to control component behavior, such as sending messages, managing the send queue, clearing messages, and regenerating responses.

```javascript
const { sendMessage, sendAIResponse, sendSystemMessage, batchSetMessages, clearMessages, regenerate, abort, fillPrompt } = useChat({
  // ...
});

// Example usage:
sendMessage('Hello from user!');
// sendAIResponse('AI response text');
// clearMessages();
// regenerate();
// abort();

```

--------------------------------

### Hybrid Usage of Callbacks and Event Bus

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

This example demonstrates a hybrid approach using both callback mechanisms within chatServiceConfig for data transformation and the event bus for handling side effects like logging or notifications. The onMessage callback transforms incoming data, while an effect hook subscribes to REQUEST_COMPLETE events on the event bus.

```javascript
const { chatEngine } = useChat({
  chatServiceConfig: {
    onMessage: (chunk) => ({ type: 'text', data: chunk.data?.content }),
  },
});

useEffect(() => {
  const unsub = chatEngine.eventBus.on(ChatEngineEventType.REQUEST_COMPLETE, () => {
    // 埋点、通知等
  });
  return unsub;
}, [chatEngine.eventBus]);
```

--------------------------------

### Initialize Messages in ChatEngine

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=api

Shows how to set static initial messages using `initialMessage` or dynamically load historical messages using `loadHistory`. This is useful for pre-populating the chat or loading previous conversations.

```javascript
import {
  useChat,
} from '@tdesign/react-chat-engine';

// Example for setting initial messages
const { messages: initialMessages } = useChat({
  initialMessage: {
    type: 'text',
    content: {
      text: 'Hello! How can I help you today?',
    },
  },
});

// Example for loading historical messages (assuming you have a function to fetch them)
const { messages: historyMessages, loadHistory } = useChat({
  // ... other configurations
});

// To load history:
// loadHistory(fetchedHistory);

// To clear history:
// clearHistory();
```

--------------------------------

### Tool Calling with AG-UI Protocol

Source: https://tdesign.tencent.com/react-chat/components/chat-engine

Explains how the AG-UI protocol enables AI Agents to call frontend tool components via TOOL_CALL events for human-AI collaboration. It highlights core hooks and components like useTools and ToolTemplate for managing tool configurations and rendering.

```javascript
import {
  Chat,
  useChat,
  useTools,
  ToolTemplate,
  Message,
} from '@arco-design/web-react';

const ToolCallingChat = () => {
  const {
    messages,
    sendMessage,
    // ... other hooks
  } = useChat({
    enableAGUI: true,
    // ...
  });

  const { registerTool } = useTools();

  // Register a tool configuration
  registerTool({
    name: 'imageGenerator',
    description: 'Generates an image based on a prompt.',
    parameters: [
      { name: 'prompt', type: 'string', required: true },
      { name: 'style', type: 'string', default: 'vivid' },
    ],
    renderComponent: ({ prompt, style }) => (
      <div>Generating image with prompt: "{prompt}" and style: "{style}"...</div>
    ),
  });

  return (
    <Chat messages={messages} renderMessage={({ type, data }) => (
      <Message type={type}>
        {type === 'toolCall' ? (
          <ToolTemplate toolCall={data} />
        ) : (
          data.text
        )}
      </Message>
    )}>
      {/* Input and send button */}
      <button onClick={() => sendMessage('Generate a picture of a cat')}>Generate Cat</button>
    </Chat>
  );
};

```

--------------------------------

### Activity vs. ToolCall

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Guidance on choosing between Activity and ToolCall based on the use case.

```APIDOC
## Activity vs. ToolCall

### Description
This section provides guidance on when to choose between using `Activity` for display-focused scenarios and `ToolCall` for interactive or state-dependent scenarios.

### Scenarios and Recommendations
| Scenario                                         | Recommended | Reason                                                                 |
|--------------------------------------------------|-------------|------------------------------------------------------------------------|
| Pure display UI (charts, progress bars, data viz) | Activity    | Lightweight, focused on display                                        |
| Streaming incremental updates (stock prices, logs) | Activity    | Natively supports JSON Patch                                           |
| User interaction forms (Human-in-the-Loop)       | ToolCall    | Supports `respond` callback                                            |
| Components subscribing to global `agentState`    | ToolCall    | Supports `subscribeKey`                                                |
| Fine-grained lifecycle control (idle/executing/complete/error) | ToolCall    | Complete state machine                                                 |

**Simple Judgment**:
- If only displaying backend data, use `Activity`.
- If interaction or global state management is needed, use `ToolCall`.
```

--------------------------------

### AG-UI Tool Call Registration and Rendering

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=api

Details the core Hooks and components for handling tool calls within the AG-UI protocol. `useTools` is used to register tool configurations (metadata, parameters, UI components), and `ToolRenderer` is responsible for finding, parsing, and rendering the appropriate UI component for a tool call.

```javascript
import {
  useTools,
  ToolRenderer,
  useChat,
} from '@tdesign/react-chat-engine';

// Define tool configuration
const toolConfig = {
  name: 'imageGenerator',
  description: 'Generates an image based on a prompt.',
  parameters: {
    type: 'object',
    properties: {
      prompt: { type: 'string', description: 'The description of the image to generate.' },
    },
    required: ['prompt'],
  },
  render: (props) => <ImageGeneratorUI {...props} /> // Custom UI component for the tool
};

// Register the tool configuration
useTools([toolConfig]);

function MyChatComponent() {
  const { messages, ...chatProps } = useChat();

  return (
    <div>
      {messages.map((msg, index) => (
        <div key={index}>
          {msg.role === 'toolCall' ? (
            <ToolRenderer toolCall={msg.content} />
          ) : (
            <ChatBubble message={msg} />
          )}
        </div>
      ))}
      <ChatInput {...chatProps} />
    </div>
  );
}

// Example custom UI component for the tool
const ImageGeneratorUI = ({ parameters, status, onUpdateStatus }) => {
  // Render UI based on parameters, status, and update status via onUpdateStatus
  return <div>Image Generator UI - Status: {status}</div>;
};
```

--------------------------------

### Callback Mechanism vs. Event Bus

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=api

Guidance on choosing between the callback mechanism (e.g., `chatServiceConfig`) and the event bus for handling events in ChatEngine.

```APIDOC
## Callback Mechanism vs. Event Bus

### Description
ChatEngine provides two mechanisms for handling events: callback functions in `chatServiceConfig` and the `eventBus`. This section details when to use each.

### Choosing the Right Mechanism
| Scenario                      | Callback Mechanism | Event Bus       | Explanation                                                                 |
|-------------------------------|--------------------|-----------------|-----------------------------------------------------------------------------|
| Parsing SSE data to message content | ✅ Recommended     | ❌              | `onMessage` can return values to affect the message content.                 |
| Custom request parameters/headers | ✅ Recommended     | ❌              | `onRequest` handles request configuration.                                  |
| Logging and monitoring        | ⚠️ Available       | ✅ Recommended  | Event bus offers better decoupling.                                         |
| Cross-component state synchronization | ❌                 | ✅ Recommended  | Multiple components can subscribe to the same event.                        |
| Event tracking and data analysis | ⚠️ Available       | ✅ Recommended  | Separates side effects from data flow.                                      |
| Waiting for a specific event completion (Promise) | ❌                 | ✅ Recommended  | `waitFor` offers unique capabilities.                                         |

**Simple Decision Guide:**
- Use callbacks (`onMessage`/`onRequest`) for **data transformation** where you can return values to influence the data flow.
- Use the event bus for **side effect handling** such as logging, analytics, notifications, and cross-component communication.

### Hybrid Usage Example
```javascript
// Recommended: Hybrid usage
const { chatEngine } = useChat({
  chatServiceConfig: {
    // ✅ Callback: Data transformation
    onMessage: (chunk) => ({ type: 'text', data: chunk.data?.content }),
  },
});

// ✅ Event bus: Side effects
useEffect(() => {
  const unsub = chatEngine.eventBus.on(ChatEngineEventType.REQUEST_COMPLETE, () => {
    // Event tracking, notifications, etc.
  });
  return unsub;
}, [chatEngine.eventBus]);
```
```

--------------------------------

### Using Chat Engine with Callbacks and Event Bus (React)

Source: https://tdesign.tencent.com/react-chat/components/chat-engine

Demonstrates a recommended hybrid approach for using Chat Engine, leveraging callbacks for data transformation (e.g., onMessage) and the event bus for side effects like logging or notifications. This snippet highlights the flexibility of Chat Engine's event handling mechanisms.

```javascript
const { chatEngine } = useChat({
  chatServiceConfig: {
    // ✅ Callback: Data transformation
    onMessage: (chunk) => ({ type: 'text', data: chunk.data?.content }),
  },
});

// ✅ Event bus: Side effects
useEffect(() => {
  const unsub = chatEngine.eventBus.on(ChatEngineEventType.REQUEST_COMPLETE, () => {
    // Logging, notifications, etc.
  });
  return unsub;
}, [chatEngine.eventBus]);
```

--------------------------------

### Configure ChatEngine Data Processing (React)

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Explains the core configuration of ChatEngine, focusing on `endpoint`, `onRequest`, `onMessage`, `onStart`, `onComplete`, `onError`, and `onAbort`. It details how to handle custom protocols and AG-UI protocols for data transformation and communication with the backend.

```javascript
import {
  useChat,
  type UseChatOptions,
  type RequestConfig
} from '@//tdesign/react-chat';

const options: UseChatOptions = {
  requestConfig: {
    endpoint: '/api/chat',
    onRequest: (config: RequestConfig) => {
      // Modify request headers or parameters
      config.headers = { ...config.headers, 'Authorization': 'Bearer YOUR_TOKEN' };
      return config;
    },
    onMessage: (rawData: any) => {
      // Transform backend data to component format
      // For custom protocols:
      return { role: 'assistant', content: rawData.response };
      // For AG-UI protocol, this might be null if handled automatically
    },
    onStart: () => console.log('Request started'),
    onComplete: () => console.log('Request completed'),
    onError: (error) => console.error('Request error:', error),
    onAbort: () => console.log('Request aborted'),
  },
};

const { ... } = useChat(options);
```

--------------------------------

### Activity Event Handling with AG-UI Protocol (React)

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Details how the AG-UI protocol supports dynamic content display through `ACTIVITY` events. It covers registering Activity configurations with `useActivity` and rendering components based on activity types using the `ActivityRenderer` component.

```javascript
import {
  useChat,
  useActivity,
  ActivityRenderer,
  type ActivityConfig,
  type UseChatOptions
} from '@//tdesign/react-chat';

// Define activity configurations
const planTodoActivity: ActivityConfig = {
  type: 'plan-todo',
  uiComponent: ({ data }) => (
    <div>
      {data.steps.map((step: any, index: number) => (
        <div key={index} style={{ textDecoration: step.completed ? 'line-through' : 'none' }}>
          {step.name}
        </div>
      ))}
    </div>
  ),
};

const travelProgressActivity: ActivityConfig = {
  type: 'travel-progress',
  uiComponent: ({ data }) => (
    <div style={{ width: `${data.percentage}%`, backgroundColor: 'blue', height: '20px' }}></div>
  ),
};

const App = () => {
  const { messages, ... } = useChat({
    requestConfig: {
      enableAGUI: true,
    },
  });

  // Register activities
  useActivity([planTodoActivity, travelProgressActivity]);

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          {msg.type === 'activity' ? (
            <ActivityRenderer activity={msg.activity} />
          ) : (
            <div>{msg.content}</div>
          )}
        </div>
      ))}
      {/* Input and send button */}
    </div>
  );
};

export default App;
```

--------------------------------

### AG-UI Protocol Basic Usage (React)

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=demo

Shows how to enable AG-UI protocol support in ChatEngine to automatically parse standard event types like `TOOL_CALL`, `STATE_SNAPSHOT`, `STATE_DELTA`, and `ACTIVITY`. This simplifies integration with AG-UI compliant backend services.

```javascript
import {
  useChat,
  type UseChatOptions
} from '@//tdesign/react-chat';

const options: UseChatOptions = {
  requestConfig: {
    // ... other configurations
    enableAGUI: true, // Enable AG-UI protocol support
  },
};

const { ... } = useChat(options);
```

--------------------------------

### Chat Engine Event Handling with Callbacks and Event Bus (React)

Source: https://tdesign.tencent.com/react-chat/components/chat-engine_tab=api

Demonstrates how to use both callback mechanisms within chatServiceConfig and the eventBus for handling events in ChatEngine. It highlights when to use callbacks for data transformation and the event bus for side effects like logging and cross-component communication.

```javascript
const { chatEngine } = useChat({
  chatServiceConfig: {
    // ✅ Callback: Data transformation
    onMessage: (chunk) => ({ type: 'text', data: chunk.data?.content }),
  },
});

// ✅ Event Bus: Side effects
useEffect(() => {
  const unsub = chatEngine.eventBus.on(ChatEngineEventType.REQUEST_COMPLETE, () => {
    // Logging, notifications, etc.
  });
  return unsub;
}, [chatEngine.eventBus]);
```
Tokens:
Raw