API du serveur

Le serveur ADK-Rust fournit une API REST pour exécuter des agents, gérer des sessions et accéder aux artefacts. Lorsque vous déployez votre agent en utilisant le Launcher en mode serveur, il expose ces points de terminaison ainsi qu'une interface utilisateur web.

Vue d'ensemble

Le serveur est bâti sur Axum et fournit :

API REST : Points de terminaison HTTP pour l'exécution d'agents et la gestion des sessions
Événements Envoyés par le Serveur (SSE) : Diffusion en temps réel des réponses d'agents
Interface utilisateur web : Interface interactive basée sur navigateur
Prise en charge de CORS : Requêtes cross-origin activées
Télémétrie : Observabilité intégrée avec traçage

Démarrage du serveur

Utilisez le Launcher pour démarrer le serveur :

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
}

Démarrez le serveur :

cargo run -- serve --port 8080

Points d'accès de l'API REST

Vérification de l'état de santé

Vérifie si le serveur est en cours d'exécution :

GET /api/health

Réponse :

OK

Exécuter l'Agent avec Streaming

Exécute un Agent et diffuse les réponses en utilisant les Server-Sent Events :

POST /api/run_sse

Corps de la requête :

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

Réponse :

Content-Type: text/event-stream
Diffuse les événements sous forme d'objets JSON

Format de l'événement :

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

Gestion de Session

Créer une Session

Crée une nouvelle Session :

POST /api/sessions

Corps de la requête :

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

Réponse :

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

Obtenir une Session

Récupère les détails de la Session :

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

Réponse :

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

Supprimer une Session

Supprime une Session :

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

Réponse :

Statut : 204 No Content

Lister les Sessions

Liste toutes les Sessions pour un utilisateur :

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

Réponse :

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

Gestion des Artefacts

Lister les Artefacts

Liste tous les Artefacts pour une Session :

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

Réponse :

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

Obtenir un Artefact

Télécharger un Artefact :

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

Réponse :

Content-Type : Déterminé par l'extension du fichier
Corps : Contenu binaire ou textuel

Gestion des Applications

Lister les Applications

Liste tous les Agents disponibles :

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

Réponse :

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

Interface utilisateur web

Le serveur inclut une interface utilisateur web intégrée, accessible à l'adresse :

http://localhost:8080/ui/

Fonctionnalités

Chat interactif : Envoyez des messages et recevez des réponses en streaming
Gestion de Session : Créez, consultez et basculez entre les Sessions
Support multi-Agent : Visualisez les transferts d'Agent et les hiérarchies
Visionneuse d'Artefacts : Affichez et téléchargez les Artefacts de Session
Mises à jour en temps réel : Streaming basé sur SSE pour des réponses instantanées

Routes de l'interface utilisateur

/ - Redirige vers /ui/
/ui/ - Interface de chat principale
/ui/assets/* - Assets statiques (CSS, JS, images)
/ui/assets/config/runtime-config.json - Configuration d'exécution

Exemples de Client

JavaScript/TypeScript

Utilisation de l'API Fetch avec 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

Utilisation de la bibliothèque 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
  }'

Configuration du Serveur

Port Personnalisé

Spécifier un port personnalisé :

cargo run -- serve --port 3000

Service d'Artéfact Personnalisé

Fournissez votre propre service d'artéfact :

use adk_artifact::InMemoryArtifactService;

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

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

Service de Session Personnalisé

Pour les déploiements en production, utilisez un service de session persistant :

use adk_session::DatabaseSessionService;

// Remarque : Cela nécessite l'implémentation d'une configuration de serveur personnalisée
// Le Launcher utilise InMemorySessionService par défaut

Gestion des Erreurs

L'API utilise des codes de statut HTTP standard :

Code de Statut	Signification
200	Succès
204	Succès (Pas de Contenu)
400	Mauvaise Requête
404	Non Trouvé
500	Erreur Interne du Serveur

Format de Réponse d'Erreur :

{
  "error": "Error message description"
}

Configuration CORS

Le serveur active le CORS permissif par défaut, autorisant les requêtes de toute origine. Ceci est adapté au développement mais devrait être restreint en production.

Télémétrie

Le serveur initialise automatiquement la télémétrie au démarrage. Les logs sont émis vers stdout avec un formatage structuré.

Niveaux de Log :

ERROR : Erreurs critiques
WARN : Avertissements
INFO : Informations générales (par défaut)
DEBUG : Débogage détaillé
TRACE : Tracé très détaillé

Définissez le niveau de log avec la variable d'environnement RUST_LOG :

RUST_LOG=debug cargo run -- serve

Bonnes Pratiques

Session Management : Toujours créer une session avant d'exécuter un agent
Error Handling : Vérifier les codes d'état HTTP et gérer les erreurs de manière appropriée
Streaming : Utiliser SSE pour les réponses en temps réel ; analyser les événements ligne par ligne
Sécurité : En production, implémenter l'authentification et restreindre CORS
Persistance : Utiliser DatabaseSessionService pour les déploiements en production
Surveillance : Activer telemetry et surveiller les logs pour les problèmes

Exemple Full-Stack

Pour un exemple complet et fonctionnel d'application frontend interagissant avec un backend ADK, consultez l'exemple Research Paper Generator. Ceci démontre :

Frontend : Client HTML/JavaScript avec streaming en temps réel
Backend : Agent ADK avec des FunctionTool de recherche et de génération de PDF personnalisés
Intégration : Utilisation complète de l'API REST avec streaming SSE
Artefacts : Génération et téléchargement de PDF
Session Management : Création et gestion automatique des sessions

L'exemple montre un modèle prêt pour la production pour la construction d'applications web alimentées par l'IA avec ADK-Rust.

Démarrage Rapide :

# 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

Fichiers :

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

Liens Connexes

Lanceur - Démarrage du serveur
Sessions - Session management
Artefacts - Stockage des artefacts
Observabilité - Telemetry et logging

Précédent : ← Launcher | Suivant : A2A Protocol →