bot

挂载了 Bot 类的实例，上面集合了一系列与 Agent 交互的方法。具体可参考 Bot 类的详细文档。

使用示例

const agentList = await ai.bot.list({ pageNumber: 1, pageSize: 10 });

Bot

用于与 Agent 交互的类。

get()

获取某个 Agent 的信息。

使用示例

const res = await ai.bot.get({ botId: "botId-xxx" });
console.log(res);

类型声明

function get(props: { botId: string });

参数

参数名	必填	类型	说明
props.botId	是	string	要获取信息的 Agent 的 id

返回值

属性名	类型	示例	说明
botId	string	`"bot-27973647"`	Agent ID
name	string	`"信达雅翻译"`	Agent 名称
introduction	string		Agent 简介
welcomeMessage	string		Agent 欢迎语
avatar	string		Agent 头像链接
background	string		Agent 聊天背景图链接
isNeedRecommend	boolean		Agent 回答后是否推荐问题
type	string		Agent 类型

list()

批量获取多个 Agent 的信息。

使用示例

await ai.bot.list({
  pageNumber: 1,
  pageSize: 10,
  name: "",
  enable: true,
  information: "",
  introduction: "",
});

类型声明

function list(props: {
  name: string;
  introduction: string;
  information: string;
  enable: boolean;
  pageSize: number;
  pageNumber: number;
});

参数

参数名	必填	类型	说明
props.pageNumber	是	number	分页下标
props.pageSize	是	number	分页大小
props.enable	是	boolean	Agent 是否启用
props.name	是	string	Agent 名字，用于模糊查询
props.information	是	string	Agent 信息，用于模糊查询
props.introduction	是	string	Agent 简介，用于模糊查询

返回值

属性名	类型	示例	说明
total	number	---	Agent 总数
botList	`Array<object>`		Agent 列表
`botList[n].botId`	string	`"bot-27973647"`	Agent ID
`botList[n].name`	string	`"信达雅翻译"`	Agent 名称
`botList[n].introduction`	string		Agent 简介
`botList[n].welcomeMessage`	string		Agent 欢迎语
`botList[n].avatar`	string		Agent 头像链接
`botList[n].background`	string		Agent 聊天背景图链接
`botList[n].isNeedRecommend`	boolean		Agent 回答后是否推荐问题
`botList[n].type`	string		Agent 类型

sendMessage()

与 Agent 进行对话。响应会通过 SSE 返回，该接口的返回值对 SSE 做了不同程度的封装，开发者能根据实际需求获取到文本流和完整数据流。

使用示例

const res = await ai.bot.sendMessage({
  botId: "botId-xxx",
  history: [{ content: "你是李白。", role: "user" }],
  msg: "你好",
});
for await (let str of res.textStream) {
  console.log(str);
}
for await (let data of res.dataStream) {
  console.log(data);
}

类型声明

function sendMessage(props: {
  botId: string;
  msg: string;
  history: Array<{
    role: string;
    content: string;
  }>;
}): Promise<StreamResult>;

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.msg	是	string	此次对话要发送的消息
props.history	是	[]	在此次对话前发生的聊天记录
`props.history[n].role`	是	string	本聊天信息的发送角色
`props.history[n].content`	是	string	本聊天信息的内容

返回值

Promise<StreamResult>

StreamResult 属性名	类型	说明
textStream	`AsyncIterable<string>`	以流式返回的 Agent 生成文本，可参考使用示例获取到生成的增量文本。
dataStream	`AsyncIterable<AgentStreamChunk>`	以流式返回的 Agent 生成文本，可参考使用示例获取到生成的增量文本。

AgentStreamChunk 属性名	类型	说明
created	number	对话时间戳
record_id	string	对话记录ID
model	string	大模型类型
version	string	大模型版本
type	string	回复类型： text: 主要回答内容，thinking: 思考过程，search: 查询结果，knowledge: 知识库
role	string	对话角色，响应中固定为 assistant
content	string	对话内容
finish_reasion	string	对话结束标志，continue 表示对话未结束，stop 表示对话结束
reasoning_content	string	深度思考内容（仅deepseek-r1是不为空字符串）
usage	object	token使用量
usage.prompt_tokens	number	表示prompt的tokens数，多次返回中保持不变
usage.completion_tokens	number	回答的token总数，在流式返回中，表示到目前为止所有completion的tokens总数，多次返回中持续累加
usage.total_tokens	number	表示prompt_tokens和completion_tokens之和
knowledge_base	string[]	对话中使用到的知识库
search_info	object	搜索结果信息，需要开启联网查询
search_info.search_results	object[]	搜索引文信息
search_info.search_results[n].index	string	搜索引文序号
search_info.search_results[n].title	string	搜索引文标题
search_info.search_results[n].url	string	搜索引文链接

getChatRecords()

获取聊天记录。

使用示例

await ai.bot.getChatRecords({
  botId: "botId-xxx",
  pageNumber: 1,
  pageSize: 10,
  sort: "asc",
});

类型声明

function getChatRecords(props: {
  botId: string;
  sort: string;
  pageSize: number;
  pageNumber: number;
});

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.sort	是	string	排序方式
props.pageSize	是	number	分页大小
props.pageNumber	是	number	分页下标

返回值

属性名	类型	说明
total	number	对话总数
recordList	`Array<object>`	对话总数
`recordList[n].botId`	string	Agent ID
`recordList[n].recordId`	string	对话 ID，由系统生成
`recordList[n].role`	string	对话中的角色
`recordList[n].content`	string	对话内容
`recordList[n].conversation`	string	用户标识
`recordList[n].type`	string	对话数据类型
`recordList[n].image`	string	对话生成的图片链接
`recordList[n].triggerSrc`	string	对话发起来源
`recordList[n].replyTo`	string	对话回复的记录 ID
`recordList[n].createTime`	string	对话时间

sendFeedback()

发送对某条聊天记录的反馈信息。

使用示例

const res = await ai.bot.sendFeedback({
  userFeedback: {
    botId: "botId-xxx",
    recordId: "recordId-xxx",
    comment: "非常棒",
    rating: 5,
    tags: ["优美"],
    aiAnswer: "落英缤纷",
    input: "来个成语",
    type: "upvote",
  },
  botId: "botId-xxx",
});

类型声明

function sendFeedback(props: { userFeedback: IUserFeedback; botId: string });

参数

参数名	必填	类型	说明
props.userFeedback	是	IUserFeedback	用户反馈，详见 IUserFeedback 类型定义
props.botId	是	string	将要反馈的 Agent id

getFeedback()

获取已存在的反馈信息。

使用示例

const res = await ai.bot.getFeedback({
  botId: "botId-xxx",
  from: 0,
  to: 0,
  maxRating: 4,
  minRating: 3,
  pageNumber: 1,
  pageSize: 10,
  sender: "user-a",
  senderFilter: "include",
  type: "upvote",
});

类型声明

function sendFeedback(props: {
  botId: string;
  type: string;
  sender: string;
  senderFilter: string;
  minRating: number;
  maxRating: number;
  from: number;
  to: number;
  pageSize: number;
  pageNumber: number;
});

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.type	是	string	用户反馈类型，点赞 upvote 点踩 downvote
props.sender	是	string	评论创建用户
props.senderFilter	是	string	评论创建用户过滤关系 include:包含 exclude:不包含 equal:等于 unequal:不等于 prefix:前缀
props.minRating	是	number	最低评分
props.maxRating	是	number	最高评分
props.from	是	number	开始时间戳
props.to	是	number	结束时间戳
props.pageSize	是	number	分页大小
props.pageNumber	是	number	分页下标

返回值

属性名	类型	说明
feedbackList	object[]	反馈查询结果
feedbackList[n].recordId	string	对话记录 ID
feedbackList[n].type	string	用户反馈类型，点赞 upvote 点踩 downvote
feedbackList[n].botId	string	Agent ID
feedbackList[n].comment	string	用户评论
feedbackList[n].rating	number	用户评分
feedbackList[n].tags	string[]	用户反馈的标签数组
feedbackList[n].input	string	用户输入的问题
feedbackList[n].aiAnswer	string	Agent 的回答
total	number	反馈总数

uploadFiles()

将云存储中的文件上传至 Agent，用于进行文档聊天。

使用示例

// 上传文件
await ai.bot.uploadFiles({
  botId: "botId-xxx",
  fileList: [
    {
      fileId: "cloud://xxx.docx",
      fileName: "xxx.docx",
      type: "file",
    },
  ],
});

// 进行文档聊天
const res = await ai.bot.sendMessage({
  botId: "your-bot-id",
  msg: "这个文件的内容是什么",
  files: ["xxx.docx"], // 文件 fileId 数组
});

for await (let text of res.textStream) {
  console.let(text);
}

类型声明

function uploadFiles(props: {
  botId: string;
  fileList: Array<{
    fileId: "string";
    fileName: "string";
    type: "file";
  }>;
});

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.fileList	是	string	文件列表
props.fileList[n].fileId	是	string	云存储文件 id
props.fileList[n].fileName	是	string	文件名
props.fileList[n].type	是	string	暂时只支持 `"file"`

getRecommendQuestions()

获取推荐的问题。

使用示例

const res = ai.bot.getRecommendQuestions({
  botId: "botId-xxx",
  history: [{ content: "你是谁啊", role: "user" }],
  msg: "你好",
  agentSetting: "",
  introduction: "",
  name: "",
});

for await (let str of res.textStream) {
  console.log(str);
}

类型声明

function getRecommendQuestions(props: {
  botId: string;
  name: string;
  introduction: string;
  agentSetting: string;
  msg: string;
  history: Array<{
    role: string;
    content: string;
  }>;
}): Promise<StreamResult>;

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.name	是	string	Agent 名称
props.introduction	是	string	Agent 简介
props.agentSetting	是	string	Agent 设定
props.msg	是	string	用户发送信息
props.history	是	Array	历史对话信息
`props.history[n].role`	是	string	历史信息角色
`props.history[n].content`	是	string	历史信息内容

返回值

Promise<StreamResult>

StreamResult 属性名	类型	说明
textStream	`AsyncIterable<string>`	以流式返回的 Agent 生成文本，可参考使用示例获取到生成的增量文本。
dataStream	`AsyncIterable<AgentStreamChunk>`	以流式返回的 Agent 生成文本，可参考使用示例获取到生成的增量文本。

AgentStreamChunk 属性名	类型	说明
created	number	对话时间戳
record_id	string	对话记录ID
model	string	大模型类型
version	string	大模型版本
type	string	回复类型： text: 主要回答内容，thinking: 思考过程，search: 查询结果，knowledge: 知识库
role	string	对话角色，响应中固定为 assistant
content	string	对话内容
finish_reasion	string	对话结束标志，continue 表示对话未结束，stop 表示对话结束
reasoning_content	string	深度思考内容（仅deepseek-r1是不为空字符串）
usage	object	token使用量
usage.prompt_tokens	number	表示prompt的tokens数，多次返回中保持不变
usage.completion_tokens	number	回答的token总数，在流式返回中，表示到目前为止所有completion的tokens总数，多次返回中持续累加
usage.total_tokens	number	表示prompt_tokens和completion_tokens之和
knowledge_base	string[]	对话中使用到的知识库
search_info	object	搜索结果信息，需要开启联网查询
search_info.search_results	object[]	搜索引文信息
search_info.search_results[n].index	string	搜索引文序号
search_info.search_results[n].title	string	搜索引文标题
search_info.search_results[n].url	string	搜索引文链接

createConversation()

创建与 Agent 的新对话。

使用示例

const res = await ai.bot.createConversation({
  botId: "botId-xxx",
  title: "我的对话",
}): Promise<IConversation>;

类型声明

function createConversation(props: IBotCreateConversation);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.title	否	string	对话标题

返回值

Promise<IConversation>

getConversation()

获取对话列表。

使用示例

const res = await ai.bot.getConversation({
  botId: "botId-xxx",
  pageSize: 10,
  pageNumber: 1,
  isDefault: false,
});

类型声明

function getConversation(props: IBotGetConversation);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.pageSize	否	number	分页大小，默认 10
props.pageNumber	否	number	分页下标，默认 1
props.isDefault	否	boolean	是否只获取默认对话

deleteConversation()

删除指定对话。

使用示例

await ai.bot.deleteConversation({
  botId: "botId-xxx",
  conversationId: "conv-123",
});

类型声明

function deleteConversation(props: IBotDeleteConversation);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.conversationId	是	string	要删除的对话 ID

speechToText()

语音转文字。

使用示例

const res = await ai.bot.speechToText({
  botId: "botId-xxx",
  engSerViceType: "16k_zh",
  voiceFormat: "mp3",
  url: "https://example.com/audio.mp3",
});

类型声明

function speechToText(props: IBotSpeechToText);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.engSerViceType	是	string	引擎类型，如"16k_zh"
props.voiceFormat	是	string	音频格式，如"mp3"
props.url	是	string	音频文件 URL
props.isPreview	否	boolean	是否为预览模式

textToSpeech()

文字转语音。

使用示例

const res = await ai.bot.textToSpeech({
  botId: "botId-xxx",
  voiceType: 1,
  text: "你好，我是AI助手",
});

类型声明

function textToSpeech(props: IBotTextToSpeech);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.voiceType	是	number	语音类型
props.text	是	string	要转换的文本
props.isPreview	否	boolean	是否为预览模式

getTextToSpeechResult()

获取文字转语音的结果。

使用示例

const res = await ai.bot.getTextToSpeechResult({
  botId: "botId-xxx",
  taskId: "task-123",
});

类型声明

function getTextToSpeechResult(props: IBotGetTextToSpeechResult);

参数

参数名	必填	类型	说明
props.botId	是	string	Agent ID
props.taskId	是	string	任务 ID
props.isPreview	否	boolean	是否为预览模式

IBotCreateConversation

interface IBotCreateConversation {
  botId: string;
  title?: string;
}

IBotGetConversation

interface IBotGetConversation {
  botId: string;
  pageSize?: number;
  pageNumber?: number;
  isDefault?: boolean;
}

IBotDeleteConversation

interface IBotDeleteConversation {
  botId: string;
  conversationId: string;
}

IBotSpeechToText

interface IBotSpeechToText {
  botId: string;
  engSerViceType: string;
  voiceFormat: string;
  url: string;
  isPreview?: boolean;
}

IBotTextToSpeech

interface IBotTextToSpeech {
  botId: string;
  voiceType: number;
  text: string;
  isPreview?: boolean;
}

IBotGetTextToSpeechResult

interface IBotGetTextToSpeechResult {
  botId: string;
  taskId: string;
  isPreview?: boolean;
}

BotInfo

interface BotInfo {
  botId: string;
  name: string;
  introduction: string;
  agentSetting: string;
  welcomeMessage: string;
  avatar: string;
  background: string;
  tags: Array<string>;
  isNeedRecommend: boolean;
  knowledgeBase: Array<string>;
  type: string;
  initQuestions: Array<string>;
  enable: true;
}

IUserFeedback

interface IUserFeedback {
  recordId: string;
  type: string;
  botId: string;
  comment: string;
  rating: number;
  tags: Array<string>;
  input: string;
  aiAnswer: string;
}

IConversation

Agent 会话。

interface IConversation {
  id: string;
  envId: string;
  ownerUin: string;
  userId: string;
  conversationId: string;
  title: string;
  startTime: string; // date-time format
  createTime: string;
  updateTime: string;
}

bot​

使用示例​

Bot​

get()​

使用示例​

类型声明​

参数​

返回值​

list()​

使用示例​

类型声明​

参数​

返回值​

sendMessage()​

使用示例​

类型声明​

参数​

返回值​

getChatRecords()​

使用示例​

类型声明​

参数​

返回值​

sendFeedback()​

使用示例​

类型声明​

参数​

getFeedback()​

使用示例​

类型声明​

参数​

返回值​

uploadFiles()​

使用示例​

类型声明​

参数​

getRecommendQuestions()​

使用示例​

类型声明​

参数​

返回值​

createConversation()​

使用示例​

类型声明​

参数​

返回值​

getConversation()​

使用示例​

类型声明​

参数​

deleteConversation()​

使用示例​

类型声明​

参数​

speechToText()​

使用示例​

类型声明​

参数​

textToSpeech()​

使用示例​

类型声明​

参数​

getTextToSpeechResult()​

使用示例​

类型声明​

参数​

IBotCreateConversation​

IBotGetConversation​

IBotDeleteConversation​

IBotSpeechToText​

IBotTextToSpeech​

IBotGetTextToSpeechResult​

BotInfo​

IUserFeedback​

IConversation​

bot

使用示例

Bot

get()

使用示例

类型声明

参数

返回值

list()

使用示例

类型声明

参数

返回值

sendMessage()

使用示例

类型声明

参数

返回值

getChatRecords()

使用示例

类型声明

参数

返回值

sendFeedback()

使用示例

类型声明

参数

getFeedback()

使用示例

类型声明

参数

返回值

uploadFiles()

使用示例

类型声明

参数

getRecommendQuestions()

使用示例

类型声明

参数

返回值

createConversation()

使用示例

类型声明

参数

返回值

getConversation()

使用示例

类型声明

参数

deleteConversation()

使用示例

类型声明

参数

speechToText()

使用示例

类型声明

参数

textToSpeech()

使用示例

类型声明

参数

getTextToSpeechResult()

使用示例

类型声明

参数

IBotCreateConversation

IBotGetConversation

IBotDeleteConversation

IBotSpeechToText

IBotTextToSpeech

IBotGetTextToSpeechResult

BotInfo

IUserFeedback

IConversation