सर्वर API

adk-rust सर्वर agents चलाने, sessions प्रबंधित करने और artifacts तक पहुँचने के लिए एक REST API प्रदान करता है। जब आप Launcher का उपयोग करके अपने agent को server mode में डिप्लॉय करते हैं, तो यह इन endpoints को एक web UI के साथ expose करता है।

अवलोकन

सर्वर Axum पर आधारित है और प्रदान करता है:

REST API: agent execution और session management के लिए HTTP endpoints
Server-Sent Events (SSE): agent responses की रीयल-टाइम स्ट्रीमिंग
Web UI: इंटरेक्टिव ब्राउज़र-आधारित इंटरफ़ेस
CORS Support: Cross-origin requests सक्षम
Telemetry: tracing के साथ बिल्ट-इन observability

सर्वर शुरू करना

सर्वर शुरू करने के लिए 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 एंडपॉइंट्स

स्वास्थ्य जांच

जांचें कि सर्वर चल रहा है या नहीं:

GET /api/health

प्रतिक्रिया:

OK

स्ट्रीमिंग के साथ Agent चलाएं

एक Agent चलाएं और Server-Sent Events का उपयोग करके प्रतिक्रियाओं को स्ट्रीम करें:

POST /api/run_sse

अनुरोध बॉडी:

{
  "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 ऑब्जेक्ट के रूप में स्ट्रीम करता है

इवेंट प्रारूप:

{
  "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."
        }
      ]
    }
  }
}

सेशन प्रबंधन

सेशन बनाएं

एक नया सेशन बनाएं:

POST /api/sessions

अनुरोध बॉडी:

{
  "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": {}
  }
]

आर्टिफैक्ट प्रबंधन

आर्टिफैक्ट्स सूचीबद्ध करें

एक सेशन के लिए सभी आर्टिफैक्ट्स सूचीबद्ध करें:

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: फ़ाइल एक्सटेंशन द्वारा निर्धारित
बॉडी: बाइनरी या टेक्स्ट कंटेंट

एप्लीकेशन प्रबंधन

एप्लीकेशन सूचीबद्ध करें

सभी उपलब्ध Agents सूचीबद्ध करें:

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

प्रतिक्रिया:

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

वेब UI

सर्वर में एक अंतर्निहित वेब UI शामिल है, जो यहां पहुंच योग्य है:

http://localhost:8080/ui/

विशेषताएं

इंटरैक्टिव चैट: संदेश भेजें और स्ट्रीमिंग प्रतिक्रियाएं प्राप्त करें
सेशन प्रबंधन: सेशन बनाएं, देखें और उनके बीच स्विच करें
मल्टी-एजेंट सपोर्ट: Agent स्थानांतरण और पदानुक्रम को विज़ुअलाइज़ करें
आर्टिफैक्ट दर्शक: सेशन आर्टिफैक्ट्स देखें और डाउनलोड करें
रीयल-टाइम अपडेट: तत्काल प्रतिक्रियाओं के लिए SSE-आधारित स्ट्रीमिंग

UI रूट्स

/ - /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 Service

अपनी स्वयं की Artifact Service प्रदान करें:

use adk_artifact::InMemoryArtifactService;

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

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

कस्टम Session Service

प्रोडक्शन डिप्लॉयमेंट के लिए, एक परसिस्टेंट Session Service का उपयोग करें:

use adk_session::DatabaseSessionService;

// नोट: इसके लिए एक कस्टम सर्वर सेटअप को लागू करने की आवश्यकता है
// Launcher डिफ़ॉल्ट रूप से InMemorySessionService का उपयोग करता है

त्रुटि प्रबंधन

API मानक HTTP स्टेटस कोड का उपयोग करती है:

स्टेटस कोड	अर्थ
200	सफलता
204	सफलता (कोई सामग्री नहीं)
400	खराब अनुरोध
404	नहीं मिला
500	आंतरिक सर्वर त्रुटि

त्रुटि प्रतिक्रिया प्रारूप:

{
  "error": "Error message description"
}

CORS कॉन्फ़िगरेशन

सर्वर डिफ़ॉल्ट रूप से परमिटिव CORS को सक्षम करता है, जो किसी भी ओरिजिन से अनुरोधों की अनुमति देता है। यह डेवलपमेंट के लिए उपयुक्त है लेकिन प्रोडक्शन में प्रतिबंधित होना चाहिए।

टेलीमेट्री

सर्वर शुरू होने पर स्वचालित रूप से टेलीमेट्री इनिशियलाइज़ करता है। लॉग संरचित फॉर्मेटिंग के साथ stdout पर आउटपुट होते हैं।

लॉग स्तर:

ERROR: गंभीर त्रुटियाँ
WARN: चेतावनियाँ
INFO: सामान्य जानकारी (डिफ़ॉल्ट)
DEBUG: विस्तृत डीबगिंग
TRACE: बहुत विस्तृत ट्रेसिंग

RUST_LOG एनवायरनमेंट वेरिएबल के साथ लॉग स्तर सेट करें:

RUST_LOG=debug cargo run -- serve

सर्वोत्तम अभ्यास

Session Management: एजेंट चलाने से पहले हमेशा एक session बनाएं
Error Handling: HTTP स्थिति कोड जांचें और त्रुटियों को उचित रूप से संभालें
Streaming: रीयल-टाइम प्रतिक्रियाओं के लिए SSE का उपयोग करें; घटनाओं को पंक्ति-दर-पंक्ति पार्स करें
Security: उत्पादन में, प्रमाणीकरण लागू करें और CORS को प्रतिबंधित करें
Persistence: उत्पादन डिप्लॉयमेंट के लिए DatabaseSessionService का उपयोग करें
Monitoring: telemetry सक्षम करें और समस्याओं के लिए लॉग की निगरानी करें

फुल-स्टैक उदाहरण

ADK बैकएंड के साथ इंटरैक्ट करने वाले फ्रंटएंड एप्लिकेशन के पूर्ण कार्यशील उदाहरण के लिए, Research Paper Generator उदाहरण देखें। यह दर्शाता है:

Frontend: रीयल-टाइम स्ट्रीमिंग के साथ HTML/JavaScript क्लाइंट
Backend: कस्टम रिसर्च और PDF जनरेशन tools के साथ ADK agent
Integration: SSE स्ट्रीमिंग के साथ पूर्ण REST API उपयोग
Artifacts: PDF जनरेशन और डाउनलोड
Session Management: स्वचालित session निर्माण और हैंडलिंग

यह उदाहरण ADK-Rust के साथ AI-संचालित वेब एप्लिकेशन बनाने के लिए एक उत्पादन-तैयार पैटर्न दिखाता है।

त्वरित शुरुआत:

# 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

सर्वर API

अवलोकन

सर्वर शुरू करना

REST API एंडपॉइंट्स

स्वास्थ्य जांच

स्ट्रीमिंग के साथ Agent चलाएं

सेशन प्रबंधन

सेशन बनाएं

सेशन प्राप्त करें

सेशन हटाएं

सेशन सूचीबद्ध करें

आर्टिफैक्ट प्रबंधन

आर्टिफैक्ट्स सूचीबद्ध करें

आर्टिफैक्ट प्राप्त करें

एप्लीकेशन प्रबंधन

एप्लीकेशन सूचीबद्ध करें

वेब UI

विशेषताएं

UI रूट्स

क्लाइंट उदाहरण

JavaScript/TypeScript

Python

cURL

सर्वर कॉन्फ़िगरेशन

कस्टम पोर्ट

कस्टम Artifact Service

कस्टम Session Service

त्रुटि प्रबंधन

CORS कॉन्फ़िगरेशन

टेलीमेट्री

सर्वोत्तम अभ्यास

फुल-स्टैक उदाहरण

संबंधित