LlmAgent

Der LlmAgent ist der zentrale Agententyp in ADK-Rust, der ein Large Language Model für Schlussfolgerungen und Entscheidungsfindung verwendet.

Schnellstart

Erstelle ein neues Projekt:

cargo new llm_agent
cd llm_agent

Füge Abhängigkeiten zu Cargo.toml hinzu:

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

Erstelle .env mit deinem API-Schlüssel:

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

Ersetze 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-2.5-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(())
}

Führe es aus:

cargo run

Interaktion mit deinem Agenten

Du wirst eine interaktive Eingabeaufforderung sehen:

🤖 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!

---

Agentenverhalten mit Anweisungen gestalten

Die Methode instruction() definiert die Persönlichkeit und das Verhalten deines Agenten. Dies ist der System-Prompt, der jede Antwort leitet:

// 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()?;

Beispielausgaben

Benutzer-Prompt: "What is Rust?"

Formeller Business-Assistent:

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.

Freundlicher Coding-Tutor:

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?

Kreativer Geschichtenerzähler:

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

Anweisungsvorlagen

Anweisungen unterstützen das Einfügen von Variablen mit der {var}-Syntax. Variablen werden zur Laufzeit aus dem Sitzungsstatus aufgelöst:

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

Schritt-für-Schritt-Anleitung zur Verwendung von Vorlagen:

1. Erstelle den Agenten mit Vorlagenvariablen in der Anweisung
2. Richte Runner und SessionService ein, um den Status zu verwalten
3. Erstelle eine Sitzung mit Statusvariablen, die zu deiner Vorlage passen
4. Führe den Agenten aus - Vorlagen werden automatisch ersetzt

Hier ist ein vollständiges, funktionierendes Beispiel:

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

Typen von Vorlagenvariablen:

Ausgabe-Beispiel:

Vorlage: "You are helping {user_name}. Their role is {user_role}."
Wird zu: "You are helping Alice. Their role is Senior Developer."

Der Agent wird dann personalisierte Inhalte basierend auf dem Namen und dem Erfahrungsniveau des Benutzers zurückgeben!

---

Tools hinzufügen

Tools geben deinem Agenten Fähigkeiten über die Unterhaltung hinaus — sie können Daten abrufen, Berechnungen durchführen, das Web durchsuchen oder externe APIs aufrufen. Der LLM entscheidet anhand der Anfrage des Benutzers, wann ein Tool verwendet werden soll.

Wie Tools funktionieren

1. Agent empfängt Benutzernachricht → "Wie ist das Wetter in Tokio?"
2. LLM entscheidet, das Tool aufzurufen → Wählt get_weather mit {"city": "Tokyo"} aus
3. Tool wird ausgeführt → Gibt {"temperature": "22°C", "condition": "sunny"} zurück
4. LLM formatiert die Antwort → "Das Wetter in Tokio ist sonnig bei 22°C."

Ein Tool mit FunctionTool erstellen

FunctionTool ist der einfachste Weg, ein Tool zu erstellen — umschließe einfach eine asynchrone Rust-Funktion, und der LLM kann sie aufrufen. Du gibst einen Namen, eine Beschreibung und eine Handler-Funktion an, die JSON-Argumente entgegennimmt und ein JSON-Ergebnis zurückgibt.

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
    },
);

Eingebaute anbieternative Tools können jetzt mit FunctionTool-Instanzen im selben Agenten gemischt werden. ADK leitet die nativen Tool-Deklarationen an den Anbieter weiter, während gewöhnliche Funktionstools weiterhin lokal ausgeführt werden.

Einen Multi-Tool-Agenten erstellen

Erstelle ein neues Projekt:

cargo new tool_agent
cd tool_agent

Füge Abhängigkeiten zu Cargo.toml hinzu:

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

Erstelle .env:

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

Ersetze src/main.rs durch einen Agenten mit drei Tools:

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

Starte deinen Agenten:

cargo run

Beispielinteraktion

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!

---

Strukturierte Ausgabe mit JSON-Schema

Für Anwendungen, die strukturierte Daten benötigen, verwende 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-2.5-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(())
}

Wie Anbieter das Schema durchsetzen

output_schema gelangt als GenerateContentConfig::response_schema zum Anbieter. Was der Anbieter damit macht, unterscheidet sich, und der Agent validiert das Ergebnis in jedem Fall:

Wenn ein Provider nur Syntax erzwingt oder gar nichts, fügt der Agent das Schema dennoch als Anweisung ein und validiert die Antwort, sodass eine nicht konforme Antwort einen erneuten Versuch kostet, statt fehlerhafte Daten zurückzugeben.

Hinweis: DeepSeek erfordert, dass das Wort "json" in der Eingabeaufforderung erscheint, wenn JSON Output aktiviert ist; andernfalls kann der API leeren Inhalt zurückgeben. Der Adapter fügt diese Erwähnung selbst hinzu, wenn sie in Ihrer Eingabeaufforderung noch nicht enthalten ist.

JSON Ausgabe-Beispiel

Eingabe: "John traf Sarah am 25. Dezember in Paris"

Ausgabe:

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

---

Erweiterte Funktionen

Inhalte einbeziehen

Sichtbarkeit des Gesprächsverlaufs steuern:

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

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

Ausgabe-Schlüssel

Agentenantworten im Sitzungsstatus speichern:

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

Dynamische Anweisungen

Anweisungen zur Laufzeit berechnen:

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

Callbacks

Agentenverhalten abfangen:

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

---

Builder-Referenz

Iterationssteuerung

Die Methode max_iterations() begrenzt, wie viele LLM Round-Trips ein Agent vor dem Stoppen durchführen kann. Das ist nützlich für:

• Verhindern von außer Kontrolle geratener Tool-Aufruf-Schleifen
• Kontrolle der Kosten in der Produktion
• Setzen sinnvoller Grenzen für komplexe Aufgaben

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

Der Standardwert ist 100 Iterationen, was für die meisten Anwendungsfälle ausreicht. Niedrigere Werte (5–20) werden für einfache Q&A-Agenten empfohlen, während höhere Werte für komplexe mehrstufige Reasoning-Aufgaben erforderlich sein können.

---

Dynamische Toolsets

Für Tools, die vom Aufrufkontext abhängen (z. B. browser sessions pro Benutzer), verwende .toolset() statt .tool(). Toolsets werden zu Beginn jedes run()-Aufrufs aufgelöst:

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

Du kannst statische .tool() und dynamische .toolset() im selben Agenten mischen. Doppelte Tool-Namen über statische Tools und Toolsets hinweg erzeugen einen deterministischen Fehler.

RealtimeAgentBuilder unterstützt außerdem .toolset() mit derselben Semantik, sodass Realtime-Voice-Agenten ebenfalls eine dynamische Tool-Auflösung erhalten.

Toolset-Zusammensetzung

Verwende FilteredToolset, MergedToolset und PrefixedToolset aus adk-tool, um komplexe Toolset-Konfigurationen zusammenzustellen:

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

Alle Zusammensetzungs-Utilities funktionieren mit jeder Toolset-Implementierung, einschließlich McpToolset und BrowserToolset.

Parallele Tool-Ausführung

Wenn ein LLM mehrere Tool-Aufrufe in einer einzigen Antwort zurückgibt, kannst du steuern, wie sie verteilt werden:

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

Es sind drei Strategien verfügbar:

• Sequential (Standard) — Tools werden nacheinander in LLM-Reihenfolge ausgeführt
• Parallel — alle Tools werden gleichzeitig ausgeführt; diese explizite Überschreibung umgeht Sicherheitsmetadaten, daher trägt der Aufrufer die Verantwortung für die Sicherheit
• Auto — Aufrufe, deren Tools sowohl read-only als auch concurrency-safe sind, werden zuerst parallel ausgeführt; alle verbleibenden Aufrufe laufen danach sequenziell

Ergebnisse werden unabhängig von der Strategie immer in der ursprünglichen LLM-Reihenfolge zurückgegeben. Fehlgeschlagene Tools erzeugen eine JSON-Fehlermeldung, ohne den Batch abzubrechen.

Die Strategie wird pro Agent über LlmAgentBuilder::tool_execution_strategy() festgelegt. Wenn sie nicht gesetzt ist, ist der Standard Sequential.

Tool-Resilienz

Konfiguriere Retry-Budgets und Circuit Breaker für Produktionsagenten:

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

After-Tool-Callbacks können strukturierte ToolOutcome-Metadaten über CallbackContext::tool_outcome() inspizieren:

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

---

Vollständiges Beispiel

Ein produktionsreifer Agent mit mehreren Tools (Wetter, Rechner, Suche) und Ausgabe, die im Session-Status gespeichert wird:

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

Probiere diese Prompts aus:

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.

---

Verwandtes

• Workflow Agents - Sequenzielle, parallele und Loop-Agenten
• Multi-Agent Systems - Aufbau von Agenten-Hierarchien
• Function Tools - Eigene Tools erstellen
• Callbacks - Agentenverhalten abfangen

---

Vorherige: Quickstart | Nächste: Workflow Agents →