الأدوات المدمجة

ADK-Rust توفر العديد من الأدوات المدمجة التي توسع قدرات الـ Agent دون الحاجة إلى تطبيق مخصص. هذه الأدوات جاهزة للاستخدام فورًا وتتكامل بسلاسة مع إطار عمل الـ Agent.

يتم الآن الإعلان عن الأدوات الأصلية للموفر من خلال Tool API العادية بدلاً من GenerateContentConfig.extensions blobs الخاصة بالموفر. هذا يعني أنه يمكنك مزج الأدوات الأصلية مثل Gemini Google Search، Anthropic Web Search، أو OpenAI Responses web search مع مثيلات FunctionTool العادية في نفس الـ Agent.

نظرة عامة

GoogleSearchTool

يتيح GoogleSearchTool للوكلاء البحث في الويب باستخدام Google Search. يتم التعامل مع هذه الأداة داخليًا بواسطة Gemini models من خلال ميزة grounding، مما يعني أن البحث يتم تنفيذه من جانب الخادم بواسطة النموذج نفسه.

الاستخدام الأساسي

use adk_rust::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Create the GoogleSearchTool
    let search_tool = GoogleSearchTool;

    // Add to agent
    let agent = LlmAgentBuilder::new("research_assistant")
        .description("An assistant that can search the web for information")
        .instruction(
            "You are a research assistant. When asked about current events, \
             recent news, or factual information, use the google_search tool \
             to find accurate, up-to-date information."
        )
        .model(Arc::new(model))
        .tool(Arc::new(search_tool))
        .build()?;

    println!("Agent created with Google Search capability!");
    Ok(())
}

كيف تعمل

على عكس function tools العادية، يعمل GoogleSearchTool بشكل مختلف:

1. التنفيذ من جانب الخادم: يتم إجراء البحث بواسطة ميزة grounding الخاصة بـ Gemini، وليس محليًا
2. الاستدعاء التلقائي: يقرر النموذج متى يبحث بناءً على الاستعلام
3. النتائج المتكاملة: يتم دمج نتائج البحث مباشرة في استجابة النموذج

يعيد تنفيذ الأداة خطأً إذا تم استدعاؤها مباشرة لأن البحث الفعلي يحدث داخل Gemini API:

// This is handled internally - you don't call it directly
async fn execute(&self, _ctx: Arc<dyn ToolContext>, _args: Value) -> Result<Value> {
    Err(AdkError::tool("GoogleSearch is handled internally by Gemini"))
}

تفاصيل الأداة

حالات الاستخدام

• الأحداث الجارية: "ماذا حدث في الأخبار اليوم؟"
• الاستفسارات الواقعية: "كم عدد سكان طوكيو؟"
• المعلومات الحديثة: "ما هي آخر التطورات في الذكاء الاصطناعي؟"
• مهام البحث: "ابحث عن معلومات حول اتجاهات الطاقة المتجددة"

أمثلة على الاستعلامات

// The agent will automatically use Google Search for queries like:
// - "What's the weather forecast for New York this week?"
// - "Who won the latest championship game?"
// - "What are the current stock prices for tech companies?"

AgentTool

AgentTool يغلف أي Agent كأداة قابلة للاستدعاء، مما يتيح تركيب الـ Agent حيث يمكن لـ Agent أب استدعاء Agent ابن كجزء من سير عمل استدعاء الأدوات الخاص به. يتم إعادة توجيه تغييرات الحالة والتحف من الـ sub-agent تلقائيًا إلى سياق الـ Agent الأب.

الاستخدام الأساسي

use adk_rust::prelude::*;
use adk_tool::AgentTool;
use std::sync::Arc;

let sub_agent = LlmAgentBuilder::new("summarizer")
    .description("Summarizes text content")
    .instruction("Summarize the provided text concisely.")
    .model(model.clone())
    .build()?;

let agent_tool = AgentTool::new(Arc::new(sub_agent));

let coordinator = LlmAgentBuilder::new("coordinator")
    .instruction("Use the summarizer tool when asked to summarize content.")
    .model(model.clone())
    .tool(Arc::new(agent_tool))
    .build()?;

كيف يعمل

1. يقرر الـ Agent الأب استدعاء الـ Agent المغلف كأداة
2. AgentTool ينشئ سياق استدعاء باستخدام StreamingMode::None
3. يعمل الـ sub-agent حتى الاكتمال ويجمع استجابته الكاملة
4. يتم إرجاع نص الاستجابة إلى الـ Agent الأب
5. يتم إعادة توجيه فروقات الحالة وفروقات التحف إلى سياق الـ Agent الأب

تفاصيل الأداة

السلوك الرئيسي

• الوكلاء الفرعيون يعملون في وضع غير تدفقي داخليًا لالتقاط الاستجابات بشكل موثوق
• تتغير الحالة (output_key) من الوكيل الفرعي وتنتشر إلى الجلسة الأصلية
• يتم إعادة توجيه المخرجات المحفوظة بواسطة الوكيل الفرعي إلى السياق الأصلي
• انظر Multi-Agent Systems للمزيد حول أنماط تركيب الوكلاء

ExitLoopTool

ExitLoopTool هي أداة تحكم تُستخدم مع LoopAgent للإشارة إلى متى يجب أن تتوقف عملية تكرارية. عند استدعائها، تقوم بتعيين علامة escalate، مما يتسبب في خروج الحلقة.

الاستخدام الأساسي

use adk_rust::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Create an agent with ExitLoopTool for iterative refinement
    let refiner = LlmAgentBuilder::new("content_refiner")
        .description("Iteratively improves content quality")
        .instruction(
            "Review the content and improve it. Check for:\n\
             1. Clarity and readability\n\
             2. Grammar and spelling\n\
             3. Logical flow\n\n\
             If the content meets all quality standards, call the exit_loop tool.\n\
             Otherwise, provide an improved version."
        )
        .model(Arc::new(model))
        .tool(Arc::new(ExitLoopTool::new()))
        .build()?;

    // Use in a LoopAgent
    let loop_agent = LoopAgent::new(
        "iterative_refiner",
        vec![Arc::new(refiner)],
    ).with_max_iterations(5);

    println!("Loop agent created with exit capability!");
    Ok(())
}

كيف تعمل

1. يقوم الوكيل بتقييم ما إذا كان سيستمر أم سيخرج
2. عندما يكون جاهزًا للخروج، يستدعي الوكيل exit_loop
3. تقوم الأداة بتعيين actions.escalate = true و actions.skip_summarization = true
4. يكتشف LoopAgent علامة التصعيد ويتوقف عن التكرار

تفاصيل الأداة

أفضل الممارسات

1. معايير خروج واضحة: حدد شروطًا محددة في تعليمات الوكيل
2. قم دائمًا بتعيين max_iterations: لمنع الحلقات اللانهائية كإجراء أمان
3. تعليمات ذات معنى: ساعد الوكيل على فهم متى يجب الخروج

// Good: Clear exit criteria
.instruction(
    "Improve the text until it:\n\
     - Has no grammatical errors\n\
     - Is under 100 words\n\
     - Uses active voice\n\
     When all criteria are met, call exit_loop."
)

// Avoid: Vague criteria
.instruction("Improve the text. Exit when done.")

LoadArtifactsTool

LoadArtifactsTool يسمح للوكلاء باسترداد القطع الأثرية المخزنة بالاسم. هذا مفيد عندما يحتاج الوكلاء إلى الوصول إلى الملفات أو الصور أو أي بيانات ثنائية أخرى تم حفظها مسبقًا.

الاستخدام الأساسي

use adk_rust::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Create agent with artifact loading capability
    let agent = LlmAgentBuilder::new("document_analyzer")
        .description("Analyzes stored documents")
        .instruction(
            "You can load and analyze stored artifacts. \
             Use the load_artifacts tool to retrieve documents by name. \
             The tool accepts an array of artifact names."
        )
        .model(Arc::new(model))
        .tool(Arc::new(LoadArtifactsTool::new()))
        .build()?;

    println!("Agent created with artifact loading capability!");
    Ok(())
}

تفاصيل الأداة

المعلمات

تتوقع الأداة كائن JSON مع مصفوفة artifact_names:

{
  "artifact_names": ["document.txt", "image.png", "data.json"]
}

تنسيق الاستجابة

تُرجع الأداة كائنًا يحتوي على العناصر المحملة:

{
  "artifacts": [
    {
      "name": "document.txt",
      "content": "The text content of the document..."
    },
    {
      "name": "image.png",
      "content": {
        "mime_type": "image/png",
        "data": "base64-encoded-data..."
      }
    },
    {
      "name": "missing.txt",
      "error": "Artifact not found"
    }
  ]
}

المتطلبات

لكي يعمل LoadArtifactsTool، تحتاج إلى:

1. ArtifactService مُكوّن في الـ runner
2. Artifacts تم حفظها مسبقًا في الخدمة
3. الأداة مضافة إلى الـ agent

use adk_rust::prelude::*;
use std::sync::Arc;

// Set up artifact service
let artifact_service = Arc::new(InMemoryArtifactService::new());

// Configure runner with artifact service
let runner = Runner::new(agent)
    .with_artifact_service(artifact_service);

دمج الأدوات المدمجة

يمكنك استخدام أدوات مدمجة متعددة معًا:

use adk_rust::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Create agent with multiple built-in tools
    let agent = LlmAgentBuilder::new("research_agent")
        .description("Research agent with search and artifact capabilities")
        .instruction(
            "You are a research agent. You can:\n\
             - Search the web using google_search for current information\n\
             - Load stored documents using load_artifacts\n\
             Use these tools to help answer questions comprehensively."
        )
        .model(Arc::new(model))
        .tool(Arc::new(GoogleSearchTool))
        .tool(Arc::new(LoadArtifactsTool::new()))
        .build()?;

    println!("Multi-tool agent created!");
    Ok(())
}

إنشاء أدوات مدمجة مخصصة

يمكنك إنشاء أدواتك الخاصة باتباع نفس النمط المتبع في الأدوات المدمجة عن طريق تطبيق الـ trait Tool:

use adk_rust::prelude::*;
use async_trait::async_trait;
use serde_json::{json, Value};
use std::sync::Arc;

pub struct MyCustomTool;

impl MyCustomTool {
    pub fn new() -> Self {
        Self
    }
}

#[async_trait]
impl Tool for MyCustomTool {
    fn name(&self) -> &str {
        "my_custom_tool"
    }

    fn description(&self) -> &str {
        "Description of what this tool does"
    }

    async fn execute(&self, ctx: Arc<dyn ToolContext>, args: Value) -> Result<Value> {
        // Your tool logic here
        Ok(json!({ "result": "success" }))
    }
}

مرجع API

GoogleSearchTool

impl GoogleSearchTool {
    /// Create a new GoogleSearchTool instance
    pub fn new() -> Self;
}

ExitLoopTool

impl ExitLoopTool {
    /// Create a new ExitLoopTool instance
    pub fn new() -> Self;
}

LoadArtifactsTool

impl LoadArtifactsTool {
    /// Create a new LoadArtifactsTool instance
    pub fn new() -> Self;
}

impl Default for LoadArtifactsTool {
    fn default() -> Self;
}

ذات صلة

• Function Tools - إنشاء أدوات وظائف مخصصة
• MCP Tools - استخدام خوادم MCP كمزودي أدوات
• Workflow Agents - استخدام ExitLoopTool مع LoopAgent
• Artifacts - إدارة البيانات الثنائية باستخدام Artifacts

---

السابق: ← Function Tools | التالي: Browser Tools →