启动器

Launcher 提供了一种简单的单行方式来运行 ADK 代理。在默认的最小层级中，它是来自 adk-runner 的轻量级控制台启动器。当需要完整的 CLI 参数解析器和 HTTP 服务器模式时，可以启用可选的 CLI 功能，例如 cli-openai。

概述

Launcher 旨在让代理部署尽可能简单。只需一行代码，即可：

• 在交互式控制台中运行代理，用于测试和开发
• 当使用 cli-* 功能或 cargo-adk api 模板时，将代理部署为带有 Web UI 的 HTTP 服务器
• 自定义应用程序名称和构件存储

基本用法

控制台模式（默认）

使用 Launcher 的最简单方式是使用代理创建它，然后调用 run()：

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

#[tokio::main]
async fn main() -> Result<()> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-3.7-flash")?);
    
    let agent = LlmAgentBuilder::new("my_agent")
        .description("A helpful assistant")
        .instruction("You are a helpful assistant.")
        .model(model)
        .build()?;
    
    // Run with the lightweight console launcher
    Launcher::new(Arc::new(agent)).run().await
}

运行代理：

# Interactive console (default)
cargo run

# Full CLI mode is available when your app enables a `cli-*` feature

服务器模式

要将代理作为带有 Web UI 的 HTTP 服务器运行，请使用 api 模板或启用 cli-* 功能：

cargo adk new my-api --template api
cd my-api
cargo run

服务器启动后将显示：

🚀 ADK Server starting on http://localhost:8080
📱 Open http://localhost:8080 in your browser
Press Ctrl+C to stop

配置选项

自定义应用程序名称

默认情况下，Launcher 使用代理名称作为应用程序名称。你可以对其进行自定义：

Launcher::new(Arc::new(agent))
    .app_name("my_custom_app")
    .run()
    .await

自定义构件服务

提供你自己的构件服务实现：

use adk_artifact::InMemoryArtifactService;

let artifact_service = Arc::new(InMemoryArtifactService::new());

Launcher::new(Arc::new(agent))
    .with_artifact_service(artifact_service)
    .run()
    .await

控制台模式详情

在控制台模式下，Launcher：

1. 创建内存中的会话服务
2. 为用户创建会话
3. 启动交互式 REPL 循环
4. 实时流式传输代理响应
5. 处理多代理系统中的代理转移

控制台交互

🤖 Agent ready! Type your questions (or 'exit' to quit).

You: What is the capital of France?
Assistant: The capital of France is Paris.

You: exit
👋 Goodbye!

多代理控制台

使用多代理系统时，控制台会显示正在响应的代理：

You: I need help with my order

[Agent: customer_service]
Assistant: I'll help you with your order. What's your order number?

You: ORDER-12345

🔄 [Transfer requested to: order_lookup]

[Agent: order_lookup]
Assistant: I found your order. It was shipped yesterday.

服务器模式详情

在服务器模式下，Launcher：

1. 初始化可观测性遥测
2. 创建内存中的会话服务
3. 启动带有 REST API 端点的 HTTP 服务器
4. 提供用于与您的 agent 交互的 Web UI

生产环境应急方案

对于需要自定义路由、中间件、指标或自行控制服务循环的生产应用，请使用 build_app()：

let app = Launcher::new(Arc::new(agent))
    .with_a2a_base_url("https://agent.example.com")
    .build_app()?;

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

如果您希望显式启用 A2A 路由，请使用 build_app_with_a2a(...)。

可用端点

服务器公开以下 REST API 端点：

• GET /health - 健康检查端点
• POST /run_sse - 使用 Server-Sent Events 流式传输运行 agent
• GET /sessions - 列出会话
• POST /sessions - 创建新会话
• GET /sessions/:app_name/:user_id/:session_id - 获取会话详细信息
• DELETE /sessions/:app_name/:user_id/:session_id - 删除会话

有关端点规范的详细信息，请参阅 服务器 API 文档。

Web UI

服务器包含一个内置 Web UI，可通过 http://localhost:8080/ui/ 访问。该 UI 提供：

• 交互式聊天界面
• 会话、状态、工件和事件时间线检查
• 实时流式响应和工具活动
• 精确的团队委派和交接拓扑
• agent 和 UI 协议能力发现

CLI 参数

完整的 CLI 启动器在启用 cli-* 功能时支持以下命令：

完整示例

以下是同时展示两种模式的完整示例：

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

#[tokio::main]
async fn main() -> Result<()> {
    // Load API key
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");
    
    // Create model
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-3.7-flash")?);
    
    // Create agent with tools
    let weather_tool = FunctionTool::new(
        "get_weather",
        "Get the current weather for a location",
        |params, _ctx| async move {
            let location = params["location"].as_str().unwrap_or("unknown");
            Ok(json!({
                "location": location,
                "temperature": 72,
                "condition": "sunny"
            }))
        },
    );
    
    let agent = LlmAgentBuilder::new("weather_agent")
        .description("An agent that provides weather information")
        .instruction("You are a weather assistant. Use the get_weather tool to provide weather information.")
        .model(model)
        .tool(Arc::new(weather_tool))
        .build()?;
    
    // Run with Launcher. Enable a `cli-*` feature for full CLI/server mode.
    Launcher::new(Arc::new(agent))
        .app_name("weather_app")
        .run()
        .await
}

在控制台模式下运行：

cargo run

从生成的 API 项目以服务器模式运行：

cargo adk new weather-api --template api
cd weather-api
cargo run

部署前验证

在部署 agent 之前，使用 cargo adk build 验证项目是否能够正确编译，而无需实际部署：

# Verify compilation (no deployment)
cargo adk build

# Build with release optimizations
cargo adk build --release

这可以在提交部署之前捕获编译错误、缺少的依赖项和配置问题。在 CI 流水线中，它尤其适合作为 cargo adk deploy 之前的检查门。

请参阅 cargo adk build 获取完整的命令文档。

最佳实践

1. 环境变量：始终从环境变量中加载敏感配置（API 密钥）
2. 错误处理：使用 Result 类型进行适当的错误处理
3. 优雅关闭：Launcher 在两种模式下都能优雅地处理 Ctrl+C
4. 端口选择：选择不会与其他服务冲突的端口（默认端口为 8080）
5. 会话管理：在生产环境中，考虑使用 PostgresSessionService 或 SqliteSessionService，而不是内存会话
6. 部署前检查：在部署前运行 cargo adk build，以便尽早发现问题

相关内容

• 服务器 API - 详细的 REST API 文档
• 会话 - 会话管理
• 工件 - 工件存储
• 可观测性 - 遥测与日志记录

---

上一页：← 遥测 | 下一页：服务器 →