开发定制 AI 智能体小程序

注意事项

如果您仅想构建一个智能体小程序，且不需要深度定制小程序的外观与功能，推荐直接使用智能体平台生成的小程序。

前提条件

已阅读 Ray 新手村任务，了解 Ray 框架的基础知识。
已阅读智能体开发平台，了解智能体的各项概念。

构建内容

您可以利用小程序开发构建出一个基于 Ray 框架的 AI 智能体小程序，并充分利用小程序的扩展能力，实现自定义功能和外观，满足您多种多样的业务需要。

所需条件

智能生活 OEM App（必选）
- 如果未创建，请先创建智能生活 OEM App。
智能产品（可选，如果您不需要智能体来控制设备，仅需要对话问答，可以不需要创建智能产品）
- 如果未创建，请先创建产品。
Tuya MiniApp IDE
NVM 及 Node 开发环境（建议使用 18.x 系列版本）
Yarn 依赖管理工具

详见智能小程序 > 搭建环境。

创建

准备好 智能生活 OEM App 和智能产品（可选）后，需要在智能体平台上创建智能体。

单击 创建 Agent 按钮，填入项目相关必选信息后，单击确定创建一个智能体。

依照您的需求，在 01 模型能力配置 下定制智能体的模型、记忆、工具、知识库及工作流等功能，再在 02 提示词开发 下配置提示词（Prompt），完成当前数据中心的智能体创建。

调试

配置完成 Prompt 后，单击 获取调试二维码 按钮获取二维码。

使用国内版 智能生活 App 扫码，即可在 App 上使用模板小程序体验您的智能体。尝试发起问答，查看智能体的回答是否符合您的预期。确认没有问题后，单击 前往配置 按钮。

在智能体的应用管理页面，绑定您拥有的 App，单击保存。在真机上安装您的 App，使用 App 内建的扫码功能，再次扫描获取的二维码，即可在您的 App 上测试该智能体。

发布

按照您的需要，分别配置不同数据中心的智能体，然后单击发布按钮，发布智能体。

复制并记录智能体的 Agent ID，在后续实现对话页面的配置中会使用到：

完成

至此，您已经成功创建了一个智能体。如果不需要深度定制功能和界面，则可直接使用智能体平台生成的小程序。

开发者平台创建智能小程序

智能小程序的开发在 小程序开发者 平台上进行操作，首先请前往小程序开发者平台完成平台的注册登录。

在平台上创建一个小程序后，单击 添加 App 将小程序投放到您的 OEM App 中，并选择您想发布的数据中心。

创建本地工程

接下来，创建本地工程，需要在 Tuya MiniApp IDE 上进行操作，详细操作步骤可以参考智能小程序 > 三、初始化工程。注意，选择模板为 App 通用的 Ray 应用 来创建一个智能小程序工程。

App 版本

智能生活 v6.3.0 及以上版本。

Kit 依赖

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

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

组件依赖

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

{
  "dependencies": {
    "@ray-js/ray": "^1.6.8",
    "@ray-js/t-agent": "^0.0.7",
    "@ray-js/t-agent-plugin-assistant": "^0.0.7",
    "@ray-js/t-agent-ui-ray": "^0.0.7"
  }
}

依赖安装

添加完成后，在项目根目录下执行以下命令安装依赖：

yarn install

修改 src/pages/Home/index.tsx 文件，引入智能体 SDK，实现对话页面。将 填写你的 [Agent ID] 处改成您的智能体 ID，保存并等待编译完成。

import React from 'react'
import {View} from '@ray-js/components'
import {createChatAgent, withDebug, withUI} from '@ray-js/t-agent'
import {ChatContainer, MessageInput, MessageList} from '@ray-js/t-agent-ui-ray'
import {withAssistant, withBuildIn} from '@ray-js/t-agent-plugin-assistant'

const createAgent = () => {
  const agent = createChatAgent(
    withUI(),
    withAssistant({
      channel: '填写你的 [Agent ID]',
      multiModal: false,
    }),
    withDebug(),
    withBuildIn()
  )

  const {onChatStart, createMessage, onChatResume, session} = agent

  // 创建一条初始的欢迎信息
  onChatStart(async (result) => {
    const hello = createMessage({
      role: 'assistant',
    })

    hello.bubble.setText('Hello, world!')
    result.messages.push(hello)
    await hello.persist('createText')
  })

  // 恢复聊天时，发送一条消息
  onChatResume(async (result) => {
    const lastMessage = session.getLatestMessage()
    const lastMessageCreateTime = lastMessage?.meta?.raw?.TEXT_FINISH?.createTime
    if (lastMessageCreateTime < Date.now() - 1000 * 60 * 60 * 2) {
      const welcomeBack = createMessage({
        role: 'assistant',
      })

      welcomeBack.bubble.setText('Welcome back')
      result.messages.push(welcomeBack)
      await welcomeBack.persist('createText')
    }
  })
  return agent
}

export default function Home() {
  return (
    <View style={{height: '100vh'}}>
      <ChatContainer createAgent={createAgent}>
        <MessageList/>
        <MessageInput/>
      </ChatContainer>
    </View>
  )
}

此时，您可以看到一个简单的对话页面，便可以和智能体进行对话了。

在 IDE 中模拟对话

在开发状态下，可以使用 Mock 机制在 IDE 下进行模拟对话。新建一个文件，例如 src/pages/Home/mock.ts，用于模拟消息回复。

import { mock } from '@ray-js/t-agent-plugin-assistant'
mock.hooks.hook('sendToAssistant', context => {
  if (context.options.block?.includes('hello')) {
    context.responseText = 'hello, who are you?';
  }
});

再在 src/pages/Home/index.tsx 中引入该文件。

import './mock'
// 余下内容

此时，当您在 IDE 中发送 hello 时，智能体会回复 hello, who are you?。

真机预览

同时，您可以使用真机预览，在您的 OEM App 上调试真实的 AI 对话。

当您创建的产品支持 AI 控制时，您可以在智能体中实现对设备的控制。

配置产品支持 AI 控制

访问 AI 产品指令配置页面，完成指令配置并且发布。

关于配置方法和发布方法，请参考使用语音工作台。

设置智能体支持控制设备

回到我的智能体页面，定位到您刚刚创建的智能体，并单击 Agent管理 按钮进入管理页面。
单击 + 开发版本 创建一个新版本。
单击 工具集 下的 + 按钮，在 新增工具集 窗口的 设备控制工具集 > 选择工具 下选择 控制设备、查询设备 两项，然后单击添加。

修改提示词，描述设备控制的功能，例如：

# 角色
你是一位设备控制智能体，精通智能设备管理，擅长远程控制和设备同步，对设备自动化和智能家居系统有独到的见解。

## 技能
### 技能 1: 远程设备控制
### 技能 2: 设备状态监测与同步

最后单击发布按钮，发布智能体。
再次真机预览您的小程序，与智能体对话，尝试控制设备。

您可以定制这个对话页面的任何外观，例如修改背景颜色、字体颜色、字体大小等。

功能按钮

例如，您想在消息列表和输入框之间，增加一个功能按钮：

export default function Home() {
  // ... 前面的代码
  return (
    <View style={{height: '100vh'}}>
      <ChatContainer createAgent={createAgent}>
        <MessageList/>
        <Button>功能按钮</Button> {/* 新增功能按钮 */}
        <MessageInput/>
      </ChatContainer>
    </View>
  )
}

气泡颜色

您可以修改气泡的颜色，创建一个 chat.css 文件，填入以下内容，然后引入页面：

.t-agent-message-list-row-start .t-agent-bubble-tile-bubble {
  background-color: blue;
}

.t-agent-message-list-row-end .t-agent-bubble-tile-bubble {
  background-color: gray;
}

import './chat.css'

@ray-js/t-agent-ui-ray 组件库提供了一些默认的样式，您可以根据自己的需求进行修改。

如果您想在用户进入对话页面时，发送一条欢迎消息，或者在用户隔一段时间后重新进入小程序时，发送一条问候消息，可以在 src/pages/Home/index.tsx 中添加以下代码：

// 修改 createAgent 函数
const createAgent = () => {
  
  // ... 前面的代码
  
  const { onChatStart, createMessage, onChatResume } = agent

  // 创建一条初始的欢迎信息
  onChatStart(async (result) => {
    const hello = createMessage({
      role: 'assistant',
    })

    hello.bubble.setText(I18n.t('message.hello')) // 此处定义您想写的问候的多语言
    
    result.messages.push(hello)
    
    await hello.persist('createText') // 将这个消息气泡持久化下来
  })

  // 恢复聊天时，发送一条消息
  onChatResume(async (result) => {
    // 判断上一条消息是否是两小时前
    const lastMessage = session.getLatestMessage()
    const lastMessageCreateTime = lastMessage?.meta?.raw?.TEXT_FINISH?.createTime
    
    if (lastMessageCreateTime < Date.now() - 1000 * 60 * 60 * 2) {
      // 如果是，发送一条欢迎回来的消息
      const welcomeBack = createMessage({
        role: 'assistant',
      })

      welcomeBack.bubble.setText(I18n.t('message.welcomeBack')) // 此处定义您想写的欢迎回来的多语言
      result.messages.push(welcomeBack)
      await welcomeBack.persist('createText')
    }
  })
  return agent
}

T-Agent SDK 提供了一些默认的组件，可以帮助您快速搭建一个对话页面，同时在 SDK 设计上提供了一定的自定义能力。

目前支持以下内容的深度定制：

自定义消息列表：替换 MessageList 实现。
自定义消息输入框：替换 MessageInput 实现。
自定义消息气泡：传入 renderOptions.renderTileAs 的方法，替换 BubbleTile 实现。
生成一条自定义消息：在生命周期钩子里，使用 agent.createMessage 创建一条消息。

SDK 核心设计理念是将对话智能体的行为和外观分离，通过插件和 Hook 机制来实现对话智能体的定制。下图为对 SDK 的核心类和机制的简单介绍。

ChatAgent 对话智能体 Agent

对话智能体的核心类，负责管理对话的生命周期、消息的创建、消息的持久化等，支持插件和 Hook 机制，可以扩展对话智能体的功能。

Hook 机制

ChatAgent 仅定义了一个运行框架和数据结构，具体行为是由 Hook 机制实现的。Hook 机制是一种事件驱动的编程模型，通过注册回调函数来实现对话智能体的行为。

ChatSession 会话容器

ChatSession 存储和智能体聊天的消息列表，上下文数据等内容，在 ChatAgent 创建时一同创建。

ChatMessage 对话消息

ChatMessage 是对话消息的抽象，用于存储消息的内容、状态等信息，也提供了一系列方便的方法用于操作消息。一条消息 ChatMessage 下，会有多个 ChatTile，用于展示不同的内容。

生命周期

ChatAgent 在不同的阶段会触发不同的 Hook，开发者可以通过注册 Hook 来实现自定义行为。

Plugin 插件机制

插件是基于以上的 Hook 机制实现的，插件可以实现对话智能体的功能，例如对接 AI 平台，提供 UI 界面等。插件也可以暴露一些方法和属性，供开发者使用。

详细说明和示例请参考 SDK 的 T-Agent SDK 文档，自行实现对话页面的各个组件。

恭喜你 🎉 完成了本教程的学习！
有任何问题可以联系涂鸦智能小程序团队

反馈