Learning outcome
Clone the exact source, configure the private server and connect a phone.
Use the published checkpoint below, so the code excerpts and test counts remain reproducible. Open only a2ui/ in Android Studio; each cookbook topic is an independent project. You need Kotlin/Compose and coroutine basics, Git, Android SDK Platform 37, an API 26+ emulator or phone, Node.js 22+, and a Gemini project with an available model and quota.
Clone and create your learning branch
git clone https://github.com/AndroidEngineers/android-ai-cookbook.git
cd android-ai-cookbook
git switch --detach 33ff08b56b3e5f00240c99cf2848f0e35bdde998
git switch -c learning/pocketcommunity
cd a2ui
./gradlew :app:assembleDebug :app:testDebugUnitTest :app:lintDebug
The Gradle daemon criteria pin Java 25; the app compiler toolchain targets Java 17. Foojay can provision toolchains, so the first build can download them. Gradle 9.3.1, AGP 9.1.1, Compose 1.13.0-alpha03, Material 3 1.5.0-alpha28 and A2UI 1.0.0-alpha01 are pinned together. Do not independently upgrade an alpha dependency while reproducing the baseline. Windows users can use gradlew.bat.
Start the companion server in a separate terminal
cd android-ai-cookbook/a2ui/server
cp .env.example .env
# Edit .env locally: set GEMINI_API_KEY and GEMINI_MODEL.
# Choose a model available to your own Gemini project.
npm start
The key goes in server/.env. Never paste it into Kotlin, Gradle, assets, screenshots, a learning log, or the app Setup field. .env and local.properties are ignored. Restart the server after changing environment values. The sample uses Node built-ins and has no runtime npm packages to install.
Check configuration and connect a physical phone
curl http://127.0.0.1:8787/health
adb devices
# Replace DEVICE_SERIAL with your selected connected phone.
adb -s DEVICE_SERIAL reverse tcp:8787 tcp:8787
Enter this URL in the app Setup field
| Target | Debug endpoint |
|---|---|
| Physical phone using ADB reverse | http://127.0.0.1:8787/chat |
| Standard Android emulator | http://10.0.2.2:8787/chat |
| Release build | An authorized HTTPS service; production deployment is not supplied |
Run the app configuration from Android Studio on the selected device. Keep the server and ADB connection alive; reapply port reverse after reconnection. configured: true from /health means a key is present, not that it is valid or the model is available. Send a real prompt and inspect the native response to verify the full connection. Gemini usage may incur charges.
Connection failures
Connection refused usually means the server is stopped, the port is wrong, or reverse was not applied to this device. A 503 key message means server configuration is missing. A model access/quota error requires checking the Gemini project, not changing Android UI code. No Firebase configuration is used here.
Practice and checkpoint
Ask for Android events in Bengaluru, request a venue, and then a checklist. Save the build result and a screenshot without credentials. Stop the server and send another request: the app must show a retryable error rather than a new event card. Restart the server and retry. Record actual results; a working /health response is insufficient.
Source and next steps
- Pinned implementation — The exact app and server revision used by this lesson.
Back to roadmap · Practice this unit in the codelab