Server-API

Der ADK-Rust Server bietet eine REST-API zum Ausführen von Agents, Verwalten von Sessions und Zugreifen auf Artefakte. Wenn Sie Ihren Agent mit dem Launcher im Servermodus bereitstellen, werden diese Endpunkte zusammen mit einer Web-UI verfügbar gemacht.

Übersicht

Der Server basiert auf Axum und bietet:

REST-API: HTTP-Endpunkte für die Agent-Ausführung und Session-Verwaltung
Server-Sent Events (SSE): Echtzeit-Streaming von Agent-Antworten
Web-UI: Interaktive browserbasierte Oberfläche
CORS-Unterstützung: Cross-Origin-Anfragen aktiviert
Telemetrie: Integrierte Beobachtbarkeit mit Tracing

ServerConfig bietet auch einen Runner-Level-Passthrough für langlebige Bereitstellungen:

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

Server starten

Verwenden Sie den Launcher, um den Server zu starten:

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
}

Starten Sie vom validierten API-Gerüst aus:

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

REST-API-Endpunkte

Zustandsprüfung

Überprüfen Sie, ob der Server läuft:

GET /api/health

Antwort:

OK

Agent mit Streaming ausführen

Führen Sie einen Agenten aus und streamen Sie Antworten mithilfe von Server-Sent Events:

POST /api/run_sse

Anfragetext:

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

Antwort:

Content-Type: text/event-stream
Streamt Ereignisse als JSON-Objekte

Ereignisformat:

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

Sitzungsverwaltung

Sitzung erstellen

Eine neue Sitzung erstellen:

POST /api/sessions

Anfragetext:

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

Antwort:

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

Sitzung abrufen

Sitzungsdetails abrufen:

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

Antwort:

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

Sitzung löschen

Eine Sitzung löschen:

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

Antwort:

Antwortstatus: 204 No Content

Sitzungen auflisten

Alle Sitzungen für einen Benutzer auflisten:

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

Antwort:

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

Artefaktverwaltung

Artefakte auflisten

Alle Artefakte für eine Sitzung auflisten:

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

Antwort:

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

Artefakt abrufen

Ein Artefakt herunterladen:

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

Antwort:

Content-Type: Bestimmt durch Dateierweiterung
Inhalt: Binärer oder Textinhalt

Anwendungsverwaltung

Anwendungen auflisten

Alle verfügbaren Agents auflisten:

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

Antwort:

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

Web-Benutzeroberfläche

Der Server enthält eine integrierte Web-Benutzeroberfläche, die unter folgender Adresse zugänglich ist:

http://localhost:8080/ui/

Funktionen

Interaktiver Chat: Nachrichten senden und Streaming-Antworten empfangen
Sitzungsverwaltung: Sitzungen erstellen, anzeigen und zwischen ihnen wechseln
Multi-Agent-Unterstützung: Agentenübertragungen und -hierarchien visualisieren
Artefakt-Viewer: Sitzungsartefakte anzeigen und herunterladen
Echtzeit-Updates: SSE-basiertes Streaming für sofortige Antworten

UI-Routen

/ - Leitet weiter zu /ui/
/ui/ - Haupt-Chat-Oberfläche
/ui/assets/* - Statische Assets (CSS, JS, Bilder)
/ui/assets/config/runtime-config.json - Laufzeitkonfiguration

Client-Beispiele

JavaScript/TypeScript

Verwendung der Fetch API mit 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

Verwendung der requests Bibliothek:

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

Serverkonfiguration

Benutzerdefinierter Port

Für einen benutzerdefinierten Port setzen Sie PORT, bevor Sie den generierten Server starten:

PORT=3000 cargo run

Benutzerdefinierter Artefakt-Dienst

Stellen Sie Ihren eigenen Artefakt-Dienst bereit:

use adk_artifact::InMemoryArtifactService;

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

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

Benutzerdefinierter Sitzungsdienst

Für Produktionsbereitstellungen verwenden Sie einen persistenten Sitzungsdienst:

use adk_session::SqliteSessionService;

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

Fehlerbehandlung

Die API verwendet strukturierte Fehlerantworten mit HTTP-Statuscodes, die von der Fehlerkategorie abgeleitet sind:

Statuscode	Kategorie	Bedeutung
200	—	Erfolg
204	—	Erfolg (Kein Inhalt)
400	`invalid_input`	Fehlerhafte Anfrage — ungültige Parameter oder Konfiguration
401	`unauthorized`	Fehlende oder ungültige Anmeldeinformationen
403	`forbidden`	Gültige Anmeldeinformationen, unzureichende Berechtigungen
404	`not_found`	Ressource nicht gefunden
408	`timeout`	Zeitüberschreitung des Vorgangs
429	`rate_limited`	Upstream-Ratenlimit überschritten
500	`internal`	Interner Serverfehler
501	`unsupported`	Funktion nicht unterstützt
503	`unavailable`	Upstream-Dienst nicht verfügbar

Fehlerantwortformat (Problem JSON):

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

Felder requestId, retryAfter und upstreamStatusCode sind enthalten, wenn verfügbar (ansonsten null).

CORS-Konfiguration

Der Server aktiviert standardmäßig eine permissive CORS-Konfiguration, die Anfragen von jeder Herkunft zulässt. Dies ist für die Entwicklung geeignet, sollte aber in der Produktion eingeschränkt werden.

Telemetrie

Der Server initialisiert die Telemetrie automatisch beim Start. Protokolle werden mit strukturierter Formatierung auf stdout ausgegeben.

Protokollstufen:

ERROR: Kritische Fehler
WARN: Warnungen
INFO: Allgemeine Informationen (Standard)
DEBUG: Detailliertes Debugging
TRACE: Sehr detailliertes Tracing

Legen Sie die Protokollstufe mit der Umgebungsvariable RUST_LOG fest:

RUST_LOG=debug cargo run

Bewährte Verfahren

Session Management: Erstellen Sie immer eine Session, bevor Sie einen Agent ausführen Fehlerbehandlung: Überprüfen Sie HTTP-Statuscodes und behandeln Sie Fehler entsprechend Streaming: Verwenden Sie SSE für Echtzeit-Antworten; parsen Sie Ereignisse Zeile für Zeile Sicherheit: Implementieren Sie in der Produktion Authentifizierung und beschränken Sie CORS Persistenz: Verwenden Sie SqliteSessionService oder PostgresSessionService für Produktionsbereitstellungen Monitoring: Aktivieren Sie Telemetrie und überwachen Sie Logs auf Probleme

Full-Stack Beispiel

Für ein vollständiges, funktionierendes Server-Gerüst verwenden Sie die validierte cargo-adk API template. Dies demonstriert:

Frontend: HTML/JavaScript client mit Echtzeit-Streaming
Backend: ADK agent mit benutzerdefinierten Forschungs- und PDF-Generierungstools
Integration: Vollständige REST API Nutzung mit SSE streaming
Artefakte: PDF-Generierung und -Download
Session Management: Automatische Session-Erstellung und -Handhabung

Das Beispiel zeigt ein produktionsreifes Muster zum Erstellen von KI-gestützten Webanwendungen mit ADK-Rust.

Schnellstart:

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

Dateien:

Backend: adk-rust-guide/examples/deployment/full_stack_research.rs
Frontend: examples/research_paper/frontend.html
Dokumentation: examples/research_paper/README.md
Architektur: examples/research_paper/architecture.md

Launcher - Server starten
Sessions - Session-Verwaltung
Artifacts - Artefakt-Speicherung
Observability - Telemetrie und Protokollierung

Zurück: ← Launcher | Weiter: A2A Protocol →

Server-API

Übersicht

Server starten

REST-API-Endpunkte

Zustandsprüfung

Agent mit Streaming ausführen

Sitzungsverwaltung

Sitzung erstellen

Sitzung abrufen

Sitzung löschen

Sitzungen auflisten

Artefaktverwaltung

Artefakte auflisten

Artefakt abrufen

Anwendungsverwaltung

Anwendungen auflisten

Web-Benutzeroberfläche

Funktionen

UI-Routen

Client-Beispiele

JavaScript/TypeScript

Python

cURL

Serverkonfiguration

Benutzerdefinierter Port

Benutzerdefinierter Artefakt-Dienst

Benutzerdefinierter Sitzungsdienst

Fehlerbehandlung

CORS-Konfiguration

Telemetrie

Bewährte Verfahren

Full-Stack Beispiel

Verwandt