创建智能体实例

描述

通过向本接口，您可以创建智能体实例，并将智能体实例加入到语音（RTC）对话之中。

接口原型

请求方法：POST
请求地址：https://aigc-aiagent-api.zegotech.cn?Action=CreateAgentInstance
传输协议：HTTPS
调用频率限制：10 次/秒

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
AgentId	String	是	已注册智能体的唯一标识。
UserId	String	是	用于登录 RTC 房间的真实用户 ID。仅支持数字、英文字符、'-'、'_'，长度不得超过 32 字节。
RTC	Object	是	RTC 相关信息。本参数结构，请参考 RTC。
LLM	Object	否	大语言模型参数。本参数结构，请见常用参数说明 - LLM。
TTS	Object	否	文本转语音参数。本参数结构，请见常用参数说明 - TTS。
ASR	Object	否	语音识别参数。本参数结构，请见常用参数说明 - ASR。
MessageHistory	Object	否	供智能体实例使用的历史消息，最多 100 条。本参数结构，请参考 MessageHistory。
CallbackConfig	Object	否	服务端回调配置参数。本参数结构，请参考 CallbackConfig。

RTC

说明

RoomId、AgentStreamId、AgentUserId、UserStreamId 说明如下：

字符限制：仅支持数字、英文字符、‘-’、‘_’。
长度限制：
- RoomId、AgentStreamId、UserStreamId：128 字节。
- AgentUserId：32 字节。

参数	类型	是否必选	描述
RoomId	String	是	RTC 房间 ID。
AgentStreamId	String	是	智能体实例推流使用的流 ID。说明请确保当前运行中的多个智能体实例（即便不再同一个 RTC 房间）使用不同的流 ID，否则会导致后创建的智能体实例推流失败。
AgentUserId	String	是	智能体实例的用户 ID。说明需确保同时在运行中的多个智能体实例（即便不再同一个 RTC 房间）使用不同的用户 ID，否则先创建的智能体实例会被踢出 RTC 房间。
UserStreamId	String	是	真实用户推流使用的流 ID。

MessageHistory

参数	类型	是否必选	描述
SyncMode	Number	否	消息同步模式： 0：从 ZIM 同步。说明使用此模式前，请确认您的项目已开通 ZIM 服务。若该 UserID 未通过 ZIM 客户端登录服务或未在 ZIM 服务端完成注册，实时互动 AI Agent 后台将自动为其执行 ZIM 服务注册流程。建议您提前注册该用户，以便完善用户信息设置并提升智能体实例的创建效率。 1：通过下列 `Messages` 参数同步。
Messages	Array of Object	否	消息列表。本参数结构，请参考 Messages。
WindowSize	Number	否	每次调用 LLM 服务时，以最近多少条历史消息作为上下文。默认 20 条，最大 100 条。取值范围为 [0, 100]。
ZIM	Object	否	ZIM 相关信息。本参数结构，请参考 ZIM。说明仅当 `SyncMode` 为 0 时有效。

Messages

参数	类型	是否必选	描述
Role	String	是	消息发送者角色。取值如下： `user`：用户。 `assistant`：智能体
Content	String	是	发送的内容。

ZIM

参数	类型	是否必选	描述
RobotId	String	否	ZIM 机器人 ID，用于加载用户与该 ZIM 机器人的聊天上下文，并将对话过程中产生的消息同步至 ZIM。如果此参数为空，实时互动 AI Agent 后台将随机生成。
LoadMessageCount	Number	否	创建智能体实例时，从 ZIM 服务获取多少条消息作为上下文。默认为 0，取值不得大于 `WindowSize`。

CallbackConfig

参数	类型	是否必选	描述
ASRResult	Number	否	是否开启服务端回调 ASR结果。 0：不开启（默认）。 1：开启。ZEGO 服务端将会按照每句话返回 ASR 输出结果。请参考通用回调了解如何配置回调地址和具体字段说明。
LLMResult	Number	否	是否开启服务端回调 LLM结果。 0：不开启（默认）。 1：开启。ZEGO 服务端将会按照每句话返回 LLM 输出结果。请参考通用回调了解如何配置回调地址和具体字段说明。

请求示例

请求地址 URL：

Untitled

https://aigc-aiagent-api.zegotech.cn?Action=CreateAgentInstance
&<公共请求参数>

Copied!

请求消息体：

Untitled

{
    "AgentId": "xiaozhi",
    "UserId": "user_1",
    "RtcInfo": {
        "RoomId": "room_1",
        "AgentStreamId": "agent_stream_1",
        "AgentUserId": "agent_user_1",
        "UserStreamId": "user_stream_1"
    }
}

Copied!

响应参数

参数	类型	描述
Code	Number	返回码。0 表示成功，其他值表示失败。如需了解错误码及响应处理建议，请参考返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
Data	Object	返回数据。
└AgentInstanceId	String	智能体实例的唯一标识。

响应示例

Untitled

{
    "Code": 0,
    "Message": "success",
    "RequestId": "3151527792559699732",
    "Data": {
        "AgentInstanceId": "1912122918452641792"
    }
}

Copied!