启动器

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

概述

启动器旨在使代理部署尽可能简单。通过一行代码，您可以：

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

基本用法

控制台模式（默认）

使用启动器最简单的方法是使用您的代理创建它并调用 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-2.5-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::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

控制台模式详情

在控制台模式下，启动器：

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.

服务器模式详情

在服务器模式下，启动器：

1. 初始化遥测以进行可观测性
2. 创建一个内存会话服务
3. 启动一个带有 REST API 端点的 HTTP 服务器
4. 提供一个用于与您的代理交互的 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 流式传输运行代理
• 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 提供：

• 交互式聊天界面
• 会话管理
• 实时流式响应
• 多代理可视化

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-2.5-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 以尽早发现问题

相关

• Server API - 详细的 REST API 文档
• Sessions - 会话管理
• Artifacts - Artifact 存储
• Observability - 遥测和日志记录

---

上一页：← Telemetry | 下一页：Server →