Setup and Running

Choose the first result you want, then install its dependencies. The workspace uses Rust 1.93+ (the checked-in toolchain pins 1.93.1).

Goal	Path	Additional requirements
Run a text agent	Published crate or hello-text example	Model credentials; no audio feature
Run a microphone conversation	hello-voice or Live builder	voice-io, local audio devices and headers
Test conversation logic	Offline cookbook or conversation CI	No model credentials
Inspect the UI	Repository Web UI	Provider setup for live actions

On Ubuntu/Debian, native TLS builds use pkg-config, libssl-dev, and the normal Rust build toolchain. Install libasound2-dev only for local audio paths. macOS builds use the Xcode command-line tools. Match dependencies to the feature set you compile.

Authentication for live requests

Pick one platform. The same variables serve the whole stack — Live voice sessions and text agents both accept the GEMINI_API_KEY / GOOGLE_GENAI_API_KEY / GOOGLE_API_KEY chain.

Google AI

export GEMINI_API_KEY=your-api-key   # https://aistudio.google.com/apikey

Vertex AI — project-scoped Google Cloud

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=us-central1
gcloud auth login   # connect_from_env falls back to gcloud auth print-access-token

Repo examples also read these from a .env at the workspace root (cp .env.example .env).

The SDK resolves a platform-specific model default. Provider access and model availability can change independently of the SDK. Pin GEMINI_LIVE_MODEL or .model(...) when needed; use GEMINI_TEXT_MODEL separately for text agents.

Path A — build your own project

cargo new my-agent && cd my-agent

[dependencies]
gemini-adk-fluent-rs = "2.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

For microphone/speaker use, change the dependency to gemini-adk-fluent-rs = { version = "2.0", features = ["voice-io"] }. The crate ships default = ["tls-native", "gemini-llm"]:

Feature	Default	Enables	Without it
gemini-llm	on	Text generation via GeminiLlm	Only with --no-default-features: compiles, then errors at runtime: “requires the ‘gemini-llm’ feature flag”
voice-io	off	talk() microphone/speaker duplex	No talk() method on the handle
voice	off	Bundle: voice-io, denoise, dsp, vad-wavekat	Enable the pieces you need individually
full	off	Bundle: voice plus sip, http-tools, templates, otel-otlp	Same

--no-default-features drops the TLS backend along with gemini-llm. Name tls-native or tls-rustls again when you do that: with neither, the crate still compiles, and the first wss:// dial fails immediately with NoTlsBackend, an error that names the feature to enable.

Then copy either Quickstart program from the workspace README into src/main.rs — both are complete files, compiled in CI exactly as printed — and cargo run.

Writing typed tools later adds three dependencies:

serde = { version = "1", features = ["derive"] }
serde_json = "1"
schemars = "0.8"   # the 0.8 pin matters — schemars 1.x is a different trait

Prefer scaffolding? cargo install gemini-adk-cli-rs then adk create my-agent.

Path B — run this repository

git clone https://github.com/vamsiramakrishnan/gemini-rs
cd gemini-rs
cp .env.example .env    # fill in credentials from the Authentication section

The quickstart programs

cargo run -p example-quickstart --bin hello-text    # first token, no audio needed
cargo run -p example-quickstart --bin hello-voice   # first sound, mic + speakers

The ADK Web UI and Flow Studio

cargo run -p gemini-adk-web-rs

Open http://localhost:25125. The landing page lists every bundled app — open a voice app such as voice-chat, call-screening, or debt-collection, allow microphone access, and use the DevTools panel on the right to inspect state, phases, metrics, tools, and traces. /flows is the Flow Studio.

The cookbook

The cookbook contains separate examples for configuration, tools, evaluation, and live integration. Start with a model-free example before configuring a provider. See the source of each binary for its requirements:

cargo run -p example-cookbook --bin 01-foundations
cargo run -p example-cookbook --bin 17-evaluation-suite
cargo run -p example-cookbook --bin 37-governed-flow

Tier	Binaries	Focus
Crawl	01–10	Single-agent foundations, tools, callbacks, state, guards
Walk	11–20	Routing, fallback, middleware, context, evaluation, artifacts
Run	21–40	Production compositions, voice, tool policies, MCP, governed flows

The full list with descriptions is examples/INDEX.md.

Verify the workspace

cargo test --workspace    # ~2,500 tests, no credentials required

For frontend-only changes:

node --check apps/gemini-adk-web-rs/static/js/app.js
node --check apps/gemini-adk-web-rs/static/js/devtools.js

Troubleshooting

Symptom	Check
Connect fails: “not found for API version v1beta” / setup closes without setupComplete	The model isn’t in your platform’s catalog. Leave .model() unset for a platform-appropriate default, or list what your key reaches: curl "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY" and look for bidiGenerateContent (Live) or generateContent (text) under supportedGenerationMethods.
“GeminiLlm requires the ‘gemini-llm’ feature flag”	You built with --no-default-features; add gemini-llm back (it is on by default).
No talk() method	Add features = ["voice-io"]; Linux also needs libasound2-dev.
JsonSchema bound errors / “multiple versions of crate schemars”	Pin schemars = "0.8".
Web UI does not open	Confirm the server printed http://localhost:25125 and no firewall blocks the port.
Microphone is silent	Browser microphone permission must be allowed; Linux also needs libasound2-dev.
Live API auth fails	.env at the repository root (or exported vars) with GEMINI_API_KEY or the Vertex AI trio.
Vertex AI rejects setup fields	The SDK strips Google AI-only fields automatically; confirm GOOGLE_GENAI_USE_VERTEXAI=true.
Linker fails with ld terminated	Retry after closing other large builds; usually linker memory pressure, not Rust code.

What to Inspect in DevTools

Panel	Use it for
Timeline	Event ordering, interruptions, tool calls, turn boundaries
Events	Raw JSON payloads for exact debugging
State	Canonical state, raw extractor output, state_meta:* provenance
Phases	Current phase, requirements, transitions, state promotion decisions
Metrics	Latency, tokens, interruptions, playback buffer health
Traces	Span timing across model, tools, and runtime work
Cookbook	Source path, run command, and app-specific inspection checklist