Skip to main content
  • Core Products
  • Add-Ons
  • Extensions Marketplace

REST quickstart

This page describes how to call the Conversational AI Engine RESTful APIs to start and stop an AI agent.

Understand the tech​

Agora’s Conversational AI technology enables real-time voice interactions between users and an AI-driven agent within an Agora channel. The basic process is as follows:

  1. User joins a Agora channel: A user joins an Agora channel.
  2. Start an AI agent: The user sends a request to your business server, which then makes an API call to the Conversational AI engine to start an agent. The agent joins the same channel as the user.
  3. Real-time interaction: The user communicates with the AI agent through voice, leveraging the specified LLM, a text-to-speech service, and Agora's low-latency SD-RTN™.
  4. Stop the AI agent: When the user ends the conversation, the business server sends a request to stop the AI agent. The agent then leaves the Agora channel.
  5. User leaves the Agora channel: The user disconnects from the session.
Conversational AI Engine workflow

Prerequisites​

Before you begin, make sure that you have:

  • Enabled Agora conversational AI for your project.

  • The following information from Agora Console:

    • App ID: The string identifier for your project used to call the Conversational AI Engine RESTful API.
    • Customer ID and Customer secret: Used for HTTP authentication when calling the RESTful APIs.
    • A temporary token: The token is used by the agent for authentication when joining an Agora channel.

  • Obtained an API key and callback URL from a Large Language Model (LLM) provider such as OpenAI.

  • Obtained an API key from a text-to-speech (TTS) provider such as Microsoft Azure.

  • Implemented the voice or video calling quickstart.

    info

    For the best conversational experience, Agora recommends using Conversational AI Engine with specific Agora Video/Voice SDK versions. For details, contact technical support.

Implementation​

This section introduces the basic RESTful API requests you use to start and stop a Conversational AI agent. In a production environment, implement these requests on your business server.

Start a conversational AI agent​

Call the join endpoint to create an agent instance that joins an Agora channel. Pass in the channel name and token for agent authentication.

Sample request:

const fetch = require('node-fetch');

const url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/join";

const headers = {
  "Authorization": "Basic <your_base64_encoded_credentials>",
  "Content-Type": "application/json"
};

const data = {
  "name": "unique_name",
  "properties": {
    "channel": "<your_channel_name>",
    "token": "<your_rtc_token>",
    "agent_rtc_uid": "0",
    "remote_rtc_uids": ["*"],
    "enable_string_uid": false,
    "idle_timeout": 120,
    "llm": {
      "url": "https://api.openai.com/v1/chat/completions",
      "api_key": "<your_llm_api_key>",
      "system_messages": [
        {
          "role": "system",
          "content": "You are a helpful chatbot."
        }
      ],
      "greeting_message": "Hello, how can I help you?",
      "failure_message": "Sorry, I don't know how to answer this question.",
      "max_history": 10,
      "params": {
        "model": "gpt-4o-mini"
      }
    },
    "asr": {
      "language": "en-US"
    },
    "tts": {
      "vendor": "microsoft",
      "params": {
          "key": "<your_tts_api_key>",
          "region": "eastus",
          "voice_name": "en-US-AndrewMultilingualNeural"
      }
    }
  }
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
  .then(response => response.json())
  .then(json => console.log(json))
  .catch(error => console.error("Error:", error));

For complete information on all request parameters, see Start a conversational AI agent.

If the request is successful, you receive the following response:


_6
// 200 OK
_6
{
_6
"agent_id": "1NT29X10YHxxxxxWJOXLYHNYB",
_6
"create_ts": 1737111452,
_6
"status": "RUNNING"
_6
}

Store the agent_id for use in subsequent API calls to query, update, and stop the AI agent.

Stop the conversational AI agent​

To end the conversation with the AI agent, call the leave endpoint. This causes the agent to leave the Agora channel.

Sample request:

const url = 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/leave';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Basic <your_base64_encoded_credentials>',
    'Content-Type': 'application/json'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

If the request is successful, the server responds with a 200 OK status and an empty JSON object.


_2
// 200 OK
_2
{}

info

The number of Peak Concurrent Users (PCU) allowed to call the server API under a single App ID is limited to 20. If you need to increase this limit, please contact technical support.

Reference​

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

API reference​

vundefined