← 返回博客

adk-rust 入门：在 Rust 中构建您的第一个 AI 代理

使用 Rust 释放 AI 代理的强大功能。本指南将向您展示如何构建、运行和部署您的第一个智能代理。

2023 年 10 月 26 日•阅读时长 12 分钟
adk-rustRustAI 代理Google Gemini开发教程

目录

  • 1. adk-rust 简介
  • 2. 前提条件和设置
  • 3. 创建您的第一个 ADK 项目
  • 4. adk-rust 代理的结构
  • 5. 实现您的简单 AI 代理
  • 6. 构建和运行您的代理
  • 7. 后续步骤

1. adk-rust 简介

代理开发挑战

构建能够执行复杂任务的智能代理长期以来一直是一个充满挑战的领域。编排大型语言模型（LLMs）、管理状态、处理多样化输入以及有效部署这些代理通常需要定制解决方案和大量的工程投入。这种复杂性对于希望将强大 AI 功能集成到其应用程序中的开发人员来说可能是一个主要障碍。

adk-rust 登场：简化 AI 代理开发

代理开发工具包 (ADK) 旨在使 AI 代理开发更像传统的软件开发，而 `adk-rust` 是其强大的 Rust 实现。它提供了一个灵活、模块化的框架，专为开发和部署复杂的 AI 代理而设计。虽然针对 Gemini 和 Google 生态系统进行了优化，但 `adk-rust` 是模型无关且部署无关的，确保了跨各种平台的兼容性和灵活性。本指南将引导您设置环境、创建您的第一个 `adk-rust` 项目并部署一个基本的 AI 助手，为您的代理之旅奠定坚实的基础。

2. 前提条件和设置

在我们深入构建代理之前，请确保您的开发环境已准备就绪。您需要一个最新的 Rust 工具链，并将 adk-rust 库添加到您的项目中。adk-rust 还需要一个 Google API 密钥，以便与 Gemini 等模型进行交互。 首先，请确保您已安装 Rust。如果没有，推荐的方法是通过 rustup： 
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
确保您的 Rust 版本为 1.75 或更高： 
rustc --version
接下来，我们将添加 adk-rust 作为依赖项。我们还将添加 tokio 用于 asynchronous 操作，以及 dotenv 来管理环境变量，例如您的 API 密钥。在创建项目后（我们将在下一步中完成），您可以使用 cargo add 添加它们： 
cargo add adk-rust
cargo add tokio --features full
cargo add dotenv
或者，您可以手动将这些添加到您的 Cargo.toml 文件中： 
[dependencies]
adk-rust = "0.1"
tokio = { version = "1.40", features = ["full"] }
dotenv = "0.15"
最后，您需要一个用于 Gemini 的 Google API 密钥。您可以从 Google AI Studio 或 Google Cloud Console 获取。在项目的根目录中创建一个 .env 文件并添加您的密钥： 
GOOGLE_API_KEY="YOUR_GEMINI_API_KEY_HERE"

3. 创建您的第一个 ADK 项目

环境设置完成后，让我们创建一个新的 Rust 项目，它将作为我们 adk-rust 代理的容器。我们将使用标准的 cargo new 命令来开始。 打开您的终端并运行： 
cargo new my_first_adk_agent
cd my_first_adk_agent
此命令初始化一个名为 my_first_adk_agent 的新 Rust 项目。生成的项目结构对于 Rust 开发者来说会很熟悉： 
my_first_adk_agent/
├── Cargo.toml          # Project manifest and dependencies
└── src/
    └── main.rs         # Your agent's main logic goes here
现在，您可以在此 my_first_adk_agent 目录中运行上一节中的 cargo add 命令。请记住在根目录 (my_first_adk_agent/) 中手动创建一个 .env 文件，用于您的 GOOGLE_API_KEY。

4. adk-rust 代理的剖析

一个 adk-rust 代理通常围绕 LlmAgentBuilder 构建，并使用 Launcher 执行。核心思想是定义代理的角色、指令以及它应该使用的 LLM。让我们看看在 adk-rust 代理的 src/main.rs 文件中可以找到的基本组件。 在 adk-rust 中，一个 LlmAgent 配置了描述、指令（作为 LLM 的系统提示）和一个特定的语言模型（如 Gemini）。然后，Launcher 接收此代理并处理执行，提供交互式控制台或 Web 服务器接口。这种抽象简化了代理与外部世界的交互。 下面是一个 adk-rust 代理的完整“Hello World”示例。将此代码复制到您的 src/main.rs 文件中。我们将在下一节中详细分解每个部分。 
use adk_rust::prelude::*;
use adk_rust::Launcher;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // 1. Load environment variables from .env file
    dotenv::dotenv().ok();
    
    // 2. Get API key from environment
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    // 3. Create the Gemini model
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // 4. Build your agent
    let agent = LlmAgentBuilder::new("my_assistant")
        .description("A helpful AI assistant")
        .instruction("You are a friendly and helpful assistant. Answer questions clearly and concisely.")
        .model(Arc::new(model))
        .build()?;

    // 5. Run the agent with the CLI launcher
    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

5. 实现您的简单 AI 代理

现在，让我们深入了解 adk-rust 代理的“Hello World”示例，重点关注代码的每个部分如何有助于创建一个功能性 AI 助手。您应该已将上一节中的代码复制到您的 src/main.rs 文件中。 1. **环境变量加载**：dotenv::dotenv().ok(); 从您的 .env 文件中加载变量，使您的 GOOGLE_API_KEY 在您的 Rust 应用程序中可用。 2. **API 密钥检索**：std::env::var("GOOGLE_API_KEY") 从环境中获取您的 API 密钥。.expect() 调用确保如果找不到密钥，程序将崩溃并提供清晰的错误消息，从而防止在初始化模型时出现静默故障。 3. **模型初始化**：let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?; 实例化一个 GeminiModel。在这里，我们提供我们的 API 密钥并指定所需的 Gemini 模型版本 (gemini-2.5-flash)。此对象封装了与实际 LLM 服务的连接和交互逻辑，抽象了 API 调用的复杂性。 4. **代理构建**：在这里，您使用 LlmAgentBuilder 定义代理的核心身份和行为： * LlmAgentBuilder::new("my_assistant")：开始构建代理，为其分配一个唯一的 ID。 * .description("A helpful AI assistant")：提供代理目的的人类可读描述，用于文档或更高级别的编排。 * .instruction("You are a friendly and helpful assistant. Answer questions clearly and concisely.")：这是您的系统提示。它指导底层的 LLM 如何行为、响应以及其整体角色。 * .model(Arc::new(model))：将代理与我们创建的 GeminiModel 关联。Arc（原子引用计数）是一个线程安全的引用计数指针，在此用于共享所有权，这在 asynchronous Rust 应用程序中很常见。 * .build()?：完成代理构建。它返回一个 Result，? 用于方便的错误传播。 5. **代理启动**：Launcher::new(Arc::new(agent)).run().await?; 接收您配置的代理并执行它。Launcher::run() 的默认行为是启动一个交互式控制台，您可以在其中向代理键入提示并查看其响应。await 关键字表示这是一个 asynchronous 操作，这对于与 LLM 交互等 I/O 密集型任务很典型。

6. 构建和运行您的代理

一旦您的 src/main.rs 文件填充了代理代码，并且您的 Cargo.toml 更新了依赖项，您就可以让您的代理投入使用了！cargo 是您的主要工具。 首先，构建您的项目以将 Rust 代码编译成可执行文件： 
cargo build
此命令编译您的代理及其依赖项。如果成功，您将在 target/debug/ 目录中（如果您使用 --release 构建，则在 target/release/ 中）获得一个可执行文件。 要以交互式控制台模式运行您的代理（这对于测试和快速交互非常有用），请使用： 
cargo run
您的终端将成为一个交互式聊天界面，您可以在其中输入问题，您的代理将使用配置的 Gemini 模型进行响应。要退出，通常可以键入 exit 或按 Ctrl+C。 adk-rust 还提供了一种将您的代理作为 Web 服务器运行的方式，允许您通过 HTTP 请求与其交互。这对于将您的代理集成到 Web 应用程序或其他服务中特别有用： 
cargo run -- serve
默认情况下，这将在 http://127.0.0.1:8080 上启动服务器。如果需要，您可以指定不同的端口： 
cargo run -- serve --port 3000
现在，您的代理可以通过 Web API 访问了！您可以使用 curl 等工具或 Web 浏览器向配置的端点（例如 http://127.0.0.1:8080/v1/agent）发送请求。这使您的 AI 代理成为一个可部署、可调用的服务。

7. 后续步骤

恭喜！您已成功使用 adk-rust 构建并运行了您的第一个 AI 代理。这只是您使用该框架可以实现的目标的开始。以下是一些后续步骤的建议： * **探索 ADK 文档**：深入研究官方 adk-rust 文档，以了解更高级的功能，例如与其他组件集成、管理状态或创建更复杂的代理工作流。 * **自定义工具和功能**：学习如何为您的代理配备自定义工具，使其能够与外部 API、数据库交互，或执行超出文本生成的特定计算。这是扩展代理功能的强大特性。 * **部署选项**：研究您的 adk-rust 代理的不同部署策略，无论是使用 Docker 进行容器化、部署到云平台，还是集成到现有的 Rust 服务中。 * **社区参与**：加入 adk-rust 社区。分享您的项目、提问并参与讨论可以显著加速您的学习和问题解决。与最新的发展和最佳实践保持联系。