跳到主要内容

AI Agent 接口介绍

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

Agent 使用流程

Agent 数据模型

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

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

Agent 配置

agentConfig 由以下模块组成:conversationStatsEnabledmodelpromptmemoryhooks

基础设置

参数类型必传说明
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 的对话权限删除用户限制记录
查询限制列表批量查看被限制的用户列表查询限制列表