canonical: https://jentic.com/apis/agora.io/agora

# Agora Conversational AI API

Jentic publishes the only available OpenAPI specification for Agora Conversational AI API, keeping it validated and agent-ready. The API provisions and controls AI voice agents that join Agora real-time channels and run an ASR-LLM-TTS pipeline against participants. Eight endpoints under /api/conversational-ai-agent/v2 cover the full agent lifecycle: join a channel, query status, list active agents, update configuration, broadcast a TTS message, interrupt the agent, retrieve conversation history, and leave. Authentication uses HTTP Basic with the Agora App ID and customer secret.

## For AI agents

Spawn, control, and tear down voice AI agents inside Agora RTC channels - start, stop, query, update, speak, interrupt, and pull conversation history.

## Scope

Does not handle channel token minting, RTC media transport, or recording - use for conversational AI agent lifecycle and control inside Agora channels only.

## Capabilities

- Start a conversational AI agent in an Agora channel with an ASR-LLM-TTS configuration
- Stop a running agent so it leaves the channel cleanly
- Query agent runtime status by ID or list every running agent in a project
- Update an active agent's configuration without recreating the session
- Broadcast a TTS message through the agent into the channel
- Interrupt the agent's current speech to yield to a human speaker
- Retrieve the full conversation history for a finished or running agent

## Use cases

### Voice AI Customer Support Sessions

Support teams spin up an Agora conversational agent the moment a caller joins a channel, configuring the LLM with company knowledge and the TTS voice for the brand. The agent handles the conversation while a human supervisor can intervene by calling the interrupt endpoint, and the conversation history endpoint provides the transcript for QA or model fine-tuning.

Example prompt: POST /api/conversational-ai-agent/v2/projects/{appid}/join with the channel name, LLM config, and TTS voice

### AI Voice Concierge in Live Apps

Consumer apps embed an Agora-powered voice agent that greets users, answers questions, and hands back to a human when needed. The /speak endpoint lets the host trigger announcements, and /interrupt yields the floor immediately. Active agent listing helps the app surface a control panel of running sessions.

Example prompt: POST /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/speak with the announcement text

### Real-Time Conversation Audit

Compliance and analytics pipelines pull the conversation history endpoint as soon as an agent leaves the channel, archiving transcripts for review. Because the same endpoint works against live and finished agents, monitoring tools can poll it to provide near-real-time supervisor dashboards.

Example prompt: GET /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/history and store the transcript for review

### AI Agent Voice Operations via Jentic

An orchestrating agent built on Jentic can launch, supervise, and retire Agora voice agents based on natural-language operator commands. Jentic stores the App ID and secret in its vault and applies HTTP Basic at request time, so the credentials never sit in the agent's working memory.

Example prompt: Use Jentic to search 'start an Agora conversational agent', execute the join, then call interrupt when a human joins

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /api/conversational-ai-agent/v2/projects/{appid}/join | Start a conversational AI agent |
| POST | /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/leave | Stop a running agent |
| GET | /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId} | Query agent status |
| GET | /api/conversational-ai-agent/v2/projects/{appid}/agents | List active agents |
| POST | /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/update | Update agent configuration |
| POST | /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/speak | Broadcast TTS through the agent |
| POST | /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/interrupt | Interrupt agent speech |
| GET | /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/history | Retrieve conversation history |

## Key resources

- **Agent Lifecycle** — Join, leave, and list voice AI agents in Agora channels
- **Agent Control** — Update configuration, broadcast TTS, and interrupt an agent mid-speech
- **Agent History** — Retrieve full conversation history for an agent session

## Why Jentic

- **Setup:** Wiring the Agora Conversational AI API by hand means combining an App ID and Customer Secret into a Basic Authorization header and coding calls across the agent join, speak, and interrupt lifecycle. Through Jentic you install once, import the Agora Conversational AI API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Agora puts the project appid and agent id in the URL path (/projects/{appid}/agents/{agentId}/...), so a rule can pin the agent to one project or conversational agent. You choose which operations it may call, such as reading agent history, so leaving or interrupting an agent is not included unless you add it.
- **Credential handling:** Your Agora App ID and Customer Secret are stored once, encrypted, by your own Jentic One instance as basic-auth credentials and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'start a conversational AI agent in an Agora channel', and Jentic returns the join, leave, speak, and interrupt operations with their input schemas so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Twilio** — Programmable voice and messaging platform with media streams that can pipe audio to AI services
- **OpenAI** — LLM and Realtime audio APIs that can power the language layer of an Agora agent
- **Anthropic Messages** — Claude messages API for the LLM behind a conversational voice agent
- **Zoom Meetings** — Video conferencing platform with bot SDKs for joining meetings programmatically

## FAQ

### Why is there no official OpenAPI spec for Agora Conversational AI API?

Agora does not publish an OpenAPI specification for the Conversational AI surface. Jentic generates and maintains this spec so that AI agents and developers can call the Agora Conversational AI API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Agora Conversational AI API use?

HTTP Basic authentication using your Agora App ID and Customer Secret. Through Jentic, both values are stored in the credential vault and combined into the Authorization header at request time, so the agent never sees the raw secret.

### How do I start a voice AI agent in an Agora channel?

Call POST /api/conversational-ai-agent/v2/projects/{appid}/join with the channel name, LLM provider configuration, ASR settings, and TTS voice. The response returns an agentId you use for all subsequent control calls.

### Can I interrupt the agent while it is speaking?

Yes. POST /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/interrupt cuts the current TTS playback so a human or another speaker can take the floor. The agent stays joined to the channel and can resume speaking on the next /speak call.

### How do I stop an Agora conversational agent through Jentic?

Search Jentic for 'stop an Agora conversational agent', load the POST /api/conversational-ai-agent/v2/projects/{appid}/agents/{agentId}/leave schema, and execute it with the project App ID and the agent ID returned by the original join call.

### What are the rate limits for the Agora Conversational AI API?

The OpenAPI spec does not declare explicit per-second limits. Concurrency is bounded by your Agora project's allowance for active conversational agents - list active agents via GET /api/conversational-ai-agent/v2/projects/{appid}/agents to monitor utilisation.

### Can I limit what my agent is allowed to do with the Agora Conversational AI API?

Yes. Because you run Jentic One yourself, your own rules decide which of the eight operations the agent may call and which credentials it may use. Since Agora puts the project App ID and agent ID in the URL path, you can pin the agent to a single project or a single conversational agent. You might allow it to start an agent and read conversation history while withholding the leave and interrupt operations, so it cannot end or cut off a session unless you grant those calls.