cargo adk build

개요

cargo adk build 명령은 배포하지 않고 ADK-Rust 에이전트 프로젝트를 컴파일합니다. 이를 통해 에이전트가 올바르게 컴파일되는지 빠르게 확인할 수 있으며, 전체 배포 주기를 진행하기 전에 종속성 문제, 타입 오류 및 구성 문제를 발견할 수 있습니다.

cargo adk build을 로컬 개발 워크플로 및 CI 파이프라인의 일부로 사용하여 플랫폼 자격 증명이나 네트워크 액세스 없이도 변경 사항을 조기에 검증할 수 있습니다.

명령 구문

cargo adk build [OPTIONS]

이 명령은 기본적으로 cargo build --release을 래핑하여 에이전트 프로젝트를 대상으로 합니다. 성공하면 빌드 프로필, 대상 디렉터리 및 바이너리 크기를 보고합니다.

플래그 및 옵션

예제

# 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 — 개발 중 컴파일을 확인하거나, 병합 전에 CI 파이프라인의 게이트로 사용하거나, 종속성 업데이트로 인해 에이전트가 손상되지 않는지 확인할 때 사용합니다.
• cargo adk deploy — 에이전트를 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

컴파일 중 메모리 부족

증상: 빌드 프로세스가 종료되거나 할당 실패로 패닉이 발생합니다.

해결 방법: 병렬 처리 수준을 낮추거나 RAM이 더 많은 시스템을 사용합니다.

# Limit parallel compilation jobs
CARGO_BUILD_JOBS=2 cargo adk build

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