🦀ADK-Rust

مقدمة إلى ADK-Rust

مجموعة تطوير الوكيل (ADK) هي إطار عمل مرن ومعياري لتطوير ونشر وكلاء الذكاء الاصطناعي. بينما تم تحسينه لـ Gemini والنظام البيئي لـ Google، فإن ADK محايد للموديل، ومحايد للنشر، ومصمم للتوافق مع أطر العمل الأخرى. صُممت ADK لجعل تطوير الوكلاء يشبه تطوير البرمجيات، مما يسهل على المطورين إنشاء ونشر وتنسيق بنى وكلاء تتراوح من المهام البسيطة إلى سير العمل المعقد.

ملاحظة: يتطلب ADK-Rust v0.2.0 إصدار Rust 1.85.0 أو أعلى

التثبيت

أضف ADK-Rust إلى مشروعك:

cargo add adk-rust

أو أضفه إلى ملف Cargo.toml الخاص بك:

[dependencies]
adk-rust = "0.2.0"
tokio = { version = "1.40", features = ["full"] }

مثال سريع

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")?;
    
    let agent = LlmAgentBuilder::new("assistant")
        .description("A helpful AI assistant")
        .model(Arc::new(model))
        .build()?;
    
    println!("Agent '{}' ready!", agent.name());
    Ok(())
}

نظرة عامة على البنية

يستخدم ADK-Rust بنية طبقية مصممة للنمطية والقابلية للتوسع:

┌─────────────────────────────────────────────────────────────┐
│                    طبقة التطبيق                              │
│              CLI • REST Server • Web UI                      │
├─────────────────────────────────────────────────────────────┤
│                      طبقة Runner                             │
│           تنفيذ Agent • إدارة السياق                        │
├─────────────────────────────────────────────────────────────┤
│                      طبقة Agent                              │
│    LlmAgent • CustomAgent • Workflow Agents                  │
├─────────────────────────────────────────────────────────────┤
│                     طبقة الخدمة                               │
│      Models • Tools • Sessions • Artifacts • Memory          │
└─────────────────────────────────────────────────────────────┘

المفاهيم الأساسية

تم بناء ADK-Rust حول العديد من البدائيات الرئيسية التي تعمل معًا لإنشاء Agents ذكاء اصطناعي قوية:

Agents

وحدة العامل الأساسية المصممة لمهام محددة. يوفر ADK-Rust عدة أنواع من الـ Agent:

  • LlmAgent: يستخدم نموذج لغة كبير للاستدلال واتخاذ القرار. هذا هو نوع الـ Agent الأساسي لمعظم حالات الاستخدام.
  • RealtimeAgent: Agents يدعمون الصوت باستخدام OpenAI Realtime API أو Gemini Live API لبث الصوت ثنائي الاتجاه.
  • GraphAgent: تنسيق سير العمل بأسلوب LangGraph مع إدارة الحالة، ونقاط التحقق، ودعم التدخل البشري.
  • CustomAgent: يسمح لك بتنفيذ منطق مخصص مع تحكم كامل في سلوك الـ Agent.
  • وكلاء Workflow: Agents حتميون يتبعون مسارات تنفيذ محددة مسبقًا:
    • SequentialAgent: ينفذ الـ sub-Agents بالترتيب
    • ParallelAgent: ينفذ الـ sub-Agents بالتوازي
    • LoopAgent: ينفذ الـ sub-Agents بشكل متكرر حتى يتم استيفاء شرط

Tools

تمنح الـ Tools الـ Agents قدرات تتجاوز المحادثة، مما يسمح لهم بالتفاعل مع واجهات برمجة التطبيقات (APIs) الخارجية، أو البحث عن المعلومات، أو تنفيذ عمليات مخصصة:

  • FunctionTool: يغلف أي دالة Rust غير متزامنة كـ Tool
  • GoogleSearchTool: قدرة بحث ويب مدمجة
  • BrowserToolset: 46 WebDriver Tools لأتمتة الويب (التنقل، النماذج، لقطات الشاشة، إلخ.)
  • ExitLoopTool: تتحكم في إنهاء الحلقة في LoopAgent
  • McpToolset: التكامل مع خوادم Model Context Protocol

Sessions

تتعامل الـ Sessions مع سياق محادثة واحدة، بما في ذلك:

  • Session ID: معرف فريد للمحادثة
  • الأحداث: سجل المحادثة (رسائل المستخدم، استجابات الـ Agents، استدعاءات الـ Tools)
  • الحالة: ذاكرة العمل للمحادثة مع بادئات محددة النطاق (app:, user:, temp:)

دوال الاستدعاء

رمز مخصص يتم تشغيله في نقاط محددة من تنفيذ الـ Agent:

  • before_agent / after_agent: اعتراض استدعاءات الـ Agent
  • before_model / after_model: اعتراض استدعاءات LLM
  • before_tool / after_tool: اعتراض عمليات تنفيذ الـ Tool

تتيح دوال الاستدعاء (Callbacks) التسجيل، والضمانات، والتخزين المؤقت، وتعديل السلوك.

القطع الأثرية

تخزين البيانات الثنائية للملفات أو الصور أو أي محتوى آخر غير نصي:

  • حفظ وتحميل القطع الأثرية مع إدارة الإصدارات
  • تحديد نطاق مساحات الأسماء (على مستوى الـ Session أو مستوى المستخدم)
  • خلفيات تخزين قابلة للتوصيل

الأحداث

الوحدة الأساسية للاتصال التي تمثل الأشياء التي تحدث أثناء الـ Session:

  • رسائل المستخدم
  • استجابات الـ Agents
  • استدعاءات الـ Tools والنتائج
  • تغييرات الحالة

تشكل الأحداث سجل المحادثة وتمكن من إعادة التشغيل وتصحيح الأخطاء.

النماذج

نموذج اللغة الكبير (LLM) الأساسي الذي يدعم LlmAgents. تم تحسين ADK-Rust لـ Gemini ولكنه يدعم العديد من المزودين من خلال الـ Llm trait:

  • Gemini: نماذج Gemini من Google (gemini-3-pro-preview, gemini-2.5-flash, gemini-2.5-pro)
  • OpenAI: gpt-5.2, gpt-4o, gpt-4o-mini, Azure OpenAI
  • Anthropic: claude-sonnet-4-5, claude-opus-4-5, claude-sonnet-4
  • DeepSeek: deepseek-chat, deepseek-reasoner مع وضع التفكير
  • Groq: استدلال فائق السرعة مع llama-3.3-70b-versatile, mixtral-8x7b-32768
  • Ollama: استدلال محلي مع llama3.2, qwen2.5, mistral, phi4
  • mistral.rs: استدلال محلي عالي الأداء مع تسريع الأجهزة

جميع المزودين ينفذون الـ trait نفسه للاستخدام القابل للتبديل:

pub trait Llm: Send + Sync {
    async fn generate(&self, request: LlmRequest) -> Result<LlmResponse>;
    async fn generate_stream(&self, request: LlmRequest) -> Result<LlmResponseStream>;
}

Runner

المحرك الذي يدير تدفق التنفيذ، وينسق تفاعلات الـ Agents، وينسق مع الخدمات الخلفية. يتعامل الـ Runner مع:

  • استدعاء الـ Agent ومعالجة الاستجابات
  • تنفيذ الـ Tool
  • إدارة الـ Session والحالة
  • تدفق الأحداث

علامات الميزات

يستخدم ADK-Rust ميزات Cargo لتحقيق النمطية:

# Full installation (default)
adk-rust = "0.2.0"

# Minimal: Only agents + Gemini
adk-rust = { version = "0.2.0", default-features = false, features = ["minimal"] }

# Custom: Pick what you need
adk-rust = { version = "0.2.0", default-features = false, features = ["agents", "gemini", "tools"] }

الميزات المتاحة:

  • agents: تطبيقات العامل (LlmAgent, CustomAgent, workflow agents)
  • models: تكاملات النماذج (Gemini)
  • openai: نماذج OpenAI (GPT-5, GPT-4o)
  • anthropic: نماذج Anthropic (Claude 4.5, Claude 4)
  • deepseek: نماذج DeepSeek (chat, reasoner)
  • groq: استدلال Groq فائق السرعة
  • ollama: نماذج Ollama المحلية
  • tools: نظام الأدوات والأدوات المضمنة
  • sessions: إدارة الجلسات
  • artifacts: تخزين البيانات الاصطناعية
  • memory: نظام الذاكرة مع البحث الدلالي
  • runner: وقت تشغيل تنفيذ العامل
  • server: خادم HTTP (REST + A2A)
  • telemetry: تكامل OpenTelemetry
  • cli: مشغل CLI

لغات أخرى

ADK متوفر بلغات متعددة:

التالي: Quickstart →