المشغل

يوفر Launcher طريقة بسيطة ومباشرة لتشغيل وكلاء ADK. في الطبقة الدنيا الافتراضية، هو مشغل وحدة تحكم خفيف الوزن من adk-runner. قم بتمكين ميزة CLI الاختيارية مثل cli-openai عندما تحتاج إلى محلل وسائط CLI الكامل ووضع خادم HTTP.

نظرة عامة

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

• تشغيل وكيلك في وحدة تحكم تفاعلية للاختبار والتطوير
• نشر وكيلك كخادم HTTP مع واجهة مستخدم ويب عند استخدام ميزة cli-* أو قالب cargo-adk api
• تخصيص اسم التطبيق وتخزين البيانات الاصطناعية

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

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

أبسط طريقة لاستخدام المشغل هي إنشاؤه مع وكيلك واستدعاء 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 the lightweight console launcher
    Launcher::new(Arc::new(agent)).run().await
}

قم بتشغيل وكيلك:

# Interactive console (default)
cargo run

# Full CLI mode is available when your app enables a `cli-*` feature

وضع الخادم

لتشغيل وكيلك كخادم HTTP مع واجهة مستخدم ويب، استخدم قالب api أو قم بتمكين ميزة cli-*:

cargo adk new my-api --template api
cd my-api
cargo run

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

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

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

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

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

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

خدمة البيانات الاصطناعية المخصصة

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

use adk_artifact::InMemoryArtifactService;

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

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

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

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

1. إنشاء خدمة جلسة في الذاكرة
2. إنشاء جلسة للمستخدم
3. بدء حلقة REPL تفاعلية
4. بث استجابات الوكيل في الوقت الفعلي
5. التعامل مع عمليات نقل الوكيل في أنظمة متعددة الوكلاء

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

🤖 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!

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

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

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.

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

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

1. تهيئة القياس عن بعد للمراقبة
2. إنشاء خدمة جلسة في الذاكرة
3. بدء خادم HTTP مع نقاط نهاية REST API
4. تقديم واجهة مستخدم ويب للتفاعل مع وكيلك

مخرج الإنتاج

لتطبيقات الإنتاج التي تحتاج إلى مسارات مخصصة، أو برمجيات وسيطة، أو مقاييس، أو ملكية حلقة الخدمة، استخدم build_app():

let app = Launcher::new(Arc::new(agent))
    .with_a2a_base_url("https://agent.example.com")
    .build_app()?;

let app = app.merge(my_admin_routes());
let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
axum::serve(listener, app).await?;

استخدم build_app_with_a2a(...) إذا كنت تريد تمكين مسارات A2A بشكل صريح.

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

يعرض الخادم نقاط نهاية 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 - حذف جلسة

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

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

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

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

وسائط CLI

يدعم مشغل CLI الكامل الأوامر التالية عند تمكين ميزة cli-*:

مثال كامل

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

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. Enable a `cli-*` feature for full CLI/server mode.
    Launcher::new(Arc::new(agent))
        .app_name("weather_app")
        .run()
        .await
}

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

cargo run

تشغيل في وضع الخادم من مشروع API مُنشأ:

cargo adk new weather-api --template api
cd weather-api
cargo run

التحقق قبل النشر

قبل نشر وكيلك، استخدم cargo adk build للتحقق من أن المشروع يتم تجميعه بشكل صحيح دون نشره فعليًا:

# Verify compilation (no deployment)
cargo adk build

# Build with release optimizations
cargo adk build --release

يساعد هذا في اكتشاف أخطاء التجميع، والتبعيات المفقودة، ومشكلات التكوين قبل الالتزام بالنشر. وهو مفيد بشكل خاص في مسارات CI كبوابة قبل cargo adk deploy.

انظر cargo adk build للاطلاع على الوثائق الكاملة للأمر.

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

1. متغيرات البيئة: قم دائمًا بتحميل التكوينات الحساسة (مفاتيح API) من متغيرات البيئة
2. معالجة الأخطاء: استخدم معالجة الأخطاء المناسبة مع أنواع Result
3. إيقاف التشغيل السلس: يتعامل Launcher مع Ctrl+C بسلاسة في كلا الوضعين
4. اختيار المنفذ: اختر منافذ لا تتعارض مع الخدمات الأخرى (الافتراضي 8080)
5. إدارة الجلسات: في بيئة الإنتاج، فكر في استخدام PostgresSessionService أو SqliteSessionService بدلاً من الجلسات المخزنة في الذاكرة
6. فحص ما قبل النشر: قم بتشغيل cargo adk build قبل النشر لاكتشاف المشكلات مبكرًا

ذات صلة

• Server API - وثائق REST API مفصلة
• Sessions - إدارة الجلسات
• Artifacts - تخزين البيانات الاصطناعية
• Observability - القياس عن بعد والتسجيل

---

السابق: ← القياس عن بعد | التالي: الخادم →