跳到主要内容

AI Agent 接口介绍

融云提供 AI Agent 管理与接入能力，帮助您快速构建智能对话与任务执行系统。您可以在应用中创建 Agent，通过配置模型、提示词和记忆等参数，实现智能交互与任务处理。

Agent 使用流程​

Agent 数据模型​

下表展示 Agent 资源的常见顶层属性：

属性名称类型说明
agentIdStringAgent 唯一标识，建议长度 3–64 个字符。
nameStringAgent 名称，建议长度 2–128 个字符。
descriptionStringAgent 描述，长度 ≤ 256 个字符。
typeStringAgent 类型，当前仅支持 chat。
statusStringAgent 状态，可选：active、inactive、draft。
createdAtLong创建时间的 Unix 时间戳（毫秒）。
updatedAtLong最近更新时间的 Unix 时间戳（毫秒）。
agentConfigObjectAgent 配置对象，见下方"Agent 配置"模块。

Agent 配置​

agentConfig 由以下模块组成：conversationStatsEnabled、model、prompt、memory、hooks。

基础设置​

参数类型必传说明
conversationStatsEnabledBoolean否是否开启对话统计，默认 false。开启后统计对话轮数和天数，用于 Hooks 条件判断。

模型配置​

参数类型必传说明
model.nameString是模型名称。
model.optionsObject否模型选项配置。

参考：模型可用列表

模型选项​

参数类型必传说明
model.options.temperatureDouble否随机性控制，范围 0.0–2.0。
model.options.topPDouble否核采样，范围 0.0–1.0。
model.options.maxTokensInt否最大输出 tokens，范围 1–8192。
model.options.frequencyPenaltyDouble否频率惩罚，范围 -2.0–2.0。
model.options.presencePenaltyDouble否存在惩罚，范围 -2.0–2.0。
model.options.stopString[]否停止词列表，最多 10 个，每个 ≤ 50 字符。

提示词配置​

参数类型必传说明
prompt.idString否系统指令模板 ID，长度 0–64 字符。
prompt.variablesMap<String, String>否系统指令模板变量，用于替换模板中的占位符。
prompt.instructionsString否系统指令，长度 ≤ 10000 字符。当填写了系统指令模板 ID（prompt.id）时，该项可不填。

参考：提示词模板

记忆配置​

参数类型必传说明
memory.providerString否记忆存储来源，用于指定对话上下文的获取方式。可选值：
- default：使用系统默认存储获取上下文信息。
- history：从 IM 历史消息中获取上下文信息，用于复用已有对话记录。
memory.strategyString否记忆策略，当前仅支持：
  • sliding_window：消息数量限制 - 维护对话历史，但确保总消息数不超过设定的最大值。
memory.maxMessagesInt否最大记忆消息数，范围 1–150。当 strategy=sliding_window 时建议填写。

Hooks 配置​

参数类型必传说明
hooksArray<Object>否对话前拦截钩子配置，支持意图检测、条件触发等功能。详见 配置 Agent Hooks。

使用方式​

机器人已原生支持 AI Agent。您可以通过以下两种方式使用 Agent：

  1. 机器人回调通道（被动触发）

    当用户向机器人发送私聊消息或在群聊中 @ 机器人时，平台将基于 Agent 配置触发推理并返回结果。

  2. 服务端 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 的对话权限删除用户限制记录
查询限制列表批量查看被限制的用户列表查询限制列表
最后于 更新