CreateAgentInstance
https://aigc-aiagent-api.zegotech.cn/
通过本接口，您可以创建智能体实例，并将智能体实例加入到语音（RTC）对话之中。
- 如果创建智能体实例的用户超过 120 秒（可通过 AdvancedConfig.MaxIdleTime 参数自定义）不在 RTC 房间内，则智能体实例会自动销毁，并触发 Event 为 AgentInstanceDeleted 的回调，Data.Code 为 1202。
- 默认情况下一个账号下最多同时存在 10 个智能体实例，超过限制后创建智能体实例会失败，如需调整请联系 ZEGO 商务。
Request
Query Parameters
可选值: [CreateAgentInstance]
接口原型参数
https://aigc-aiagent-api.zegotech.cn?Action=CreateAgentInstance
💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台 获取。
💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考 签名示例。
💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考 签名示例，最多允许 10 分钟的误差。
💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。
可选值: [2.0]
默认值: 2.0
💡公共参数。签名版本号。
- application/json
Body
required
- OpenAIChat：OpenAI 的 Chat Completions 接口类型。
- OpenAIResponses：OpenAI 的 Responses API 接口类型。
- MiniMax：https://api.minimax.chat/v1/text/chatcompletion_v2
- 火山引擎（豆包）：https://ark.cn-beijing.volces.com/api/v3/chat/completions
- 阿里云百炼（通义千问）：https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
- 阶跃星辰：https://api.stepfun.com/v1/chat/completions
- MiniMax：
- MiniMax-Text-01
- 火山引擎（豆包）：
- doubao-1-5-pro-32k-250115
- doubao-1-5-lite-32k-250115
- 阿里云百炼（通义千问）：
- qwen-plus
- 阶跃星辰：
- step-2-16k
- room_id: 房间 ID
- user_id: 用户 ID
- agent_instance_id: 智能体实例 ID
- 需要在 LLM > SystemPrompt 中定义哪些内容应该放在指定标点符号内
- 此参数在更新智能体实例时无法更新
- Array[
- ]
- 0: 从即时通讯 (ZIM) 同步
- 1: 通过 Messages 参数同步
- Array[
- user: 用户
- assistant: 智能体
- ]
- 0: 立即打断。如果在 AI 说话时用户说话，那么 AI 将被立刻打断，停止说话。
- 1: 不打断。如果在 AI 说话时用户说话，那么 AI 不会被影响直到内容说完。
已注册的智能体唯一标识符
可选值: <= 32 characters
与该 AI Agent 实例交互的真实用户 ID。 仅支持数字、英文字符、'-'、'_'。
RTC objectrequired
RTC 相关信息
📌 重要说明
所有属性字符限制：仅支持数字、英文字符、'_'、'-'、'.'。
可选值: <= 128 characters
RTC 房间 ID。
可选值: <= 128 characters
智能体实例推流使用的流 ID。
📌 重要说明
请确保当前运行中的多个智能体实例（即便不在同一个 RTC 房间）使用不同的流 ID，否则会导致后创建的智能体实例推流失败。
可选值: <= 32 characters
智能体实例的用户 ID。
📌 重要说明
需确保同时在运行中的多个智能体实例（即便不在同一个 RTC 房间）使用不同的用户 ID，否则先创建的智能体实例会被踢出 RTC 房间。
可选值: <= 128 characters
真实用户推流使用的流 ID。
LLM object
可选值: [OpenAIChat, OpenAIResponses]
默认值: OpenAIChat
LLM 接口的供应商类别。
接收请求的端点（可以是你自己的服务，也可以是任何 LLM 服务提供商提供的服务）。
如果 Vendor 为 OpenAIChat ，则必须兼容 OpenAI Chat Completions API。
例如：https://api.openai.com/v1/chat/completions
如果 Vendor 为 OpenAIResponses ，则必须兼容 OpenAI Responses API。
例如：https://ark.cn-beijing.volces.com/api/v3/responses
📌 重要说明
如果 ApiKey 设置为 "zego_test"，则必须使用以下 Url 地址之一：
LLM 服务提供商用于认证的参数。默认为空，但在生产环境中必须提供。
📌 重要说明
在接入测试期间(AI Agent 服务开通 2 周内)，可以将该参数值设置为 "zego_test" 即可使用该服务。
LLM 模型。不同的 LLM 服务提供商支持不同的模型，请参考其官方文档选择合适的模型。
📌 重要说明
如果 ApiKey 设置为 "zego_test"，则必须使用以下模型之一：
智能体系统提示（prompt）。调用 LLM 时附加在最前的预定义信息，用于控制 LLM 输出。可以是角色设定、提示词和回答样例等。
可选值: >= 0 and <= 2
默认值: 0.7
数值越高，输出越随机；数值越低，输出越集中和确定。
可选值: >= 0 and <= 1
默认值: 0.9
采样方法，数值越小，确定性越强；数值越大，随机性越强。
LLM 服务提供商支持的其他参数，如最大 Token 数量限制等。不同的 LLM 提供商支持不同的参数，请参考其官方文档并根据需要填写。
默认值: false
如果此值为 true，AI Agent 服务器在请求 LLM 服务时会在请求参数中包含智能体信息（agent_info）。包含的智能体信息数示例请参考使用自定义 LLM。 您可以使用此参数在自定义 LLM 服务中执行额外的业务逻辑。
agent_info 的结构如下：
📌 重要说明：仅在 Vendor 为 "OpenAIChat" 时有效。
AgentExtraInfo object
额外信息键。
额外信息值，可以是任意类型。
TTS object
可选值: [Aliyun, ByteDance, ByteDanceV3, ByteDanceFlowing, MiniMax, CosyVoice]
语音合成（TTS）服务提供商。详细请参考配置 TTS > TTS 参数说明
Params objectrequired
用于 TTS 服务鉴权，不同的 Vendor 值要求传入的 app 参数的结构不同，详细请参考配置 TTS > Params 参数说明
📌 重要说明
other_params 不是一个有效参数，仅仅是为了说明如何透传厂商参数。 除 app 参数外，其余参数均直接透传厂商参数。详细请参考配置 TTS > Params 参数说明
FilterText object[]
从 LLM 返回的内容中过滤指定标点符号内的文本，然后再进行语音合成。注意：
过滤文本的开始标点符号。例如，如果要过滤 () 中的内容，请设置为 (。
过滤文本的结束标点符号。例如，如果要过滤 () 中的内容，请设置为 )。
可选值: <= 4 characters
可用于设置 TTS 的终止文本。若输入 TTS 的文本中出现匹配 TerminatorText 字符串的内容，则本轮 TTS 从 TerminatorText 字符串（包含）开始的内容将不再进行语音合成。
📌 重要说明
双向流式只能设置一个字符。
ASR object
可选值: [Tencent, AliyunParaformer, AliyunGummy, Microsoft]
默认值: Tencent
ASR 厂商。可参考配置 ASR 参数说明。
厂商参数，具体使用方式参考配置 ASR 中的 Params 参数说明。
可选值: >= 200 and <= 2000
默认值: 500
用于设置用户说话停顿多少秒后，不再将两句话视为一句。 单位为 ms，范围 [200，2000]，默认为 500。 详细说明请参考语音识别断句。
📌 重要说明
当 Vendor 为 "Tencent" （默认）时，最大值为 1500。
可选值: >= 200 and <= 2000
用于设置用户说话停顿多少秒内，将两句话视为一句，即 ASR 多句拼接。 单位为 ms，范围 [200，2000]。 仅当此值大于 VADSilenceSegmentation 时，才会启用 ASR 多句拼接。 详细说明请参考语音识别断句。
该参数已废弃。请通过 Params 厂商参数设置。
MessageHistory object
可选值: [0, 1]
默认值: 0
消息同步模式：
Messages object[]
<= 100可选值: [user, assistant]
消息发送者的角色
消息内容
可选值: >= 0 and <= 500
默认值: 20
每次调用 LLM 服务时使用的近期历史消息数量。影响 LLM 上下文理解能力，建议设置为 10-30。
ZIM object
📌 重要说明
- 仅当 MessageHistory.SyncMode 为 0 时有效。
- 请确保您的项目已开通 ZIM 服务。
- 请确保已调用 ZIM 机器人注册接口，并将返回的 UserInfo.UserId 作为 RobotId。
- 建议您提前注册机器人，以便完善用户信息设置并提升智能体实例的创建效率。
ZIM 机器人 ID。即调用 ZIM 注册机器人接口对应的 UserInfo.UserId 。用于加载用户与该 ZIM 机器人的聊天上下文，并将对话过程中产生的消息同步至 ZIM。如果此参数为空，实时互动 AI Agent 后台将随机生成。
可选值: >= 0 and <= 500
创建智能体实例时，从 ZIM 服务获取多少条消息作为上下文。默认为 WindowSize 的值（取值上限）。
CallbackConfig object
📌 重要说明
在配置以下参数前，你需要参考 接收回调 设置好回调地址，并了解具体字段说明。
可选值: [0, 1]
默认值: 0
是否开启服务端回调 ASR 结果。
可选值: [0, 1]
默认值: 0
是否开启服务端回调 LLM 结果。如果开启，则 ZEGO 服务端将会按照每句话返回 LLM 输出结果。
可选值: [0, 1]
默认值: 0
是否开启服务端回调智能体被打断结果。
可选值: [0, 1]
默认值: 0
是否开启服务端回调用户说话的回调。
可选值: [0, 1]
默认值: 0
是否开启服务端回调智能体实例状态的回调。
可选值: [0, 1]
默认值: 0
是否开启服务端回调用户说话音频数据。
AdvancedConfig object
可选值: [0, 1]
默认值: 0
智能体说话时被用户语音打断的模式：
可选值: >= 10 and <= 1800
默认值: 120
智能体实例的自动销毁时间。创建实例的用户（UserId）若超过 MaxIdleTime 不在 RTC 房间内，则智能体实例会自动销毁，并触发 Event 为 AgentInstanceDeleted 的回调，Data.Code 为 1202。默认为 120s，取值范围 [10, 1800]。
默认值: false
是否禁用 TTS 功能。如果设置为 true，则智能体实例不会进行语音合成。
📌 重要说明
DisableTTS 为 true 时，调用创建数字人智能体实例及主动调用 TTS接口都会报错。
Responses
- 200
- application/json
- 数据结构
- 按数据结构生成的示例
Schema
返回码，0 表示成功，其他值表示失败。详情请参考 返回码 说明。
请求结果说明
请求 ID
Data object
智能体实例的唯一标识。
{
"Code": 0,
"Message": "Success",
"RequestId": "3151527792559699732",
"Data": {
"AgentInstanceId": "1912122918452641792"
}
}{
"Code": 0,
"Message": "Success",
"RequestId": "3151527792559699732",
"Data": {
"AgentInstanceId": "1912122918452641792"
}
}