واجهة برمجة تطبيقات الخادم

يوفر خادم ADK-Rust واجهة REST API لتشغيل agents، وإدارة sessions، والوصول إلى artifacts. عند نشر agent الخاص بك باستخدام Launcher في وضع الخادم، فإنه يكشف عن نقاط النهاية هذه بالإضافة إلى واجهة مستخدم الويب.

نظرة عامة

الخادم مبني على Axum ويوفر:

• REST API: نقاط نهاية HTTP لتنفيذ agent وإدارة session
• Server-Sent Events (SSE): تدفق استجابات agent في الوقت الفعلي
• Web UI: واجهة تفاعلية تعتمد على المتصفح
• CORS Support: تمكين طلبات عبر النطاقات
• Telemetry: قابلية ملاحظة مدمجة مع التتبع

بدء تشغيل الخادم

استخدم Launcher لبدء تشغيل الخادم:

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()?;
    
    Launcher::new(Arc::new(agent)).run().await
}

ابدأ تشغيل الخادم:

cargo run -- serve --port 8080

نقاط نهاية REST API

فحص السلامة (Health Check)

تحقق مما إذا كان الخادم قيد التشغيل:

GET /api/health

الاستجابة:

OK

تشغيل Agent مع البث (Streaming)

نفذ Agent وقم ببث الاستجابات باستخدام أحداث مرسلة من الخادم (Server-Sent Events):

POST /api/run_sse

نص الطلب (Request Body):

{
  "appName": "my_agent",
  "userId": "user123",
  "sessionId": "session456",
  "newMessage": {
    "role": "user",
    "parts": [
      {
        "text": "What is the capital of France?"
      }
    ]
  },
  "streaming": true
}

الاستجابة:

• Content-Type: text/event-stream
• تبث الأحداث ككائنات JSON

تنسيق الحدث (Event Format):

{
  "id": "evt_123",
  "timestamp": 1234567890,
  "author": "my_agent",
  "content": {
    "role": "model",
    "parts": [
      {
        "text": "The capital of France is Paris."
      }
    ]
  },
  "actions": {},
  "llm_response": {
    "content": {
      "role": "model",
      "parts": [
        {
          "text": "The capital of France is Paris."
        }
      ]
    }
  }
}

إدارة الجلسات (Session Management)

إنشاء جلسة

أنشئ جلسة جديدة:

POST /api/sessions

نص الطلب (Request Body):

{
  "appName": "my_agent",
  "userId": "user123",
  "sessionId": "session456"
}

الاستجابة:

{
  "id": "session456",
  "appName": "my_agent",
  "userId": "user123",
  "lastUpdateTime": 1234567890,
  "events": [],
  "state": {}
}

الحصول على جلسة

استرد تفاصيل الجلسة:

GET /api/sessions/:app_name/:user_id/:session_id

الاستجابة:

{
  "id": "session456",
  "appName": "my_agent",
  "userId": "user123",
  "lastUpdateTime": 1234567890,
  "events": [],
  "state": {}
}

حذف جلسة

احذف جلسة:

DELETE /api/sessions/:app_name/:user_id/:session_id

الاستجابة:

• الحالة: 204 No Content

سرد الجلسات

اسرد جميع الجلسات لمستخدم:

GET /api/apps/:app_name/users/:user_id/sessions

الاستجابة:

[
  {
    "id": "session456",
    "appName": "my_agent",
    "userId": "user123",
    "lastUpdateTime": 1234567890,
    "events": [],
    "state": {}
  }
]

إدارة المرفقات (Artifact Management)

سرد المرفقات

اسرد جميع المرفقات لجلسة:

GET /api/sessions/:app_name/:user_id/:session_id/artifacts

الاستجابة:

[
  "image1.png",
  "document.pdf",
  "data.json"
]

الحصول على مرفق

حمّل مرفقًا:

GET /api/sessions/:app_name/:user_id/:session_id/artifacts/:artifact_name

الاستجابة:

• Content-Type: يتم تحديده بواسطة امتداد الملف
• النص الأساسي: محتوى ثنائي أو نصي

إدارة التطبيقات (Application Management)

سرد التطبيقات

اسرد جميع الـ Agents المتاحة:

GET /api/apps
GET /api/list-apps  (legacy compatibility)

الاستجابة:

{
  "apps": [
    {
      "name": "my_agent",
      "description": "A helpful assistant"
    }
  ]
}

واجهة المستخدم الويب (Web UI)

يتضمن الخادم واجهة مستخدم ويب مدمجة يمكن الوصول إليها على:

http://localhost:8080/ui/

الميزات

• دردشة تفاعلية: أرسل الرسائل واستقبل الاستجابات المتدفقة
• إدارة الجلسات: أنشئ الجلسات واعرضها وتنقل بينها
• دعم متعدد الـ Agent: تصور عمليات نقل الـ Agent والتسلسلات الهرمية
• عارض المرفقات: اعرض وقم بتنزيل مرفقات الجلسة
• تحديثات في الوقت الفعلي: بث قائم على SSE للاستجابات الفورية

مسارات واجهة المستخدم (UI Routes)

• / - يعيد التوجيه إلى /ui/
• /ui/ - واجهة الدردشة الرئيسية
• /ui/assets/* - الأصول الثابتة (CSS، JS، الصور)
• /ui/assets/config/runtime-config.json - تهيئة وقت التشغيل

أمثلة العميل

JavaScript/TypeScript

استخدام Fetch API مع SSE:

async function runAgent(message) {
  const response = await fetch('http://localhost:8080/api/run_sse', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      appName: 'my_agent',
      userId: 'user123',
      sessionId: 'session456',
      newMessage: {
        role: 'user',
        parts: [{ text: message }]
      },
      streaming: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');
    
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const event = JSON.parse(line.slice(6));
        console.log('Event:', event);
      }
    }
  }
}

Python

استخدام مكتبة requests:

import requests
import json

def run_agent(message):
    url = 'http://localhost:8080/api/run_sse'
    payload = {
        'appName': 'my_agent',
        'userId': 'user123',
        'sessionId': 'session456',
        'newMessage': {
            'role': 'user',
            'parts': [{'text': message}]
        },
        'streaming': True
    }
    
    response = requests.post(url, json=payload, stream=True)
    
    for line in response.iter_lines():
        if line:
            line_str = line.decode('utf-8')
            if line_str.startswith('data: '):
                event = json.loads(line_str[6:])
                print('Event:', event)

run_agent('What is the capital of France?')

cURL

# Create session
curl -X POST http://localhost:8080/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my_agent",
    "userId": "user123",
    "sessionId": "session456"
  }'

# Run agent with streaming
curl -X POST http://localhost:8080/api/run_sse \
  -H "Content-Type: application/json" \
  -d '{
    "appName": "my_agent",
    "userId": "user123",
    "sessionId": "session456",
    "newMessage": {
      "role": "user",
      "parts": [{"text": "What is the capital of France?"}]
    },
    "streaming": true
  }'

تكوين الخادم

منفذ مخصص

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

cargo run -- serve --port 3000

خدمة 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

خدمة Session مخصصة

لعمليات النشر في بيئة الإنتاج، استخدم خدمة Session مستمرة:

use adk_session::DatabaseSessionService;

// Note: This requires implementing a custom server setup
// The Launcher uses InMemorySessionService by default

معالجة الأخطاء

تستخدم واجهة برمجة التطبيقات (API) رموز حالة HTTP القياسية:

تنسيق استجابة الخطأ:

{
  "error": "Error message description"
}

تكوين CORS

يقوم الخادم بتمكين CORS المتساهل افتراضيًا، مما يسمح بالطلبات من أي مصدر. هذا مناسب للتطوير ولكن يجب تقييده في بيئة الإنتاج.

القياس عن بعد (Telemetry)

يقوم الخادم بتهيئة القياس عن بعد تلقائيًا عند بدء التشغيل. يتم إخراج السجلات إلى stdout بتنسيق منظم.

مستويات السجل:

• ERROR: أخطاء حرجة
• WARN: تحذيرات
• INFO: معلومات عامة (افتراضي)
• DEBUG: تصحيح أخطاء مفصل
• TRACE: تتبع مفصل للغاية

قم بتعيين مستوى السجل باستخدام متغير البيئة RUST_LOG:

RUST_LOG=debug cargo run -- serve

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

1. إدارة Session: قم دائمًا بإنشاء Session قبل تشغيل agent
2. معالجة الأخطاء: تحقق من رموز حالة HTTP وتعامل مع الأخطاء بشكل مناسب
3. التدفق (Streaming): استخدم SSE للاستجابات في الوقت الفعلي؛ قم بتحليل الأحداث سطرًا بسطر
4. الأمان: في بيئات الإنتاج، قم بتطبيق المصادقة وتقييد CORS
5. المثابرة: استخدم DatabaseSessionService لعمليات النشر في بيئات الإنتاج
6. المراقبة: قم بتمكين telemetry وراقب السجلات بحثًا عن المشكلات

مثال متكامل (Full-Stack)

للاطلاع على مثال عملي كامل لتطبيق واجهة أمامية يتفاعل مع ADK backend، راجع مثال مولد الأوراق البحثية (Research Paper Generator). يوضح هذا:

• الواجهة الأمامية (Frontend): عميل HTML/JavaScript مع تدفق في الوقت الفعلي
• الواجهة الخلفية (Backend): ADK agent مع أدوات مخصصة للبحث وتوليد PDF
• التكامل: استخدام كامل لـ REST API مع تدفق SSE
• Artifacts: توليد PDF وتنزيله
• إدارة Session: إنشاء Session ومعالجتها تلقائيًا

يوضح المثال نمطًا جاهزًا للإنتاج لبناء تطبيقات الويب المدعومة بالذكاء الاصطناعي باستخدام adk-rust.

بدء سريع:

# Start the server
cargo run --example full_stack_research -p adk-rust-guide -- serve --port 8080

# Open the frontend
open examples/research_paper/frontend.html

الملفات:

• Backend: adk-rust-guide/examples/deployment/full_stack_research.rs
• Frontend: examples/research_paper/frontend.html
• Documentation: examples/research_paper/README.md
• Architecture: examples/research_paper/architecture.md

ذو صلة

• Launcher - بدء الخادم
• Sessions - إدارة Session
• Artifacts - تخزين Artifacts
• Observability - telemetry والتسجيل

---

السابق: ← Launcher | التالي: A2A Protocol →