सर्वर API

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

अवलोकन

सर्वर 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

ServerConfig लंबे समय तक चलने वाले deployments के लिए runner-level passthrough भी उजागर करता है:

let config = ServerConfig::new(agent_loader, session_service)
    .with_compaction(compaction_config)
    .with_context_cache(context_cache_config, cache_capable_model);

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

सर्वर शुरू करने के लिए 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
}

मान्य API scaffold से शुरू करें:

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

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

हेल्थ चेक

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

GET /api/health

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

OK

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

एक agent को execute करें और Server-Sent Events का उपयोग करके responses को स्ट्रीम करें:

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 objects के रूप में events को स्ट्रीम करता है

इवेंट फॉर्मेट:

{
  "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 बनाएँ:

POST /api/sessions

अनुरोध बॉडी:

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

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

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

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

session विवरण प्राप्त करें:

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

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

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

सेशन हटाएँ

एक session हटाएँ:

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

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

स्थिति: 204 No Content

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

एक उपयोगकर्ता के लिए सभी sessions सूचीबद्ध करें:

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

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

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

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

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

एक session के लिए सभी artifacts सूचीबद्ध करें:

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

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

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

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

एक artifact डाउनलोड करें:

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/

विशेषताएँ

इंटरैक्टिव चैट: संदेश भेजें और स्ट्रीमिंग responses प्राप्त करें
सेशन प्रबंधन: sessions बनाएँ, देखें और उनके बीच स्विच करें
मल्टी-एजेंट सपोर्ट: agent transfers और hierarchies को विज़ुअलाइज़ करें
आर्टिफैक्ट व्यूअर: session artifacts देखें और डाउनलोड करें
रीयल-टाइम अपडेट: तत्काल responses के लिए SSE-आधारित स्ट्रीमिंग

UI रूट्स

/ - /ui/ पर रीडायरेक्ट करता है
/ui/ - मुख्य चैट इंटरफ़ेस
/ui/assets/* - स्टैटिक एसेट्स (CSS, JS, images)
/ui/assets/config/runtime-config.json - रनटाइम कॉन्फ़िगरेशन

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

JavaScript/TypeScript

SSE के साथ Fetch API का उपयोग करना:

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
  }'

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

कस्टम पोर्ट

एक कस्टम पोर्ट के लिए, जेनरेटेड सर्वर शुरू करने से पहले PORT सेट करें:

PORT=3000 cargo run

कस्टम आर्टिफैक्ट सर्विस

अपनी खुद की 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

कस्टम सेशन सर्विस

प्रोडक्शन deployments के लिए, एक persistent session service का उपयोग करें:

use adk_session::SqliteSessionService;

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

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

API त्रुटि श्रेणी से प्राप्त HTTP स्टेटस कोड के साथ संरचित त्रुटि responses का उपयोग करता है:

स्टेटस कोड	श्रेणी	अर्थ
200	—	सफलता
204	—	सफलता (कोई सामग्री नहीं)
400	`invalid_input`	खराब अनुरोध — अमान्य पैरामीटर या कॉन्फ़िग
401	`unauthorized`	क्रेडेंशियल गुम या अमान्य हैं
403	`forbidden`	मान्य क्रेडेंशियल, अपर्याप्त अनुमतियाँ
404	`not_found`	संसाधन नहीं मिला
408	`timeout`	ऑपरेशन का समय समाप्त हो गया
429	`rate_limited`	अपस्ट्रीम दर सीमा पार हो गई
500	`internal`	आंतरिक सर्वर त्रुटि
501	`unsupported`	सुविधा समर्थित नहीं है
503	`unavailable`	अपस्ट्रीम सेवा अनुपलब्ध है

त्रुटि प्रतिक्रिया प्रारूप (समस्या JSON):

{
  "error": {
    "code": "model.openai.rate_limited",
    "message": "OpenAI rate limit exceeded",
    "component": "model",
    "category": "rate_limited",
    "requestId": "req-abc123",
    "retryAfter": 5000,
    "upstreamStatusCode": 429
  }
}

फ़ील्ड requestId, retryAfter, और upstreamStatusCode उपलब्ध होने पर शामिल किए जाते हैं (अन्यथा शून्य)।

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

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

टेलीमेट्री

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

लॉग स्तर:

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

RUST_LOG पर्यावरण चर के साथ लॉग स्तर सेट करें:

RUST_LOG=debug cargo run

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

Session प्रबंधन: हमेशा एक Agent चलाने से पहले एक Session बनाएँ
त्रुटि प्रबंधन: HTTP स्थिति कोड की जाँच करें और त्रुटियों को उचित रूप से संभालें
स्ट्रीमिंग: वास्तविक समय की प्रतिक्रियाओं के लिए SSE का उपयोग करें; घटनाओं को पंक्ति दर पंक्ति पार्स करें
सुरक्षा: उत्पादन में, प्रमाणीकरण लागू करें और CORS को प्रतिबंधित करें
दृढ़ता: उत्पादन परिनियोजन के लिए SqliteSessionService या PostgresSessionService का उपयोग करें
निगरानी: टेलीमेट्री सक्षम करें और समस्याओं के लिए लॉग की निगरानी करें

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

एक पूर्ण कार्यशील सर्वर स्केफोल्ड के लिए, मान्य cargo-adk API टेम्पलेट का उपयोग करें। यह प्रदर्शित करता है:

फ्रंटएंड: वास्तविक समय स्ट्रीमिंग के साथ HTML/JavaScript क्लाइंट
बैकएंड: कस्टम शोध और PDF जनरेशन Tool के साथ ADK Agent
एकीकरण: SSE स्ट्रीमिंग के साथ पूर्ण REST API उपयोग
कलाकृतियाँ: PDF जनरेशन और डाउनलोड
Session प्रबंधन: स्वचालित Session निर्माण और हैंडलिंग

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

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

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

फ़ाइलें:

बैकएंड: adk-rust-guide/examples/deployment/full_stack_research.rs
फ्रंटएंड: examples/research_paper/frontend.html
दस्तावेज़ीकरण: examples/research_paper/README.md
आर्किटेक्चर: examples/research_paper/architecture.md

लॉन्चर - सर्वर शुरू करना
Sessions - Session प्रबंधन
कलाकृतियाँ - कलाकृति भंडारण
अवलोकन क्षमता - टेलीमेट्री और लॉगिंग

पिछला: ← लॉन्चर | अगला: A2A प्रोटोकॉल →

सर्वर API

अवलोकन

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

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

हेल्थ चेक

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

सेशन प्रबंधन

सेशन बनाएँ

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

सेशन हटाएँ

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

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

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

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

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

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

वेब UI

विशेषताएँ

UI रूट्स

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

JavaScript/TypeScript

Python

cURL

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

कस्टम पोर्ट

कस्टम आर्टिफैक्ट सर्विस

कस्टम सेशन सर्विस

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

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

टेलीमेट्री

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

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

संबंधित