Connect your agent

After publishing your agent, you can integrate it into your applications using the Conversational AI Engine API. The Embed option in Studio provides a pre-configured API call with your agent's identifiers already populated.

Prerequisites

A published agent
Agora Customer ID and Customer secret for API authentication

Get the embed code

To get the API call for your agent:

In Agent Studio, select Agents from the sidebar.
From the agent list, open the Actions menu for your agent and select Embed Agent.
Copy the generated code snippet. It includes your agent's name, pipeline_id, channel settings, and a valid RTC token.

Use this as the starting point for integrating the agent into your backend service. For full API reference, see Start a conversational AI agent.

Authentication

This endpoint requires Basic Auth. Generate a Base64-encoded credential with your Customer ID and Customer Secret. The generated code snippet includes an RTC token under properties which is valid for 24 hours.

Sample code

The following examples show how to start an agent call using your embed credentials. Replace <BASE64_ENCODED_CREDENTIALS> with your Base64-encoded Agora Customer ID and Customer secret.

curl
Python
Node.js

curl --request POST \
  --url https://api.agora.io/api/conversational-ai-agent/v2/projects/<appid>/join \
  --header 'Authorization: Basic <BASE64_ENCODED_CREDENTIALS>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "<agent_name>",
    "pipeline_id": "<pipeline_id>",
    "properties": {
      "channel": "<channel_name>",
      "agent_rtc_uid": "<agent_rtc_uid>",
      "remote_rtc_uids": ["*"],
      "token": "<token>"
    }
  }'

import requests
url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/<appid>/join"
payload = {
    "name": "<agent_name>",
    "pipeline_id": "<pipeline_id>",
    "properties": {
        "channel": "<channel_name>",
        "agent_rtc_uid": "<agent_rtc_uid>",
        "remote_rtc_uids": ["*"],
        "token": "<token>"
    }
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Basic <BASE64_ENCODED_CREDENTIALS>"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)

const options = {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Basic <BASE64_ENCODED_CREDENTIALS>'
    },
    body: JSON.stringify({
        name: '<agent_name>',
        pipeline_id: '<pipeline_id>',
        properties: {
            channel: '<channel_name>',
            agent_rtc_uid: '<agent_rtc_uid>',
            remote_rtc_uids: ['*'],
            token: '<token>'
        }
    })
};
fetch('https://api.agora.io/api/conversational-ai-agent/v2/projects/<appid>/join', options)
    .then(res => res.json())
    .then(res => console.log(res))
    .catch(err => console.error(err));

About pipeline_id

The pipeline_id in the embed code is the internal identifier for your published agent configuration. It is automatically populated when you copy the embed code from the Embed Agent option in Studio.

Prerequisites​

Get the embed code​

Sample code​

See also​

Prerequisites

Get the embed code

Sample code

See also