البدء مع adk-rust: وكيلك الأول للذكاء الاصطناعي في Rust

1. مقدمة إلى adk-rust

تحدي تطوير الوكلاء

لطالما كان بناء وكلاء أذكياء قادرين على أداء مهام معقدة مجالًا مليئًا بالتحديات. غالبًا ما يتطلب تنسيق نماذج اللغة الكبيرة (LLMs)، وإدارة الحالة، والتعامل مع المدخلات المتنوعة، ونشر هؤلاء الوكلاء بفعالية حلولًا مخصصة وجهدًا هندسيًا كبيرًا. يمكن أن يكون هذا التعقيد عقبة رئيسية للمطورين الذين يتطلعون إلى دمج قدرات الذكاء الاصطناعي القوية في تطبيقاتهم.

تقديم adk-rust: تبسيط تطوير وكلاء الذكاء الاصطناعي

يهدف Agent Development Kit (ADK) إلى جعل تطوير وكلاء الذكاء الاصطناعي يشبه تطوير البرمجيات التقليدي، و`adk-rust` هو تنفيذه القوي لـ Rust. يوفر إطار عمل مرنًا ومعياريًا مصممًا لتطوير ونشر وكلاء ذكاء اصطناعي متطورين. بينما تم تحسينه لـ Gemini ونظام Google البيئي، فإن `adk-rust` مستقل عن النموذج ومستقل عن النشر، مما يضمن التوافق والمرونة عبر مختلف المنصات. سيرشدك هذا الدليل خلال إعداد بيئتك، وإنشاء مشروعك الأول لـ `adk-rust`، ونشر مساعد ذكاء اصطناعي أساسي، مما يمنحك أساسًا متينًا لمشاريعك القائمة على الوكلاء.

2. المتطلبات الأساسية والإعداد

قبل أن نتعمق في بناء الوكلاء، دعنا نتأكد من أن بيئة التطوير الخاصة بك جاهزة. ستحتاج إلى سلسلة أدوات Rust حديثة ومكتبة adk-rust مضافة إلى مشروعك. يتطلب adk-rust أيضًا مفتاح API من Google للتفاعل مع نماذج مثل Gemini. أولاً، تأكد من تثبيت Rust. إذا لم يكن كذلك، فإن الطريقة الموصى بها هي عبر rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

تأكد من أن إصدار Rust الخاص بك هو 1.75 أو أعلى:

rustc --version

بعد ذلك، سنضيف adk-rust كاعتمادية. سنضيف أيضًا tokio للعمليات غير المتزامنة (async) وdotenv لإدارة متغيرات البيئة مثل مفتاح API الخاص بك. يمكنك إضافتها باستخدام cargo add بمجرد إنشاء مشروعك (وهو ما سنفعله في الخطوة التالية):

cargo add adk-rust
cargo add tokio --features full
cargo add dotenv

بدلاً من ذلك، يمكنك إضافة هذه يدويًا إلى ملف Cargo.toml الخاص بك:

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

أخيرًا، ستحتاج إلى مفتاح API من Google لـ Gemini. احصل عليه من Google AI Studio أو Google Cloud Console. أنشئ ملف .env في الدليل الجذر لمشروعك وأضف مفتاحك:

GOOGLE_API_KEY="YOUR_GEMINI_API_KEY_HERE"

3. إنشاء مشروع ADK الأول الخاص بك

بعد إعداد بيئتك، دعنا ننشئ مشروع Rust جديدًا، والذي سيكون بمثابة الحاوية لوكيل adk-rust الخاص بنا. سنستخدم الأمر القياسي cargo new للبدء. افتح طرفيتك وقم بتشغيل:

cargo new my_first_adk_agent
cd my_first_adk_agent

يقوم هذا الأمر بتهيئة مشروع Rust جديد باسم my_first_adk_agent. سيبدو هيكل المشروع الذي تم إنشاؤه مألوفًا لمطوري Rust:

my_first_adk_agent/
├── Cargo.toml          # Project manifest and dependencies
└── src/
    └── main.rs         # Your agent's main logic goes here

الآن، يمكنك تشغيل أوامر cargo add من القسم السابق داخل دليل my_first_adk_agent هذا. تذكر أن تنشئ يدويًا ملف .env في الدليل الجذر (my_first_adk_agent/) لـ GOOGLE_API_KEY الخاص بك.

4. تشريح وكيل adk-rust

يتم بناء وكيل adk-rust عادةً حول LlmAgentBuilder ويتم تنفيذه باستخدام Launcher. الفكرة الأساسية هي تحديد شخصية وكيلك، تعليماته، وLLM التي يجب أن يستخدمها. دعنا نلقي نظرة على المكونات الأساسية التي ستجدها في ملف src/main.rs لوكيل adk-rust. في adk-rust، يتم تكوين LlmAgent بوصف، وتعليمات (تعمل كموجه نظام لـ LLM)، ونموذج لغة محدد (مثل Gemini). ثم يأخذ Launcher هذا الوكيل ويتعامل مع التنفيذ، موفرًا واجهة طرفية تفاعلية أو واجهة خادم ويب. يبسط هذا التجريد تفاعل الوكيل مع العالم الخارجي. أدناه هو المكافئ الكامل لـ 'Hello World' لوكيل adk-rust. انسخ هذا الكود إلى ملف src/main.rs الخاص بك. سنقوم بتفصيل كل جزء في القسم التالي.

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

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    // 1. Load environment variables from .env file
    dotenv::dotenv().ok();
    
    // 2. Get API key from environment
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    // 3. Create the Gemini model
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // 4. Build your agent
    let agent = LlmAgentBuilder::new("my_assistant")
        .description("A helpful AI assistant")
        .instruction("You are a friendly and helpful assistant. Answer questions clearly and concisely.")
        .model(Arc::new(model))
        .build()?;

    // 5. Run the agent with the CLI launcher
    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

5. تنفيذ وكيل الذكاء الاصطناعي البسيط الخاص بك

الآن، دعنا ننتقل إلى مكافئ 'Hello World' لوكيل adk-rust، مع التركيز على كيفية مساهمة كل جزء من الكود في إنشاء مساعد ذكاء اصطناعي وظيفي. يجب أن تكون قد نسخت الكود من القسم السابق إلى ملف src/main.rs الخاص بك. 1. **تحميل متغيرات البيئة**: يقوم dotenv::dotenv().ok(); بتحميل المتغيرات من ملف .env الخاص بك، مما يجعل GOOGLE_API_KEY متاحًا داخل تطبيق Rust الخاص بك. 2. **استرداد مفتاح API**: يقوم std::env::var("GOOGLE_API_KEY") بجلب مفتاح API الخاص بك من البيئة. يضمن استدعاء .expect() أن البرنامج سيتوقف عن العمل ويوفر رسالة خطأ واضحة إذا لم يتم العثور على المفتاح، مما يمنع الفشل الصامت عند تهيئة النموذج. 3. **تهيئة النموذج**: يقوم let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?; بإنشاء مثيل لـ GeminiModel. هنا، نقدم مفتاح API الخاص بنا ونحدد إصدار نموذج Gemini المطلوب (gemini-2.5-flash). يغلف هذا الكائن منطق الاتصال والتفاعل مع خدمة LLM الفعلية، مجردًا تعقيدات استدعاءات API. 4. **بناء الوكيل**: هذا هو المكان الذي تحدد فيه الهوية والسلوك الأساسيين لوكيلك باستخدام LlmAgentBuilder: * LlmAgentBuilder::new("my_assistant"): يبدأ بناء وكيل، ويخصص له معرفًا فريدًا. * .description("A helpful AI assistant"): يوفر وصفًا سهل القراءة لهدف وكيلك، وهو مفيد للتوثيق أو التنسيق على مستوى أعلى. * .instruction("You are a friendly and helpful assistant. Answer questions clearly and concisely."): هذا هو موجه النظام الخاص بك. يوجه LLM الأساسي حول كيفية التصرف والاستجابة وشخصيته العامة. * .model(Arc::new(model)): يربط الوكيل بـ GeminiModel الذي أنشأناه. Arc (عداد المراجع الذري) هو مؤشر عد المراجع آمن للخيوط، يستخدم هنا للملكية المشتركة، وهو أمر شائع في تطبيقات Rust غير المتزامنة (async). * .build()?: ينهي بناء الوكيل. يعيد Result، ويستخدم ? لتسهيل نشر الأخطاء. 5. **إطلاق الوكيل**: يأخذ Launcher::new(Arc::new(agent)).run().await?; وكيلك المكون وينفذه. السلوك الافتراضي لـ Launcher::run() هو بدء وحدة تحكم تفاعلية حيث يمكنك كتابة موجهات لوكيلك ورؤية ردوده. تشير الكلمة المفتاحية await إلى أن هذه عملية غير متزامنة (async)، وهي نموذجية للمهام المقيدة بالإدخال/الإخراج مثل التفاعل مع LLM.

6. بناء وتشغيل وكيلك

بمجرد ملء ملف src/main.rs الخاص بك بكود الوكيل وتحديث Cargo.toml الخاص بك بالاعتماديات، تكون جاهزًا لإحياء وكيلك! cargo هي أداتك الأساسية لذلك. أولاً، قم ببناء مشروعك لتجميع كود Rust إلى ملف تنفيذي:

cargo build

يقوم هذا الأمر بتجميع وكيلك واعتمادياته. إذا نجح، سيكون لديك ملف تنفيذي في دليل target/debug/ (أو target/release/ إذا قمت بالبناء باستخدام --release). لتشغيل وكيلك في وضع وحدة التحكم التفاعلية، وهو ممتاز للاختبار والتفاعلات السريعة، استخدم:

cargo run

ستصبح طرفيتك واجهة دردشة تفاعلية حيث يمكنك كتابة الأسئلة، وسيرد وكيلك باستخدام نموذج Gemini المكون. للخروج، يمكنك عادةً كتابة exit أو الضغط على Ctrl+C. يوفر adk-rust أيضًا طريقة لتشغيل وكيلك كخادم ويب، مما يتيح لك التفاعل معه عبر طلبات HTTP. هذا مفيد بشكل خاص لدمج وكيلك في تطبيقات الويب أو الخدمات الأخرى:

cargo run -- serve

افتراضيًا، سيبدأ هذا الخادم على http://127.0.0.1:8080. يمكنك تحديد منفذ مختلف إذا لزم الأمر:

cargo run -- serve --port 3000

الآن، وكيلك متاح عبر API ويب! يمكنك إرسال طلبات إليه باستخدام أدوات مثل curl أو متصفح ويب إلى نقطة النهاية المكونة (على سبيل المثال، http://127.0.0.1:8080/v1/agent). هذا يجعل وكيل الذكاء الاصطناعي الخاص بك خدمة قابلة للنشر والاستدعاء.

7. الخطوات التالية

تهانينا! لقد قمت بنجاح ببناء وتشغيل أول وكيل ذكاء اصطناعي خاص بك باستخدام adk-rust. هذه مجرد البداية لما يمكنك تحقيقه باستخدام الإطار. إليك بعض الاقتراحات لما يمكنك فعله بعد ذلك: * **استكشاف وثائق ADK**: تعمق أكثر في وثائق adk-rust الرسمية لفهم الميزات الأكثر تقدمًا، مثل التكامل مع المكونات الأخرى، وإدارة الحالة، أو إنشاء سير عمل وكيل أكثر تعقيدًا. * **الأدوات والقدرات المخصصة**: تعلم كيفية تزويد وكيلك بأدوات مخصصة، مما يسمح له بالتفاعل مع APIs الخارجية، قواعد البيانات، أو إجراء حسابات محددة تتجاوز مجرد توليد النصوص. هذه ميزة قوية لتوسيع قدرات الوكيل. * **خيارات النشر**: استكشف استراتيجيات نشر مختلفة لوكلاء adk-rust الخاصين بك، سواء كان ذلك بالحاويات مع Docker، أو النشر على منصات سحابية، أو التكامل في خدمات Rust الحالية. * **المشاركة المجتمعية**: انضم إلى مجتمع adk-rust. يمكن أن يؤدي مشاركة مشاريعك، وطرح الأسئلة، والمساهمة في المناقشات إلى تسريع تعلمك وحل المشكلات بشكل كبير. ابق على اتصال بآخر التطورات وأفضل الممارسات.