Introduction

What adk-rs is, the ideas behind it, and how the crate is organised.

adk-rs is an open-source, code-first Rust framework for building, evaluating, and deploying AI agents — built for teams that want low overhead, predictable latency, and the safety guarantees of the Rust toolchain.

ADK applies software-engineering discipline to agent construction: agents are plain values you compose in code, models are swappable behind one trait, and every run is an append-only stream of typed events. The crate is model-agnostic (Gemini, Anthropic, any OpenAI-compatible endpoint) and deployment-agnostic (a library first; the HTTP server, CLI, and A2A bridge are opt-in features).

§Design at a glance

• One crate, twenty feature flags. adk-rs was originally a workspace of 17 sub-crates and is now a single feature-gated front door. Heavy dependencies (sqlx, axum, reqwest, OpenTelemetry) only compile when you opt in.
• Agents are a trait. BaseAgent is implemented by LlmAgent and by the Sequential/Parallel/Loop workflow agents — and by anything you write yourself. Composition is just nesting values.
• Everything is an event. A run produces an EventStream — a Stream of Event values carrying content, tool calls, state deltas, and control actions. Sessions are append-only event logs.
• Services are pluggable. Session, artifact, memory, and credential storage are traits with in-memory, filesystem, SQLite, and PostgreSQL implementations.
• Secure by default. Credential-bearing clients refuse plaintext HTTP, dev servers refuse non-loopback binds without auth, and the Docker code executor is locked down out of the box. See Security.

§A complete agent in ~25 lines

use adk_rs::agents::LlmAgent;
use adk_rs::providers::gemini::Gemini;
use adk_rs::runner::Runner;
use adk_rs::services::mem::InMemorySessionService;
use futures::StreamExt;
use std::sync::Arc;

#[tokio::main]
async fn main() -> adk_rs::Result<()> {
    let agent = LlmAgent::builder("greeter")
        .description("A friendly greeter")
        .model(Arc::new(Gemini::from_env("gemini-2.5-flash")?))
        .instruction("You greet the user warmly.")
        .build()?;

    let runner = Runner::builder()
        .app_name("hello")
        .agent(Arc::new(agent))
        .session_service(Arc::new(InMemorySessionService::new()))
        .build()?;

    let mut events = runner.run("user", None, "Hello!").await?;
    while let Some(event) = events.next().await {
        if let Some(content) = event?.response.content {
            println!("{}", content.text_concat());
        }
    }
    Ok(())
}

Three pieces appear in every adk-rs program: an agent (here an LlmAgent talking to Gemini), a runner that owns services and orchestrates invocations, and the event stream you consume with ordinary futures combinators.

§Crate layout

§Where to go next

• Installation — feature flags and provider credentials.
• Quickstart — build and run your first agent.
• Agents overview — the BaseAgent trait and the four built-in agent kinds.
• Examples — annotated walkthroughs of every example in the repo.