빠른 시작

이 가이드는 ADK-Rust를 사용하여 빠르게 시작하는 방법을 보여줍니다. 10분 안에 첫 번째 AI agent를 만들게 될 것입니다.

전제 조건

시작하기 전에 다음을 확인하세요:

• Rust 1.85.0 이상 (rustup update stable)
• Gemini용 Google API key

1단계: 새 프로젝트 생성

새 Rust 프로젝트를 생성합니다:

cargo new my_agent
cd my_agent

프로젝트 구조는 다음과 같습니다:

my_agent/
├── Cargo.toml
├── src/
│   └── main.rs
└── .env          # API key를 위해 이 파일을 생성합니다

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 Key 설정

이 프로젝트는 API key를 필요로 하는 Gemini API를 사용합니다. key가 없다면, Google AI Studio에서 key를 생성하세요.

프로젝트 루트에 .env 파일을 생성합니다:

Linux / macOS:

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

Windows (PowerShell):

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

보안 팁: API key가 커밋되지 않도록 .gitignore에 .env를 추가하세요.

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 key를 가져옵니다
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    // Gemini model을 생성합니다
    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: 안녕하세요! 무엇을 도와드릴 수 있나요?
Assistant: 안녕하세요! 저는 도움이 되는 AI assistant입니다. 다음을 도와드릴 수 있습니다:
- 다양한 주제에 대한 질문에 답변
- 개념 설명
- 정보 및 제안 제공
- 친근한 대화

무엇을 알고 싶으신가요?

You: exit
👋 안녕히 계세요!

6단계: 도구 추가

Google Search Tool을 사용하여 에이전트의 기능을 강화하고 실시간 정보에 접근할 수 있도록 해봅시다:

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...

웹 서버로 실행하기

웹 기반 인터페이스의 경우, 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 (원자적 참조 카운트)는 비동기 작업에서 모델과 에이전트를 안전하게 공유할 수 있도록 합니다.

모델 생성

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

Llm 트레이트를 구현하는 Gemini 모델 인스턴스를 생성합니다. 이 모델은 다음을 수행합니다:

• API 키를 사용하여 인증을 처리합니다.
• 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): 웹 인터페이스가 있는 REST API
• 세션 상태, 스트리밍 응답 및 정상적인 종료를 관리합니다.

다른 모델 사용하기

ADK-Rust는 여러 LLM 제공업체를 기본적으로 지원합니다. Cargo.toml의 기능 플래그를 통해 활성화할 수 있습니다:

[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 (키 필요 없음, 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")?;

    // Standard chat model
    let model = DeepSeekClient::chat(api_key)?;

    // Or use reasoner for chain-of-thought reasoning
    // 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();

    // Requires: 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 구성 - 모든 구성 옵션
• Function Tools - 사용자 지정 Tool 생성
• Workflow Agents - 다단계 파이프라인 구축
• Sessions - 대화 상태 관리
• Callbacks - Agent 동작 사용자 지정

---

이전: 소개 | 다음: LlmAgent