Agora Conversational AI Android Quickstart

This repository is a template-style Android starter for building a Voice AI app with Agora Conversational AI.

It gives you a Kotlin + Jetpack Compose app backed by a small Python service that:

• joins an Agora RTC channel
• starts and manages an Agora Conversational AI agent through the backend
• listens for transcript, agent state, and pipeline metrics over RTM
• lets the user talk, mute, interrupt, and end the session
• keeps the App Certificate and token generation off the Android device

Note

This quickstart requires the included Python backend. Local mobile testing uses a temporary public HTTPS tunnel so the Android device can reach the development server.

Prerequisites

• Android Studio with JDK 17 or newer
• Python 3.10 or newer
• Bash for the scripts in server/
• An Android device or emulator with microphone support
• An Agora account with access to Conversational AI
• A development tunnel provider; the included helper supports Cloudflare Tunnel, ngrok, Tailscale Funnel, and LocalTunnel

The commands below assume a macOS or Linux shell. On Windows, run the backend scripts from WSL or an equivalent Bash environment.

Quick Start

1. Install the Agora CLI and sign in

Skip this step if agora is already on your PATH.

curl -fsSL https://dl.agora.io/cli/install.sh | sh
agora --help
agora login

2. Get the quickstart

The recommended path lets the CLI clone the template and bind an Agora project. Replace my-android-demo with your app folder name:

agora init my-android-demo --template android
cd my-android-demo

agora init selects or creates an Agora project and records the project binding in .agora/project.json.

To work from an existing clone instead:

git clone https://github.com/AgoraIO-Conversational-AI/agent-quickstart-android.git
cd agent-quickstart-android

If you use an existing clone, you will select the Agora project when you configure the server in the next step.

3. Configure and run the Python server

python3 -m venv server/.venv
source server/.venv/bin/activate
pip install -r server/requirements-dev.txt
cp -n server/.env.example server/.env.local
agora project env write server/.env.local --template standard
./server/run.sh

The command above uses the project selected by agora init. For an existing clone, select the project explicitly instead:

agora project env write server/.env.local \
  --project <project-name-or-id> \
  --template standard
./server/run.sh

The server listens on http://127.0.0.1:8000 and keeps AGORA_APP_CERTIFICATE off the Android device. Leave this terminal running. The local endpoint uses HTTP; the selected tunnel provider supplies the public HTTPS endpoint required by Android.

4. Create a temporary public HTTPS URL

In another terminal, run:

./server/tunnel.sh --provider ngrok

Choose cloudflare, ngrok, tailscale, or localtunnel with --provider. Keep the tunnel running and copy its generated https:// URL.

Verify that the public endpoint reaches the Python server:

curl https://your-public-host/health

The response must be backend health JSON, not a tunnel-provider login or warning page. See Local HTTPS tunnels for explicit ngrok, Cloudflare Tunnel, Tailscale Funnel, and LocalTunnel commands.

5. Configure Android

Write the public server URL to root local.properties:

./server/configure-android.sh https://your-public-host

The script writes only this client value:

QUICKSTART_SERVER_URL=https://your-public-host

Do not put AGORA_APP_CERTIFICATE in local.properties.

6. Build the app

JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew :app:assembleDebug

If your shell already uses JDK 17 or newer, ./gradlew :app:assembleDebug is sufficient.

7. Run it

Open the project in Android Studio, or run it from the command line, then launch it on a device or emulator.

Tap Start voice session, allow microphone permission, speak to the agent, and watch transcripts appear in real time.

If the agent does not join or transcripts do not appear, run:

agora project doctor --deep

If the temporary tunnel URL changes, run server/configure-android.sh again, rebuild, and reinstall the app. For manual setup, optional configuration, and production notes, see docs/setup.md.

What To Read First

If you are using this as a template, start here:

• ConversationScreen.kt
• ConversationViewModel.kt
• AgoraConversationSessionManager.kt
• ConversationAgoraApi.kt
• Python backend

Those files show the full flow from UI action to Agora session setup.

What To Customize First

Most teams will customize these pieces first:

1. ConversationScreen.kt for UI layout, branding, and session cards
2. ConversationViewModel.kt for app state, button actions, and session orchestration
3. AgoraConversationSessionManager.kt for RTC, RTM, and media behavior
4. server/app/agora_client.py for agent presets, geofence, and model configuration

Build And Test

Run the Python server tests:

server/.venv/bin/python -m pytest server/tests

Compile Kotlin:

JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew :app:compileDebugKotlin

Run unit tests:

JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew :app:testDebugUnitTest

Assemble debug APK:

JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew :app:assembleDebug

Docs

• Setup: CLI, server, tunnel, and Android configuration
• Local HTTPS tunnels: expose the development server to a physical device
• Backend runbook: local server, public tunnel, API contract, deployment, and smoke checks
• Architecture: app structure, code map, session lifecycle, and state flow
• Troubleshooting: common setup, agent, RTM, metrics, and microphone issues
• Agent coding guidance: Agora CLI skills and guidance for AI coding agents

Security Note

AGORA_APP_CERTIFICATE stays in server/.env.local and is never compiled into Android. The Python server generates the Android user's RTC/RTM token and uses the Agora Python SDK to start, interrupt, and stop the agent. A development tunnel URL is public while the tunnel is running, so stop the tunnel when testing is complete and add appropriate application authentication before adapting this demo for production.