Agora Voice Agents

Deploy an Agora voice agent on Vercel

Use this path when you want a live voice agent, not just the UI preview.

Agora provides the realtime media channel and ConvoAI agent. Vercel hosts the React app and the server routes that mint RTC tokens and start the agent.

What ships

The deployed app has three moving parts:

  1. An Agora project with RTC enabled and an App Certificate.
  2. A published Agora AI Studio / ConvoAI pipeline.
  3. The agora-agent-pipeline-template Next.js app deployed on Vercel.

The browser never receives your Agora App Certificate. The template's server route creates RTC tokens and starts the ConvoAI agent.

Quick start with npm create

Create a fresh app from the published scaffold package:

npm create agora-realtime-agent@latest my-agent
cd my-agent
cp .env.example .env.local

Fill .env.local with AGORA_APP_ID, AGORA_APP_CERTIFICATE, and AGORA_CONVOAI_PIPELINE_ID, then run:

npm run dev

npm init agora-realtime-agent@latest my-agent and npx create-agora-realtime-agent@latest my-agent are equivalent. Use -- --no-install when you only want to copy the template.

1. Create the Agora project

In the Agora Console:

  1. Create or select an Agora project.
  2. Copy the App ID.
  3. Enable or copy the App Certificate for token generation.
  4. Confirm that the project can use RTC and Conversational AI / AI Studio features in the region you plan to use.

You will deploy these values as Vercel server-side environment variables:

AGORA_APP_ID=...
AGORA_APP_CERTIFICATE=...

2. Publish an AI Studio pipeline

In Agora AI Studio / Conversational AI:

  1. Create a voice pipeline.
  2. Choose the pipeline's speech recognition, model, voice, and turn detection settings.
  3. Test the pipeline in AI Studio until the agent responds the way you expect.
  4. Publish the pipeline.
  5. Copy the published pipeline ID.

Set the ID as:

AGORA_CONVOAI_PIPELINE_ID=...

The template passes this value to agora-agents as pipelineId. The setup route sends it to Agora as the top-level pipeline_id, so the published pipeline owns ASR, LLM, TTS, and turn detection defaults.

3. Verify locally from this repo

Install dependencies and build the SDK:

npm install
npm --workspace agora-realtime-react run build

Create templates/agora-agent-pipeline/.env.local:

AGORA_APP_ID=...
AGORA_APP_CERTIFICATE=...
AGORA_CONVOAI_PIPELINE_ID=...

Start the template:

npm run dev:template

Open http://localhost:3000. Localhost is treated as a secure context by browsers, so microphone capture works for local testing.

4. Deploy the template on Vercel

The fastest path is the hosted Deploy Button:

Deploy to Vercel

The button points directly at the GitHub subdirectory templates/agora-agent-pipeline instead of the monorepo root. That matters because the root vercel.json builds the marketing website, while the template has its own local vercel.json:

{
  "buildCommand": "npm run build",
  "installCommand": "npm install",
  "outputDirectory": ".next"
}

If you import manually, import this subdirectory URL as the template source:

https://github.com/AgoraIO-Community/agora-realtime-agent/tree/main/templates/agora-agent-pipeline

Add these Vercel environment variables for Production and Preview:

AGORA_APP_ID=...
AGORA_APP_CERTIFICATE=...
AGORA_CONVOAI_PIPELINE_ID=...

Deploy. After deployment, open the Vercel URL and start a voice session. The template calls:

  • POST /api/agora/realtime/setup to mint RTC tokens and start the ConvoAI agent.
  • POST /api/agora/realtime/end to stop the agent when the session ends.

Why this split works

Agora does the realtime work: channel join, mic audio, subscribed agent audio, and the ConvoAI pipeline. Vercel does the web app work: React UI, server routes, environment variables, previews, and production deployment.

That split keeps sensitive Agora credentials out of the browser while still giving product teams a normal Vercel workflow.

Troubleshooting

  • agora_credentials_missing: AGORA_APP_ID or AGORA_APP_CERTIFICATE is missing in the Vercel environment.
  • convoai_agent_start_failed: the pipeline ID, Agora project access, region, or ConvoAI entitlement is not valid for the current project.
  • Browser joins but no agent audio: open the debug panel with ?debug=1 and check setup, join, publish, subscribe, and remote audio events.
  • Microphone fails in production: use HTTPS. Browsers block microphone capture on insecure origins.

References

  • Agora: https://www.agora.io/en/
  • Agora Docs (English): https://docs.agora.io/en/
  • Agora realtime voice docs: https://docs.agora.io/en/realtime-media/voice
  • Agora AI and Conversational AI docs: https://docs.agora.io/en/ai
  • Agora Console: https://console.agora.io/
  • Agora Agents SDK: node_modules/agora-agents/README.md
  • Template setup route: templates/agora-agent-pipeline/app/api/agora/realtime/setup/route.ts
  • Vercel monorepo deployment: https://vercel.com/docs/monorepos
  • Vercel environment variables: https://vercel.com/docs/environment-variables