Runner

adk-runner 中的执行运行时，用于编排 agent 执行。

概述

Runner 管理 agent 执行的完整生命周期：

• 会话管理（创建/检索会话）
• 内存注入（搜索并注入相关内存）
• Artifact 处理（作用域内 Artifact 访问）
• 事件流（处理和转发事件）
• Agent 转移（处理多 agent 移交）

安装

[dependencies]
adk-runner = "0.2.0"

RunnerConfig

使用所需服务配置 Runner：

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

let config = RunnerConfig {
    app_name: "my_app".to_string(),
    agent: Arc::new(my_agent),
    session_service: Arc::new(InMemorySessionService::new()),
    artifact_service: Some(Arc::new(InMemoryArtifactService::new())),
    memory_service: None,
    run_config: None,
};

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

配置字段

运行 Agent

使用用户输入执行一个 agent：

use adk_core::Content;
use futures::StreamExt;

let user_content = Content::new("user").with_text("Hello!");

let mut stream = runner.run(
    "user-123".to_string(),
    "session-456".to_string(),
    user_content,
).await?;

while let Some(event) = stream.next().await {
    match event {
        Ok(e) => {
            if let Some(content) = e.content() {
                for part in &content.parts {
                    if let Some(text) = part.text() {
                        print!("{}", text);
                    }
                }
            }
        }
        Err(e) => eprintln!("Error: {}", e),
    }
}

执行流程

┌─────────────────────────────────────────────────────────────┐
│                     Runner.run()                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  1. 会话检索                                │
│                                                             │
│   SessionService.get(app_name, user_id, session_id)        │
│   → 如果会话不存在则创建新会话                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  2. Agent 选择                              │
│                                                             │
│   检查会话状态以获取活动的 Agent                            │
│   → 使用根 Agent 或已转移的 Agent                           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                3. 上下文创建                                │
│                                                             │
│   InvocationContext，包含：                                 │
│   - Session (可变)                                          │
│   - Artifacts (会话范围)                                    │
│   - Memory (如果已配置)                                     │
│   - 执行配置                                                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  4. Agent 执行                              │
│                                                             │
│   agent.run(ctx) → EventStream                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                 5. 事件处理                                 │
│                                                             │
│   对于每个事件：                                            │
│   - 更新会话状态                                            │
│   - 处理转移                                                │
│   - 转发给调用者                                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  6. 会话保存                                │
│                                                             │
│   SessionService.append_event(session, events)             │
└─────────────────────────────────────────────────────────────┘

InvocationContext

在执行期间提供给 Agent 的上下文：

pub trait InvocationContext: CallbackContext {
    /// 正在执行的 Agent
    fn agent(&self) -> Arc<dyn Agent>;
    
    /// 内存服务（如果已配置）
    fn memory(&self) -> Option<Arc<dyn Memory>>;
    
    /// 当前会话
    fn session(&self) -> &dyn Session;
    
    /// 执行配置
    fn run_config(&self) -> &RunConfig;
    
    /// 发出调用结束信号
    fn end_invocation(&self);
    
    /// 检查调用是否已结束
    fn ended(&self) -> bool;
}

RunConfig

执行选项：

pub struct RunConfig {
    /// 响应的流式传输模式
    pub streaming_mode: StreamingMode,
}

pub enum StreamingMode {
    /// 无流式传输，返回完整响应
    None,
    /// Server-Sent Events（默认）
    SSE,
    /// 双向流式传输（实时）
    Bidi,
}

注意：max_turns 和 include_history 等附加字段计划在未来版本中发布。

Agent 转移

Runner 会自动处理多 Agent 转移：

// In an agent's tool or callback
if should_transfer {
    // Set transfer in event actions
    ctx.set_actions(EventActions {
        transfer_to_agent: Some("specialist_agent".to_string()),
        ..Default::default()
    });
}

Runner 将：

1. 检测事件中的转移请求
2. 在 sub_agents 中找到目标 Agent
3. 使用新的活动 Agent 更新 Session 状态
4. 继续使用新 Agent 执行

与 Launcher 集成

Launcher 内部使用 Runner：

// Launcher creates Runner with default services
Launcher::new(agent)
    .app_name("my_app")
    .run()
    .await?;

// Equivalent to:
let runner = Runner::new(RunnerConfig {
    app_name: "my_app".to_string(),
    agent,
    session_service: Arc::new(InMemorySessionService::new()),
    artifact_service: Some(Arc::new(FileArtifactService::new("./artifacts")?)),
    memory_service: None,
    run_config: None,
})?;

自定义 Runner 用法

对于高级场景，直接使用 Runner：

use adk_runner::{Runner, RunnerConfig};
use adk_session::DatabaseSessionService;
use adk_artifact::S3ArtifactService;
use adk_memory::QdrantMemoryService;

// Production configuration
let config = RunnerConfig {
    app_name: "production_app".to_string(),
    agent: my_agent,
    session_service: Arc::new(DatabaseSessionService::new(db_pool)),
    artifact_service: Some(Arc::new(S3ArtifactService::new(s3_client))),
    memory_service: Some(Arc::new(QdrantMemoryService::new(qdrant_client))),
    run_config: None,  // Uses default SSE streaming
};

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

// Use in HTTP handler
async fn chat_handler(runner: &Runner, request: ChatRequest) -> Response {
    let stream = runner.run(
        request.user_id,
        request.session_id,
        request.content,
    ).await?;
    
    // Stream events to client
    Response::sse(stream)
}

---

上一页：← 核心类型 | 下一页：Launcher →