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"

أنشئ .env باستخدام مفتاح API الخاص بك:

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°م."

إنشاء أداة باستخدام 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" في المطالبة كلما كان JSON Output مفعّلًا، وإلا فقد يعيد 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 تكرار، وهي كافية لمعظم حالات الاستخدام. ويُوصى بقيم أقل (5-20) لوكلاء الأسئلة والأجوبة البسيطة، بينما قد تكون هناك حاجة إلى قيم أعلى لمهام الاستدلال المعقدة متعددة الخطوات.

---

مجموعات الأدوات الديناميكية

بالنسبة إلى الأدوات التي تعتمد على سياق الاستدعاء (مثل جلسات المتصفح لكل مستخدم)، استخدم .toolset() بدلًا من .tool(). ويتم حل مجموعات الأدوات في بداية كل استدعاء لـ 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() بالدلالات نفسها، ولذلك تحصل وكلاء الصوت الفوري على حل ديناميكي للأدوات أيضًا.

تركيب مجموعات الأدوات

استخدم FilteredToolset وMergedToolset وPrefixedToolset من adk-tool لتركيب إعدادات معقدة لمجموعات الأدوات:

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

تعمل جميع أدوات التركيب مع أي تنفيذ لـ Toolset، بما في ذلك McpToolset وBrowserToolset.

تنفيذ الأدوات بالتوازي

عندما يعيد 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()?;

يمكن لعمليات الاستدعاء بعد الأداة فحص البيانات الوصفية المهيكلة ToolOutcome عبر CallbackContext::tool_outcome():

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

---

ذو صلة

• وكلاء سير العمل - وكلاء تسلسليون ومتوازون ووكلاء حلقات
• الأنظمة متعددة الوكلاء - بناء تسلسلات هرمية للوكلاء
• أدوات الدوال - إنشاء أدوات مخصصة
• عمليات الاستدعاء - اعتراض سلوك الوكيل

---

السابق: البدء السريع | التالي: وكلاء سير العمل ←