---
title: AI 助手方案 - t-agent
summary: t-agent 对话智能体 SDK 开发文档，基于 TypeScript 构建，支持插件扩展。涵盖核心概念：ChatAgent（生命周期管理、消息创建与持久化）、生命周期钩子（onAgentStart、onChatStart、onInputBlocksPush 等）、ChatSession（会话数据与消息列表管理）、ChatMessage（消息状态与 tile 管理）、ChatTile（可视化元素）、气泡消息快捷方式、插件系统（withUI、withDebug、withAIStream、withBuildIn）、错误处理机制及工具函数（Logger、Emitter 事件总线、StreamResponse）。
---

# t-agent 开发者文档

## 概述

t-agent 是一个用 TypeScript 构建的对话智能体 SDK，用于构建功能丰富的对话交互应用。它支持插件扩展，是一个纯粹的 SDK，不包含 UI 组件，可以与任何框架配合使用。

t-agent 具备强大的 Hook 机制、错误处理、消息状态管理等功能，提供了强大的开发体验。

想了解更多详细信息，请访问[官方文档](https://developer.tuya.com/material/library_oHEKLjj0/component?code=TAgent#t-agent)。

## 核心概念

### ChatAgent

ChatAgent 是整个对话系统的核心类，负责处理对话的生命周期、消息创建、持久化等核心功能，并支持通过插件和钩子扩展功能。

**主要属性**：
- `agent.session`：存储会话数据
- `agent.plugins`：包含已应用插件的方法和钩子

**核心方法**：
- `agent.start()`：激活对话代理
- `agent.dispose()`：停用对话代理
- `agent.pushInputBlocks()`：将用户消息推送给 ChatAgent
- `agent.createMessage()`：创建消息
- `agent.emitTileEvent()`：发送 tile 事件
- `agent.removeMessage()`：删除消息
- `agent.flushStreamToShow()`：流式更新消息

### 生命周期钩子

ChatAgent 通过钩子系统实现事件驱动的行为模式。Hook 按照以下顺序执行：

```
onAgentStart → onChatStart/onChatResume → onMessageListInit → onInputBlocksPush
```

主要钩子包括：

- `onAgentStart`：代理初始化时触发
- `onChatStart`：对话开始时触发
- `onChatResume`：对话继续时触发
- `onMessageListInit`：消息列表初始化时触发
- `onInputBlocksPush`：接收到输入消息块时触发
- `onMessageChange`：消息更新时触发
- `onMessagePersist`：消息持久化时触发
- `onTileEvent`：消息块事件触发时调用
- `onAgentDispose`：代理销毁时触发
- `onUserAbort`：用户终止对话时触发
- `onError`：发生错误时触发

### 增强钩子

- `onMessageFeedback`：消息反馈时触发
- `onClearHistory`：清空历史时触发

使用示例：

```tsx
// 注册消息反馈处理
agent.plugins.ui.hook('onMessageFeedback', async context => {
  const { messageId, rate, content } = context.payload;
  try {
    await submitFeedback({ messageId, rate, content });
    context.result = { success: true };
  } catch (error) {
    context.result = { success: false };
  }
});

// 注册清空历史处理
agent.plugins.ui.hook('onClearHistory', async context => {
  try {
    await clearChatHistory();
    context.result = { success: true };
  } catch (error) {
    context.result = { success: false };
  }
});
```

### ChatSession

ChatSession 持有消息列表和会话相关数据，随 ChatAgent 一起创建。

**主要属性**：
- `session.messages`：消息列表
- `session.sessionId`：唯一会话 ID
- `session.isNewChat`：区分新会话或继续会话

**主要方法**：
- `session.set/get`：设置/获取会话数据
- `session.getData`：获取所有会话数据
- `session.getLatestMessage`：获取最新消息

**Hooks**：
- `session.onChange`：注册会话数据变化的回调

### ChatMessage

ChatMessage 是对话内容和状态的抽象表示，由多个 ChatTile 组成。

**主要属性**：
- `message.id`：唯一消息标识符
- `message.role`：消息角色（'user'/'assistant'）
- `message.status`：消息状态（`ChatMessageStatus` 枚举）
- `message.tiles`：消息包含的 tile 列表
- `message.bubble`：快速访问主要的气泡 tile
- `message.meta`：消息附带的额外数据
- `message.isShow`：是否已经展示到界面上

**主要方法**：
- `message.show/update/remove`：控制消息显示状态
- `message.persist`：持久化消息
- `message.addTile/removeTile`：管理消息块
- `message.setTilesLocked`：设置消息的所有 tile 的锁定状态
- `message.set`：设置消息属性
- `message.setMetaValue`：按 key-value 设置 meta 的属性
- `message.deleteMetaValue`：删除 meta 的属性
- `message.setMeta`：直接设置 meta 对象
- `message.findTileByType`：通过 tile 类型查找 tile

### ChatTile

ChatTile 是消息中的可视化元素，可以是文本、图片、视频等不同类型。

**主要属性**：
- `tile.id`：唯一标识符
- `tile.type`：tile 类型
- `tile.data`：tile 的数据
- `tile.children`：子 tile 列表
- `tile.locked`：是否锁定
- `tile.fallback`：当 tile 无法展示时的回退内容
- `tile.message`：所属的消息引用

**主要方法**：
- `tile.update`：是 `tile.message.update` 的快捷方式
- `tile.show`：是 `tile.message.show` 的快捷方式
- `tile.setLocked`：设置锁定状态
- `tile.addTile`：添加子 tile
- `tile.setData`：设置 tile 数据
- `tile.setFallback`：设置后备显示内容
- `tile.findByType`：通过 tile 类型查找子 tile

#### 气泡消息快捷方式

`message.bubble` 是一个快捷方式，访问它就会在当前消息中快速添加一个气泡 tile：

```tsx
const message = createMessage({ role: 'assistant' });

message.bubble.setText('Hello, world!');
// 等价于
message.addTile('bubble', {}).addTile('text', { text: 'Hello, world!' });

await message.show();
```

针对气泡消息，还额外提供了：

- `message.bubble.text`：读取气泡文本
- `message.bubble.setText`：设置气泡文本
- `message.bubble.isMarkdown`：是否是 markdown 格式
- `message.bubble.setIsMarkdown`：设置是否是 markdown 格式
- `message.bubble.status`：气泡状态
- `message.bubble.setStatus`：设置气泡状态
- `message.bubble.info`：气泡信息
- `message.bubble.setInfo`：设置气泡信息
- `message.bubble.initWithInputBlocks`：用输入块初始化气泡

### 插件系统

t-agent 支持通过插件扩展功能。插件是基于 Hook 机制实现的，插件可以暴露方法和属性供开发者使用。

常用插件包括：

- `withUI()`：提供 UI 相关功能和消息总线
- `withDebug()`：提供调试功能
- `withAIStream()`：对接小程序 AI 智能体平台
- `withBuildIn()`：提供内置功能

### 错误处理

增强了错误处理机制，支持更详细的错误信息和错误分类：

```tsx
agent.onError(error => {
  console.error('Agent error:', error);
  // 错误处理逻辑
});
```

内置支持的错误类型：
- `network-offline`：网络已断开
- `timeout`：发送超时
- `invalid-params`：无效参数
- `session-create-failed`：连接失败
- `connection-closed`：连接已关闭

## 内置插件

### withDebug

withDebug 插件会在 console 里打印日志，方便调试。

```tsx
const agent = createChatAgent(
  withDebug({
    autoStart: true, // 是否自动启动，默认为 true
  })
);
```

### withUI

withUI 插件提供了默认的 UI 行为和消息总线。

```tsx
const agent = createChatAgent(withUI());

// 滚动到底部
agent.plugins.ui.emitEvent('scrollToBottom', { animation: false });

// 监听事件
const off = agent.plugins.ui.onEvent('scrollToBottom', payload => {
  console.log('scroll to bottom', payload.animation);
});
```

主要事件：
- `messageListInit`：初始化消息列表
- `messageChange`：消息变化
- `scrollToBottom`：滚动到底部
- `sendMessage`：发送消息
- `setInputBlocks`：设置输入块
- `sessionChange`：会话数据变化

## 工具函数

### getLogger(prefix: string): Logger

创建一个 logger，用于打印日志。

```tsx
import { getLogger } from '@ray-js/t-agent';
const logger = getLogger('MyPlugin');
logger.debug('Hello, world!');
```

### Emitter 事件总线

Emitter 是一个事件总线，用于注册和触发事件。

```tsx
import { Emitter, EmitterEvent } from '@ray-js/t-agent';
const emitter = new Emitter();

// 注册事件
emitter.addEventListener('event', event => console.log(event.detail));

// 触发事件
emitter.dispatchEvent(new EmitterEvent('event', { detail: 'Hello!' }));
```

### 其他工具

- `StreamResponse`：流式响应对象
- `createHooks`、`Hookable`：Hook 机制相关
- `isAbortError`：判断是否是中断错误
- `safeParseJSON`：安全地解析 JSON 字符串

## 总结

t-agent 是一个灵活的对话代理 SDK，通过其核心概念、强大的 Hook 系统和插件机制，可以构建丰富的对话交互体验。开发者可以利用 t-agent 快速构建具有现代功能的对话应用，如聊天机器人、客服系统或智能助手。

更多详细信息和 API 说明，请访问[官方文档](https://developer.tuya.com/material/library_oHEKLjj0/component?code=TAgent#t-agent)。