AI Agent 接口介绍
融云提供 AI Agent 管理与接入能力,帮助您快速构建智能对话与任务执行系统。您可以在应用中创建 Agent,通过配置模型、提示词和记忆等参数,实现智能交互与任务处理。
Agent 使用流程
Agent 数据模型
下表展示 Agent 资源的常见顶层属性:
| 属性名称 | 类型 | 说明 |
|---|---|---|
agentId | String | Agent 唯一标识,建议长度 3–64 个字符。 |
name | String | Agent 名称,建议长度 2–128 个字符。 |
description | String | Agent 描述,长度 ≤ 256 个字符。 |
type | String | Agent 类型,当前仅支持 chat。 |
status | String | Agent 状态,可选:active、inactive、draft。 |
createdAt | Long | 创建时间的 Unix 时间戳(毫秒)。 |
updatedAt | Long | 最近更新时间的 Unix 时间戳(毫秒)。 |
agentConfig | Object | Agent 配置对象,见下方"Agent 配置"模块。 |
Agent 配置
agentConfig 由以下模块组成:conversationStatsEnabled、model、prompt、memory、hooks。
基础设置
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
conversationStatsEnabled | Boolean | 否 | 是否开启对话统计,默认 false。开启后统计对话轮数和天数,用于 Hooks 条件判断。 |
模型配置
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
model.name | String | 是 | 模型名称。 |
model.options | Object | 否 | 模型选项配置。 |
参考:模型可用列表
模型选项
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
model.options.temperature | Double | 否 | 随机性控制,范围 0.0–2.0。 |
model.options.topP | Double | 否 | 核采样,范围 0.0–1.0。 |
model.options.maxTokens | Int | 否 | 最大输出 tokens,范围 1–8192。 |
model.options.frequencyPenalty | Double | 否 | 频率惩罚,范围 -2.0–2.0。 |
model.options.presencePenalty | Double | 否 | 存在惩罚,范围 -2.0–2.0。 |
model.options.stop | String[] | 否 | 停止词列表,最多 10 个,每个 ≤ 50 字符。 |
提示词配置
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
prompt.id | String | 否 | 系统指令模板 ID,长度 0–64 字符。 |
prompt.variables | Map<String, String> | 否 | 系统指令模板变量,用于替换模板中的占位符。 |
prompt.instructions | String | 否 | 系统指令,长度 ≤ 10000 字符。当填写了系统指令模板 ID(prompt.id)时,该项可不填。 |
参考:提示词模板
记忆配置
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
memory.provider | String | 否 | 记忆存储来源,用于指定对话上下文的获取方式。可选值: - default:使用系统默认存储获取上下文信息。- history:从 IM 历史消息中获取上下文信息,用于复用已有对话记录。 |
memory.strategy | String | 否 | 记忆策略,当前仅支持:
|
memory.maxMessages | Int | 否 | 最大记忆消息数,范围 1–150。当 strategy=sliding_window 时建议填写。 |
Hooks 配置
| 参数 | 类型 | 必传 | 说明 |
|---|---|---|---|
hooks | Array<Object> | 否 | 对话前拦截钩子配置,支持意图检测、条件触发等功能。详见 配置 Agent Hooks。 |
使用方式
机器人已原生支持 AI Agent。您可以通过以下两种方式使用 Agent:
-
机器人回调通道(被动触发)
当用户向机器人发送私聊消息或在群聊中 @ 机器人时,平台将基于 Agent 配置触发推理并返回结果。
-
服务端 API(主动触发)
直接调用对话接口 对话生成,支持流式与非流式返回。
提示
复用现有机器人集成能力,无需自建中间层,即可将 Agent 能力用于 IM 会话内的对话与应答。
相关文档
Agent 管理
| 功能 | 说明 | 文档 |
|---|---|---|
| 创建 Agent | 创建一个新的 AI Agent,用于对话与任务执行 | 创建 Agent |
| 更新 Agent | 更新指定 Agent 的信息和配置 | 更新 Agent |
| 获取指定 Agent | 获取指定 Agent 的详细信息 | 获取指定 Agent |
| 列出 Agent | 分页查询 Agent 列表 | 列出 Agent |
| 删除 Agent | 删除指定的 Agent | 删除 Agent |
Agent 配置
| 功能 | 说明 | 文档 |
|---|---|---|
| 配置 Hooks | 配置对话前拦截钩子,支持意图检测、条件触发等 | 配置 Agent Hooks |
| Hooks 回调 | Hooks 触发时的 Webhook 回调说明 | Agent Hooks 回调 |
| 模型列表 | 查看支持的大语言模型列表 | 模型可用列表 |
| 提示词模板 | 查看内置的提示词模板 | 提示词模板 |
对话接口
| 功能 | 说明 | 文档 |
|---|---|---|
| 对话生成 | 发起对话生成,获取 Agent 的回复(支持流式/非流式) | 对话生成 |
对话限制
| 功能 | 说明 | 文档 |
|---|---|---|
| 添加用户限制 | 限制用户与指定 Agent 的对话权限 | 添加用户限制 |
| 获取用户限制记录 | 查看用户是否被限制使用指定 Agent | 获取用户限制记录 |
| 删除用户限制记录 | 恢复用户与指定 Agent 的对话权限 | 删除用户限制记录 |
| 查询限制列表 | 批量查看被限制的用户列表 | 查询限制列表 |