ADK-Rust

https://github.com/zavora-ai/adk-rust
Admin
ADK-Rust is a production-ready Rust implementation of Google's Agent Development Kit (ADK) for...
Tokens:2,274,255
Snippets:14,801
Trust Score:3.7
License:Apache-2.0
Update:2 days ago
Show doc for...
Tokens:
Raw
### Clone repository and run quickstart example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/README.md

Clones the adk-playground repository, sets the GOOGLE_API_KEY environment variable, and runs the quickstart example with cargo.

```bash
git clone https://github.com/zavora-ai/adk-playground.git
cd adk-playground

# Set your API key
export GOOGLE_API_KEY="your-key"

# Run any example
cargo run --example quickstart
```

--------------------------------

### Setup commands for plugin_system example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/plugin_system/README.md

Commands to set up the example: change to the plugin_system directory, copy the .env.example file to .env, and edit it to add your Google API key.

```bash
cd examples/plugin_system
cp .env.example .env
# Edit .env and add your Google API key
```

--------------------------------

### Run the runtime-ui-tools example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/runtime_ui_showcase/tools/README.md

Use this command to run the example binary. It starts the embedded runtime UI, which you can open at http://127.0.0.1:8088/ui/.

```bash
cargo run --manifest-path examples/runtime_ui_showcase/Cargo.toml \
  --bin runtime-ui-tools
```

--------------------------------

### Quick Start: Run the RAG pipeline with GOOGLE_API_KEY

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-rag/README.md

Runs the quick start example with the GOOGLE_API_KEY environment variable set. Replace 'your-key-here' with your actual API key.

```bash
GOOGLE_API_KEY=your-key-here cargo run

```

--------------------------------

### Setup: Copy environment file and add API key

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/gemini_managed_agents/README.md

Copy the .env.example file to .env and add your API key. This is required before running the examples.

```bash
cp .env.example .env
# Add your API key to .env
```

--------------------------------

### Run the A2A Quickstart Server

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/a2a_quickstart/README.md

Starts the A2A quickstart server on http://localhost:8003.

```bash
cargo run -p a2a-quickstart
```

--------------------------------

### Run the desktop agent

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/desktop_agent/README.md

Run the example with the default task. Requires the environment setup and the computer-use-mcp server installed.

```bash
cargo run --manifest-path examples/desktop_agent/Cargo.toml
```

--------------------------------

### Setup: Copy .env.example and set ADK_API_KEY

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/enterprise_custom_tool/README.md

Copy the environment template and edit .env to set your ADK_API_KEY. Required before running the example.

```bash
cp .env.example .env
# Edit .env and set your ADK_API_KEY
```

--------------------------------

### Setup and Run Commands

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/autonomy_validation/README.md

Copy the environment file and set API keys, then run the example with the specified provider and scenario arguments. The process prints one line per scenario and provider, then a summary table, and exits non-zero when any scenario fails.

```bash
cp examples/autonomy_validation/.env.example examples/autonomy_validation/.env
# set OPENAI_API_KEY, ANTHROPIC_API_KEY, and GEMINI_API_KEY

cargo run --manifest-path examples/autonomy_validation/Cargo.toml -- --provider all --scenario all
cargo run --manifest-path examples/autonomy_validation/Cargo.toml -- --provider anthropic --scenario shared_state_fresh,graph_resume_once
```

--------------------------------

### Run the awp_agent example

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-awp/README.md

Copy the example environment file and run the example with cargo. The example loads business.toml, installs authenticated A2A dispatch to a real LLM agent, protects management routes separately, and exercises each endpoint.

```bash
cp examples/awp_agent/.env.example examples/awp_agent/.env   # add your GOOGLE_API_KEY
cargo run --manifest-path examples/awp_agent/Cargo.toml
```

--------------------------------

### Setup commands

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/retry_reflect/README.md

Commands to set up the retry_reflect example: copy the .env.example to .env and edit it to add your Google API key.

```bash
cd examples/retry_reflect
cp .env.example .env
# Edit .env and add your Google API key
```

--------------------------------

### Set up development environment and run tests

Source: https://github.com/zavora-ai/adk-rust/wiki/development/development-guidelines

Commands to clone the repository, enter the development shell, build, install cargo-nextest, run tests, check lints, and format code. Use Option A (Nix/devenv) for reproducible environments, Option B (setup script) for installing dependencies, or Option C (manual) for a basic build.

```bash
# Clone the repository
git clone https://github.com/zavora-ai/adk-rust.git
cd adk-rust

# Option A: Nix/devenv (reproducible — identical on Linux, macOS, CI)
devenv shell

# Option B: Setup script (installs sccache, cmake, etc.)
./scripts/setup-dev.sh

# Option C: Manual
cargo build

# Install cargo-nextest (parallel test runner, ~10x faster)
curl -LsSf https://get.nexte.st/latest/mac | tar zxf - -C ${CARGO_HOME:-~/.cargo}/bin

# Run all tests
cargo nextest run --workspace

# Check for lints
cargo clippy --all-targets --all-features

# Format code
cargo fmt --all
```

--------------------------------

### Setup script for Linux and macOS

Source: https://github.com/zavora-ai/adk-rust/blob/main/CONTRIBUTING.md

Installs recommended tools or checks what's installed. The script is idempotent and checks feature-gated build tools like protoc and NASM.

```bash
./scripts/setup-dev.sh          # Install recommended tools
./scripts/setup-dev.sh --check  # Just check what's installed
```

--------------------------------

### Setup: Copy and edit environment file

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/desktop_audio/README.md

Copy the .env.example file to .env and edit it to add your Gemini API key. This is only needed for the voice-agent example.

```bash
# Copy and edit the environment file (only needed for voice-agent)
cp examples/desktop_audio/.env.example examples/desktop_audio/.env
# Edit .env and add your Gemini API key

```

--------------------------------

### Run commands: web UI and console demo

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/streaming_bash/README.md

Commands to run the example. The first starts the web UI on http://localhost:3000; the second runs a console demo. Set PORT to change the web port.

```bash
# Web UI (default) — open http://localhost:3000
cargo run --manifest-path examples/streaming_bash/Cargo.toml

# Console demo
cargo run --manifest-path examples/streaming_bash/Cargo.toml -- cli

```

--------------------------------

### Quick start with OpenAIResponsesClient

Source: https://github.com/zavora-ai/adk-rust/wiki/models/openai-responses

Rust example showing how to create an OpenAIResponsesClient, build an agent, create a session, and run a conversation using the Runner. It prints the assistant's text responses.

```rust
use adk_rust::prelude::*;
use adk_rust::session::{CreateRequest, SessionService};
use adk_rust::futures::StreamExt;
use adk_model::openai::{OpenAIResponsesClient, OpenAIResponsesConfig};
use std::collections::HashMap;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    let api_key = std::env::var("OPENAI_API_KEY")?;

    // 1. Create the Responses API client
    let config = OpenAIResponsesConfig::new(&api_key, "gpt-4.1-nano");
    let model = Arc::new(OpenAIResponsesClient::new(config)?);

    // 2. Build an agent
    let agent = Arc::new(
        LlmAgentBuilder::new("assistant")
            .instruction("You are a helpful assistant. Be concise.")
            .model(model)
            .build()?,
    );

    // 3. Create a session
    let sessions: Arc<dyn SessionService> = Arc::new(InMemorySessionService::new());
    sessions.create(CreateRequest {
        app_name: "my_app".into(),
        user_id: "user".into(),
        session_id: Some("s1".into()),
        state: HashMap::new(),
    }).await?;

    // 4. Run through the Runner
    let runner = Runner::builder()
        .app_name("my_app")
        .agent(agent)
        .session_service(sessions)
        .build()?;

    let message = Content::new("user").with_text("What is the capital of France?");
    let mut stream = runner.run(
        adk_rust::UserId::new("user")?,
        adk_rust::SessionId::new("s1")?,
        message,
    ).await?;

    while let Some(event) = stream.next().await {
        let event = event?;
        if let Some(content) = &event.llm_response.content {
            for part in &content.parts {
                if let Some(text) = part.text() {
                    print!("{text}");
                }
            }
        }
    }
    println!();
    Ok(())
}

```

--------------------------------

### Install adk-rag with Cargo.toml dependencies

Source: https://github.com/zavora-ai/adk-rust/wiki/rag

Add the adk-rag crate to your Cargo.toml. The core-only version uses an in-memory store and all chunkers with no external dependencies; the gemini feature enables Gemini embeddings and is recommended for getting started.

```toml
[dependencies]
# Core only (in-memory store, all chunkers, no external deps)
adk-rag = "0.8.0"

# With Gemini embeddings (recommended for getting started)
adk-rag = { version = "0.8.0", features = ["gemini"] }
```

--------------------------------

### Setup Commands

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/prompt_optimizer/README.md

Copy the .env.example file to .env and edit it to add your Google API key.

```bash
cp .env.example .env
# Edit .env and add your Google API key
```

--------------------------------

### Set up environment for context compaction example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/context_compaction/README.md

Copy the .env.example file to .env and edit it to add your GOOGLE_API_KEY.

```bash
cp examples/context_compaction/.env.example examples/context_compaction/.env
# Edit .env and add your GOOGLE_API_KEY
```

--------------------------------

### GET /api/projects/:id/webhook/*path

Source: https://github.com/zavora-ai/adk-rust/wiki/studio/triggers

GET webhook endpoint that starts a workflow with query parameters.

```APIDOC
## GET /api/projects/:id/webhook/*path

### Description
GET webhook endpoint that starts a workflow with query parameters.

### Method
GET

### Endpoint
/api/projects/:id/webhook/*path

### Parameters
#### Path Parameters
- **id** (string) - Required - Project ID
- **path** (string) - Required - Webhook path (e.g., `/my-path`)

#### Query Parameters
- **message** (string) - Optional - Message to process

### Request Example
GET /api/projects/:id/webhook/my-path?message=Hello

### Response
#### Success Response (200)
- **sessionId** (string) - Session ID

#### Response Example
{
  "sessionId": "..."
}
```

--------------------------------

### Install ADK for Go

Source: https://github.com/zavora-ai/adk-rust/wiki/introduction

Install the Go ADK package using go get. The package path is google.golang.org/adk.

```bash
go get google.golang.org/adk
```

--------------------------------

### Set up API key from .env.example

Source: https://github.com/zavora-ai/adk-rust/wiki/quickstart

Copies the .env.example file to .env and instructs to edit it to add the GOOGLE_API_KEY. This is required before running the agent.

```bash
cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY
```

--------------------------------

### GET webhook endpoint example

Source: https://github.com/zavora-ai/adk-rust/wiki/studio/triggers

Shows the URL format for a GET webhook trigger, including query parameters for the message.

```http
GET /api/projects/:id/webhook/my-path?message=Hello
```

--------------------------------

### Set up environment for node caching example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/node_caching/README.md

Copy the .env.example file to .env and edit it to add your GOOGLE_API_KEY. This is a prerequisite for running the example.

```bash
cp examples/node_caching/.env.example examples/node_caching/.env
# Edit .env and add your GOOGLE_API_KEY
```

--------------------------------

### Run the OpenCode Go example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/opencode/README.md

Commands to set up and run the example. Requires an OPENCODE_API_KEY for an OpenCode Go account; running uses that account's quota.

```bash
cd examples/opencode
cp .env.example .env   # add your OPENCODE_API_KEY
cargo run
```

--------------------------------

### Install dependencies and start development server

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-server/webui/README.md

Run `npm ci` to install dependencies and `npm run dev` to start the Vite development server. Vite proxies no API calls, so an ADK server must run on the same origin or use the embedded build for end-to-end testing.

```bash
npm ci
npm run dev

```

--------------------------------

### A2aServer quick_start example

Source: https://github.com/zavora-ai/adk-rust/blob/main/docs/official_docs/a2a/getting-started.md

Sets up an A2A server with one function call, using in-memory sessions, agent card endpoints, JSON-RPC at /a2a, and streaming enabled.

```rust
use adk_rust::prelude::*;
use adk_rust::server::A2aServer;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    let api_key = std::env::var("GOOGLE_API_KEY")?;

    let model = GeminiModel::new(api_key, "gemini-3.7-flash")?;

    let agent: Arc<dyn Agent> = Arc::new(
        LlmAgentBuilder::new("my-agent")
            .description("A helpful AI assistant")
            .instruction("You are a helpful assistant exposed via A2A.")
            .model(Arc::new(model))
            .build()?,
    );

    let app = A2aServer::quick_start(agent);
    let listener = tokio::net::TcpListener::bind("127.0.0.1:8080").await?;
    axum::serve(listener, app).await?;
    Ok(())
}
```

--------------------------------

### Setup script for Windows PowerShell

Source: https://github.com/zavora-ai/adk-rust/blob/main/CONTRIBUTING.md

Installs recommended tools or checks what's installed on Windows. Requires a POSIX shell for devenv and the bash script.

```powershell
./scripts/setup-dev.ps1         # Install recommended tools
./scripts/setup-dev.ps1 -Check  # Just check what's installed
```

--------------------------------

### Set up environment for delta checkpoints example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/delta_checkpoints/README.md

Copy the example environment file and edit it to add your GOOGLE_API_KEY. This is required before running the example.

```bash
cp examples/delta_checkpoints/.env.example examples/delta_checkpoints/.env
# Edit .env and add your GOOGLE_API_KEY
```

--------------------------------

### Run the example with explicit manifest path

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/gemini_interactions_agent/README.md

Alternative command to run the example by specifying the manifest path directly.

```bash
cargo run --manifest-path examples/gemini_interactions_agent/Cargo.toml
```

--------------------------------

### Run the MCP resources example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/mcp_resources/README.md

Commands to set the API key, build both binaries, and run the client agent. The client spawns the server automatically.

```bash
export GOOGLE_API_KEY=your_key

# Build both binaries
cargo build --manifest-path examples/mcp_resources/Cargo.toml

# Run the agent (spawns the server automatically)
cargo run --manifest-path examples/mcp_resources/Cargo.toml --bin resources-client
```

--------------------------------

### Quick start: create AgentRetrievalStore with ADC

Source: https://github.com/zavora-ai/adk-rust/blob/main/docs/official_docs/rag/agent-retrieval.md

Creates an AgentRetrievalStore using Application Default Credentials and environment configuration, then creates a collection. This is the minimal setup to start using the backend.

```rust
use adk_rag::VectorStore;
use adk_rag::agent_retrieval::{AgentRetrievalConfig, AgentRetrievalStore};

async fn run() -> adk_rag::Result<()> {
    // Application Default Credentials; project/location from the environment.
    let store = AgentRetrievalStore::new_with_adc(AgentRetrievalConfig::from_env()?)?;

    store.create_collection("docs", 768).await?;
    // upsert / search / delete exactly as with any other VectorStore backend
    Ok(())
}

```

--------------------------------

### Quick Start: Cargo dependencies for adk-rag with Gemini

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-rag/README.md

Adds the adk-rag crate with the 'gemini' feature, along with tokio for async runtime. Required for the quick start RAG pipeline example.

```toml
[dependencies]
adk-rag = { version = "3.0.0", features = ["gemini"] }
tokio = { version = "1", features = ["full"] }

```

--------------------------------

### Run example_store example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/README.md

Runs the example_store example, which demonstrates Vertex AI Example Store for few-shot upsert and similarity search against a pre-provisioned store. Requires Google Cloud ADC (gcloud auth application-default login).

```bash
cargo run --manifest-path examples/example_store/Cargo.toml
```

--------------------------------

### Run the managed-agents-files example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/managed_agents_files/README.md

Executes the example with cargo. Ensure the environment is set up as described.

```bash
cargo run -p managed-agents-files
```

--------------------------------

### Get or Create Pattern

Source: https://github.com/zavora-ai/adk-rust/blob/main/docs/official_docs/sessions/sessions.md

Example of a get-or-create pattern to avoid creating a session when it already exists.

```APIDOC
## Get or Create Pattern

### Description
Shows how to create a session only when `get` reports it missing, and read it again when `create` loses a race.

### Example
```rust
use adk_session::{CreateRequest, GetRequest, Session, SessionService};
use std::collections::HashMap;

async fn get_or_create(
    service: &dyn SessionService,
    app_name: &str,
    user_id: &str,
    session_id: &str,
) -> adk_core::Result<Box<dyn Session>> {
    let get = || GetRequest {
        app_name: app_name.to_string(),
        user_id: user_id.to_string(),
        session_id: session_id.to_string(),
        num_recent_events: None,
        after: None,
    };
    match service.get(get()).await {
        Err(error) if error.is_not_found() => {
            let created = service
                .create(CreateRequest {
                    app_name: app_name.to_string(),
                    user_id: user_id.to_string(),
                    session_id: Some(session_id.to_string()),
                    state: HashMap::new(),
                })
                .await;
            match created {
                Err(error) if error.is_conflict() => service.get(get()).await,
                other => other,
            }
        }
        other => other,
    }
}
```
```

--------------------------------

### DeclarativePolicy Builder

Source: https://github.com/zavora-ai/adk-rust/blob/main/docs/official_docs/security/tool-authorization.md

Example of building a DeclarativePolicy with rules for denying, allowing, and requiring approval, and installing it on a Runner.

```APIDOC
## DeclarativePolicy Builder

### Description
Builds a `DeclarativePolicy` that decides every tool call the run makes, based on rules matched in order. The first matching rule decides; a call no rule matches is denied by default.

### Usage
```rust
use adk_core::{ArgPredicate, DeclarativePolicy, PolicyRule};
use adk_runner::Runner;
use std::sync::Arc;

let policy = DeclarativePolicy::builder()
    // Rules added earlier win, so this deny applies even though the tool is read-only.
    .deny("read_secret", "secrets are never exposed to the model")
    .allow_read_only()
    .rule(PolicyRule::allow("transfer").when(ArgPredicate::at_most("/amount", 100.0)))
    .require_approval("transfer", "transfers over 100 need a person")
    .rule(PolicyRule::allow("fetch_url").when(ArgPredicate::domain_in("/url", ["docs.rs"])))
    .build();

let runner = Runner::builder()
    .app_name("treasury")
    .agent(agent)
    .session_service(session_service)
    .tool_policy(Arc::new(policy))
    .build()?;
```

### Policy Decisions
- `PolicyDecision::Allow` - The call proceeds to guardrails and execution.
- `PolicyDecision::Deny { reason }` - The tool does not run; the model receives `{"error": "Tool '<name>' denied by policy: <reason>"}`.
- `PolicyDecision::RequireApproval { reason }` - The call goes through confirmation, as if the agent required it.

### Argument Predicates
- `ArgPredicate::equals(pointer, value)` - Holds when the argument equals `value`.
- `ArgPredicate::in_set(pointer, values)` - Holds when the argument equals one of `values`.
- `ArgPredicate::at_most(pointer, max)` - Holds when the argument is a JSON number no greater than `max`.
- `ArgPredicate::starts_with(pointer, prefix)` - Holds when the argument is a string with that prefix (lexical — screen paths with a guardrail).
- `ArgPredicate::domain_in(pointer, domains)` - Holds when the argument is an `http(s)` URL whose host is listed; `*.example.com` matches subdomains. URLs with user information, backslashes, or percent-encoded hosts never match.

A predicate whose pointer is missing or whose value has the wrong type does not hold.

### Rule Restrictions
- `for_agent(glob)` - Matches the acting agent's `AgentId`.
- `for_tenant(tenant)` - Matches the acting agent's principal tenant.
- `for_class(class)` - Matches the acting agent's principal class.

Such a rule never matches a call without an acting context.
```

--------------------------------

### State usage example

Source: https://github.com/zavora-ai/adk-rust/wiki/core

Demonstrates how to set and get state values with different prefixes in a callback or tool.

```APIDOC
## State usage example

### Description
Demonstrates how to set and get state values with different prefixes in a callback or tool.

### Code Example
```rust
// In a callback or tool
let state = ctx.session().state();

// User preference (persists across sessions)
state.set("user:theme".into(), json!("dark"));

// Session-specific data
state.set("current_topic".into(), json!("weather"));

// Temporary data (cleared after this turn)
state.set("temp:step_count".into(), json!(1));

// Read values
if let Some(theme) = state.get("user:theme") {
    println!("Theme: {}", theme);
}
```
```

--------------------------------

### Setup: Copy .env.example and add API key

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/managed_agents_custom_tools/README.md

Copies the environment template and instructs to add the ANTHROPIC_API_KEY with Managed Agents beta access.

```bash
cp ../../.env.example .env
# Add your ANTHROPIC_API_KEY to .env

```

--------------------------------

### generate_content()

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-gemini/README.md

Starts a content generation request. Chain with `with_user_message` and `execute` to send the request and get a response.

```APIDOC
## generate_content()

### Description
Starts a content generation request. Chain with `with_user_message` and `execute` to send the request and get a response.

### Method
Method

### Returns
A request builder for content generation.

### Example
```rust
let response = client
    .generate_content()
    .with_user_message("Name one planet in a short sentence.")
    .execute()
    .await?;
```
```

--------------------------------

### Groq Complete Example

Source: https://github.com/zavora-ai/adk-rust/blob/main/docs/official_docs/models/providers.md

Sets up a Groq-powered agent using GroqClient::new with GroqConfig::gpt_oss_120b, the default model. Requires GROQ_API_KEY environment variable.

```rust
use adk_rust::Launcher;
use adk_rust::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("GROQ_API_KEY")?;
    let model = GroqClient::new(GroqConfig::gpt_oss_120b(&api_key))?;

    let agent = LlmAgentBuilder::new("groq_assistant")
        .description("Groq-powered assistant")
        .instruction("You are a helpful assistant. Be concise.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;
    Ok(())
}
```

--------------------------------

### Install and run adk-cli

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-cli/README.md

Commands to install adk-cli via cargo and run the adk-rust binary with various options, including interactive setup, provider pre-configuration, chat, web server, and coding agent modes.

```bash
cargo install adk-cli

# Just run it — interactive setup picks your provider on first run
adk-rust

# Or pre-configure a provider
adk-rust --provider openai --api-key sk-...

# Equivalent to:
adk-rust chat

# Web server
adk-rust serve --port 3000

# Coding agent (sandboxed to the directory)
adk-rust code "make the failing test pass"
adk-rust goal "all tests green" --until "cargo test" --resume   # autonomous, durable
adk-rust ultracode "add input validation"                       # parallel ultra-review
```

--------------------------------

### Run the example with GOOGLE_API_KEY

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/gemini3_builtin_tools/README.md

Sets the required API key and runs the example crate. This is the primary command to execute the example.

```bash
export GOOGLE_API_KEY=your-key-here
cargo run --manifest-path examples/gemini3_builtin_tools/Cargo.toml
```

--------------------------------

### Create a DockerExecutor with persistent container and run Python code

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-code/README.md

Sets up a DockerExecutor with a persistent container, installs numpy and pandas, enables network, and runs two Python executions reusing the same container. The example shows building an ExecutionRequest with SandboxPolicy::strict_python() and NetworkPolicy::Enabled, then starting, executing, and cleaning up. The container's network mode is fixed at creation; requests with stricter policies are rejected with ExecutionError::UnsupportedPolicy.

```rust
use adk_code::{
    CodeExecutor, DockerConfig, DockerExecutor, ExecutionLanguage, ExecutionPayload,
    ExecutionRequest, NetworkPolicy, SandboxPolicy,
};

fn python(code: &str) -> ExecutionRequest {
    let mut sandbox = SandboxPolicy::strict_python();
    sandbox.network = NetworkPolicy::Enabled; // the container below has network access
    ExecutionRequest {
        language: ExecutionLanguage::Python,
        payload: ExecutionPayload::Source { code: code.to_string() },
        argv: vec![],
        stdin: None,
        input: None,
        sandbox,
        identity: None,
    }
}

async fn run() -> Result<(), Box<dyn std::error::Error>> {
    let executor =
        DockerExecutor::new(DockerConfig::python().pip_install(&["numpy", "pandas"]).with_network())?;
    executor.start().await?;

    // Multiple executions reuse the same container
    let first = executor.execute(python("import numpy; print(numpy.__version__)")).await?;
    let second = executor.execute(python("print('still running')")).await?;
    println!("{}\n{}", first.stdout, second.stdout);

    executor.cleanup().await?; // Prefer explicit cleanup over Drop
    Ok(())
}
```

--------------------------------

### Run simple example

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-gemini/examples/README.md

Command to run the basic content generation example.

```bash
GEMINI_API_KEY="your-api-key" cargo run --example simple
```

--------------------------------

### ScriptedLlm setup example

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-managed/README.md

Creates a ScriptedLlm instance with two scripted turns, including a tool call for web_search. Each model call gets the next scripted turn; requests() returns what the runtime sent on every call, and a call past the last turn fails with model.scripted.exhausted. This is not a mock; it implements the real Llm trait and exercises the full runtime (durable runs, checkpoints, replay, event mapping).

```rust
use adk_managed::testing::{ScriptedLlm, ScriptedTurn, ScriptedToolCall};
use serde_json::json;

let llm = ScriptedLlm::new("test", vec![
    ScriptedTurn {
        text: Some("I'll search for that.".into()),
        tool_calls: vec![ScriptedToolCall {
            name: "web_search".into(),
            input: json!({"query": "rust agents"}),
            id: Some("tc_1".into()),
        }],
    },
    ScriptedTurn {
        text: Some("Here are the results...".into()),
        tool_calls: vec![],
    },
]);
```

--------------------------------

### Quick start: create agent, stream events, and archive session

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-enterprise/README.md

Rust example showing how to use EnterpriseClient to create an agent, start a session, stream events, and archive the session. Requires the adk-enterprise, futures, and tokio dependencies.

```rust
use adk_enterprise::{EnterpriseClient, CreateAgentParams, SessionEvent, ContentBlock};
use futures::StreamExt;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = EnterpriseClient::from_env()?;

    // Create an agent (any model — Gemini, OpenAI, Anthropic, etc.)
    let agent = client.create_agent(CreateAgentParams {
        name: "Hello Agent".into(),
        model: "gemini-3.7-flash".into(),
        system: Some("You are brief and friendly.".into()),
        ..Default::default()
    }).await?;

    // Start a session and open the event stream
    let session = client.create_session(&agent.id, None).await?;
    let mut stream = client.stream_events(&session.id).await?;

    // Send a message
    client.send_message(&session.id, "What is 2+2?").await?;

    // Process real-time events
    while let Some(event) = stream.next().await {
        match event? {
            SessionEvent::Message { content, .. } => {
                for block in content {
                    if let ContentBlock::Text { text } = block {
                        println!("{text}");
                    }
                }
            }
            SessionEvent::StatusIdle { .. } => break,
            _ => {}
        }
    }

    client.archive_session(&session.id).await?;
    Ok(())
}
```

--------------------------------

### Basic Server Setup with ServerConfig and create_app

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-server/README.md

Creates a ServerConfig with an agent loader and session service, then builds the app and serves it on 127.0.0.1:8080 using axum.

```rust
use adk_server::{create_app, ServerConfig};
use std::sync::Arc;

let config = ServerConfig::new(
    Arc::new(SingleAgentLoader::new(Arc::new(agent))),
    Arc::new(InMemorySessionService::new()),
);

let app = create_app(config);

let listener = tokio::net::TcpListener::bind("127.0.0.1:8080").await?;
axum::serve(listener, app).await?;
```

--------------------------------

### Start WebDriver server (ChromeDriver and Selenium)

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-browser/README.md

Commands to start a WebDriver-compatible server on port 4444. ChromeDriver is installed via Homebrew and run directly; Selenium is run via Docker with an optional noVNC viewer on port 7900.

```bash
# ChromeDriver
brew install chromedriver && chromedriver --port=4444
```

```bash
# Selenium (Docker)
docker run -d -p 4444:4444 -p 7900:7900 selenium/standalone-chrome
```

--------------------------------

### Use ExampleStoreProvider in an agent

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/example_store/README.md

Shows how to create an ExampleStoreClient with ADC, wrap it in an ExampleStoreProvider with top_k 3, and attach it as a before_model_callback to an LlmAgentBuilder. On every model call, the callback searches the store with the latest user message and prepends retrieved examples to the request preamble.

```rust
use adk_tool::example_store::{ExampleStoreClient, ExampleStoreConfig, ExampleStoreProvider};
use std::sync::Arc;

let client = Arc::new(ExampleStoreClient::new_with_adc(ExampleStoreConfig::from_env()?)?);
let provider = ExampleStoreProvider::new(client).with_top_k(3);

let agent = LlmAgentBuilder::new("support")
    .model(model)
    .instruction("You are a helpful support assistant.")
    .before_model_callback(provider.into_before_model_callback())
    .build()?;
```

--------------------------------

### Ollama Server Startup Output

Source: https://github.com/zavora-ai/adk-rust/wiki/models/ollama

Example output when starting the Ollama server, showing key generation and listening address.

```text
Couldn't find '/Users/you/.ollama/id_ed25519'. Generating new private key.
Your new public key is: ssh-ed25519 AAAA...
time=2024-01-05T12:00:00.000Z level=INFO source=server.go msg="Listening on 127.0.0.1:11434"
```

--------------------------------

### Run any example with GEMINI_API_KEY

Source: https://github.com/zavora-ai/adk-rust/blob/main/adk-gemini/examples/README.md

Command to run any example in the directory. Requires a GEMINI_API_KEY environment variable, obtainable from Google AI Studio.

```bash
GEMINI_API_KEY="your-api-key" cargo run --example <example_name>
```

--------------------------------

### Run the action nodes example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/action_nodes/README.md

Executes the example using Cargo. No external services or Docker required; all scenarios use in-process execution and temp files.

```bash
cargo run --manifest-path examples/action_nodes/Cargo.toml
```

--------------------------------

### CI pipeline integration with GitHub Actions

Source: https://github.com/zavora-ai/adk-rust/blob/main/docs/official_docs/development/cargo-adk-build.md

Example GitHub Actions workflow that installs cargo-adk and runs cargo adk build on ubuntu-latest.

```yaml
# .github/workflows/ci.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo install cargo-adk
      - run: cargo adk build
```

--------------------------------

### Start Redis servers for session backends example

Source: https://github.com/zavora-ai/adk-rust/blob/main/examples/session_backends/README.md

Starts a standalone Redis server on port 6380 and a three-node Redis Cluster on ports 7001-7003. Requires Redis 7 or later; redis-cli --cluster create needs at least three nodes.

```bash
redis-server --port 6380 --daemonize yes --save ""
for port in 7001 7002 7003; do
  mkdir -p /tmp/adk-cluster/$port
  redis-server --port $port --cluster-enabled yes --dir /tmp/adk-cluster/$port \
    --daemonize yes --save ""
done
redis-cli --cluster create 127.0.0.1:7001 127.0.0.1:7002 127.0.0.1:7003 \
  --cluster-replicas 0 --cluster-yes
```

--------------------------------

### Run MCP Manager Example

Source: https://github.com/zavora-ai/adk-rust/blob/main/docs/official_docs/mcp/manager.md

Run the verified MCP manager example using Cargo. The example starts a real Rust MCP child process, discovers and calls a tool, adds and enables a second server, updates it, saves the registry, disables and removes it, and closes all sessions. It requires no model, API key, package download, or network access.

```bash
cargo run --manifest-path examples/mcp_manager/Cargo.toml
```

--------------------------------

### Example with protocol selection (mcp_apps)

Source: https://github.com/zavora-ai/adk-rust/wiki/tools/ui-tools

JSON example showing how to select the mcp_apps protocol and provide a resource URI for the surface.

```json
{
  "protocol": "mcp_apps",
  "mcp_apps": {
    "resource_uri": "ui://demo/surface"
  }
}
```

--------------------------------

### Setup and run commands

Source: https://github.com/zavora-ai/adk-rust/blob/main/cargo-adk/README.md

Commands to set up and run a generated agent project: copy the environment file, add an API key, run the interactive console, verify compilation, and deploy to the platform.

```bash
cd my-agent
cp .env.example .env    # add your API key
cargo run               # interactive console
cargo adk build         # verify compilation
cargo adk deploy        # push to platform
```
Tokens:
Raw