المُشغِّل

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

نظرة عامة

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

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

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

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

إن أبسط طريقة لاستخدام المُشغِّل هي إنشاؤه باستخدام وكيلك واستدعاء 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-3.7-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

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

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

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

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

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

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

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

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

منفذ الهروب للإنتاج

بالنسبة إلى تطبيقات الإنتاج التي تحتاج إلى مسارات مخصصة أو برمجيات وسيطة أو مقاييس أو التحكم في حلقة التقديم، استخدم 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-*:

الأمر	الوصف	المثال
(لا شيء)	وحدة تحكم تفاعلية (افتراضيًا)	`cargo run`
`chat`	وحدة تحكم تفاعلية (بشكل صريح)	`cargo run -- chat`
`serve`	وضع الخادم HTTP	`cargo run -- serve`
`serve --port PORT`	الخادم على منفذ مخصص HTTP	`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-3.7-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 للاطلاع على توثيق الأمر الكامل.

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

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

الخادم API - توثيق REST API التفصيلي
الجلسات - إدارة الجلسات
المصنوعات - تخزين المصنوعات
قابلية المراقبة - القياس عن بُعد والتسجيل

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