# Agent UI 小程序组件

Agent UI 是一个小程序源码组件，帮助开发者快速搭建聊天界面，支持对接云开发 Agent（智能体）和大模型。

Agent UI 提供以下功能：

对接云开发 Agent — 通过 chatMode: "bot" 使用
对接云开发大模型 — 通过 chatMode: "model" 使用
内置文件上传、图片上传、语音输入、联网搜索、多会话管理等能力

# 快速体验

方式一： 通过微信开发者工具模板创建

打开微信开发者工具，点击新建小程序项目，在「开发模式」中选择「小程序」，「模板」分类中找到并选择 Agent UI / 云开发 AI 相关模板，创建后即可按模板指引直接运行体验。

方式二： 下载源码包导入

下载项目示例源码包，导入到微信开发者工具使用。

导入后需手动修改 app.json 中的 env 为你的环境 ID，以及 pages/chatBot/chatBot.js 中的 botId 为你的 Agent ID。

# 引入组件到已有小程序

# 1. 拷贝组件目录

将 miniprogram/components/agent-ui 目录拷贝到你的小程序项目中。

# 2. 注册组件

在页面的 .json 配置文件中注册组件：

{
  "usingComponents": {
    "agent-ui": "/components/agent-ui/index"
  }
}

# 3. 使用组件

在页面的 .wxml 文件中使用组件：


<agent-ui
        agentConfig="{{agentConfig}}"
        showBotAvatar="{{showBotAvatar}}"
        chatMode="{{chatMode}}"
        modelConfig="{{modelConfig}}"
        envShareConfig="{{envShareConfig}}"
/>

# 4. 配置参数

在页面的 .js 文件中编写配置：

Page({
    data: {
        chatMode: "bot", // "bot" 使用 Agent，"model" 使用大模型
        showBotAvatar: true,
        agentConfig: {
            botId: "<你的 Agent ID>",
            allowWebSearch: true,
            allowUploadFile: true,
            allowPullRefresh: true,
            allowUploadImage: true,
            showToolCallDetail: true,
            allowMultiConversation: true,
            allowVoice: true,
        },
    },
});

# 5. 初始化云开发

在 app.js 的 onLaunch 中初始化：

App({
    onLaunch() {
        wx.cloud.init({
            env: "<云开发环境ID>",
        });
    },
});

# 组件参数

# 基础参数

参数	类型	说明
chatMode	`"bot"` \| `"model"`	`"bot"` 使用 Agent，`"model"` 使用大模型
showBotAvatar	boolean	是否在对话框左侧显示头像

# agentConfig（Agent 模式）

当 chatMode = "bot" 时使用：

参数	类型	说明
botId	string	必填，Agent ID
allowWebSearch	boolean	允许客户端选择启用联网搜索
allowUploadFile	boolean	允许上传文件
allowUploadImage	boolean	允许上传图片
allowPullRefresh	boolean	允许下拉刷新
allowMultiConversation	boolean	是否展示会话列表和创建会话按钮
showToolCallDetail	boolean	是否展示工具调用细节
allowVoice	boolean	是否展示语音输入按钮

# modelConfig（大模型模式）

当 chatMode = "model" 时使用：

参数	类型	说明
modelProvider	string	必填，大模型服务商标识，见模型版本
quickResponseModel	string	必填，具体的模型版本，见模型版本
logo	string	模型头像 URL
welcomeMsg	string	欢迎语

# envShareConfig（环境共享）

跨小程序调用其他环境的 AI 能力时使用：

参数	类型	说明
resourceAppid	string	资源方小程序的 AppID
resourceEnv	string	资源方的云开发环境 ID

# 使用示例

# 使用 Agent

Page({
    data: {
        chatMode: "bot",
        showBotAvatar: true,
        agentConfig: {
            botId: "<你的 Agent ID>",
            allowWebSearch: true,
            allowUploadFile: true,
            allowPullRefresh: true,
            allowUploadImage: true,
            showToolCallDetail: true,
            allowMultiConversation: true,
            allowVoice: true,
        },
    },
});

# 使用 DeepSeek V3 模型

Page({
    data: {
        chatMode: "model",
        showBotAvatar: true,
        modelConfig: {
            modelProvider: "deepseek",
            quickResponseModel: "deepseek-v3",
            logo: "",
            welcomeMsg: "你好！我是 DeepSeek，有什么可以帮你的？",
        },
    },
});

# 使用 DeepSeek R1 模型（深度推理）

Page({
    data: {
        chatMode: "model",
        showBotAvatar: true,
        modelConfig: {
            modelProvider: "deepseek",
            quickResponseModel: "deepseek-r1",
            logo: "",
            welcomeMsg: "你好！我是 DeepSeek R1 推理模型。",
        },
    },
});

# 使用混元模型

Page({
    data: {
        chatMode: "model",
        showBotAvatar: true,
        modelConfig: {
            modelProvider: "hunyuan-open",
            quickResponseModel: "hunyuan-lite",
            logo: "",
            welcomeMsg: "你好！我是混元大模型。",
        },
    },
});

# 模型版本

# hunyuan

modelProvider	quickResponseModel	说明
`hunyuan-open`	`hunyuan-lite`	具备强大的中文创作能力，复杂语境下的逻辑推理能力

# deepseek

modelProvider	quickResponseModel	说明
`deepseek`	`deepseek-v3`	专注于自然语言处理、知识问答、内容创作等通用任务
`deepseek`	`deepseek-r1`	推理模型，专为数学、代码生成和复杂逻辑推理任务设计

Agent UI 组件中的 modelProvider 和 quickResponseModel 与 ai.createModel() 中的模型标识不同。 createModel("cloudbase") 是 API 调用时使用的统一标识，而 Agent UI 组件需要分别指定 modelProvider（厂商）和 quickResponseModel（模型版本）。

# 功能说明

# 文件上传

大小限制： 单文件不超过 10MB
数量限制： 单次最多 5 个文件
文件类型： pdf、txt、doc、docx、ppt、pptx、xls、xlsx、csv
域名配置： 需要在微信公众平台中将 https://{envid}.api.tcloudbasegateway.com 添加到 request 合法域名列表（将 {envid} 替换为你的环境 ID）

# 图片上传

每次仅支持上传单张图片，最大不超过 30MB

# 语音功能

需要授予小程序麦克风权限，组件会自动发起权限申请

# 通过环境共享调用其他环境的 AI 能力

如果 A 小程序开通了云开发环境，B 小程序想跨环境调用 A 小程序的 AI 能力：

# 前提条件

A 和 B 小程序必须是同一个主体
A 小程序已开通环境共享，并将环境共享给 B 小程序

# 配置方式

在 B 小程序中使用 Agent UI 时，通过 envShareConfig 传入 A 小程序的信息：

Page({
    data: {
        chatMode: "model",
        showBotAvatar: true,
        modelConfig: {
            modelProvider: "deepseek",
            quickResponseModel: "deepseek-v3",
            logo: "",
            welcomeMsg: "欢迎使用",
        },
        envShareConfig: {
            resourceAppid: "wx7a******5f4f", // A 小程序的 AppID
            resourceEnv: "chr**************46d2d", // A 小程序的环境 ID
        },
    },
});

不使用环境共享时，不要传 envShareConfig 参数，或将其设为 null。

# 获取 Agent ID

在云开发控制台 → AI → Agent 中创建 Agent 后，可以获取对应的 Agent ID：