快速开始

在 5 分钟内创建你的第一个 AI agent。

前提条件

• Rust 1.95.0 或更高版本（rustup update stable）
• 一个 Google API key（点此获取）

步骤 1：搭建你的项目脚手架

cargo install cargo-adk
cargo adk new my_agent
cd my_agent

这会生成一个可工作的项目，包含正确的依赖和样板代码。

其他模板

# Agent with custom tools using #[tool] macro
cargo adk new my_agent --template tools

# RAG agent with Gemini embeddings and in-memory vector search
cargo adk new my_agent --template rag

# REST API server ready for deployment
cargo adk new my_agent --template api

# OpenAI GPT-5-mini agent
cargo adk new my_agent --template openai

# A2A protocol agent with builder API
cargo adk new my_agent --template a2a

# Use any provider with any template
cargo adk new my_agent --template tools --provider anthropic

# Add optional addons to any template
cargo adk new my_agent --template tools --addon docker --addon ci

提示： 使用 --addon 标志来组合带有可选附加项的模板，例如 docker、ci、telemetry 等。请参阅 Composable Templates 页面，查看全部 9 个附加项和 5 种企业模式。

第 2 步：添加你的 API 密钥

cp .env.example .env
# Edit .env and add your GOOGLE_API_KEY

第 3 步：运行

cargo run

就是这样——你已经拥有一个可工作的代理。现在就在终端里与它聊天吧。

ADK Console Mode
Agent: my_agent
Type your message and press Enter. Ctrl+C to exit.

> Hello! What can you help me with?

I'm a helpful AI assistant. I can help you with answering questions,
explaining concepts, and having a friendly conversation.

---

无配置替代方案 — adk::run()

如果你只是想在不搭建脚手架的情况下快速运行一个代理，可以使用这一行命令：

use adk_rust::run;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    // Minimal default: set GOOGLE_API_KEY. Add provider features for OpenAI/Anthropic.
    let response = run("You are a helpful assistant.", "Explain Rust in one sentence.").await?;
    println!("{response}");
    Ok(())
}

这会在一次调用中处理已编译提供方的提供方检测、会话创建、代理构建和执行。非常适合脚本、原型和快速实验。

---

理解生成的代码

脚手架生成的 src/main.rs：

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

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok();
    let api_key = std::env::var("GOOGLE_API_KEY")?;

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

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

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

---

添加自定义工具

添加工具最快的方式是 #[tool] 宏。将 adk-tool 添加到你的依赖中：

[dependencies]
adk-tool = "2.0.0"
schemars = "1"
serde = { version = "1", features = ["derive"] }

然后定义一个工具——doc 注释会成为描述，args 结构体会成为 JSON 模式：

use adk_tool::{tool, AdkError};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::{json, Value};

#[derive(Deserialize, JsonSchema)]
struct WeatherArgs {
    /// The city to look up
    city: String,
}

/// Get the current weather for a city.
#[tool]
async fn get_weather(args: WeatherArgs) -> std::result::Result<Value, AdkError> {
    Ok(json!({ "temp": 22, "city": args.city, "condition": "sunny" }))
}

该宏会生成一个实现了 Tool 的 GetWeather 结构体。将它添加到你的 agent 中：

let agent = LlmAgentBuilder::new("weather_agent")
    .instruction("Use the get_weather tool for weather questions.")
    .model(Arc::new(model))
    .tool(Arc::new(GetWeather))  // Generated by #[tool]
    .build()?;

提示： 或者用已经设置好工具的项目脚手架来初始化：cargo adk new my-agent --template tools

内置工具

ADK 也包含可直接使用的工具：

// Google Search (handled server-side by Gemini)
.tool(Arc::new(GoogleSearchTool::new()))

// Exit a LoopAgent
.tool(Arc::new(ExitLoopTool::new()))

---

作为 Web 服务器运行

当你想进行 HTTP 服务时，可以脚手架一个服务器项目：

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

默认的基础模板使用轻量级控制台启动器，以获得最快的安装速度。

---

使用其他模型

通过功能标志启用提供方。默认构建为了快速安装仍保持仅 Gemini，所以只添加你需要的提供方：

[dependencies]
adk-rust = { version = "2.0.0", features = ["openai"] }

或者使用提供方进行脚手架：cargo adk new my-agent --provider openai

OpenAI

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

Anthropic

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

DeepSeek

let api_key = std::env::var("DEEPSEEK_API_KEY")?;
let model = DeepSeekClient::chat(api_key)?;         // standard
// let model = DeepSeekClient::reasoner(api_key)?;   // chain-of-thought

Groq

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

Ollama（本地）

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

支持的模型

---

下一步

• LlmAgent 配置 — 所有配置选项
• 函数工具 — 使用 #[tool] 创建自定义工具
• 工作流代理 — 顺序、并行、循环管道
• 会话 — 管理对话状态
• 回调 — 自定义代理行为

---

上一个: 介绍 | 下一个: LlmAgent