LlmAgent

LlmAgent은 추론과 의사 결정을 위해 대규모 언어 모델을 사용하는 ADK-Rust의 핵심 에이전트 유형입니다.

빠른 시작

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

cargo new llm_agent
cd llm_agent

Cargo.toml에 의존성을 추가합니다:

[dependencies]
adk-rust = "2.1.0"
tokio = { version = "1.40", features = ["full"] }
dotenvy = "0.15"
serde_json = "1.0"

API 키를 사용하여 .env를 생성합니다:

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

src/main.rs을 교체합니다:

use adk_rust::prelude::*;
use adk_rust::{SessionId, UserId};
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")?;
    let model = GeminiModel::new(&api_key, "gemini-3.7-flash")?;

    let agent = LlmAgentBuilder::new("my_agent")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

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

실행합니다:

cargo run

에이전트와 상호 작용

대화형 프롬프트가 표시됩니다:

🤖 Agent ready! Type your questions (or 'exit' to quit).

You: Hello! What can you help me with?
Assistant: Hello! I'm a helpful assistant. I can help you with:
- Answering questions on various topics
- Explaining concepts clearly
- Having a conversation

What would you like to know?

You: exit
👋 Goodbye!

---

지침으로 에이전트 동작 형성

instruction() 메서드는 에이전트의 성격과 동작을 정의합니다. 이는 모든 응답을 안내하는 시스템 프롬프트입니다:

// A formal business assistant
let formal_agent = LlmAgentBuilder::new("formal_assistant")
    .instruction("You are a professional business consultant. \
                 Use formal language. Be concise and data-driven.")
    .model(Arc::new(model))
    .build()?;

// A friendly coding tutor
let tutor_agent = LlmAgentBuilder::new("code_tutor")
    .instruction("You are a friendly coding tutor for beginners. \
                 Explain concepts simply. Use examples. \
                 Encourage questions. Never make the user feel bad for not knowing.")
    .model(Arc::new(model))
    .build()?;

// A creative storyteller
let story_agent = LlmAgentBuilder::new("storyteller")
    .instruction("You are a creative storyteller. \
                 Craft engaging narratives with vivid descriptions. \
                 Use plot twists and memorable characters.")
    .model(Arc::new(model))
    .build()?;

출력 예시

사용자 프롬프트: "Rust란 무엇인가요?"

공식 비즈니스 어시스턴트:

Rust is a systems programming language focused on performance, memory safety, 
and concurrency. Key metrics: 0 runtime overhead, 0 garbage collection. 
Adoption growing 30% YoY in enterprise. Recommended for performance-critical 
applications where reliability is paramount.

친근한 코딩 튜터:

Great question! 🎉 Rust is a programming language that helps you write fast 
and safe code. Think of it like a helpful friend who stops you from making 
mistakes before they happen!

Here's a simple example:
  let name = "Alice";  // This creates a variable

What makes Rust special is that it catches bugs at compile time, not when 
your program is running. Pretty cool, right? Want me to explain more?

창의적인 이야기꾼:

In the twilight of 2010, in a secret Mozilla laboratory, a lone developer 
named Graydon Hoare breathed life into something extraordinary—a language 
that would challenge the old gods of C and C++.

They called it Rust, named for a fungus that survives against all odds. 
Like a phoenix rising from the ashes of segmentation faults and memory 
leaks, Rust promised a new era: speed without sacrifice, power without peril.

And so, the revolution began...

지침 템플릿화

지침은 {var} 구문을 사용한 변수 삽입을 지원합니다. 변수는 런타임에 세션 상태에서 확인됩니다:

let agent = LlmAgentBuilder::new("personalized")
    .instruction("You are helping {user_name}. Their role is {user_role}. \
                 Tailor your responses to their expertise level.")
    .model(Arc::new(model))
    .build()?;

템플릿 사용 단계별 안내:

1. 지침에 템플릿 변수를 포함하여 에이전트 생성
2. 상태를 관리하도록 Runner 및 SessionService 설정
3. 템플릿과 일치하는 상태 변수를 사용하여 세션 생성
4. 에이전트 실행 - 템플릿이 자동으로 대체됩니다

다음은 완전히 작동하는 예시입니다:

use adk_rust::prelude::*;
use adk_rust::{SessionId, UserId};
use adk_rust::runner::{Runner, RunnerConfig};
use adk_rust::session::{CreateRequest, InMemorySessionService, SessionService};
use adk_rust::futures::StreamExt;
use serde_json::json;
use std::collections::HashMap;
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")?;
    let model = GeminiModel::new(&api_key, "gemini-3.7-flash")?;

    // 1. Agent with templated instruction
    let agent = LlmAgentBuilder::new("personalized")
        .instruction("You are helping {user_name}. Their role is {user_role}. \
                     Tailor your responses to their expertise level.")
        .model(Arc::new(model))
        .build()?;

    // 2. Create session service and runner
    let session_service = Arc::new(InMemorySessionService::new());
    let runner = Runner::new(RunnerConfig {
        app_name: "templating_demo".to_string(),
        agent: Arc::new(agent),
        session_service: session_service.clone(),
        artifact_service: None,
        memory_service: None,
        run_config: None,
    })?;

    // 3. Create session with state variables
    let mut state = HashMap::new();
    state.insert("user_name".to_string(), json!("Alice"));
    state.insert("user_role".to_string(), json!("Senior Developer"));

    let session = session_service.create(CreateRequest {
        app_name: "templating_demo".to_string(),
        user_id: "user123".to_string(),
        session_id: None,
        state,
    }).await?;

    // 4. Run the agent - instruction becomes:
    // "You are helping Alice. Their role is Senior Developer..."
    let mut response_stream = runner.run(
        UserId::new("user123")?,
        SessionId::new(session.id())?,
        Content::new("user").with_text("Explain async/await in Rust"),
    ).await?;

    // Print the response
    while let Some(event) = response_stream.next().await {
        let event = event?;
        if let Some(content) = event.content() {
            for part in &content.parts {
                if let Part::Text { text } = part {
                    print!("{}", text);
                }
            }
        }
    }

    Ok(())
}

템플릿 변수 유형:

출력 예시:

템플릿: "You are helping {user_name}. Their role is {user_role}."
결과: "You are helping Alice. Their role is Senior Developer."

그러면 에이전트는 사용자의 이름과 전문성 수준을 바탕으로 개인화된 콘텐츠를 응답합니다!

---

도구 추가

도구를 사용하면 에이전트에 대화 이상의 기능을 제공할 수 있습니다. 데이터를 가져오고, 계산을 수행하고, 웹을 검색하거나, 외부 APIs을 호출할 수 있습니다. LLM은 사용자의 요청을 바탕으로 도구를 사용할 시점을 결정합니다.

도구 작동 방식

1. 에이전트가 사용자 메시지를 수신 → "도쿄의 날씨는 어때?"
2. LLM가 도구 호출을 결정 → get_weather을 {"city": "Tokyo"}과 함께 선택
3. 도구가 실행 → {"temperature": "22°C", "condition": "sunny"} 반환
4. LLM가 응답 형식을 지정 → "도쿄의 날씨는 맑고 22°C입니다."

FunctionTool로 도구 만들기

FunctionTool는 도구를 만드는 가장 간단한 방법입니다. 모든 비동기 Rust 함수로 감싸면 LLM가 이를 호출할 수 있습니다. 이름, 설명, 그리고 JSON 인수를 받아 JSON 결과를 반환하는 핸들러 함수를 제공합니다.

let weather_tool = FunctionTool::new(
    "get_weather",                              // Tool name (used by LLM)
    "Get the current weather for a city",       // Description (helps LLM decide when to use it)
    |_ctx, args| async move {                   // Handler function
        let city = args.get("city")             // Extract arguments from JSON
            .and_then(|v| v.as_str())
            .unwrap_or("unknown");
        Ok(json!({ "city": city, "temperature": "22°C" }))  // Return JSON result
    },
);

이제 기본 제공자 네이티브 도구를 동일한 에이전트에서 FunctionTool 인스턴스와 함께 사용할 수 있습니다. ADK는 네이티브 도구 선언을 제공자에게 전달하면서 일반 함수 도구는 로컬에서 계속 실행합니다.

다중 도구 에이전트 빌드

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

cargo new tool_agent
cd tool_agent

Cargo.toml에 종속성을 추가합니다:

[dependencies]
adk-rust = { version = "2.1.0", features = ["tools"] }
tokio = { version = "1.40", features = ["full"] }
dotenvy = "0.15"
serde_json = "1.0"

.env을 생성합니다:

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

src/main.rs을 세 가지 도구를 가진 에이전트로 교체합니다:

use adk_rust::prelude::*;
use adk_rust::Launcher;
use serde_json::json;
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")?;
    let model = GeminiModel::new(&api_key, "gemini-3.7-flash")?;

    // Tool 1: Weather lookup
    let weather_tool = FunctionTool::new(
        "get_weather",
        "Get the current weather for a city. Parameters: city (string)",
        |_ctx, args| async move {
            let city = args.get("city").and_then(|v| v.as_str()).unwrap_or("unknown");
            Ok(json!({ "city": city, "temperature": "22°C", "condition": "sunny" }))
        },
    );

    // Tool 2: Calculator
    let calculator = FunctionTool::new(
        "calculate",
        "Perform arithmetic. Parameters: a (number), b (number), operation (add/subtract/multiply/divide)",
        |_ctx, args| async move {
            let a = args.get("a").and_then(|v| v.as_f64()).unwrap_or(0.0);
            let b = args.get("b").and_then(|v| v.as_f64()).unwrap_or(0.0);
            let op = args.get("operation").and_then(|v| v.as_str()).unwrap_or("add");
            let result = match op {
                "add" => a + b,
                "subtract" => a - b,
                "multiply" => a * b,
                "divide" => if b != 0.0 { a / b } else { 0.0 },
                _ => 0.0,
            };
            Ok(json!({ "result": result }))
        },
    );

    // Tool 3: Built-in Google Search (Note: Currently unsupported in ADK-Rust)
    // let search_tool = GoogleSearchTool::new();

    // Build agent with weather and calculator tools
    let agent = LlmAgentBuilder::new("multi_tool_agent")
        .instruction("You are a helpful assistant. Use tools when needed: \
                     - get_weather for weather questions \
                     - calculate for math")
        .model(Arc::new(model))
        .tool(Arc::new(weather_tool))
        .tool(Arc::new(calculator))
        // .tool(Arc::new(search_tool))  // Currently unsupported
        .build()?;

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

에이전트를 실행합니다:

cargo run

상호작용 예시

You: What's 15% of 250?
Assistant: [Using calculate tool with a=250, b=0.15, operation=multiply]
15% of 250 is 37.5.

You: What's the weather in Tokyo?
Assistant: [Using get_weather tool with city=Tokyo]
The weather in Tokyo is sunny with a temperature of 22°C.

You: Search for latest Rust features
Assistant: I don't have access to search functionality at the moment, but I can help with other questions about Rust or perform calculations!

---

JSON 스키마를 사용한 구조화된 출력

구조화된 데이터가 필요한 애플리케이션에는 output_schema()을 사용합니다:

use adk_rust::prelude::*;
use serde_json::json;
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")?;
    let model = GeminiModel::new(&api_key, "gemini-3.7-flash")?;

    let extractor = LlmAgentBuilder::new("entity_extractor")
        .instruction("Extract entities from the given text.")
        .model(Arc::new(model))
        .output_schema(json!({
            "type": "object",
            "properties": {
                "people": {
                    "type": "array",
                    "items": { "type": "string" }
                },
                "locations": {
                    "type": "array",
                    "items": { "type": "string" }
                },
                "dates": {
                    "type": "array",
                    "items": { "type": "string" }
                }
            },
            "required": ["people", "locations", "dates"]
        }))
        .build()?;

    println!("Entity extractor ready!");
    Ok(())
}

제공자가 스키마를 적용하는 방식

output_schema는 GenerateContentConfig::response_schema으로 제공자에게 전달됩니다. 제공자가 이를 처리하는 방식은 서로 다르지만, 어느 경우든 에이전트는 결과를 검증합니다:

제공자가 구문만 적용하거나 아무것도 적용하지 않는 경우에도 에이전트는 스키마를 지침으로 주입하고 응답을 검증하므로, 규격을 준수하지 않는 응답은 잘못된 데이터를 반환하는 대신 재시도를 발생시킵니다.

참고: DeepSeek에서는 JSON Output이 켜져 있을 때 프롬프트에 "json"이라는 단어가 포함되어야 하며, 그렇지 않으면 API가 빈 콘텐츠를 반환할 수 있습니다. 프롬프트에 해당 단어가 이미 포함되어 있지 않으면 어댑터가 직접 추가합니다.

JSON Output 예시

입력: "John met Sarah in Paris on December 25th"

출력:

{
  "people": ["John", "Sarah"],
  "locations": ["Paris"],
  "dates": ["December 25th"]
}

---

고급 기능

콘텐츠 포함

대화 기록의 표시 여부를 제어합니다:

// Full history (default)
.include_contents(IncludeContents::Default)

// Stateless - sees only injected instructions plus the current user turn
.include_contents(IncludeContents::None)

출력 키

에이전트 응답을 세션 상태에 저장합니다:

.output_key("summary")  // Response saved to state["summary"]

동적 지침

런타임에 지침을 계산합니다:

.instruction_provider(|ctx| {
    Box::pin(async move {
        let user_id = ctx.user_id();
        Ok(format!("You are assisting user {}.", user_id))
    })
})

콜백

에이전트 동작을 가로챕니다:

.before_model_callback(|ctx, request| {
    Box::pin(async move {
        println!("About to call LLM with {} messages", request.contents.len());
        Ok(BeforeModelResult::Continue)
    })
})

---

빌더 참조

반복 제어

max_iterations() 메서드는 에이전트가 중지하기 전에 수행할 수 있는 LLM 왕복 횟수를 제한합니다. 다음과 같은 경우에 유용합니다.

• 무한히 반복되는 도구 호출 루프 방지
• 프로덕션 환경에서 비용 제어
• 복잡한 작업에 대한 합리적인 제한 설정

let agent = LlmAgentBuilder::new("bounded_agent")
    .model(Arc::new(model))
    .instruction("You are a helpful assistant.")
    .tool(Arc::new(my_tool))
    .max_iterations(10)  // Stop after 10 LLM calls
    .build()?;

기본값은 100회 반복이며, 대부분의 사용 사례에 충분합니다. 간단한 Q&A 에이전트에는 더 낮은 값(5~20)을 권장하며, 복잡한 다단계 추론 작업에는 더 높은 값이 필요할 수 있습니다.

---

동적 도구 세트

호출 컨텍스트에 따라 달라지는 도구(예: 사용자별 브라우저 세션)에는 .tool() 대신 .toolset()를 사용합니다. 도구 세트는 각 run() 호출이 시작될 때 확인됩니다.

use adk_browser::{BrowserSessionPool, BrowserToolset, BrowserConfig};
use adk_agent::LlmAgentBuilder;
use std::sync::Arc;

let pool = Arc::new(BrowserSessionPool::new(BrowserConfig::new(), 10));
let toolset = Arc::new(BrowserToolset::with_pool(pool));

let agent = LlmAgentBuilder::new("web_agent")
    .model(model)
    .instruction("You are a web automation assistant.")
    .toolset(toolset)  // Resolved per-user at runtime
    .build()?;

동일한 에이전트에서 정적 .tool()과 동적 .toolset()을 함께 사용할 수 있습니다. 정적 도구와 도구 세트 간에 도구 이름이 중복되면 결정론적 오류가 발생합니다.

RealtimeAgentBuilder는 동일한 의미 체계로 .toolset()도 지원하므로, 실시간 음성 에이전트에서도 동적 도구 확인이 가능합니다.

도구 세트 구성

adk-tool의 FilteredToolset, MergedToolset, PrefixedToolset을 사용하여 복잡한 도구 세트 구성을 조합합니다.

use adk_tool::{BasicToolset, FilteredToolset, MergedToolset, PrefixedToolset, string_predicate};

// Prefix weather tools to avoid name collisions
let weather = Arc::new(PrefixedToolset::new(weather_toolset, "wx"));

// Filter utility tools to only expose search and calculate
let utils = Arc::new(FilteredToolset::new(
    utility_toolset,
    string_predicate(vec!["search".into(), "calculate".into()]),
));

// Merge into a single toolset
let composed = MergedToolset::new("all", vec![weather, utils]);

let agent = LlmAgentBuilder::new("agent")
    .model(model)
    .toolset(Arc::new(composed))
    .build()?;

모든 구성 유틸리티는 McpToolset 및 BrowserToolset을 포함한 모든 Toolset 구현과 함께 작동합니다.

병렬 도구 실행

LLM가 단일 응답에서 여러 도구 호출을 반환하는 경우, 해당 호출이 디스패치되는 방식을 제어할 수 있습니다.

use adk_core::ToolExecutionStrategy;

let agent = LlmAgentBuilder::new("fast_agent")
    .model(Arc::new(model))
    .instruction("You are a research assistant. Use multiple tools in parallel.")
    // Auto requires both safety signals for concurrent inclusion
    .tool_execution_strategy(ToolExecutionStrategy::Auto)
    .tool(Arc::new(
        search_tool
            .with_read_only(true)
            .with_concurrency_safe(true),
    ))
    .tool(Arc::new(
        lookup_tool
            .with_read_only(true)
            .with_concurrency_safe(true),
    ))
    .tool(Arc::new(save_tool)) // runs after the concurrent safe subset
    .build()?;

세 가지 전략을 사용할 수 있습니다.

• Sequential (기본값) — 도구가 LLM 순서로 한 번에 하나씩 실행됩니다.
• Parallel — 모든 도구가 동시에 실행됩니다. 이 명시적 재정의는 안전성 메타데이터를 우회하므로, 안전성에 대한 책임은 호출자에게 있습니다.
• Auto — 도구가 읽기 전용이고 동시 실행에 안전한 호출이 먼저 동시에 실행되며, 나머지 호출은 순차적으로 실행됩니다.

결과는 전략과 관계없이 항상 원래 LLM 순서로 반환됩니다. 실패한 도구는 배치를 중단하지 않고 JSON 오류 응답을 생성합니다.

전략은 에이전트별로 LlmAgentBuilder::tool_execution_strategy()을 통해 설정합니다. 설정하지 않으면 기본값은 Sequential입니다.

도구 복원력

프로덕션 에이전트에 재시도 예산과 회로 차단기를 구성합니다:

use adk_core::RetryBudget;
use std::time::Duration;

let agent = LlmAgentBuilder::new("resilient_agent")
    .model(model)
    .tool(Arc::new(my_tool))
    // Retry all tools up to 2 times with 500ms delay
    .default_retry_budget(RetryBudget::new(2, Duration::from_millis(500)))
    // Override for a specific tool
    .tool_retry_budget("flaky_api", RetryBudget::new(4, Duration::from_secs(1)))
    // Disable a tool after 3 consecutive failures in one invocation
    .circuit_breaker_threshold(3)
    // Provide a fallback when a tool fails
    .on_tool_error(Box::new(|_ctx, tool, _args, error| {
        Box::pin(async move {
            tracing::warn!(tool = tool.name(), %error, "tool failed");
            Ok(None) // None = propagate error; Some(value) = use as fallback
        })
    }))
    .build()?;

도구 실행 후 콜백은 CallbackContext::tool_outcome()를 통해 구조화된 ToolOutcome 메타데이터를 검사할 수 있습니다:

.after_tool_callback(Box::new(|ctx| {
    Box::pin(async move {
        if let Some(outcome) = ctx.tool_outcome() {
            println!(
                "Tool '{}' {} in {:?} (attempt {})",
                outcome.tool_name,
                if outcome.success { "succeeded" } else { "failed" },
                outcome.duration,
                outcome.attempt,
            );
        }
        Ok(None)
    })
}))

---

전체 예제

여러 도구(날씨, 계산기, 검색)를 사용하고 출력을 세션 상태에 저장하는 프로덕션용 에이전트입니다:

use adk_rust::prelude::*;
use adk_rust::Launcher;
use serde_json::json;
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")?;
    let model = GeminiModel::new(&api_key, "gemini-3.7-flash")?;

    // Weather tool
    let weather = FunctionTool::new(
        "get_weather",
        "Get weather for a city. Parameters: city (string)",
        |_ctx, args| async move {
            let city = args.get("city").and_then(|v| v.as_str()).unwrap_or("unknown");
            Ok(json!({
                "city": city,
                "temperature": "22°C",
                "humidity": "65%",
                "condition": "partly cloudy"
            }))
        },
    );

    // Calculator tool
    let calc = FunctionTool::new(
        "calculate",
        "Math operations. Parameters: expression (string like '2 + 2')",
        |_ctx, args| async move {
            let expr = args.get("expression").and_then(|v| v.as_str()).unwrap_or("0");
            Ok(json!({ "expression": expr, "result": "computed" }))
        },
    );

    // Build the full agent
    let agent = LlmAgentBuilder::new("assistant")
        .description("A helpful assistant with weather and calculation abilities")
        .instruction("You are a helpful assistant. \
                     Use the weather tool for weather questions. \
                     Use the calculator for math. \
                     Be concise and friendly.")
        .model(Arc::new(model))
        .tool(Arc::new(weather))
        .tool(Arc::new(calc))
        // .tool(Arc::new(GoogleSearchTool::new()))  // Provider-native tools can be mixed with FunctionTool
        .output_key("last_response")
        .build()?;

    println!("✅ Agent '{}' ready!", agent.name());
    Launcher::new(Arc::new(agent)).run().await?;
    Ok(())
}

다음 프롬프트를 사용해 보세요:

You: What's 25 times 4?
Assistant: It's 100.

You: How's the weather in New York?
Assistant: The weather in New York is partly cloudy with a temperature of 22°C and 65% humidity.

You: Calculate 15% tip on $85
Assistant: A 15% tip on $85 is $12.75, making the total $97.75.

---

관련 항목

• 워크플로 에이전트 - 순차, 병렬 및 루프 에이전트
• 다중 에이전트 시스템 - 에이전트 계층 구조 구축
• 함수 도구 - 사용자 지정 도구 생성
• 콜백 - 에이전트 동작 가로채기

---

이전: 빠른 시작 | 다음: 워크플로 에이전트 →