--- title: Start and stop an agent description: Set up real-time interaction with a Conversational AI agent. sidebar_position: 0.2 platform: android exported_from: https://docs.agora.io/en/conversational-ai/develop/start-stop-agent exported_on: '2026-06-05T05:02:31.005067Z' exported_file: start-stop-agent.md --- > For a complete site index fetch https://docs.agora.io/llms.txt. For all pages in this product fetch https://docs.agora.io/en/conversational-ai/overview/product-overview.md [HTML Version](https://docs.agora.io/en/conversational-ai/develop/start-stop-agent) # Start and stop an agent 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. 1. **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. 1. **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 Software-Defined Real-Time Network (SDRTN®). 1. **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. 1. **User leaves the Agora channel**: The user disconnects from the session. **Conversational AI Engine workflow** ![](https://docs-md.agora.io/images/conversational-ai/ai-agent-tech.svg) ## Prerequisites - [Enabled Agora conversational AI](https://docs-md.agora.io/en/conversational-ai/get-started/manage-agora-account.md) for your project. - The following information from Agora Console: - [App ID](https://docs-md.agora.io/en/conversational-ai/get-started/manage-agora-account.md): The string identifier for your project used to call the Conversational AI Engine RESTful API. - [Customer ID and Customer secret](https://docs-md.agora.io/en/conversational-ai/rest-api/restful-authentication.md): Used for HTTP authentication when calling the RESTful APIs. - A [temporary token](https://docs-md.agora.io/en/conversational-ai/get-started/manage-agora-account.md): The token is used by the agent for authentication when joining an Agora channel. - Obtained API keys for: - A supported Large Language Model (LLM) provider such as [OpenAI](https://openai.com/index/openai-api/). - A supported text-to-speech (TTS) provider such as [Microsoft Azure](https://azure.microsoft.com/en-us/products/ai-services/ai-speech). > 💡 **Tip** > If you don't yet have API keys from a third-party LLM or TTS provider, [Use presets](https://docs-md.agora.io/en/conversational-ai/develop/presets.md) to start your first agent without ASR, LLM, and TTS credentials. - Implemented the [Voice Calling](https://docs-md.agora.io/en/voice-calling/get-started/get-started-sdk.md) or [Video Calling](https://docs-md.agora.io/en/video-calling/get-started/get-started-sdk.md) 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](https://docs-md.agora.io/en/mailto:support@agora.io.md). ## 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. To generate your base64-encoded credentials, see [RESTful authentication](https://docs-md.agora.io/en/conversational-ai/rest-api/restful-authentication.mdx.md). **Node.js** ```js const fetch = require('node-fetch'); const url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/join"; const headers = { "Authorization": "Basic ", "Content-Type": "application/json" }; const data = { "name": "unique_name", "properties": { "channel": "", "token": "", "agent_rtc_uid": "0", "remote_rtc_uids": ["1002"], "enable_string_uid": false, "idle_timeout": 120, "llm": { "url": "https://api.openai.com/v1/chat/completions", "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": "", "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)); ``` **Curl** ```json curl --request POST \ --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/join \ --header 'Authorization: Basic ' \ --header 'Content-Type: application/json' \ --data ' { "name": "unique_name", "properties": { "channel": "", "token": "", "agent_rtc_uid": "0", "remote_rtc_uids": ["1002"], "enable_string_uid": false, "idle_timeout": 120, "llm": { "url": "https://api.openai.com/v1/chat/completions", "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": "", "region": "eastus", "voice_name": "en-US-AndrewMultilingualNeural" } } } }' ``` **Python** ```python import requests import json url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/join" headers = { "Authorization": "Basic ", "Content-Type": "application/json" } data = { "name": "unique_name", "properties": { "channel": "", "token": "", "agent_rtc_uid": "0", "remote_rtc_uids": ["1002"], "enable_string_uid": False, "idle_timeout": 120, "llm": { "url": "https://api.openai.com/v1/chat/completions", "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": "", "region": "eastus", "voice_name": "en-US-AndrewMultilingualNeural" } } } } response = requests.post(url, headers=headers, data=json.dumps(data)) print(response.text) ``` For complete information on all request parameters, see [Start a conversational AI agent](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/join.md). If the request is successful, you receive the following response: ```json // 200 OK { "agent_id": "1NT29X10YHxxxxxWJOXLYHNYB", "create_ts": 1737111452, "status": "RUNNING" } ``` Store the `agent_id` for use in subsequent API calls to [query](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/query.md), [update](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/update.md), and [stop](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/leave.md) 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. **Node.js** ```js const url = 'https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/leave'; const options = { method: 'POST', headers: { 'Authorization': 'Basic ', 'Content-Type': 'application/json' } }; fetch(url, options) .then(res => res.json()) .then(json => console.log(json)) .catch(err => console.error(err)); ``` **Curl** ```bash curl --request post \ --url https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/leave \ --header 'Authorization: Basic ' ``` **Python** ```python import requests url = "https://api.agora.io/api/conversational-ai-agent/v2/projects/:appid/agents/:agentId/leave" headers = { "Authorization": "Basic ", "Content-Type": "application/json" } response = requests.post(url, headers=headers) print(response.text) ``` If the request is successful, the server responds with a `200 OK` status and an empty JSON object. ```json // 200 OK {} ``` > ℹ️ **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](https://docs-md.agora.io/en/mailto:support@agora.io.md). ## 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 - [Start a conversational AI agent](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/join.md) - [Stop a conversational AI agent](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/leave.md) - [Update agent configuration](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/update.md) - [Query agent status](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/query.md) - [Retrieve a list of agents](https://docs-md.agora.io/en/conversational-ai/rest-api/agent/list.md)