ADK-Rust

Server API

Der ADK-Rust-Server stellt eine REST API zum Ausführen von Agenten, Verwalten von Sitzungen und Zugreifen auf Artefakte bereit. Wenn Sie Ihren Agenten mithilfe des Launchers im Servermodus bereitstellen, stellt er diese Endpunkte zusammen mit einer Weboberfläche bereit.

Übersicht

Der Server basiert auf Axum und bietet:

  • REST API: HTTP-Endpunkte für die Ausführung von Agenten und die Sitzungsverwaltung
  • Server-Sent Events (SSE): Echtzeit-Streaming von Agentenantworten
  • Weboberfläche: Interaktive browserbasierte Benutzeroberfläche
  • CORS-Unterstützung: Cross-Origin-Anfragen aktiviert
  • Telemetrie: Integrierte Beobachtbarkeit mit tracing

ServerConfig stellt außerdem eine Weiterleitung auf Runner-Ebene für langlebige Bereitstellungen bereit:

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

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

Starten Sie aus dem validierten API-Gerüst:

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

REST API-Endpunkte

Zustandsprüfung

Prüfen Sie, ob der Server ausgeführt wird:

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

Agent ausführen (ohne Streaming)

Führen Sie einen Agenten bis zum Abschluss aus und empfangen Sie alle Ereignisse in einer einzigen JSON-Antwort:

POST /api/run

Anfragetext: gleiche Struktur wie POST /api/run_sse (das Feld streaming wird ignoriert):

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

Antwort:

  • Content-Type: application/json
  • Ein JSON-Array mit jedem vom Lauf erzeugten Ereignis in der entsprechenden Reihenfolge und im selben Ereignisformat wie /api/run_sse

Dieser Endpunkt bildet die nicht streamende /run-Route von Google ADKs api_server nach.

Sitzungsverwaltung

Sitzung erstellen

Eine neue Sitzung erstellen:

POST /api/sessions

Anfragerumpf:

{
  "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: Wird durch die Dateierweiterung bestimmt
  • Body: Binärer oder Textinhalt

Anwendungsverwaltung

Anwendungen auflisten

Alle verfügbaren Agenten auflisten:

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

Antwort:

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

Weboberfläche

Der Server enthält eine integrierte Weboberfläche, die unter folgender Adresse erreichbar ist:

http://localhost:8080/ui/

Einen Agenten auffordern, eine animierte Teamübergabe verfolgen und Telemetriedaten in der eingebetteten Laufzeitoberfläche untersuchen

Der Schnellstart in fünf Minuten erstellt ein auf OpenAI basierendes Servergerüst und öffnet diese Oberfläche mit vier Befehlen. Die Aufzeichnung verwendet ein Team, um die aktive Topologiekante sichtbar zu machen; Blattagenten, Tools, Graphen, Workflows, Echtzeitagenten und Remote-Agenten verwenden dieselbe Oberfläche.

Funktionen

  • Interaktive Abläufe: Nachrichten und Anhänge senden und sicher gerendertes Markdown, Streaming-Text, Tool-Aufrufe, Fehler und Übergaben überprüfen
  • Sitzungsverwaltung: Sitzungen erstellen, anzeigen und zwischen ihnen wechseln
  • Portierbare Teamtopologie: Exakte Delegations-und-Rückgabe-Kanten von Kontrollübergaben unterscheiden, mit einer Animation im Stil von Studio Next für das aktive Mitglied und die eingehende Kante
  • Laufzeitinspektor: Geordnete Ereignisse, dedizierte Telemetrie-Spans, gemeinsamen Sitzungsstatus, konfigurierte Laufzeitdienste, A2A-Erkennung sowie Unterstützung des UI-/MCP-Apps-Protokolls überprüfen
  • Echtzeitwiedergabe: Echtzeit-Agenten erkennen, Transkriptänderungen zusammenführen und abgeschlossene PCM-Ausgabe als WAV-Audio abspielen
  • Artefakt-Viewer: Sitzungsartefakte anzeigen und herunterladen
  • Responsive Designs: Tastaturzugängliche System-, helle und dunkle Layouts ohne externe Assets

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
  • /api/ui/agents/{name} – Agentenfähigkeiten, Hierarchie und Metadaten der portierbaren Topologie

Die Oberfläche wird in adk-server/webui gepflegt, und ihr Produktions-Build ist in den Server-Crate eingebettet. Dadurch verwenden generierte Projekte und Deployments dieselbe Laufzeitoberfläche ohne einen separaten Frontend-Dienst.

Die ausführbare Laufzeit-UI-Demonstration enthält separate, auf OpenAI basierende Anleitungen und Screenshots für einen Agenten mit Tool-Aufrufen, einen deterministischen Graph-Workflow und ein portables Übergabe-Team. Die Galerie für fortgeschrittene Agenten ergänzt einen Umgebungszeitplan, die OpenAI-Echtzeit-Sprachwiedergabe, die A2A-Erkennung, die MCP-Erkennung von 2026-07-28 mit SEP-2663-Aufgaben sowie konfigurierte Telemetrie-, Artefakt- und Speicherdienste in einem Server. Die Marke ADK Runtime verweist in einem neuen Tab auf adk-rust.com.

Client-Beispiele

JavaScript/TypeScript

Verwendung von 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 Bibliothek 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
  }'

Serverkonfiguration

Benutzerdefinierter Port

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

PORT=3000 cargo run

Benutzerdefinierter Artefaktdienst

Stellen Sie Ihren eigenen Artefaktdienst 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

Verwenden Sie für Produktivbereitstellungen einen persistenten Sitzungsdienst:

use adk_session::SqliteSessionService;

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

Fehlerbehandlung

API verwendet strukturierte Fehlerantworten mit HTTP-Statuscodes, die aus der Fehlerkategorie abgeleitet werden:

StatuscodeKategorieBedeutung
200—Erfolg
204—Erfolg (Kein Inhalt)
400invalid_inputFehlerhafte Anfrage — ungültige Parameter oder Konfiguration
401unauthorizedFehlende oder ungültige Anmeldedaten
403forbiddenGültige Anmeldedaten, unzureichende Berechtigungen
404not_foundRessource nicht gefunden
408timeoutZeitüberschreitung des Vorgangs
429rate_limitedRatenlimit des Upstream-Dienstes überschritten
500internalInterner Serverfehler
501unsupportedFunktion nicht unterstützt
503unavailableUpstream-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
  }
}

Die Felder requestId, retryAfter und upstreamStatusCode werden aufgenommen, sofern sie verfügbar sind (andernfalls null).

CORS Konfiguration

Der Server aktiviert standardmäßig eine freizügige CORS, 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 beim Start automatisch die Telemetrie. Protokolle werden mit strukturierter Formatierung nach stdout ausgegeben.

Protokollstufen:

  • ERROR: Kritische Fehler
  • WARN: Warnungen
  • INFO: Allgemeine Informationen (Standard)
  • DEBUG: Detaillierte Fehlersuche
  • TRACE: Sehr detaillierte Ablaufverfolgung

Legen Sie die Protokollstufe mit der Umgebungsvariablen RUST_LOG fest:

RUST_LOG=debug cargo run

Bewährte Vorgehensweisen

  1. Sitzungsverwaltung: Erstellen Sie immer eine Sitzung, bevor Sie einen Agenten ausführen
  2. Fehlerbehandlung: Überprüfen Sie die HTTP-Statuscodes und behandeln Sie Fehler angemessen
  3. Streaming: Verwenden Sie SSE für Echtzeitantworten; analysieren Sie Ereignisse zeilenweise
  4. Sicherheit: Implementieren Sie in der Produktion eine Authentifizierung und schränken Sie CORS ein
  5. Persistenz: Verwenden Sie SqliteSessionService oder PostgresSessionService für Produktionsbereitstellungen
  6. Überwachung: Aktivieren Sie die Telemetrie und überwachen Sie die Protokolle auf Probleme

Full-Stack-Beispiel

Verwenden Sie für ein vollständiges, funktionsfähiges Servergerüst die validierte cargo-adk-Vorlage API. Diese veranschaulicht:

  • Frontend: HTML/JavaScript-Client mit Echtzeit-Streaming
  • Backend: ADK-Agent mit benutzerdefinierten Recherche- und PDF-Generierungswerkzeugen
  • Integration: Vollständige Verwendung von REST API mit SSE-Streaming
  • Artefakte: PDF-Generierung und -Download
  • Sitzungsverwaltung: Automatische Sitzungserstellung und -verwaltung

Das Beispiel zeigt ein produktionsbereites Muster zum Erstellen KI-gestützter 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

Verwandte Themen

Zurück: ← Starter | Weiter: A2A Protokoll →

Server API - ADK-Rust Dokumentation | ADK-Rust