بدء التشغيل السريع

يوضح لك هذا الدليل كيفية البدء والعمل مع adk-rust. ستنشئ وكيل الذكاء الاصطناعي الأول الخاص بك في أقل من 10 دقائق.

المتطلبات الأساسية

قبل البدء، تأكد من أن لديك:

• Rust 1.85.0 أو أحدث (rustup update stable)
• مفتاح Google API لـ Gemini

الخطوة 1: إنشاء مشروع جديد

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

cargo new my_agent
cd my_agent

سيبدو هيكل مشروعك كالتالي:

my_agent/
├── Cargo.toml
├── src/
│   └── main.rs
└── .env          # ستقوم بإنشائه لمفتاح API الخاص بك

الخطوة 2: إضافة التبعيات

حدث ملف Cargo.toml الخاص بك بالتبعيات المطلوبة:

[package]
name = "my_agent"
version = "0.1.0"
edition = "2024"

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

تثبيت التبعيات:

cargo build

الخطوة 3: إعداد مفتاح API الخاص بك

يستخدم هذا المشروع Gemini API، والذي يتطلب مفتاح API. إذا لم يكن لديك واحد، فأنشئ مفتاحًا في Google AI Studio.

أنشئ ملف .env في جذر مشروعك:

Linux / macOS:

echo 'GOOGLE_API_KEY=your-api-key-here' > .env

Windows (PowerShell):

echo GOOGLE_API_KEY=your-api-key-here > .env

نصيحة أمنية: أضف .env إلى ملف .gitignore الخاص بك لتجنب رفع مفتاح API الخاص بك.

الخطوة 4: كتابة وكيلك

استبدل محتويات 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>> {
    // تحميل متغيرات البيئة من ملف .env
    dotenvy::dotenv().ok();
    
    // الحصول على مفتاح API من البيئة
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    // إنشاء GeminiModel
    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // بناء وكيلك
    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()?;

    // تشغيل الوكيل باستخدام مشغل سطر الأوامر
    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

الخطوة 5: تشغيل وكيلك

ابدأ وكيلك في وضع وحدة التحكم التفاعلي:

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 AI assistant. I can help you with:
- Answering questions on various topics
- Explaining concepts
- Providing information and suggestions
- Having a friendly conversation

What would you like to know?

You: exit
👋 Goodbye!

الخطوة 6: إضافة أداة

دعنا نعزز وكيلك باستخدام أداة Google Search لمنحه إمكانية الوصول إلى المعلومات في الوقت الفعلي:

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>> {
    dotenvy::dotenv().ok();
    
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");

    let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

    // Build agent with Google Search tool
    let agent = LlmAgentBuilder::new("search_assistant")
        .description("An assistant that can search the web")
        .instruction("You are a helpful assistant. Use the search tool to find current information when needed.")
        .model(Arc::new(model))
        .tool(Arc::new(GoogleSearchTool::new()))  // Add search capability
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

ابدأ وكيلك مرة أخرى في وضع وحدة التحكم التفاعلية:

cargo run

الآن يمكنك توجيه وكيلك للبحث في الويب:

You: What's the weather like in Tokyo today?
Assistant: Let me search for that information...
[Using GoogleSearchTool]
Based on current information, Tokyo is experiencing...

التشغيل كخادم ويب

لواجهة مستندة إلى الويب، قم بالتشغيل باستخدام الأمر serve:

cargo run -- serve

يؤدي هذا إلى بدء تشغيل الخادم على المنفذ الافتراضي 8080. يمكنك الوصول إليه على http://localhost:8080.

لتحديد منفذ مخصص:

cargo run -- serve --port 3000

يؤدي هذا إلى بدء تشغيل الخادم على المنفذ 3000. يمكنك الوصول إليه على http://localhost:3000.

فهم الكود

دعنا نفصل ما يفعله كل جزء:

الواردات

use adk_rust::prelude::*;  // GeminiModel, LlmAgentBuilder, Arc, etc.
use adk_rust::Launcher;    // CLI launcher for console/server modes
use std::sync::Arc;        // Thread-safe reference counting pointer

• prelude::* تستورد جميع الأنواع شائعة الاستخدام: GeminiModel, LlmAgentBuilder, Arc, وأنواع الأخطاء، والمزيد
• Launcher يوفر واجهة سطر الأوامر (CLI) لتشغيل الوكلاء
• Arc (Atomic Reference Counted) يُمكّن المشاركة الآمنة للنموذج والوكيل عبر المهام غير المتزامنة (async tasks)

إنشاء النموذج

let model = GeminiModel::new(&api_key, "gemini-2.5-flash")?;

ينشئ مثيل نموذج Gemini الذي يطبق السمة Llm. النموذج:

• يتعامل مع المصادقة باستخدام مفتاح API الخاص بك
• يدير استجابات البث من LLM
• يدعم استدعاء الوظائف للأدوات

بناء الوكيل

let agent = LlmAgentBuilder::new("my_assistant")
    .description("A helpful AI assistant")
    .instruction("You are a friendly assistant...")
    .model(Arc::new(model))
    .build()?;

نمط البناء (builder pattern) يقوم بتهيئة وكيلك:

المشغل

Launcher::new(Arc::new(agent)).run().await?;

يتعامل المشغل (Launcher) مع وقت التشغيل:

• وضع وحدة التحكم (افتراضي): محادثة تفاعلية في جهازك الطرفي
• وضع الخادم (-- serve): واجهة برمجة تطبيقات REST مع واجهة ويب
• يدير حالة الجلسة، استجابات البث، والإغلاق السلس

استخدام نماذج أخرى

يدعم adk-rust العديد من موفري LLM خارج الصندوق. قم بتمكينها عبر إشارات الميزات (feature flags) في Cargo.toml الخاص بك:

[dependencies]
adk-rust = { version = "0.2.0", features = ["openai", "anthropic", "deepseek", "groq", "ollama"] }

عيّن مفتاح API المناسب لموفرك:

# OpenAI
export OPENAI_API_KEY="your-api-key"

# Anthropic
export ANTHROPIC_API_KEY="your-api-key"

# DeepSeek
export DEEPSEEK_API_KEY="your-api-key"

# Groq
export GROQ_API_KEY="your-api-key"

# Ollama (no key needed, just run: ollama serve)

OpenAI

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>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("OPENAI_API_KEY")?;
    let model = OpenAIClient::new(OpenAIConfig::new(api_key, "gpt-4o"))?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Anthropic

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>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("ANTHROPIC_API_KEY")?;
    let model = AnthropicClient::new(AnthropicConfig::new(api_key, "claude-sonnet-4-20250514"))?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

DeepSeek

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>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("DEEPSEEK_API_KEY")?;

    // Standard chat model
    let model = DeepSeekClient::chat(api_key)?;

    // Or use reasoner for chain-of-thought reasoning
    // let model = DeepSeekClient::reasoner(api_key)?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Groq (استدلال فائق السرعة)

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>> {
    dotenvy::dotenv().ok();

    let api_key = std::env::var("GROQ_API_KEY")?;
    let model = GroqClient::new(GroqConfig::llama70b(api_key))?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

Ollama (نماذج محلية)

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>> {
    dotenvy::dotenv().ok();

    // Requires: ollama serve && ollama pull llama3.2
    let model = OllamaModel::new(OllamaConfig::new("llama3.2"))?;

    let agent = LlmAgentBuilder::new("assistant")
        .instruction("You are a helpful assistant.")
        .model(Arc::new(model))
        .build()?;

    Launcher::new(Arc::new(agent)).run().await?;

    Ok(())
}

النماذج المدعومة

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

الآن بعد أن أصبح لديك أول وكيل يعمل، استكشف هذه المواضيع:

• LlmAgent Configuration - جميع خيارات التكوين
• Function Tools - إنشاء أدوات مخصصة
• Workflow Agents - إنشاء مسارات عمل متعددة الخطوات
• Sessions - إدارة حالة المحادثة
• Callbacks - تخصيص سلوك الوكيل

---

السابق: مقدمة | التالي: LlmAgent