cargo adk build

概述

cargo adk build 命令会编译你的 ADK-Rust agent 项目，但不会部署该项目。这为你提供了一种快速验证 agent 是否能够正确编译的方式——在开始完整部署流程之前，及时发现依赖项问题、类型错误和配置问题。

将 cargo adk build 作为本地开发工作流和 CI 流水线的一部分，以便尽早验证更改，而无需平台凭据或网络访问。

命令语法

cargo adk build [OPTIONS]

该命令默认封装 cargo build --release，目标为你的 agent 项目。成功后，它会报告构建配置、目标目录和二进制文件大小。

标志和选项

标志	描述	默认值
`--manifest-path <PATH>`	`Cargo.toml` 文件的路径。从项目目录之外进行构建时很有用。	当前目录
`--debug`	使用调试模式而不是发布模式进行构建。编译速度更快，但生成的二进制文件未经优化。	发布模式

示例

# Build in release mode (default)
cargo adk build

# Build in debug mode for faster iteration
cargo adk build --debug

# Build a project at a specific path
cargo adk build --manifest-path /path/to/my-agent/Cargo.toml

构建与部署

cargo adk build 和 cargo adk deploy 在代理开发生命周期中发挥着不同的作用：

方面	`cargo adk build`	`cargo adk deploy`
用途	编译并验证	编译、打包并推送到平台
需要网络	否	是（平台服务器）
身份验证	无	需要令牌（`--token` 或 `ADK_DEPLOY_TOKEN`）
输出	`target/` 中的本地二进制文件	上传到平台的部署包
构建配置	发布版（或使用 `--debug` 的调试版）	始终为发布版
密钥处理	无	从 `.env` 上传密钥
所需清单	仅 `Cargo.toml`	`Cargo.toml` + `adk-deploy.toml`
使用场景	本地开发、CI 检查	生产部署

各自的使用时机

cargo adk build — 在开发期间用于验证编译，在 CI 流程中作为合并前的门禁，或用于检查依赖项更新是否会破坏你的 agent。
cargo adk deploy — 准备将你的 agent 发布到 ADK 平台时使用。部署内部包含构建步骤（可通过 --skip-build 跳过）。

使用示例

构建成功

$ cargo adk build
   Compiling adk-core v0.9.2
   Compiling adk-agent v0.9.2
   Compiling my-agent v0.1.0 (/home/user/my-agent)
    Finished `release` profile [optimized] target(s) in 42.3s
✅ Build successful
   profile: release
   target:  target/release
   binary:  target/release/my-agent (12.4 MB)

用于更快迭代的调试构建

$ cargo adk build --debug
   Compiling my-agent v0.1.0 (/home/user/my-agent)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 8.1s
✅ Build successful
   profile: debug
   target:  target/debug
   binary:  target/debug/my-agent (45.2 MB)

CI 流程集成

# .github/workflows/ci.yml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo install cargo-adk
      - run: cargo adk build

错误场景与解决方案

缺少依赖项

症状： 编译因未解析的导入错误而失败。

error[E0432]: unresolved import `adk_tool`
 --> src/main.rs:3:5
  |
3 | use adk_tool::FunctionTool;
  |     ^^^^^^^^ use of undeclared crate or module `adk_tool`

解决方案： 将缺少的 crate 添加到 Cargo.toml 依赖项中：

[dependencies]
adk-tool = { version = "2.1.0", features = ["mcp"] }

项目结构无效

症状： cargo adk build 找不到 Cargo.toml。

Error: failed to run cargo build: No such file or directory (os error 2)

解决方案： 从项目根目录运行命令，或指定清单路径：

cargo adk build --manifest-path ./my-agent/Cargo.toml

功能标志冲突

症状： 构建因不兼容的功能组合而失败。

error: the package `my-agent` depends on `adk-realtime`, with features:
       `openai-webrtc` but `openai-webrtc` is not a feature of `adk-realtime`

解决方案： 检查功能标志是否与所使用的 ADK 版本可用功能相匹配。运行 cargo doc -p adk-realtime --open 查看可用功能，或参阅crate 文档。

锁定文件过时

症状： 升级 ADK crate 后出现版本解析错误。

error: failed to select a version for the requirement `adk-core = "^0.9.2"`

解决方案： 更新锁定文件：

cargo update
cargo adk build

构建环境问题

症状： 链接器错误或缺少系统库。

error: linker `cc` not found

解决方案： 为你的平台安装所需的构建工具链：

# Ubuntu/Debian
sudo apt install build-essential pkg-config libssl-dev

# macOS
xcode-select --install

# Fedora/RHEL
sudo dnf install gcc openssl-devel

编译期间内存不足

症状： 构建进程被终止，或因分配失败而发生 panic。

解决方案： 降低并行度，或使用内存更大的机器：

# Limit parallel compilation jobs
CARGO_BUILD_JOBS=2 cargo adk build

# Or set in .cargo/config.toml
# [build]
# jobs = 2