ADK Voice Agent: guide for agents and developers

1. Studying the recipe: how ADK Voice Agent keeps a Gemini Live voice agent responsive while coding agents work on each user's computer.
2. Maintaining the code: rules, repo layout, and commands when changing this repo.

Studying the recipe

The problem

Voice is synchronous and short-lived; coding work is slow and stateful. Combined naively:

• Blocking tool calls stall the audio stream.
• Reading a 60-line diff aloud is useless.
• Work in one thread is lost to the next without a persistent disk and named project folders.
• Coding agents holding OAuth tokens can send mail without asking.

Recipe table

Beyond the core

• Briefing a returning user. app/voice/briefing.py → collect_missed_milestones() and app/voice/instruction.py → build_orchestrator_instruction() summarize what happened while the user was away. build_connections_briefing() lists unconnected apps under NOT CONNECTED so the voice opens the Connect page via navigate (app/tools/navigation_tools.py) and resumes on [APP CONNECTED] <name>.
• Quick reads without a thread. app/tools/look_tools.py → look() runs in-process workspace_mcp tools marked readOnlyHint and shows an answer card on home. Routing rules live in app/voice/instruction.py and tests/eval/datasets/system1.json.
• ADK Voice Agent's own tools over MCP. app/api/mcp.py serves list_threads, read_thread, update_user, save_to_drive, present_card, recall, recall_conversation, and grounded search at /api/v1/mcp with a per-thread token (mint_mcp_token()), reached via the daemon's /mcp-relay and documented in connected-apps-mcp.
• Durable event log. app/store/thread_store.py → ThreadStore stores thread rows, append-only events, and ADK sessions (get_session_service() in app/app_utils/services.py) in SQLite or Postgres.
• Remembering the user. app/memory/ keeps one structured profile per user in Agent Engine Memory Bank: store.py → recall_profile(), profile.py → render_profile(), ingest.py → curated_contents() (user speech, agent replies, and start_thread, message_thread, share_context arguments; never tool output), and episodes.py for conversation/thread memories. See Architecture: memory and Security model: memory.
• Carrying context between conversations and threads. app/voice/continuity.py carries recent turns across dropped connections; share_context in app/threads/registry.py and app/threads/prompts.py → share_context_block() passes prompts, answers, changed files, and branch between threads. See Architecture: sharing context between threads.
• Screen focus and project threads. app/voice/focus.py tracks screen focus (home, project, thread) via POST /api/v1/focus and navigate (app/tools/navigation_tools.py), injecting OPEN ON SCREEN and pushing live [SCREEN FOCUS] updates. app/projects.py → project_thread() lists a project's threads and reads its status note from a running computer (else from the newest thread in the store); name_project() promotes scratch/ to projects/. See Architecture: screen focus and projects.
• Test doubles at the boundaries only. Tests swap the environment (set_environment), put a scripted claude / agy on PATH (tests/fake_agent_cli.py), and inject HTTP transports (tests/fake_integrations.py).
• One container for System 1. app/fast_api_app.py serves /run_live, REST, and the built UI; computers run sandbox/Dockerfile.

Study order

1. app/agent.py, then app/voice/: non_blocking.py, thread_updates.py, focus.py, instruction.py.
2. app/threads/: follow start_thread() in app/tools/thread_tools.py to executing (status="running"), through awaiting_permission (status="awaiting_approval") and approve(), to completed (status="idle", outcome="finished") and message_thread().
3. app/workers/workspace.py: folder selection, leases, worktrees, and per-turn commits.
4. app/workers/providers/, app/workers/environment.py, and sandbox/README.md.
5. app/api/mcp_gateway.py, app/api/mcp_permissions.py, and config/policy.yaml.
6. app/api/surfaces.py, web/src/components/stage/ThreadView.tsx, and web/src/components/a2ui/.
7. app/auth/ and config/integrations.yaml.

What to skip when studying

• Setup & deploy: scripts/onboard.py, scripts/doctor.sh, scripts/provisioning/, scripts/deploy.py, terraform/.
• UI chrome & first-boot plumbing: web/src/components/sheets/, web/src/components/stage/, sandbox/entrypoint.sh.

agents-cli metadata

agents-cli-manifest.yaml declares voice_agent in app/agent.py; manifest.yaml is the adk-recipes catalog entry.

Maintaining the code

Keep this file current

When moving, renaming, or adding a module, update the recipe table, layout, and linked docs in docs/. All file and symbol links must resolve.

Rules

• Only change code the request targets. Reuse existing protocols or registries over per-provider special cases.
• Run Python through uv run.
• Never change model values (LIVE_MODEL, GROUNDING_MODEL, harness models) unless asked; model reads go through app/app_utils/models.py. Fix a 404 by checking LIVE_MODEL_LOCATION or GOOGLE_CLOUD_LOCATION (global).
• No test-mode branches in app/. Test doubles live in tests/fakes.py, tests/fake_agent_cli.py, tests/fake_integrations.py, and tests/eval/sitecustomize.py.
• Keep app/agent.py to wiring; put voice logic in app/voice/ and thread logic in app/threads/.
• New thread states/transitions go in TRANSITIONS in app/threads/model.py, with wording in describe.py.
• New environment variables go in .env.example and docs/configuration.md.
• UI styles use tokens in web/src/styles/base.css, never hex literals.
• Never block on stdin as an agent: pass NONINTERACTIVE=1 (or --no-input) with make onboard PROJECT=<id> NONINTERACTIVE=1, and run make deploy DRY_RUN=1 before make deploy AUTO_APPROVE=1 NONINTERACTIVE=1. See Run as a coding agent.
• Import ADK tool instances, not modules: from google.adk.tools.load_web_page import load_web_page.
• Verify voice changes with make eval (uv run agents-cli eval compare <baseline> <candidate>), then make test and make lint.
• Deploy only when asked (make deploy DRY_RUN=1 first). On a terraform 409, terraform import the resource.
• If an error repeats three times, fix the root cause instead of retrying.

Layout

adk-voice-agent/
├── app/
│   ├── agent.py              # root_agent `voice_agent`: wiring only
│   ├── fast_api_app.py       # FastAPI app: ADK /run_live, REST, built UI, lifespan
│   ├── voice/                # non_blocking, thread_updates, voice_mode (VoiceSessionPlugin, live_run_config, VoiceAgent), focus (OPEN ON SCREEN), instruction, briefing, callbacks, background, preferences, continuity
│   ├── threads/              # model (states, Turn, TRANSITIONS), registry, driver, describe, prompts, titles, summaries, retention, documents (save_to_drive)
│   ├── store/                # ThreadStore, UserSettingsStore, SQLAlchemy models and engine
│   ├── memory/               # profile (UserProfile, render_profile), store (MemoryStore, MemoryBankStore, recall_profile), ingest (curated_contents, remember_on_close), episodes
│   ├── workers/
│   │   ├── environment.py    # Environment protocol: SandboxEnvironment, LocalEnvironment
│   │   ├── factory.py        # resolve_environment(), set_environment()
│   │   ├── providers/        # ComputerProvider: host, docker, static, gce; registry; reaper; last_known
│   │   ├── runs.py           # detached harness runs: launch, poll, cancel
│   │   ├── workspace.py      # home projects (code/, projects/, scratch/), leases, worktrees, commits, push
│   │   ├── policy.py         # declarative permissions and run budgets (config/policy.yaml)
│   │   ├── manifest.py       # config/workspaces.yaml loader
│   │   └── harnesses/        # CodingHarness, CliHarness, claude, antigravity, registry, activity
│   ├── api/                  # REST under /api/v1, MCP bridge (/api/v1/mcp), mcp_gateway, mcp_permissions, mcp_outputs, surfaces, projects, apps, auth, memories
│   ├── auth/                 # identity (dev / IAP), credential_store, oauth, providers, provider_hooks, google_apis, oauth_popup, adc, sandbox_credentials, env_store, verify, github/
│   ├── tools/                # thread_tools, navigation_tools (navigate), grounding_tools, look_tools (look), memory_tools
│   ├── app_utils/            # services, models (model env readers), http_client, time_utils, env_flags, model_locations, user_context, host_guard
│   ├── projects.py           # list_projects, project_thread, delete_project_history, ProjectLabels, name_project
│   ├── user_settings.py      # per-user voice preferences and default harness
│   └── context_cards.py      # context cards and answer-card kinds (CARD_KINDS, card_items)
├── config/                   # integrations.yaml, policy.yaml, workspaces.yaml
├── .mcp.json                 # connected apps' MCP servers, proxied by the gateway
├── workspace_mcp/            # built-in stdio Google Workspace MCP servers (_server.py, _google.py)
├── docs/                     # quickstart, computer, connected-apps, architecture, configuration, security-model, extending, evals
├── scripts/                  # onboard.py, provisioning/, doctor.sh, computer_ssh.py, deploy.py, run_eval.py, dev.sh
├── sandbox/                  # computer image: Dockerfile, entrypoint.sh, home/, skills/, server.py
├── terraform/                # Cloud Run + IAP, Secret Manager, Cloud SQL, Agent Engine, computer VPC/NAT/template/SA
├── tests/                    # unit/, live/, eval/ (voice/ System 1, system2_agent/ System 2, datasets/, fixtures/alex), test_runnability.py, fakes
├── web/                      # React + TypeScript + Vite UI (src/components/a2ui/answer/, src/lib/cards.ts)
├── Dockerfile                # System 1 image: built UI + API
├── Makefile                  # run `make` for targets
├── manifest.yaml             # adk-recipes catalog entry
└── agents-cli-manifest.yaml  # agents-cli project config

Commands

REST routes: Architecture: REST control plane. Troubleshooting: Quickstart, Your computer, Connected apps, Evals.