快速入门

本指南将向您展示如何快速开始使用 ADK-Rust。您将在 10 分钟内创建您的第一个 AI Agent。

先决条件

在开始之前，请确保您已具备：

• Rust 1.85.0 或更高版本 (rustup update stable)
• 一个用于 Gemini 的 Google API 密钥

步骤 1：创建新项目

创建一个新的 Rust 项目：

cargo new my_agent
cd my_agent

您的项目结构将如下所示：

my_agent/
├── Cargo.toml
├── src/
│   └── main.rs
└── .env          # 您将为您的 API 密钥创建此文件

步骤 2：添加依赖项

使用所需的依赖项更新您的 Cargo.toml 文件：

[package]
name = "my_agent"
version = "0.1.0"
edition = "2024"

[dependencies]
adk-rust = "0.2.0"
tokio = { version = "1.40", features = ["full"] }
dotenvy = "0.15"

安装依赖项：

cargo build

步骤 3：设置您的 API 密钥

本项目使用 Gemini API，它需要一个 API 密钥。如果您还没有，请在 Google AI Studio 中创建一个密钥。

在您的项目根目录中创建一个 .env 文件：

Linux / macOS:

echo 'GOOGLE_API_KEY=your-api-key-here' > .env

Windows (PowerShell):

echo GOOGLE_API_KEY=your-api-key-here > .env

安全提示： 将 .env 添加到您的 .gitignore 文件中，以避免提交您的 API 密钥。

步骤 4：编写您的 Agent

将 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>> {
    // 从 .env 文件加载环境变量
    dotenvy::dotenv().ok();
    
    // 从环境变量获取 API 密钥
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    // 创建 Gemini 模型
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // 构建您的 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()?;

    // 使用 CLI Launcher 运行 Agent
    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

步骤 5：运行您的 Agent

以交互式控制台模式启动您的 Agent：

cargo run

您将看到一个提示符，可以在其中与您的 Agent 聊天：

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

You: Hello! What can you help me with?
Assistant: Hello! I'm a helpful AI assistant. I can help you with:
- Answering questions on various topics
- Explaining concepts
- Providing information and suggestions
- Having a friendly conversation

What would you like to know?

You: exit
👋 Goodbye!

步骤 6：添加一个工具

让我们使用 Google Search 工具增强您的代理，使其能够访问实时信息：

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>> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Build agent with Google Search tool
    let agent = LlmAgentBuilder::new("search_assistant")
        .description("An assistant that can search the web")
        .instruction("You are a helpful assistant. Use the search tool to find current information when needed.")
        .model(Arc::new(model))
        .tool(Arc::new(GoogleSearchTool::new()))  // Add search capability
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

再次以交互式控制台模式启动您的代理：

cargo run

现在您可以提示您的代理搜索网页了：

You: What's the weather like in Tokyo today?
Assistant: Let me search for that information...
[Using GoogleSearchTool]
Based on current information, Tokyo is experiencing...

作为 Web 服务器运行

对于基于 Web 的界面，请使用 serve 命令运行：

cargo run -- serve

这将在 默认端口 8080 上启动服务器。通过 http://localhost:8080 访问它。

要指定自定义端口：

cargo run -- serve --port 3000

这将在 端口 3000 上启动服务器。通过 http://localhost:3000 访问它。

理解代码

让我们分解一下每个部分的功能：

导入

use adk_rust::prelude::*;  // GeminiModel, LlmAgentBuilder, Arc, etc.
use adk_rust::Launcher;    // CLI launcher for console/server modes
use std::sync::Arc;        // Thread-safe reference counting pointer

• prelude::* 导入所有常用类型：GeminiModel、LlmAgentBuilder、Arc、错误类型等
• Launcher 提供用于运行代理的 CLI 接口
• Arc（原子引用计数）允许在 async 任务之间安全地共享模型和代理

模型创建

let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

创建一个实现 Llm trait 的 Gemini 模型实例。该模型：

• 处理使用您的 API key 进行身份验证
• 管理来自 LLM 的流式响应
• 支持工具的函数调用

代理构建

let agent = LlmAgentBuilder::new("my_assistant")
    .description("A helpful AI assistant")
    .instruction("You are a friendly assistant...")
    .model(Arc::new(model))
    .build()?;

构建器模式配置您的代理：

启动器

Launcher::new(Arc::new(agent)).run().await?;

Launcher 处理运行时：

• 控制台模式（默认）：在您的终端中进行交互式聊天
• 服务器模式（-- serve）：带有 Web 界面的 REST API
• 管理会话状态、流式响应和优雅关闭

使用其他模型

adk-rust 开箱即用地支持多种 LLM 提供商。通过你的 Cargo.toml 中的 feature flags 启用它们：

[dependencies]
adk-rust = { version = "0.2.0", features = ["openai", "anthropic", "deepseek", "groq", "ollama"] }

为你的提供商设置相应的 API 密钥：

# OpenAI
export OPENAI_API_KEY="your-api-key"

# Anthropic
export ANTHROPIC_API_KEY="your-api-key"

# DeepSeek
export DEEPSEEK_API_KEY="your-api-key"

# Groq
export GROQ_API_KEY="your-api-key"

# Ollama (no key needed, just run: ollama serve)

OpenAI

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>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("OPENAI_API_KEY")?;
    let model = OpenAIClient::new(OpenAIConfig::new(api_key, "gpt-4o"))?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Anthropic

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>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("ANTHROPIC_API_KEY")?;
    let model = AnthropicClient::new(AnthropicConfig::new(api_key, "claude-sonnet-4-20250514"))?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

DeepSeek

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>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("DEEPSEEK_API_KEY")?;

    // 标准聊天模型
    let model = DeepSeekClient::chat(api_key)?;

    // 或者使用 reasoner 进行思维链推理
    // let model = DeepSeekClient::reasoner(api_key)?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Groq (超快推理)

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>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("GROQ_API_KEY")?;
    let model = GroqClient::new(GroqConfig::llama70b(api_key))?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Ollama (本地模型)

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>> {
    dotenvy::dotenv().ok();

    // 要求：ollama serve && ollama pull llama3.2
    let model = OllamaModel::new(OllamaConfig::new("llama3.2"))?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

支持的模型

接下来的步骤

在您的第一个 Agent 运行起来之后，请探索以下主题：

• LlmAgent 配置 - 所有配置选项
• 函数工具 - 创建自定义工具
• 工作流 Agent - 构建多步骤管道
• 会话 - 管理对话状态
• 回调 - 自定义 Agent 行为

---

上一页: 简介 | 下一页: LlmAgent