adk-runner 0.2.1

Agent execution runtime for Rust Agent Development Kit (ADK-Rust) agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

# adk-runner

Agent execution runtime for ADK-Rust.

[![Crates.io](https://img.shields.io/crates/v/adk-runner.svg)](https://crates.io/crates/adk-runner)
[![Documentation](https://docs.rs/adk-runner/badge.svg)](https://docs.rs/adk-runner)
[![License](https://img.shields.io/crates/l/adk-runner.svg)](LICENSE)

## Overview

`adk-runner` provides the execution runtime for [ADK-Rust](https://github.com/zavora-ai/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

## Installation

```toml
[dependencies]
adk-runner = "0.1"
```

Or use the meta-crate:

```toml
[dependencies]
adk-rust = { version = "0.1", features = ["runner"] }
```

## Quick Start

```rust
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,
    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

| Field | Type | Description |
|-------|------|-------------|
| `app_name` | `String` | Application identifier |
| `agent` | `Arc<dyn Agent>` | Root agent to execute |
| `session_service` | `Arc<dyn SessionService>` | Session storage backend |
| `artifact_service` | `Option<Arc<dyn ArtifactService>>` | Optional artifact storage |
| `memory_service` | `Option<Arc<dyn Memory>>` | Optional memory/RAG service |
| `run_config` | `Option<RunConfig>` | Streaming mode config |

## Runner vs Direct Agent Execution

| Feature | Direct `agent.run()` | `Runner` |
|---------|---------------------|----------|
| Session management | Manual | Automatic |
| Memory injection | Manual | Automatic |
| Artifact storage | Manual | Automatic |
| State persistence | Manual | Automatic |
| Agent transfers | Manual | Automatic |
| Event history | Manual | Automatic |

Use `Runner` for production; direct execution for testing.

## Agent Transfers

Runner automatically handles agent-to-agent transfers:

```rust
// 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:

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

## Related Crates

- [adk-rust](https://crates.io/crates/adk-rust) - Meta-crate with all components
- [adk-core](https://crates.io/crates/adk-core) - Core traits
- [adk-session](https://crates.io/crates/adk-session) - Session storage
- [adk-artifact](https://crates.io/crates/adk-artifact) - Artifact storage
- [adk-cli](https://crates.io/crates/adk-cli) - CLI using runner

## License

Apache-2.0

## Part of ADK-Rust

This crate is part of the [ADK-Rust](https://adk-rust.com) framework for building AI agents in Rust.