Serveur API

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

Vue d’ensemble

Le serveur repose sur Axum et fournit :

• REST API : points de terminaison HTTP pour l’exécution des agents et la gestion des sessions
• Événements envoyés par le serveur (SSE) : diffusion en temps réel des réponses de l’agent
• Interface web : interface interactive dans le navigateur
• Prise en charge de CORS : requêtes interorigines activées
• Télémétrie : observabilité intégrée avec la journalisation de suivi

ServerConfig expose également un relais direct au niveau du lanceur pour les déploiements de longue durée :

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

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

Démarrez à partir de l’ossature API validée :

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

Points de terminaison REST API

Vérification de l’état

Vérifiez si le serveur fonctionne :

GET /api/health

Réponse :

OK

Exécution d’un agent avec diffusion en continu

Exécutez un agent et diffusez les réponses à l’aide des événements envoyés par le serveur :

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 :

• Type de contenu : text/event-stream
• Diffuse les événements sous forme d’objets JSON

Format des événements :

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

Exécution d’un agent (sans diffusion en continu)

Exécutez un agent jusqu’à son terme et recevez tous les événements dans une seule réponse JSON :

POST /api/run

Corps de la requête : même structure que POST /api/run_sse (le champ streaming est ignoré) :

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

Réponse :

• Type de contenu : application/json
• Un tableau JSON contenant chaque événement produit par l’exécution, dans l’ordre, en utilisant le même format d’événement que /api/run_sse

Ce point de terminaison reproduit la route /run sans diffusion en continu de ADK de Google api_server.

Gestion des sessions

Créer une session

Créer 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érer les détails d’une 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

Supprimer une session :

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

Réponse :

• Statut : 204 No Content

Lister les sessions

Lister toutes les sessions d’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

Lister tous les artefacts d’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 :

• Type de contenu : déterminé par l’extension du fichier
• Corps : contenu binaire ou texte

Gestion des applications

Lister les applications

Lister tous les agents disponibles :

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

Réponse :

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

Interface web

Le serveur inclut une interface web intégrée accessible à l’adresse :

http://localhost:8080/ui/

Le guide de démarrage rapide en cinq minutes met en place un serveur basé sur OpenAI et ouvre cette interface avec quatre commandes. L’enregistrement utilise une équipe pour rendre visible l’arête de topologie active ; les agents feuilles, les outils, les graphes, les workflows, les agents en temps réel et les agents distants utilisent la même interface.

Fonctionnalités

• Exécutions interactives : Envoyer des messages et des pièces jointes, et inspecter un Markdown rendu de manière sécurisée, le texte en streaming, les appels d’outils, les échecs et les transferts
• Gestion des sessions : Créer, consulter et basculer entre les sessions
• Topologie d’équipe portable : Distinguer les liens exacts de délégation et de retour des transferts de contrôle, avec une animation de type Studio Next pour le membre actif et le lien entrant
• Inspecteur du runtime : Inspecter les événements ordonnés, les spans de télémétrie dédiés, l’état partagé/de session, les services du runtime configurés, la découverte de A2A et la prise en charge du protocole UI/MCP Apps
• Lecture en temps réel : Identifier les agents en temps réel, fusionner les deltas de transcription et lire la sortie PCM terminée au format audio WAV
• Visionneuse d’artefacts : Consulter et télécharger les artefacts de session
• Thèmes adaptatifs : Dispositions système, claire et sombre accessibles au clavier, sans ressources externes

Routes de l’interface

• / - Redirige vers /ui/
• /ui/ - Interface principale de discussion
• /ui/assets/* - Ressources statiques (CSS, JS, images)
• /ui/assets/config/runtime-config.json - Configuration du runtime
• /api/ui/agents/{name} - Capacités de l’agent, hiérarchie et métadonnées de topologie portable

L’interface est maintenue dans adk-server/webui et sa build de production est intégrée au crate serveur, de sorte que les projets générés et les déploiements utilisent la même interface runtime sans service frontend séparé.

La vitrine d’interface utilisateur du runtime exécutable comprend des tutoriels et des captures d’écran distincts basés sur OpenAI pour un agent appelant des outils, un workflow de graphe déterministe et une équipe de transfert portable. La galerie d’agents avancés ajoute un planning ambiant, la lecture vocale en temps réel de OpenAI, la découverte de A2A, la découverte de MCP 2026-07-28 avec des tâches SEP-2663, ainsi que des services de télémétrie, d’artefacts et de mémoire configurés sur un même serveur. La marque ADK Runtime renvoie vers adk-rust.com dans un nouvel onglet.

Exemples client

JavaScript/TypeScript

Utilisation de Fetch API 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é

Pour utiliser un port personnalisé, définissez PORT avant de démarrer le serveur généré :

PORT=3000 cargo run

Service d’artefacts personnalisé

Fournissez votre propre service d’artefacts :

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 sessions personnalisé

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

use adk_session::SqliteSessionService;

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

Gestion des erreurs

API utilise des réponses d’erreur structurées avec des codes d’état HTTP dérivés de la catégorie d’erreur :

Format de réponse d’erreur (problème JSON) :

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

Les champs requestId, retryAfter et upstreamStatusCode sont inclus lorsqu’ils sont disponibles (null dans le cas contraire).

Configuration de CORS

Le serveur active par défaut CORS permissif, ce qui autorise les requêtes provenant de n’importe quelle origine. Cette configuration convient au développement, mais doit être restreinte en production.

Télémétrie

Le serveur initialise automatiquement la télémétrie lors de son démarrage. Les journaux sont affichés sur la sortie standard dans un format structuré.

Niveaux de journalisation :

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

Définissez le niveau de journalisation avec la variable d’environnement RUST_LOG :

RUST_LOG=debug cargo run

Bonnes pratiques

1. Gestion des sessions : Créez toujours une session avant d’exécuter un agent
2. Gestion des erreurs : Vérifiez les codes d’état HTTP et gérez les erreurs de manière appropriée
3. Diffusion en continu : Utilisez SSE pour les réponses en temps réel ; analysez les événements ligne par ligne
4. Sécurité : En production, mettez en place une authentification et restreignez CORS
5. Persistance : Utilisez SqliteSessionService ou PostgresSessionService pour les déploiements en production
6. Surveillance : Activez la télémétrie et surveillez les journaux pour détecter les problèmes

Exemple full-stack

Pour obtenir une structure complète de serveur fonctionnelle, utilisez le modèle API validé de cargo-adk. Celui-ci présente :

• Frontend : client HTML/JavaScript avec diffusion en continu en temps réel
• Backend : agent ADK avec des outils personnalisés de recherche et de génération PDF
• Intégration : utilisation complète de REST API avec diffusion en continu SSE
• Artefacts : génération et téléchargement de PDF
• Gestion des sessions : création et gestion automatiques des sessions

L’exemple présente un modèle prêt pour la production destiné à créer des applications web alimentées par l’IA avec ADK-Rust.

Démarrage rapide :

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

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

Rubriques connexes

• Lanceur - Démarrage du serveur
• Sessions - Gestion des sessions
• Artefacts - Stockage des artefacts
• Observabilité - Télémétrie et journalisation

---

Précédent : ← Lanceur | Suivant : Protocole A2A →