Server-API

Der adk-rust-Server bietet eine REST API zum Ausführen von agents, Verwalten von sessions und Zugreifen auf artifacts. Wenn Sie Ihren agent mithilfe des Launcher im Servermodus bereitstellen, stellt er diese endpoints zusammen mit einer web UI bereit.

Übersicht

Der Server basiert auf Axum und bietet:

REST API: HTTP endpoints für agent-Ausführung und session-Verwaltung
Server-Sent Events (SSE): Echtzeit-Streaming von agent-Antworten
Web UI: Interaktive browserbasierte Benutzeroberfläche
CORS Support: Cross-origin-Anfragen aktiviert
Telemetry: Integrierte Observability mit tracing

Starten des Servers

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 den Server:

cargo run -- serve --port 8080

REST API Endpunkte

Gesundheitscheck

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

GET /api/health

Antwort:

OK

Agent mit Streaming ausführen

Führen Sie einen Agent aus und streamen Sie Antworten über Server-Sent Events:

POST /api/run_sse

Anfrage-Body:

{
  "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 Events als JSON-Objekte

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

Sitzungsverwaltung

Sitzung erstellen

Erstellen Sie eine neue Sitzung:

POST /api/sessions

Anfrage-Body:

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

Status: 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 die Dateierweiterung
Body: 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 wechseln
Multi-Agent-Unterstützung: Agentenübergaben und Hierarchien visualisieren
Artefakt-Viewer: Sitzungsartefakte anzeigen und herunterladen
Echtzeit-Updates: SSE-basiertes Streaming für sofortige Antworten

UI-Routen

/ - Leitet zu /ui/ weiter
/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

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

# Agent mit Streaming ausführen
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
  }'

Server-Konfiguration

Benutzerdefinierter Port

Einen benutzerdefinierten Port angeben:

cargo run -- serve --port 3000

Benutzerdefinierter Artifact Service

Einen eigenen artifact service bereitstellen:

use adk_artifact::InMemoryArtifactService;

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

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

Benutzerdefinierter Session Service

Für Produktionsbereitstellungen einen persistenten Session Service verwenden:

use adk_session::DatabaseSessionService;

// Hinweis: Dies erfordert die Implementierung eines benutzerdefinierten Server-Setups
// Der Launcher verwendet standardmäßig InMemorySessionService

Fehlerbehandlung

Die API verwendet standardmäßige HTTP-Statuscodes:

Statuscode	Bedeutung
200	Erfolg
204	Erfolg (Kein Inhalt)
400	Fehlerhafte Anfrage
404	Nicht gefunden
500	Interner Serverfehler

Fehlerantwortformat:

{
  "error": "Error message description"
}

CORS-Konfiguration

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

Telemetrie

Der Server initialisiert die Telemetrie beim Start automatisch. 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

Die Protokollstufe mit der Umgebungsvariablen RUST_LOG festlegen:

RUST_LOG=debug cargo run -- serve

Bewährte Methoden

Sitzungsverwaltung: 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 zeilenweise
Sicherheit: Implementieren Sie in der Produktion Authentifizierung und beschränken Sie CORS
Persistenz: Verwenden Sie DatabaseSessionService für Produktionsbereitstellungen
Überwachung: Aktivieren Sie Telemetrie und überwachen Sie Logs auf Probleme

Full-Stack Beispiel

Für ein vollständiges, funktionierendes Beispiel einer Frontend-Anwendung, die mit einem ADK-Backend interagiert, siehe das Beispiel Research Paper Generator. Dies demonstriert:

Frontend: HTML/JavaScript Client mit Echtzeit-Streaming
Backend: ADK Agent mit benutzerdefinierten Research- und PDF-Generierungs-Tools
Integration: Vollständige REST API-Nutzung mit SSE-Streaming
Artifacts: PDF-Generierung und -Download
Sitzungsverwaltung: Automatische Erstellung und Handhabung von Sessions

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

Schnellstart:

# 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

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

Verwandt

Launcher - Starten des Servers
Sessions - Sitzungsverwaltung
Artifacts - Speicherung von Artifacts
Observability - Telemetrie und Logging

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