빠른 시작

5분 이내에 첫 AI 에이전트를 만들어 보세요.

사전 요구 사항

• Rust 1.95.0 이상(rustup update stable)
• 이 안내를 위한 OpenAI API 키

1단계: OpenAI 서버 스캐폴딩

cargo install cargo-adk
cargo adk new quickstart_agent --template api --provider openai
cd quickstart_agent

이 명령은 OpenAI 에이전트, 메모리 내 세션, ADK HTTP 런타임, 스트리밍 엔드포인트 및 내장 개발 UI가 포함된 완전한 Rust 프로젝트를 생성합니다.

기타 템플릿

# 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 with the embedded runtime UI
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 등과 같은 선택적 애드온을 포함한 템플릿을 구성할 수 있습니다. 전체 9개 애드온과 5개 엔터프라이즈 패턴 목록은 Composable Templates 페이지를 참조하세요.

2단계: API 키 추가

cp .env.example .env
# Open .env and replace the OPENAI_API_KEY placeholder.

생성된 .gitignore에는 .env이 제외되어 있습니다. 키를 로컬에 보관하고 절대 커밋하지 마세요.

3단계: 에이전트 실행

cargo run

http://127.0.0.1:8080/ui/을 엽니다. 에이전트가 자동으로 나타나므로 먼저 세션을 만들거나 엔드포인트를 호출할 필요가 없습니다.

4단계: 런타임 UI에서 테스트

다음과 같은 프롬프트를 입력합니다.

Explain what this agent can do in three concise Markdown bullets.

응답이 대화에 스트리밍됩니다. 오른쪽의 검사기를 사용하면 페이지를 벗어나지 않고 실행 토폴로지, 정렬된 이벤트 타임라인, 상태 변경, 아티팩트, 세션, 프로토콜 기능 및 텔레메트리를 검토할 수 있습니다.

이 녹화에서는 애니메이션 핸드오프를 쉽게 확인할 수 있도록 portable-team 쇼케이스를 사용합니다. 사용자가 스캐폴딩한 에이전트도 단일 노드 토폴로지로 동일한 런타임 UI를 사용합니다.

스모크 테스트를 원한다면 HTTP 런타임을 별도로 확인하세요.

curl -fsS http://127.0.0.1:8080/api/health

이제 에이전트를 실행하고, 세션을 관리하며, 이벤트를 스트리밍하고, 자체 테스트 인터페이스를 제공하는 실행 파일 하나를 갖게 되었습니다. 별도의 프론트엔드 설치는 필요하지 않습니다.

터미널 전용 에이전트를 선호하시나요?

대신 OpenAI 콘솔 템플릿을 사용하세요.

cargo adk new quickstart_console --template openai
cd quickstart_console
cp .env.example .env   # replace the OPENAI_API_KEY placeholder
cargo run

---

구성 없는 대안 — 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(())
}

이는 컴파일된 provider 감지, 세션 생성, agent 빌드 및 실행을 한 번의 호출로 처리합니다. 스크립트, 프로토타입 및 빠른 실험에 적합합니다.

---

생성된 코드 이해하기

API scaffold의 src/main.rs는 일반적인 LlmAgent를 빌드한 다음, 이를 표준 서버에 마운트합니다. 중요한 연결은 다음과 같습니다.

use adk_rust::prelude::*;
use adk_rust::server::{ServerConfig, create_app};
use adk_rust::session::InMemorySessionService;
use std::sync::Arc;

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

    let model = adk_rust::model::openai::OpenAIClient::new(
        adk_rust::model::openai::OpenAIConfig::new(&api_key, "gpt-5.6-terra"),
    )?;

    let agent: Arc<dyn Agent> = Arc::new(
        LlmAgentBuilder::new("quickstart_agent")
            .description("REST API agent")
            .instruction("You are a helpful assistant accessible via REST API.")
            .model(Arc::new(model))
            .build()?,
    );

    let config = ServerConfig::new(
        Arc::new(adk_rust::SingleAgentLoader::new(agent)),
        Arc::new(InMemorySessionService::new()),
    );
    let app = create_app(config);

    let listener = tokio::net::TcpListener::bind("127.0.0.1:8080").await?;
    axum::serve(listener, app).await?;
    Ok(())
}

---

사용자 지정 도구 추가

도구를 추가하는 가장 빠른 방법은 #[tool] 매크로를 사용하는 것입니다. adk-tool을 종속성에 추가하세요:

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

그런 다음 도구를 정의하세요. 문서 주석이 설명이 되고, 인수 구조체가 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 구조체를 생성합니다. 이를 에이전트에 추가하세요:

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()))

---

웹 서버로 실행하기

HTTP을 제공하려는 경우 서버 프로젝트를 스캐폴딩하세요:

cargo adk new my-api --template api --provider openai
cd my-api
cp .env.example .env
cargo run

http://127.0.0.1:8080/ui/을 엽니다. 기본 기본 템플릿은 대신 경량 콘솔 런처를 사용합니다.

---

다른 모델 사용하기

기능 플래그를 통해 제공자를 활성화하세요. 빠른 설치를 위해 기본 빌드는 Gemini 전용으로 유지되므로 필요한 제공자만 추가하면 됩니다:

[dependencies]
adk-rust = { version = "2.1.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.6-terra"))?;

Anthropic

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

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::gpt_oss_120b(api_key))?;

Ollama (로컬)

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

지원되는 모델

---

다음 단계

• LlmAgent 구성 — 모든 구성 옵션
• 함수 도구 — #[tool]을 사용하여 사용자 지정 도구 생성
• 워크플로 에이전트 — 순차, 병렬, 반복 파이프라인
• 세션 — 대화 상태 관리
• 콜백 — 에이전트 동작 사용자 지정

---

이전: 소개 | 다음: LlmAgent