Get AI Agent Status

During real-time voice calls with AI Agents, you might need to know the AI agent instance's current status or receive real-time updates to handle subsequent operations or maintain system stability. You can get these updates through API requests or by listening to server callbacks.

The status messages include the following types:

• Server exception events: including AI Agent service errors, RTC errors, Large Language Model (LLM) errors, Text-to-Speech (TTS) errors (such as TTS concurrency limit reached), etc.
• AI agent instance status:
  • Status that can be queried via server API: idle, listening, thinking, speaking, etc.
  • Status that can be monitored via server callbacks: agent interruption events, which can be used to terminate ongoing tasks such as RAG tasks.

Listen for Server Exception Events

Contact ZEGOCLOUD technical support to configure the callback address for receiving AI Agent backend callbacks.

When there are exception events on the server, the AI Agent backend will send an exception event notification (Event is Exception) to the configured address. Here's a callback content sample:

{
    "AppId": 123456789,
    "Event": "Exception",
    "Nonce": "abcdd22113",
    "Timestamp":1741221508000,
    "Signature": "XXXXXXX",
    "Sequence": 1921825797275873300,
    "RoomId": "test_room",
    "AgentUserId": "test_agent",
    "AgentInstanceId": "1912124734317838336",
    "Data": {
        "Code": 2203,
        "Message": "The API key in the request is missing or invalid"
    }
}

For more detailed information, please refer to the Receiving Callback and Exception Codes documentation.

Get Agent Instance Status

Via Server API

Call the QueryAgentInstanceStatus API and pass in the corresponding AgentInstanceId. The server will return the current status of the AI agent instance (such as idle, listening, thinking, speaking, etc.).

Listen for Agent Interruption Callbacks

{
    "AppId": 123456789,
    "Nonce": "abcdd22113",
    "Timestamp": 1747033950524，
    "Sequence": 1921825797275873300,
    "Signature": "XXXXXXX",
    "Event": "Interrupted",
    "RoomId": "90000001237",
    "AgentInstanceId": "1921825671047294976",
    "AgentUserId": "apitest689_agent",
    "Data": {
        "Round": 1481651956,
        "Reason": 1
    }
}