المشغل (Launcher)

يوفر Launcher طريقة بسيطة، في سطر واحد، لتشغيل عوامل ADK الخاصة بك مع دعم مدمج لكل من وضع وحدة التحكم التفاعلية ووضع خادم HTTP. يتولى تحليل وسيطات CLI، وإدارة Session، ويوفر واجهة متسقة لنشر Agents.

نظرة عامة

تم تصميم Launcher لجعل نشر Agent بسيطًا قدر الإمكان. باستخدام سطر واحد من التعليمات البرمجية، يمكنك:

تشغيل Agent الخاص بك في وحدة تحكم تفاعلية للاختبار والتطوير
نشر Agent الخاص بك كخادم HTTP بواجهة مستخدم ويب
تخصيص اسم التطبيق وتخزين artifact

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

وضع وحدة التحكم (الافتراضي)

أبسط طريقة لاستخدام Launcher هي إنشاؤه باستخدام Agent الخاص بك واستدعاء run():

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

#[tokio::main]
async fn main() -> Result<()> {
    let api_key = std::env::var("GOOGLE_API_KEY")?;
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-2.5-flash")?);
    
    let agent = LlmAgentBuilder::new("my_agent")
        .description("A helpful assistant")
        .instruction("You are a helpful assistant.")
        .model(model)
        .build()?;
    
    // Run with CLI support (console by default)
    Launcher::new(Arc::new(agent)).run().await
}

قم بتشغيل Agent الخاص بك:

# Interactive console (default)
cargo run

# Or explicitly specify console mode
cargo run -- chat

وضع الخادم

لتشغيل Agent الخاص بك كخادم HTTP بواجهة مستخدم ويب:

# Start server on default port (8080)
cargo run -- serve

# Start server on custom port
cargo run -- serve --port 3000

سيبدأ الخادم ويعرض:

🚀 ADK Server starting on http://localhost:8080
📱 Open http://localhost:8080 in your browser
Press Ctrl+C to stop

خيارات التكوين

اسم التطبيق المخصص

بشكل افتراضي، يستخدم Launcher اسم Agent كاسم للتطبيق. يمكنك تخصيص ذلك:

Launcher::new(Arc::new(agent))
    .app_name("my_custom_app")
    .run()
    .await

خدمة Artifact مخصصة

قدم تطبيق خدمة artifact الخاص بك:

use adk_artifact::InMemoryArtifactService;

let artifact_service = Arc::new(InMemoryArtifactService::new());

Launcher::new(Arc::new(agent))
    .with_artifact_service(artifact_service)
    .run()
    .await

تفاصيل وضع وحدة التحكم

في وضع وحدة التحكم، يقوم Launcher بما يلي:

ينشئ خدمة Session داخل الذاكرة
ينشئ Session للمستخدم
يبدأ حلقة REPL تفاعلية
يقوم ببث استجابات Agent في الوقت الفعلي
يتعامل مع عمليات نقل Agent في الأنظمة متعددة Agents

التفاعل مع وحدة التحكم

🤖 Agent ready! Type your questions (or 'exit' to quit).

You: What is the capital of France?
Assistant: The capital of France is Paris.

You: exit
👋 Goodbye!

وحدة التحكم متعددة Agents

عند استخدام أنظمة متعددة Agents، تعرض وحدة التحكم أي Agent يستجيب:

You: I need help with my order

[Agent: customer_service]
Assistant: I'll help you with your order. What's your order number?

You: ORDER-12345

🔄 [Transfer requested to: order_lookup]

[Agent: order_lookup]
Assistant: I found your order. It was shipped yesterday.

تفاصيل وضع الخادم

في وضع الخادم، يقوم Launcher بما يلي:

يقوم بتهيئة القياس عن بعد للمراقبة
ينشئ خدمة جلسات في الذاكرة
يبدأ خادم HTTP بنقاط نهاية REST API
يقدم واجهة مستخدم ويب للتفاعل مع وكيلك

نقاط النهاية المتاحة

يعرض الخادم نقاط نهاية REST API التالية:

GET /health - نقطة نهاية فحص السلامة
POST /run_sse - تشغيل الوكيل مع بث أحداث مرسلة من الخادم (Server-Sent Events)
GET /sessions - سرد الجلسات
POST /sessions - إنشاء جلسة جديدة
GET /sessions/:app_name/:user_id/:session_id - الحصول على تفاصيل الجلسة
DELETE /sessions/:app_name/:user_id/:session_id - حذف جلسة

راجع وثائق واجهة برمجة تطبيقات الخادم للحصول على مواصفات مفصلة لنقاط النهاية.

واجهة المستخدم الويب

يتضمن الخادم واجهة مستخدم ويب مدمجة يمكن الوصول إليها عبر http://localhost:8080/ui/. توفر واجهة المستخدم ما يلي:

واجهة دردشة تفاعلية
إدارة الجلسات
استجابات البث في الوقت الفعلي
تصور متعدد الوكلاء

وسيطات سطر الأوامر (CLI)

يدعم Launcher أوامر CLI التالية:

Command	Description	Example
(none)	Interactive console (default)	`cargo run`
`chat`	Interactive console (explicit)	`cargo run -- chat`
`serve`	HTTP server mode	`cargo run -- serve`
`serve --port PORT`	HTTP server on custom port	`cargo run -- serve --port 3000`

مثال كامل

إليك مثال كامل يوضح كلا الوضعين:

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

#[tokio::main]
async fn main() -> Result<()> {
    // Load API key
    let api_key = std::env::var("GOOGLE_API_KEY")
        .expect("GOOGLE_API_KEY environment variable not set");
    
    // Create model
    let model = Arc::new(GeminiModel::new(&api_key, "gemini-2.5-flash")?);
    
    // Create agent with tools
    let weather_tool = FunctionTool::new(
        "get_weather",
        "Get the current weather for a location",
        |params, _ctx| async move {
            let location = params["location"].as_str().unwrap_or("unknown");
            Ok(json!({
                "location": location,
                "temperature": 72,
                "condition": "sunny"
            }))
        },
    );
    
    let agent = LlmAgentBuilder::new("weather_agent")
        .description("An agent that provides weather information")
        .instruction("You are a weather assistant. Use the get_weather tool to provide weather information.")
        .model(model)
        .tool(Arc::new(weather_tool))
        .build()?;
    
    // Run with Launcher (supports both console and server modes via CLI)
    Launcher::new(Arc::new(agent))
        .app_name("weather_app")
        .run()
        .await
}

تشغيل في وضع وحدة التحكم:

cargo run

تشغيل في وضع الخادم:

cargo run -- serve --port 8080

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

متغيرات البيئة: قم دائمًا بتحميل التكوينات الحساسة (مفاتيح API) من متغيرات البيئة
معالجة الأخطاء: استخدم معالجة الأخطاء المناسبة مع أنواع Result
الإغلاق السلس: يتعامل Launcher مع Ctrl+C بسلاسة في كلا الوضعين
اختيار المنفذ: اختر منافذ لا تتعارض مع الخدمات الأخرى (الافتراضي 8080)
إدارة الجلسات: في بيئة الإنتاج، ضع في اعتبارك استخدام DatabaseSessionService بدلاً من الجلسات المخزنة في الذاكرة