Create An Agent Instance

Description

By sending a request to this API, you can create an agent instance and add the agent instance into a voice (RTC) conversation.

Request prototype

Request method: POST
Request body format: JSON
Request URL: https://aigc-aiagent-api.zegotech.cn?Action=CreateAgentInstance
Transmission protocol: HTTPS
QPS limit: 10 times/second

Request Parameters

Listed below are the parameters specific to this request and part of the common request parameters. For the complete list of common request parameters, see Accessing Server APIs - Common request parameters.

Parameter	Type	Required	Description
AgentId	String	Yes	The unique identifier of a registered agent.
UserId	String	Yes	The real user ID used for logging into the RTC room. Only supports numbers, English characters, '-', '_', and must not exceed 32 bytes in length.
RTC	Object	Yes	RTC related information. For details, see RTC.
LLM	Object	No	Large language model parameters. For details, see Frequently Used Parameters - LLM.
TTS	Object	No	Text-to-speech parameters. For details, see Frequently Used Parameters - TTS.
ASR	Object	No	Automatic speech recognition parameters. For details, see Frequently Used Parameters - ASR.
MessageHistory	Object	No	Historical messages for use by the AI agent instance, up to 100 entries. For details, see MessageHistory.
CallbackConfig	Object	No	Server callback configuration parameters. For details, see CallbackConfig.
AdvancedConfig	Object	No	Advanced configuration. For details, see AdvancedConfig.

RTC

Note

The explanation for RoomId, AgentStreamId, AgentUserId, and UserStreamId is as follows:

Character restrictions: Only numbers, English letters, '-', and '_' are supported.
Length limits:
- RoomId, AgentStreamId, UserStreamId: 128 bytes.
- AgentUserId: 32 bytes.

Parameter	Type	Required	Description
RoomId	String	Yes	RTC room ID.
AgentStreamId	String	Yes	Stream ID used by the AI agent instance for publishing a stream. Note Ensure that multiple existing AI agent instances (even if not in the same RTC room) use different stream IDs; otherwise, it will cause the stream-publishing from the AI agent instance created later to fail.
AgentUserId	String	Yes	User ID of the AI agent instance. Note Ensure that multiple existing AI agent instances (even if not in the same RTC room) use different user IDs; otherwise, the AI agent instance created earlier will be kicked out of the RTC room.
UserStreamId	String	Yes	Stream ID used by the real user for publishing a stream.

MessageHistory

Parameter	Type	Required	Description
SyncMode	Number	No	Message synchronization mode: 0: Synchronize from In-app Chat. Note Before using this mode, please ensure that your project has enabled the In-app Chat service. If the UserID has not logged in via the In-app Chat client or registered on the In-app Chat server, the ZEGOCLOUD AI Agent server will automatically execute the In-app Chat service registration for it. We recommend you register this user in advance to improve user information settings and enhance the efficiency of creating AI agent instances. 1: Synchronize through the following `Messages` parameter.
Messages	Array of Object	No	Message list. For details, see Messages
WindowSize	Number	No	The number of recent historical messages used as context each time the LLM service is called. Default is 20, maximum is 100. Value range is [0, 100].
ZIM	Object	No	In-app Chat(ZIM) information. For details, see ZIM. Note Only valid when `SyncMode` is 0.

Messages

Parameter	Type	Required	Description
Role	String	Yes	The role of the message sender. Possible values: `user`: User. `assistant`: AI Agent.
Content	String	Yes	The content to be sent.

ZIM

Parameter	Type	Required	Description
RobotId	String	No	In-app Chat robot ID, used to load the chat context between the user and the In-app Chat robot, and synchronize messages generated during the conversation to In-app Chat. If this parameter is empty, the ZEGOCLOUD AI Agent server will randomly generate one. Note To know how to get a In-app Chat robot ID, read the In-app Chat docs Register Bots。
LoadMessageCount	Number	No	When creating an AI agent instance, how many messages are obtained from the In-app Chat service as context. The default is the value of `WindowSize` (upper limit).

CallbackConfig

Parameter	Type	Required	Description
ASRResult	Number	No	Whether to enable server-side callback for ASR results. 0: Disabled (default). 1: Enabled. The ZEGOCLOUD server will return ASR output results for each sentence. Refer to Receiving Callback for information on how to configure the callback address and specific field descriptions.
LLMResult	Number	No	Whether to enable server-side callback for LLM results. 0: Disabled (default). 1: Enabled. The ZEGOCLOUD server will return LLM output results for each sentence. Refer to Receiving Callback for information on how to configure the callback address and specific field descriptions.
Interrupted	Number	No	Whether to enable server-side callback for agent interruption results. 0: Disabled (default). 1: Enabled.
UserSpeakAction	Number	No	Whether to enable server-side callback for user speaking events. 0: Disabled (default). 1: Enabled.
AgentSpeakAction	Number	No	Whether to enable server-side callback for agent speaking events. 0: Disabled (default). 1: Enabled.
UserAudioData	Number	No	Whether to enable server-side callback for user speaking audio data. 0: Disabled (default). 1: Enabled.

AdvancedConfig

Parameter	Type	Required	Description
InterruptMode	Number	No	Whether the AI agent can be interrupted by user's voice during response: 0: Yes (default). 1: No, meaning ASR will only start after the AI agent's voice output is complete.

Sample Request

Request URL:

Untitled

https://aigc-aiagent-api.zegotech.cn?Action=CreateAgentInstance
&<Common Request Parameters>

Copied!

Request body:

Untitled

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

Copied!

Response Parameters

Parameter	Type	Description
Code	Number	The return code. 0 indicates success, and other values indicate failure. For code explanations and processing suggestions, see Return codes.
Message	String	Explanation of the request result.
RequestId	String	Request ID.
Data	Object	Returned data.
└AgentInstanceId	String	Unique identifier for the AI agent instance.

Sample Response

Untitled

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

Copied!