创建智能体实例

描述

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

接口原型

请求方法：POST
请求体格式：JSON
请求地址：https://aigc-aiagent-api.zegotech.cn?Action=CreateDigitalHumanAgentInstance
传输协议：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。
AdvancedConfig	Object	否	高级配置。本参数结构，请参考 AdvancedConfig。

参数	类型	是否必选	描述
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。
AdvancedConfig	Object	否	高级配置。本参数结构，请参考 AdvancedConfig。
DigitalHuman	Object	否	数字人参数。本参数结构，请参考 DigitalHuman。

DigitalHuman

参数	类型	是否必选	描述
DigitalHumanId	String	是	数字人形象 ID。
ConfigId	String	是	数字人配置 ID，可选 mobile、web。
EncodeCode	String	否	数字人流的视频编码格式，支持 H264、VP8，默认 H264。

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 注册机器人接口对应的`UserInfo.UserId`。用于加载用户与该 ZIM 机器人的聊天上下文，并将对话过程中产生的消息同步至 ZIM。如果此参数为空，实时互动 AI Agent 后台将随机生成。
LoadMessageCount	Number	否	创建智能体实例时，从 ZIM 服务获取多少条消息作为上下文。默认为 `WindowSize` 的值（取值上限）。

CallbackConfig

说明

在配置以下参数前，你需要参考接收回调回调地址，并了解具体字段说明。

参数	类型	是否必选	描述
ASRResult	Number	否	是否开启服务端回调 ASR结果。 0：不开启（默认）。 1：开启。ZEGO 服务端将会按照每句话返回 ASR 输出结果。
LLMResult	Number	否	是否开启服务端回调 LLM结果。 0：不开启（默认）。 1：开启。ZEGO 服务端将会按照每句话返回 LLM 输出结果。
Interrupted	Number	否	是否开启服务端回调智能体被打断结果。 0：不开启。（默认） 1：开启。
UserSpeakAction	Number	否	是否开启服务端回调用户说话的回调。 0：不开启。（默认） 1：开启。
AgentSpeakAction	Number	否	是否开启服务端回调Agent说话的回调。 0：不开启。（默认） 1：开启。
UserAudioData	Number	否	是否开启服务端回调用户说话音频数据。 0：不开启。（默认） 1：开启。

AdvancedConfig

参数	类型	是否必选	描述
InterruptMode	Int	否	智能体说话时被用户语音打断的模式： 0：立即打断。如果在 AI 说话时用户说话，那么 AI 将被立刻打断，停止说话（默认）。 1: 不打断。如果在 AI 说话时用户说话，那么 AI 不会被影响直到内容说完。

请求示例

请求地址 URL：

Untitled

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

Copied!

请求消息体：

Untitled

{
    "AgentId": "xiaozhi",
    "UserId": "user_1",
    "RTC": {
        "RoomId": "room_1",
        "AgentStreamId": "agent_stream_1",
        "AgentUserId": "agent_user_1",
        "UserStreamId": "user_stream_1"
    },
    "DigitalHuman" : {
        "DigitalHumanId": "xiaozhi",
        "EncodeCode" : "H264",
        "ConfigId" : "mobile"
    }
}

Copied!

响应参数

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

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

响应示例

Untitled

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

Copied!