通用智能体开发解决方案——AI助手开发教程（二）

通用智能体开发解决方案——AI助手开发教程（一） 

快速开始 

概览

AI 智能体 SDK 能够让开发者快速在自己的小程序中集成 AI 对话功能，这能够使开发者专注实现自己的业务逻辑，而不用在技术细节上浪费时间。

使用智能生活 App（6.0.0 及以上版本）扫描下方二维码，可以体验 AI 对话功能：

快速开始

版本说明

⚠️ 重要提示：@ray-js/t-agent-plugin-assistant 已被废弃，请使用 @ray-js/t-agent-plugin-aistream 替代。

安装依赖

在项目的 package.json 中添加以下依赖：

{
  "dependencies": {
    "@ray-js/t-agent": "^0.2.0",
    "@ray-js/t-agent-plugin-aistream": "^0.2.0",
    "@ray-js/t-agent-ui-ray": "^0.2.0"
  }
}

确保 @ray-js/t-agent、@ray-js/t-agent-plugin-aistream、@ray-js/t-agent-ui-ray 版本一致

执行 yarn install 安装依赖。

小程序 Kit 要求

{
  "dependencies": {
    "BaseKit": "3.12.0",
    "BizKit": "4.10.0",
    "DeviceKit": "4.6.1",
    "HomeKit": "3.4.0",
    "MiniKit": "3.12.1",
    "AIStreamKit": "1.0.0"
  },
  "baseversion": "2.21.10"
}

基础示例

以下是在小程序中集成 AI 对话界面的最简代码示例：

import React from 'react';
import { View } from '@ray-js/components';
import { createChatAgent, withDebug, withUI } from '@ray-js/t-agent';
import { ChatContainer, MessageInput, MessageList, MessageActionBar } from '@ray-js/t-agent-ui-ray';
import { withAIStream, withBuildIn } from '@ray-js/t-agent-plugin-aistream';
 
const createAgent = () => {
  const agent = createChatAgent(
    withUI(), // 第一个插件 withUI 插件提供了一些默认的 UI 行为，必选
    withAIStream({
      // withAIStream 插件对接小程序 AI 智能体平台，在小程序中必选
      enableTts: false, // 是否开启语音合成
      earlyStart: true, // 是否在 onAgentStart 阶段就建立连接
      agentId: '[your_agent_id]', // 输入您的智能体 ID
      tokenOptions: {
        api: 'm.life.ai.token.get',
        version: '1.0',
      },
    }),
    withDebug(), // withDebug 会在 console 里打印日志
    withBuildIn() // withBuildIn 插件提供了一些内置的功能
  );
  
  return agent;
};
 
export default function Home() {
  return (
    <View style={{ height: '100vh' }}>
      <ChatContainer createAgent={createAgent}>
        <MessageList />
        <MessageInput />
        <MessageActionBar />
      </ChatContainer>
    </View>
  );
}

请替换 [your_agent_id] 为您的 Agent ID，Agent ID 可以在涂鸦 AI 涂鸦开发者平台中获取。

高级配置

启用语音合成

withAIStream({
  agentId: '[your_agent_id]',
  enableTts: true, // 开启语音合成
  tokenOptions: {
    api: 'm.life.ai.token.get',
    version: '1.0',
  },
})

自定义历史消息大小

withAIStream({
  agentId: '[your_agent_id]',
  historySize: 500, // 历史消息大小，默认 1000
  tokenOptions: {
    api: 'm.life.ai.token.get',
    version: '1.0',
  },
})

更多详细说明和高级用法，请参考 T-Agent SDK 开发指南。

核心概念 

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

 通用智能体开发解决方案——AI助手开发教程（三）