LlmAgent

يُعدّ LlmAgent نوع الوكيل الأساسي في ADK-Rust الذي يستخدم نموذج لغة كبيرًا للاستدلال واتخاذ القرار.

البدء السريع

أنشئ مشروعًا جديدًا:

cargo new llm_agent
cd llm_agent

أضف الاعتمادات إلى Cargo.toml:

[dependencies]
adk-rust = "2.0.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-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(())
}

شغّله:

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

أنواع متغيرات القالب:

مثال على الإخراج:

القالب: "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.0.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-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(())
}

شغّل وكيلك:

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

كيف يفرض المزوّدون المخطط

يصل output_schema إلى المزوّد على أنه GenerateContentConfig::response_schema. ويختلف ما يفعله المزوّد به، لكن الوكيل يتحقق من النتيجة في كلتا الحالتين:

حيث يفرض المزوّد التحقق من البنية فقط، أو لا يفرض شيئًا على الإطلاق، فإن العامل يحقن المخطط أيضًا كتوجيه ويُتحقق من الرد، لذا فإن أي إجابة غير مطابقة ستكلّف إعادة المحاولة بدلًا من إرجاع بيانات خاطئة.

ملاحظة: DeepSeek يتطلب أن تظهر الكلمة "json" في الموجه كلما كان JSON الإخراج مفعّلًا، وإلا فقد يُرجع API محتوى فارغًا. يضيف المهايئ هذه الإشارة بنفسه عندما لا يحتوي الموجه لديك عليها بالفعل.

JSON مثال على الإخراج

المدخل: "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-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(())
}

جرّب هذه المطالبات:

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.

---

ذات صلة

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

---

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