محرك الوكيل (منصة وكلاء Gemini للمؤسسات)

تجعل ميزة agent-engine وكيل ADK-Rust قابلاً للتشغيل بواسطة منصة وكلاء Gemini للمؤسسات باعتباره ReasoningEngine في حاوية مخصصة. تستجيب حاوية تشغّل serve_agent_engine إلى reasoningEngines.query، وreasoningEngines.streamQuery، وPlayground في وحدة التحكم، وSDKs الخاص بالمنصة — وهو نفس عقد وقت التشغيل الذي يطبّقه adk-python الخاص بـ AdkApp.

نظرة عامة

تتحكم المنصة في محرك منشور من خلال نقطتي نهاية للحاوية:

كلاهما يأخذ غلاف التوزيع {"class_method": "...", "input": {...}}.
الغلاف هو snake_case — إذ توزّع المنصة الطلبات استنادًا إلى أسماء أساليب Python.
كما يوفّر التطبيق الجاهز GET /health لفحوصات صحة الحاوية.

البدء السريع

فعّل الميزة (فهي مضمنة في الميزة الشاملة gemini-agent-platform):

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "agent-engine"] }

بالنسبة إلى وكيل يستخدم المنصة كاملة — الجلسات المُدارة، وبنك الذاكرة، ومتجر الأمثلة، وبيئة الاختبار المعزولة لتنفيذ التعليمات البرمجية، وRAG، والتقييم، وسجلي الوكلاء والمهارات — توفر ميزة واحدة كل عمليات التكامل:

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gemini-agent-platform"] }

serve_agent_engine هو كامل main لمحرك قابل للنشر. فهو يربط 0.0.0.0:$PORT (والبديل الاحتياطي 8080) ويستمر في تقديم الخدمة حتى إيقافه:

use adk_rust::prelude::*;
use adk_server::agent_engine::{AgentEngineOptions, serve_agent_engine};
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("weather_agent")
        .description("Answers weather questions")
        .instruction("You are a helpful weather assistant.")
        .model(model)
        .build()?;

    serve_agent_engine(Arc::new(agent), AgentEngineOptions::new()).await
}

تحقق باستخدام حمولة مختبر التعليمات البرمجية:

curl -s -X POST localhost:8080/api/stream_reasoning_engine \
  -H 'Content-Type: application/json' \
  -d '{"class_method": "async_stream_query", "input": {"user_id": "u", "message": "hi"}}'

كل سطر استجابة هو حدث ADK واحد بتنسيق JSON.

العمليات

يسجّل المحرك مجموعة العمليات الدقيقة التي تعلن عنها adk-python's AdkApp. وتُعيّن أزواج الأسماء المتزامنة/غير المتزامنة إلى المعالج نفسه — وهذا الانقسام أثر من آثار Python يحافظ عليه عقد الاتصال السلكي.

تعيد أساليب الفئة غير المعروفة 400 مع نصّ JSON للمشكلة. وتعيد أساليب الذاكرة خطأ Unsupported (501) إلى أن تتم تهيئة خدمة ذاكرة.

ملاحظة: إن reasoningEngines:asyncQuery (مهام الاستعلام الدائمة) غير مسجّل: يجب التصريح بالقدرة عند إنشاء المحرك، ولا يمكن إضافتها بعد الإنشاء، كما أن adk-python's AdkApp لا يسجّلها أيضًا.

الواجهات الخلفية المُدارة

يُبقي الإعداد الافتراضي، الذي لا يتطلب تهيئة، الجلسات في الذاكرة — وهو ما يكفي للإجابة عن الاستعلامات، لكن المحادثات لا تستمر بعد إعادة تشغيل الحاوية. وتُهيّئ المحركات المنشورة الواجهات الخلفية المُدارة من خلال AgentEngineOptions.

الجلسات المُدارة (Vertex AI Sessions)

مع ميزة vertex-session، يقرأ VertexAiSessionConfig::from_env() المتغيرات التي تضبطها المنصة داخل الحاويات المنشورة (GOOGLE_CLOUD_PROJECT وGOOGLE_CLOUD_LOCATION و GOOGLE_CLOUD_AGENT_ENGINE_ID — معرّف المحرك الرقمي المجرّد):

use adk_server::agent_engine::AgentEngineOptions;
use adk_session::{VertexAiSessionConfig, VertexAiSessionService};
use std::sync::Arc;

fn managed_sessions() -> adk_core::Result<AgentEngineOptions> {
    let config = VertexAiSessionConfig::from_env()?;
    let sessions = Arc::new(VertexAiSessionService::new_with_adc(config)?);
    Ok(AgentEngineOptions::new().with_session_service(sessions))
}

خارج حاوية منشورة، أنشئ التهيئة صراحةً باستخدام VertexAiSessionConfig::new(project, location).with_reasoning_engine(id).

العناصر (Google Cloud Storage)

مع ميزة gcs-artifacts، يخزّن GcsArtifactService العناصر في تنسيق الكائنات الذي تقرؤه وحدة تحكم Gemini Enterprise (بتطابق بايت-ل-بايت مع adk-python). خذ الحاوية من متغير بيئة أو من خيار:

use adk_artifact::GcsArtifactService;
use adk_server::agent_engine::AgentEngineOptions;
use std::sync::Arc;

fn gcs_artifacts() -> adk_core::Result<AgentEngineOptions> {
    let bucket = std::env::var("ADK_ARTIFACT_BUCKET").unwrap_or_else(|_| "my-bucket".to_string());
    let artifacts = Arc::new(GcsArtifactService::new_with_adc(bucket)?);
    Ok(AgentEngineOptions::new().with_artifact_service(artifacts))
}

وتُوصَل خدمة العناصر بكلٍّ من المشغّل (عمليات الحفظ والتحميل المواجهة للأدوات) وحالة التوزيع.

الذاكرة

يقبل AgentEngineOptions::with_memory_service أي adk_memory::MemoryService ويمكّن أسلوبي الفئة الخاصين بالذاكرة. وستصل الواجهة الخلفية Memory Bank الخاصة بالمنصة مع ميزة vertex-memory في إصدار لاحق.

تكامل ServerBuilder

يمكن لخادم ADK موجود أن يعرِض سطح التوزيع إلى جانب مساراته الخاصة بـ REST وواجهة المستخدم وA2A:

use adk_server::{ServerBuilder, ServerConfig};

fn build_app(config: ServerConfig) -> axum::Router {
    ServerBuilder::new(config).with_agent_engine(true).build()
}

تخدم مسارات التوجيه وكيل الجذر الخاص بـ loader مع خدمتي الجلسات والقطع الأثرية المُكوَّنتين. وهي لا تحمل middleware المصادقة الخاص بالخادم: إذ تكون engine المنشورة خلف منصة تتولى مصادقة المستدعين قبل وصولهم إلى الحاوية. لا تكشف نقاط النهاية هذه مباشرةً للشبكات غير الموثوقة.

النشر من CLI

مع تثبيت adk-cli باستخدام ميزة gcp-deploy (cargo install adk-cli --features gcp-deploy)، ينشئ أمر واحد engine من صورة حاوية مُدفعة:

# 1. Build and push the image
gcloud builds submit --tag us-central1-docker.pkg.dev/PROJECT/agents/my-agent:latest

# 2. Deploy it as a ReasoningEngine
adk-rust deploy agent-engine \
  --image-uri us-central1-docker.pkg.dev/PROJECT/agents/my-agent:latest \
  --project PROJECT \
  --location us-central1 \
  --service-account agent-runner@PROJECT.iam.gserviceaccount.com

الخيارات الاختيارية: --display-name (تكون افتراضيًا اسم الصورة) و --kms-key لـ CMEK. يصرّح الأمر بعقدة الفئة-الطريقة الكاملة من جدول العمليات، وينتظر عملية الإنشاء، ثم يطبع اسم مورد engine. يتوفر العميل نفسه برمجيًا باسم adk_deploy::gcp::GcpDeployClient (الميزة الجامعة gcp-deploy).

متغيرات البيئة

عند وجود GOOGLE_CLOUD_AGENT_ENGINE_ID واستخدام خدمة الجلسات الافتراضية الموجودة في الذاكرة، يسجّل المدخل تحذيرًا: ينبغي للمحركات المنشورة استخدام جلسات مُدارة.