Agora Conversational AI Python Quickstart

Build a production-style voice agent with a Next.js web client and Python FastAPI backend. This quickstart includes live transcript, agent visualizer (Agent UIKit), and managed STT/LLM/TTS defaults.

Prerequisites

• Python 3.10+
• Bun
• Agora CLI

Run It

Install the CLI (skip if already installed), scaffold the Python quickstart, install dependencies, and run.

1. Install the Agora CLI and sign in (skip if agora is already on your PATH):

   curl -fsSL https://raw.githubusercontent.com/AgoraIO/cli/main/install.sh | sh -s -- --add-to-path
   agora login

2. Scaffold and run (replace my-python-demo with your own project name):

   agora init my-python-demo --template python
   cd my-python-demo
   bun run setup
   bun run dev

3. Open http://localhost:3000 and click Start conversation.

If the agent does not join or transcripts do not appear, run agora project doctor --deep to check credentials, feature enablement, network reachability, and local env binding.

Working from a clone of this repository

Use this path if you already cloned this repo:

git clone https://github.com/AgoraIO-Conversational-AI/agent-quickstart-python.git
cd agent-quickstart-python
agora login
agora project use <your-project>
bun run setup
agora quickstart env write .
bun run doctor:local
bun run dev

bun run setup preserves a configured server/.env, copies a legacy server/.env.local when needed, and prints the credential-writing step when the resulting file lacks real Agora values. Setup and doctor:local replace an untouched example file with configured legacy credentials. This supports CLI versions that wrote .env.local.

Services:

• Frontend: http://localhost:3000
• Backend: http://localhost:8000
• API docs: http://localhost:8000/docs

Deploy

Deploy web as a Next.js app and server as a reachable Python service.

Browser-facing /api/* routes in Next proxy to FastAPI via:

AGENT_BACKEND_URL=https://your-python-backend.example.com

Set backend env values:

AGORA_APP_ID=your_agora_app_id
AGORA_APP_CERTIFICATE=your_agora_app_certificate

To export local env values from the Agora CLI-bound project:

agora project use <your-project>
agora quickstart env write .
rg "^(AGORA_APP_ID|AGORA_APP_CERTIFICATE)=" server/.env

Environment variables

Primary backend env file: server/.env.example.

Variable	Required	Default	Notes
AGORA_APP_ID	✅	—	Agora Console -> Project -> App ID
AGORA_APP_CERTIFICATE	✅	—	Agora Console -> Project -> App Certificate (server only)
PORT		8000	FastAPI server port
AGENT_BACKEND_URL (web deploy)	✅	—	Required in deployed web app when proxying to external FastAPI

Default vs BYOK — this quickstart defaults to Agora-managed STT + LLM + TTS in the backend. Enable BYOK by uncommenting provider blocks in server/src/agent.py and adding matching keys.

Commands

# Dev
bun run setup
bun run dev

# Quality
bun run doctor
bun run doctor:local
bun run verify:backend

# CI / pre-ship
bun run verify:web
bun run verify:local
bun run verify

Run bun run verify before shipping web-only changes, and bun run verify:local when backend behavior changed.

Tests run standalone (no Agora cloud needed): pytest in server/, bun test in web/. CI runs them on Linux/macOS/Windows × Python 3.10 & 3.13.

Architecture

The browser talks to Next.js /api/* routes. In local mode, Next rewrites those routes to FastAPI using AGENT_BACKEND_URL=http://localhost:8000; FastAPI owns token generation and agent start/stop logic.

What You Get

• Next.js web client (web/) with transcript UI and agent visualizer
• FastAPI backend (server/) for token generation and agent lifecycle
• /api/get_config, /api/startAgent, and /api/stopAgent browser-facing contract
• Managed default pipeline (Deepgram STT, OpenAI LLM, MiniMax TTS)

How It Works

1. Browser requests connection config from /api/get_config.
2. Backend generates combined RTC+RTM config and returns channel + token.
3. Browser joins RTC/RTM and starts streaming audio.
4. Browser calls /api/startAgent; backend starts the cloud agent session.
5. Browser receives transcript and state updates over RTM, and /api/stopAgent ends the session.

Repo Map

• web/ — Next.js 16 + React 19 + TypeScript frontend
• server/ — Python FastAPI backend + Agora Agent Server SDK integration
• ARCHITECTURE.md — system-level flow and ownership boundaries
• AGENTS.md — contributor agent instructions

Troubleshooting

• Agent does not join or transcripts are missing: run agora project doctor --deep.
• Missing credentials: run agora quickstart env write ..
• Auth errors from backend: confirm AGORA_APP_ID and AGORA_APP_CERTIFICATE are set in server/.env.
• Frontend cannot reach backend: confirm AGENT_BACKEND_URL=http://localhost:8000 in local frontend scripts.
• Unsure who owns /api/*: Next owns browser-facing /api/*; FastAPI owns /get_config, /startAgent, /stopAgent.

More Docs

• ARCHITECTURE.md
• AGENTS.md
• docs/ai/L1/02_architecture.md — full-stack topology and lifecycle
• docs/ai/L1/03_code_map.md — curated web/ + server/ file map

License

Released under the MIT License.