开发教程与代码示例

入门

小程序框架

小程序运行时

自定义组件

基础教程

能力教程

流量入口

通用能力

推广变现

经营能力

行业能力

小程序智能体

AI 会话组件/JS API 接入指南

AI/AR 算法能力

性能优化

安全

AI 会话组件/JS API 接入指南

我的收藏

前置准备

智能体搭建

在接入 AI 会话组件/JSAPI之前，我们先前往 AI 开放平台完成智能体的搭建，具体步骤请参考搭建和发布小程序智能体。完成搭建后，我们会获得两个重要参数小程序智能体 ID 和小程序智能体版本。

隐私协议配置

AI 会话组件内部使用了小程序的剪贴板能力，用于提供快速会话的一键复制功能。在使用该能力前需要在小程序的隐私协议中声明使用剪贴板信息，否则复制功能将无法使用。

使用 JS API 之前，也需要配置隐私协议，未配置时将无法获取智能体信息、实现与智能体对话等功能。

隐私协议配置参考配置隐私协议。

更新抖音开发者工具及客户端版本

要完成 AI 会话组件的接入和开发调试，抖音开发者工具及客户端需升级至以下版本。

环境	最低支持版本
抖音开发者工具	4.4.1
抖音客户端	34.7.0 （基础库 3.74.0）

开发接入

组件接入

说明

本教程提供一个最小化 Demo，组件的详细信息，请参见 ai-agent-chat AI 会话组件。

在 AI 开放平台点击预览按钮，我们可以得到JSAPI和会话组件的配置，点击会话组件配置中的复制便可得到组件的代码，示例如下：

<ai-agent-chat 
    agent-id="ttbc02cabf230bd48016" 
    agent-version="1.21.0" 
    mode="preview"
></ai-agent-chat>

注意
preview 是预览环境使用参数，线上环境应使用 online 或保持参数为空。

在开发者工具使用关联的小程序 id 创建小程序项目，写入代码后即可预览会话组件的效果。

为了兼容低版本基础库，我们通常需要做兼容处理。示例如下：

<view tt:if="{{fallback}}">当前版本过低，请升级应用版本后使用</view>
<ai-chat tt:else agent-id="ttbc02cabf230bd48016" mode="preview" 
    agent-version="1.21.0"></ai-chat>

Page({
    data: {
        fallback: false,
    },
    onLoad: function() {
        const canIUse = tt.canIUse('ai-agent-chat');
        this.setData({
            fallback: !canIUse
        })
    },
})

这样当运行在不支持的 IDE/客户端中时，系统会展示兜底样式。

JS API 接入

注意
当前隐私协议不支持IDE调试，可使用真机查看真实效果。

说明

本教程提供一个最小化 Demo，JS API 的详细信息，请参见 tt.createAgentManager。

在 AI 开放平台点击预览按钮，可以得到 JSAPI 和会话组件的配置，点击会话组件配置中的复制便可得到组件的代码，示例如下：

const agentManager = tt.createAgentManager({
  agentId: 'ttbc02cabf230bd48016',
  agentVersion: '1.38.0',
  mode: 'preview',
});

开发者调用tt.createAgentManager可以得到一个智能体管理器AgentManager。AgentManager 上一共挂载了3个实例属性和7个实例方法，方法的具体参数见JS API文档。

	类型	说明
agentId	属性	智能体ID
agentVersion	属性	智能体版本
mode	属性	运行模式
init	异步方法	初始化管理器
getAgentInfo	同步方法	获取智能体信息
getChatHistory	异步方法	获取历史对话信息
deleteMessage	异步方法	删除单条消息
createConversation	异步方法	开启新对话
onBoarding	同步方法	拉取开场白
sendMessage	同步方法	发送消息

初始化

在与智能体进行交互之前，我们需要初始化智能体管理器：

// 创建管理器
const agentManager = tt.createAgentManager({
  agentId: 'ttbc02cabf230bd48016',
  agentVersion: '1.38.0',
  mode: 'preview',
});
// 初始化
try {
  const { hasConversation, agentInfo } = await agentManager.init()
} catch (error) {
  console.log(error.errorCode, error.message)
}

调用初始化 API 后，我们会得到一个hasConversation字段，代表当前用户在该智能体下是否存在默认会话。若不存在默认会话，则需要调用开启新对话接口（createConversation）创建新会话，创建完成后新的会话会作为用户的默认会话存储。

if (!hasConversation) {
  // 开启新会话
  await agentManager.createConversation()
}

注意
用户首次访问智能体时不会自动创建默认会话，必须通过检查 hasConversation 字段来判断。后续的历史记录、对话、删除消息等 API，均需依赖默认会话，若不存在则会直接报错。

获取智能体信息

AgentManager.init接口会异步返回当前的智能体信息，包括智能体ID、智能体名称和智能体头像，一旦初始化完成，后续可以调用AgentManager.getAgentInfo方法同步获取智能体信息，返回参数与AgentManager.init接口一致。可以使用智能体名称、头像等信息渲染自定义的UI。

//  const { hasConversation, agentInfo } = await agentManager.init()
const { agentInfo, hasConversation } = agentManager.getAgentInfo()

interface Res {
    hasConversation: boolean;
    agentInfo: {
        agentId: string;   // 智能体ID
        agentName: string; // 智能体名称
        agentIcon: string; // 智能体头像
    }
}

获取历史记录

通过AgentManager.getChatHistory方法，我们可以获取当前会话的历史对话记录。

const { messages, hasMore, nextCursor } = await agentManager.getChatHistory({
    pageSize: 10,
    // cursor: 1,
    // order: 'desc',
  })

方法的输入和输出参数如下：

输入参数：

参数名	类型	说明
pageSize	number	分页尺寸
cursor	number	下一次请求的游标，首次可不传
order	'desc'\|'asc'	排序规则，默认desc

输出参数：

参数名	类型	说明
messages	Message[]	消息数组
hasMore	boolean	是否有更多数据
nextCursor	string	下一次请求的游标

发送消息

通过AgentManager.sendMessage方法，我们可以流式接收和发送消息。当前仅支持文本内容的发送，因此contentType必须为text。

const { message, onMessage, onSuccess, onError, abort } = agentManager.sendMessage({
    content: '你是谁',
    contentType: 'text',
})

console.log('messageToSend', message)

onSuccess(() => {
    console.log('onSuccess')
})

onMessage((message) => {
    console.log('message:', message)
})

onError((error) => {
    console.log('error:', error)
})

AgentManager.sendMessage方法是一个同步方法，会返回正在发送的消息、三个事件回调注册方法和中断消息发送的方法。

当我们开发一个会话流小程序时，我们可以将正在发送的消息加入用户消息列表，onMessage回调会不断接收来自智能体的流式输出，开发者需要自行完成增量渲染。

拉取开场白

通过AgentManager.onBoarding方法，我们可以流式接收开场白信息。

const {  onMessage, onSuccess, onError, abort } = agentManager.onBoarding()


onSuccess(() => {
    console.log('onSuccess')
})

onMessage((message) => {
    console.log('message:', message)
})

onError((error) => {
    console.log('error:', error)
})

删除消息

通过AgentManager.deleteMessage方法，我们可以删除单条消息。

const res = await agentManager.deleteMessage('messageId')

开启新对话

通过 AgentManager.createConversation 方法，我们可以开启一个新对话，智能体将使用新会话中的消息记录生成回答。

const res = await agentManager.createConversation()

完整示例

const app = getApp()

Page({
    data: {
        messages: [],
        value: ''
    },
    init: async function() {
        this.agentManager = tt.createAgentManager({
            agentId: 'ttbc02cabf230bd48016',
            agentVersion: '1.38.0',
            mode: 'preview',
        });

        const {
            hasConversation,
            agentInfo
        } = await this.agentManager.init()

        if (!hasConversation) {
            await this.agentManager.createConversation();
        } else {
            const {
                messages
            } = await this.agentManager.getChatHistory({
                pageSize: 10
            })

            this.setData({
                messages
            })

        }

    },
    handleInput: function(e) {
        console.log(e)
        this.setData({
            value: e.detail.value
        })
    },

    handleSend: function() {
        const {
            message,
            onMessage
        } = this.agentManager.sendMessage({
            contentType: 'text',
            content: this.data.value
        })

        const tempList = [...this.data.messages, message]
        this.setData({
            value: '',
            messages: tempList
        })

        let tempMessage = null
        onMessage((message) => {
            if (!tempMessage) {
                tempMessage = message
            } else {
             tempMessage = {
                    ...tempMessage,
                    ...message,
                    content: {
                        ...message.content,
                        content: tempMessage.content.content + message.content.content
                    }
                }
                tempMessage.content.content += message.content.content
            }

            this.setData({
                value: '',
                messages: [...tempList, tempMessage]
            })
        })

    },
    onLoad: function() {
        this.init()
    },
})

<view class="container">
    <view class="content">
        <view tt:for="{{messages}}" tt:for-item="message" class="message-item">
            <text>role: {{message.role}} | {{message.content.content}}</text>
        </view>
    </view>
    <view class="footer">
        <textarea class="input" placeholder="请输入" bindinput="handleInput" value="{{value}}"></textarea>
        <button class="send" bindtap="handleSend">发送</button>
    </view>
</view>

.footer {
  display: flex;
  padding: 20rpx 20rpx 80rpx;
  flex-shrink: 0;
}

.input {
  border: 1rpx solid black;
  margin-right: 20rpx;
  flex: 1;
}

.send {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100rpx;
}

.container {
  height: 100vh;
  display: flex;
  flex-direction: column;
}

.content {
  flex: 1;
  overflow-y: scroll;
}

.message-item {
  border: 1px solid gray;
  margin-bottom: 16rpx;
  width: 100vw;
  padding: 16rpx;
  overflow: hidden;
  box-sizing: border-box;
}

真机预览

使用抖音客户端扫描 IDE 上的预览码即可在真机查看AI会话组件的效果。JS API 需要开发者自行实现 UI 效果。

常见问题

•

Q：一个页面支持多个AI 会话组件吗？

•

A：不支持，AI会话组件会独占当前页面，开发者编写的其他组件均不会渲染（表现上类似webview组件）。