#t-agent 开发者文档

#概述

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

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

想了解更多详细信息，请访问官方文档。

#核心概念

#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：清空历史时触发

使用示例：

// 注册消息反馈处理
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：

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()：提供内置功能

#错误处理

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

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

内置支持的错误类型：

• network-offline：网络已断开
• timeout：发送超时
• invalid-params：无效参数
• session-create-failed：连接失败
• connection-closed：连接已关闭

#内置插件

#withDebug

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

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

#withUI

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

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，用于打印日志。

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

#Emitter 事件总线

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

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 说明，请访问官方文档。