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 single Kotlin + Jetpack Compose app that:

• joins an Agora RTC channel
• starts an Agora Conversational AI agent
• listens for transcript, agent state, and pipeline metrics over RTM
• lets the user talk, mute, interrupt, and end the session
• keeps the demo in one Android project so it is easy to understand and customize

Quick Start

The recommended path is to let the Agora CLI clone the quickstart, bind an Agora project, and write Android credentials to local.properties.

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. Scaffold and bind the Android quickstart

Replace my-android-demo with your app folder name:

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

agora init clones this starter, selects or creates an Agora project, writes .agora/project.json, and writes Agora credentials to root local.properties.

3. Build the app

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

4. 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 realtime.

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

agora project doctor --deep

Working From This Repository

Use this path if you already cloned this repo, for example to contribute or fork:

git clone https://github.com/AgoraIO-Conversational-AI/agent-quickstart-android.git
cd agent-quickstart-android
agora login
agora quickstart env write . --template android --project <your-project>
agora project doctor --deep
JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home" ./gradlew :app:assembleDebug

The env command writes these values to root local.properties:

AGORA_APP_ID=...
AGORA_APP_CERTIFICATE=...

For manual setup, optional config, 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
• AgoraLocalTokenFactory.kt

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. ConversationAgoraApi.kt for agent presets, base URL, geofence, or startup behavior
4. AgoraLocalTokenFactory.kt when replacing demo-only local tokens with your backend token flow

Build And Test

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: prerequisites, CLI setup, manual setup, required config, and production security notes
• 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

This quickstart is intentionally convenient, not production-safe as-is.

Because AGORA_APP_CERTIFICATE is packaged into the app for local token generation, anyone with the built APK can extract it and use your Agora project. Before shipping publicly, move token generation and REST join, interrupt, and leave calls to your backend.