सर्वर API

ADK-Rust सर्वर एजेंट चलाने, सत्रों को प्रबंधित करने और आर्टिफैक्ट्स तक पहुँचने के लिए एक REST API प्रदान करता है। जब आप सर्वर मोड में Launcher का उपयोग करके अपने एजेंट को परिनियोजित करते हैं, तो यह वेब UI के साथ इन एंडपॉइंट्स को भी उपलब्ध कराता है।

अवलोकन

सर्वर Axum पर निर्मित है और यह सुविधाएँ प्रदान करता है:

REST API: एजेंट निष्पादन और सत्र प्रबंधन के लिए HTTP एंडपॉइंट्स
सर्वर-सेंट इवेंट्स (SSE): एजेंट प्रतिक्रियाओं की रीयल-टाइम स्ट्रीमिंग
वेब UI: ब्राउज़र-आधारित इंटरैक्टिव इंटरफ़ेस
CORS समर्थन: क्रॉस-ऑरिजिन अनुरोध सक्षम
टेलीमेट्री: tracing के साथ अंतर्निहित अवलोकनीयता

ServerConfig लंबे समय तक चलने वाले परिनियोजनों के लिए रनर-स्तरीय पासथ्रू भी उपलब्ध कराता है:

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-3.7-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 स्कैफ़ोल्ड से शुरू करें:

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

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

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

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

GET /api/health

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

OK

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

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

एजेंट चलाना (स्ट्रीमिंग रहित)

एजेंट को पूरा होने तक चलाएँ और सभी इवेंट्स को एकल JSON प्रतिक्रिया में प्राप्त करें:

POST /api/run

अनुरोध बॉडी: POST /api/run_sse के समान संरचना (streaming फ़ील्ड पर ध्यान नहीं दिया जाता):

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

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

Content-Type: application/json
एक JSON ऐरे, जिसमें रन द्वारा उत्पन्न प्रत्येक इवेंट क्रम से शामिल होता है और /api/run_sse के समान इवेंट प्रारूप का उपयोग करता है

यह एंडपॉइंट Google ADK के api_server स्ट्रीमिंग-रहित /run रूट का अनुकरण करता है।

सत्र प्रबंधन

सत्र बनाना

एक नया सत्र बनाएँ:

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

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

सामग्री-प्रकार: फ़ाइल एक्सटेंशन द्वारा निर्धारित
मुख्य भाग: बाइनरी या टेक्स्ट सामग्री

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

एप्लिकेशन की सूची बनाएँ

सभी उपलब्ध एजेंट की सूची बनाएँ:

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

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

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

वेब UI

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

http://localhost:8080/ui/

किसी एजेंट को प्रॉम्प्ट करना, एनिमेटेड टीम हैंडऑफ़ का अनुसरण करना, और एम्बेडेड रनटाइम UI में टेलीमेट्री का निरीक्षण करना

पाँच मिनट का क्विकस्टार्ट OpenAI-समर्थित सर्वर का ढाँचा तैयार करता है और चार कमांड के साथ यह इंटरफ़ेस खोलता है। रिकॉर्डिंग में सक्रिय टोपोलॉजी एज को दृश्यमान बनाने के लिए एक टीम का उपयोग किया गया है; लीफ़ एजेंट, टूल, ग्राफ़, वर्कफ़्लो, रीयलटाइम एजेंट और रिमोट एजेंट इसी इंटरफ़ेस का उपयोग करते हैं।

सुविधाएँ

इंटरैक्टिव रन: संदेश और अटैचमेंट भेजें और सुरक्षित रूप से रेंडर किए गए Markdown, स्ट्रीमिंग टेक्स्ट, टूल कॉल, विफलताओं और हैंडऑफ़ का निरीक्षण करें
सेशन प्रबंधन: सेशन बनाएँ, देखें और उनके बीच स्विच करें
पोर्टेबल टीम टोपोलॉजी: सटीक डेलिगेशन-और-वापसी एज को कंट्रोल हैंडऑफ़ से अलग पहचानें, जिसमें सक्रिय सदस्य और आने वाले एज के लिए Studio Next-शैली का एनीमेशन हो
रनटाइम इंस्पेक्टर: क्रमबद्ध इवेंट, समर्पित टेलीमेट्री स्पैन, साझा/सेशन स्थिति, कॉन्फ़िगर की गई रनटाइम सेवाएँ, A2A डिस्कवरी और UI/MCP Apps प्रोटोकॉल समर्थन का निरीक्षण करें
रीयलटाइम प्लेबैक: रीयलटाइम एजेंट को पहचानें, ट्रांसक्रिप्ट डेल्टा को मर्ज करें और पूर्ण PCM आउटपुट को WAV ऑडियो के रूप में चलाएँ
आर्टिफैक्ट व्यूअर: सेशन आर्टिफैक्ट देखें और डाउनलोड करें
रेस्पॉन्सिव थीम: बिना किसी बाहरी एसेट के कीबोर्ड-सुलभ सिस्टम, लाइट और डार्क लेआउट

UI रूट

/ - /ui/ पर रीडायरेक्ट करता है
/ui/ - मुख्य चैट इंटरफ़ेस
/ui/assets/* - स्थिर एसेट (CSS, JS, इमेज)
/ui/assets/config/runtime-config.json - रनटाइम कॉन्फ़िगरेशन
/api/ui/agents/{name} - एजेंट क्षमताएँ, पदानुक्रम और पोर्टेबल टोपोलॉजी मेटाडेटा

इंटरफ़ेस का रखरखाव adk-server/webui में किया जाता है और इसका प्रोडक्शन बिल्ड सर्वर क्रेट में एम्बेड किया गया है, इसलिए जनरेट किए गए प्रोजेक्ट और डिप्लॉयमेंट एक अलग फ्रंटएंड सेवा के बिना समान रनटाइम UI का उपयोग करते हैं।

चलने योग्य रनटाइम UI प्रदर्शन में टूल-कॉलिंग एजेंट, निर्धारक ग्राफ़ वर्कफ़्लो और पोर्टेबल हैंडऑफ़ टीम के लिए अलग-अलग OpenAI-समर्थित वॉकथ्रू और स्क्रीनशॉट शामिल हैं। उन्नत एजेंट गैलरी में एक एम्बिएंट शेड्यूल, OpenAI रीयलटाइम वॉइस प्लेबैक, A2A डिस्कवरी, SEP-2663 टास्क के साथ MCP 2026-07-28 डिस्कवरी, और एक ही सर्वर में कॉन्फ़िगर की गई टेलीमेट्री, आर्टिफ़ैक्ट और मेमोरी सेवाएँ शामिल हैं। ADK Runtime ब्रांड एक नए टैब में adk-rust.com से लिंक होता है।

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

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

कस्टम आर्टिफ़ैक्ट सेवा

अपनी स्वयं की आर्टिफ़ैक्ट सेवा प्रदान करें:

use adk_artifact::InMemoryArtifactService;

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

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

कस्टम सेशन सेवा

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

use adk_session::SqliteSessionService;

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

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

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

स्थिति कोड	श्रेणी	अर्थ
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 उपलब्ध होने पर शामिल किए जाते हैं (अन्यथा null)।

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

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

टेलीमेट्री

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

लॉग स्तर:

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

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

RUST_LOG=debug cargo run

सर्वोत्तम प्रक्रियाएँ

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

पूर्ण-स्टैक उदाहरण

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

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

यह उदाहरण 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

Launcher - सर्वर शुरू करना
Sessions - सत्र प्रबंधन
Artifacts - आर्टिफ़ैक्ट संग्रहण
Observability - टेलीमेट्री और लॉगिंग

पिछला: ← Launcher | अगला: A2A Protocol →

सर्वर API

अवलोकन

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

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

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

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

एजेंट चलाना (स्ट्रीमिंग रहित)

सत्र प्रबंधन

सत्र बनाना

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

सत्र हटाएँ

सत्रों की सूची बनाएँ

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

आर्टिफैक्ट की सूची बनाएँ

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

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

एप्लिकेशन की सूची बनाएँ

वेब UI

सुविधाएँ

UI रूट

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

JavaScript/TypeScript

Python

cURL

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

कस्टम पोर्ट

कस्टम आर्टिफ़ैक्ट सेवा

कस्टम सेशन सेवा

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

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

टेलीमेट्री

सर्वोत्तम प्रक्रियाएँ

पूर्ण-स्टैक उदाहरण

संबंधित