logo
ConsoleSign Up
AI Agent
Server
Introduction
Overview
Download SDK and Demo
Release Notes
Quick Start
Quick Start Voice Call
Quick Start Digital Human Video Call
Connect to ZEGOCLOUD Document MCP Serverlink
Basic
Configuring LLM
Configuring ASR
Configuring TTS
AI Proactive Speech: Proactively Invoke LLM or TTS
Display Subtitles
Display User And Agent Status
Get AI Agent Status
Interrupt Agent
Advanced
Best Practices
API Reference
Overview
Accessing Server APIs
Call API Online
Return Codes
Agent Configuration Management
Agent Instance Management
Agent Instance Control
Callback
FAQ
On this page

ListAgents

POST

https://aigc-aiagent-api.zegotech.cn/

By calling this API, you can obtain a list of available AI agents.

Request

Query Parameters

    Action stringrequired

    Possible values: [ListAgents]

    API Prototype Parameter

    https://aigc-aiagent-api.zegotech.cn?Action=ListAgents

    AppId uint32required

    💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

    SignatureNonce stringrequired

    💡Public parameter. A 16-character hexadecimal random string (hex encoding of 8-byte random number). Refer to Signature sample code for how to generate.

    Timestamp int64required

    💡Public parameter. Current Unix timestamp, in seconds. Refer to Signature sample code for how to generate, with a maximum error of 10 minutes.

    Signature stringrequired

    💡Public parameter. Signature, used to verify the legitimacy of the request. Refer to Signing the requests for how to generate an API request signature.

    SignatureVersion stringrequired

    Possible values: [2.0]

    Default value: 2.0

    💡Public parameter. Signature version number.

Body

required
    Limit integer

    Possible values: >= 0 and <= 10

    Default value: 5

    The number of AI agent information entries to retrieve in one request. The value range is [0, 10]. If not filled or the value is 0, it defaults to 5. If the value is less than 0 or greater than 10, the API request will return an error.

    Cursor string

    Pagination retrieval marker. Leave blank for the first request, then fill in the Cursor value returned from the previous response. When the returned Cursor is empty, it indicates that the list of AI agents has been fully retrieved.

Responses​

Success
Schema
    Code integer

    Return code. 0 indicates success, other values indicate failure. For more information on error codes and response handling recommendations, please refer to Return Codes.

    Message string

    Explanation of the request result

    RequestId string

    Request ID

    Data object
    Total integer

    Total number of AI agents that meet the query criteria

    Agents object[]
    AI Agent list
  • Array[
    • AgentId string

    AI agent unique identifier

    Name string

    AI agent name

    LLM object
    Vendor string

    Possible values: [OpenAIChat, OpenAIResponses]

    Default value: OpenAIChat

    The vendor type of the LLM interface.

    • OpenAIChat: OpenAI's Chat Completions interface type.
    • OpenAIResponses: OpenAI's Responses API interface type.
    Url stringrequired

    The endpoint that receives the request (can be your own service or any LLM service provider's service). If Vendor is OpenAIChat, it must be compatible with OpenAI Chat Completions API. For example: https://api.openai.com/v1/chat/completions

    If Vendor is OpenAIResponses, it must be compatible with OpenAI Responses API. For example: https://ark.cn-beijing.volces.com/api/v3/responses

    📌 Important Note

    If ApiKey is set to "zego_test", you must use one of the following Url addresses:

    • MiniMax：https://api.minimax.chat/v1/text/chatcompletion_v2
    • Volcano Engine (Doubao): https://ark.cn-beijing.volces.com/api/v3/chat/completions
    • Aliyun Bailei (Tongyi Qianwen): https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
    • Stepfun: https://api.stepfun.com/v1/chat/completions
    ApiKey string

    The parameter used for authentication by the LLM service provider. It is empty by default, but must be provided in production environments.

    📌 Important Note

    During the test period (within 2 weeks after the AI Agent service is enabled), you can set this parameter value to "zego_test" to use this service.

    Model stringrequired

    The LLM model. Different LLM service providers support different models, please refer to their official documentation to select the appropriate model.

    📌 Important Note

    If ApiKey is set to "zego_test", you must use one of the following models:

    • MiniMax:
      • MiniMax-Text-01
    • Volcano Engine (Doubao):
      • doubao-1-5-pro-32k-250115
      • doubao-1-5-lite-32k-250115
    • Aliyun Bailei (Tongyi Qianwen):
      • qwen-plus
    • Stepfun:
      • step-2-16k
    SystemPrompt string

    The system prompt of the AI agent. It is the predefined information that is added at the beginning when calling the LLM, used to control the output of the LLM. It can be role settings, prompts, and answer examples.

    Temperature number

    Possible values: >= 0 and <= 2

    Default value: 0.7

    The higher the value, the more random the output; the lower the value, the more concentrated and determined the output.

    TopP number

    Possible values: >= 0 and <= 1

    Default value: 0.9

    The sampling method. The smaller the value, the stronger the determinism; the larger the value, the stronger the randomness.

    Params object

    Other parameters supported by the LLM service provider, such as the maximum token limit. Different LLM providers support different parameters, please refer to their official documentation and fill in as needed.

    AddAgentInfo boolean

    Default value: false

    If this value is true, the AI Agent server will include the AI agent information(agent_info) in the request parameters when requesting the LLM service. The example of the AI agent information is as follows: Using Custom LLM. You can use this parameter to execute additional business logic in your custom LLM service.

    The structure of agent_info is as follows:

    • room_id: RTC room ID
    • user_id: User ID
    • agent_instance_id: AI agent instance ID

    📌 Important Note: Only effective when Vendor is "OpenAIChat".

    AgentExtraInfo object
    Agent extra information, the server will pass this parameter in the request parameters when requesting the LLM service. The example of the extra information is as follows: Using Custom LLM.You can use this parameter to execute additional business logic in your custom LLM service.📌 Important Note: Only effective when Vendor is "OpenAIChat".
    key string

    Extra information key.

    value

    Extra information value, can be of any type.

    TTS object
    Vendor stringrequired

    Possible values: [Aliyun, ByteDance, ByteDanceV3, ByteDanceFlowing, MiniMax, CosyVoice]

    The TTS service provider. Please refer to Configuring TTS > TTS Parameters for details.

    Params objectrequired
    TTS configuration parameters, in JSON object format. Contains app parameters (for authentication) and other parameters (for adjusting TTS effects). Please refer to Configuring TTS > Params Parameters for details.
    app objectrequired

    Used for TTS service authentication, the structure of the app parameter required by different Vendor values is different, please refer to Configuring TTS > Params Parameters for details.

    other_params string

    📌 Important Note

    other_params is not a valid parameter, it is only to explain how to pass the vendor parameters. Except for the app parameter, other parameters are directly passed to the vendor parameters. Please refer to Configuring TTS > Params Parameters for details.

    FilterText object[]
    Filters out the text enclosed by specified punctuation marks from the input content to TTS (usually the content returned by LLM or the Text parameter of the SendAgentInstanceTTS API), and then performs speech synthesis. For example, in “(happily said) Welcome to ZEGOCLOUD!”, the content within the parentheses is filtered out before synthesis.
    Note
    - Typically, you guide the LLM via prompts in LLM > SystemPrompt to specify which parts of the content should be enclosed within particular punctuation.
    - This parameter cannot be updated when updating an agent instance.
  • Array[
    • BeginCharacters stringrequired

    The start punctuation mark of the filtered text. For example, if you want to filter the content in (), set it to (.

    EndCharacters stringrequired

    The end punctuation mark of the filtered text. For example, if you want to filter the content in (), set it to ).

  • ]
    • TerminatorText string

    Possible values: <= 4 characters

    Can be used to set the termination text for TTS. If the input to TTS (usually the content returned by LLM or the Text parameter of the SendAgentInstanceTTS API) contains the TerminatorText string, then the content from the TerminatorText string (inclusive) onward will no longer be synthesized in this TTS round.

    📌 Important Note

    • For bidirectional streaming, only one character can be set.

    • Typically, the LLM is guided via prompts in LLM > SystemPrompt to specify which parts of the content should be enclosed with special punctuation.

    • This parameter cannot be updated when updating an agent instance.

    CharacterFilter string[]

    The specified strings in the content input to TTS (usually the content returned by LLM or the Text parameter of the SendAgentInstanceTTS API) will not be involved in speech synthesis. Each string in the array indicates a string to be filtered out, and each string can have up to 2 characters.

    ASR object
    Vendor string

    Possible values: [Tencent, AliyunParaformer, AliyunGummy, Microsoft]

    Default value: Tencent

    ASR provider. Please refer to Configuring ASR > ASR Parameters for details.

    Params object

    Vendor parameters, please refer to Configuring ASR > Params Parameters for details.

    VADSilenceSegmentation number

    Possible values: >= 200 and <= 2000

    Default value: 500

    Set the number of seconds after which two sentences are no longer considered as one. Unit is ms, range [200, 2000], default is 500. Please refer to Speech Segmentation Control for details.

    📌 Important Note

    When Vendor is "Tencent" (default), the maximum value is 1500.

    PauseInterval number

    Possible values: >= 200 and <= 2000

    Set the number of seconds within which two sentences are considered as one, i.e., ASR multi-sentence concatenation. Unit is ms, range [200, 2000]. Only when this value is greater than VADSilenceSegmentation, ASR multi-sentence concatenation will be enabled. Please refer to Speech Segmentation Control for details.

    VADSensitiveLevel int

    Possible values: [0, 1, 2, 3]

    Default value: 0

    VAD sensitivity, 0: medium sensitivity, default value; 1: low sensitivity; 2: high sensitivity; 3: custom mode, needs to be used in combination with VADMinSpeechDur and VADEnergyThreshold. Please refer to Voice Interruption Sensitivity Adjustment for details.

    VADMinSpeechDur int

    Possible values: >= 0 and <= 1000

    VAD minimum speech duration, unit ms, the larger the value, the less likely it is to be detected, but it may cause some short speech to be missed, the value range is [0, 1000].

    VADEnergyThreshold float

    Possible values: >= 0 and <= 1

    VAD energy threshold, the smaller the value, the higher the sensitivity, the value range is [0, 1].

    HotWord stringdeprecated

    This parameter has been deprecated. Please set it through the Params vendor parameters.

  • ]
    • Cursor string

    A non-empty value only indicates that there are still AI agent details not returned, and you need to set this field in the request parameter Cursor to fetch more AI agent information; an empty value indicates that all AI agent information has been returned.

Previous

Update Agent

Next

Query Agents Details

On this page

Back to top