adk-runner

Agent execution runtime for ADK-Rust.

Overview

adk-runner provides the execution runtime for ADK-Rust:

• Runner - Manages agent execution with full context
• Session Integration - Automatic session creation and state management
• Memory Injection - Retrieves and injects relevant memories
• Artifact Handling - Manages binary artifacts during execution
• Event Streaming - Streams agent events with state propagation
• Agent Transfer - Automatic handling of agent-to-agent transfers
• Context Compaction - Automatic summarization of older events to reduce LLM context size

Installation

[dependencies]
adk-runner = "0.4"

Or use the meta-crate:

[dependencies]
adk-rust = { version = "0.4", features = ["runner"] }

Quick Start

use adk_runner::{Runner, RunnerConfig};
use adk_session::InMemorySessionService;
use adk_artifact::InMemoryArtifactService;
use adk_core::Content;
use std::sync::Arc;

// Create services
let sessions = Arc::new(InMemorySessionService::new());
let artifacts = Arc::new(InMemoryArtifactService::new());

// Configure runner with agent
let config = RunnerConfig {
    app_name: "my_app".to_string(),
    agent: my_agent,  // Arc<dyn Agent>
    session_service: sessions,
    artifact_service: Some(artifacts),
    memory_service: None,
    plugin_manager: None,
    run_config: None,  // Uses default SSE streaming
};

// Create runner
let runner = Runner::new(config)?;

// Run agent for a user/session
let mut stream = runner.run(
    "user_123".to_string(),
    "session_456".to_string(),
    Content::new("user").with_text("Hello!"),
).await?;

// Process events
use futures::StreamExt;
while let Some(event) = stream.next().await {
    match event {
        Ok(e) => println!("Event: {:?}", e.content()),
        Err(e) => eprintln!("Error: {}", e),
    }
}

RunnerConfig

Runner vs Direct Agent Execution

Use Runner for production; direct execution for testing.

Agent Transfers

Runner automatically handles agent-to-agent transfers:

// When an agent sets transfer_to_agent in EventActions,
// Runner automatically:
// 1. Finds the target agent in the agent tree
// 2. Creates a new invocation context
// 3. Preserves session state across the transfer
// 4. Continues streaming events from the new agent

State Propagation

Runner applies state changes immediately:

// When an agent emits an event with state_delta,
// Runner applies it to the mutable session so
// downstream agents can read the updated state.

Context Compaction

Runner supports automatic context compaction to keep LLM context manageable in long conversations:

use adk_agent::LlmEventSummarizer;
use adk_runner::{Runner, RunnerConfig, EventsCompactionConfig};
use std::sync::Arc;

let summarizer = Arc::new(LlmEventSummarizer::new(summarizer_model));

let config = RunnerConfig {
    // ... other fields ...
    compaction_config: Some(EventsCompactionConfig {
        compaction_interval: 3,  // Compact every 3 invocations
        overlap_size: 1,         // Keep 1 event overlap for continuity
        summarizer,
    }),
};

Compaction runs after each invocation completes. When the user-event count reaches the interval, older events are summarized into a single compacted event. The BaseEventsSummarizer and EventsCompactionConfig types are re-exported from adk-core for convenience.

See Context Compaction for the full guide.

Context Compaction

Runner supports automatic sliding-window context compaction to keep LLM context size manageable in long-running sessions. When enabled, the runner periodically summarizes older events into a single compacted event.

use adk_runner::{Runner, RunnerConfig, EventsCompactionConfig};
use adk_agent::LlmEventSummarizer;
use std::sync::Arc;

let summarizer = LlmEventSummarizer::new(model.clone());

let config = RunnerConfig {
    app_name: "my_app".to_string(),
    agent: my_agent,
    session_service: sessions,
    artifact_service: Some(artifacts),
    memory_service: None,
    plugin_manager: None,
    run_config: None,
    compaction_config: Some(EventsCompactionConfig {
        compaction_interval: 3,  // Compact every 3 invocations
        overlap_size: 1,         // Keep 1 event overlap for continuity
        summarizer: Arc::new(summarizer),
    }),
};

let runner = Runner::new(config)?;

When compaction triggers, MutableSession::conversation_history() automatically uses the most recent compaction summary instead of the original events, keeping the context window bounded.

Re-exported for convenience: adk_runner::{BaseEventsSummarizer, EventsCompactionConfig}.

See Context Compaction for full documentation.

Related Crates

• adk-rust - Meta-crate with all components
• adk-core - Core traits
• adk-session - Session storage
• adk-artifact - Artifact storage
• adk-cli - CLI using runner

License

Apache-2.0

Part of ADK-Rust

This crate is part of the ADK-Rust framework for building AI agents in Rust.