Passer au contenu principal
@ai_kit/server fournit un serveur Hono préconfiguré qui expose vos agents et workflows sous forme d’API HTTP. Il gère les invocations synchrones, le streaming (SSE), la reprise des workflows en attente et peut générer automatiquement une documentation OpenAPI.

​
Installation

npm i @ai_kit/server
Ajoutez-le dans le même projet que @ai_kit/core afin de partager les agents et workflows que vous avez déjà déclarés.

​
Exemple minimal

import { Agent, createWorkflow } from "@ai_kit/core";
import { ServerKit } from "@ai_kit/server";

const supportAgent = new Agent({
  name: "support",
  instructions: "Réponds brièvement aux demandes internes.",
  model: /* configurez votre provider ai-sdk */ {} as any,
});

const enrichWorkflow = createWorkflow({
  id: "enrich-ticket",
  description: "Ajoute les métadonnées nécessaires avant traitement."
});

const server = new ServerKit({
  agents: { support: supportAgent },
  workflows: { "enrich-ticket": enrichWorkflow },
});

await server.listen({ port: 8787 });
Par défaut, le serveur écoute sur 0.0.0.0 et le port PORT (ou 8787). Les instances d’agent et de workflow sont conservées en mémoire et réutilisées à chaque requête.

​
Endpoints exposés

RouteDescription
GET /api/agentsListe tous les agents déclarés dans la configuration du serveur.
POST /api/agents/:id/generateExécute Agent.generate une fois et retourne la réponse complète.
POST /api/agents/:id/streamDiffuse Agent.stream via SSE ou l’API DataStreamResponse fournie par ai.
GET /api/workflowsListe tous les workflows déclarés dans la configuration du serveur.
POST /api/workflows/:id/runDémarre un run et renvoie son runId + l’état final (ou waiting_human).
POST /api/workflows/:id/streamDiffuse chaque WorkflowEvent et l’état final via SSE.
POST /api/workflows/:id/runs/:runId/resumeReprend un run suspendu avec des données humaines.
Les payloads workflow doivent inclure inputData et peuvent ajouter metadata. Pour les agents, fournissez soit prompt, soit messages (aligné sur AI SDK).

​
Streaming et reprise

  • stream utilise un ReadableStream SSE : l’événement run contient le runId, puis chaque étape déclenche un événement dont le nom = event.type.
  • Lorsque le workflow passe en waiting_human, le stream se ferme après avoir envoyé l’état. Utilisez ensuite resume avec { stepId, data } pour relancer l’exécution.
  • La route /stream annule automatiquement le run si le client ferme la connexion.

​
Swagger / OpenAPI

Swagger est activé par défaut hors production. Personnalisez-le via swagger : 
const server = new ServerKit({
  agents: { support: supportAgent },
  swagger: {
    enabled: true,
    route: "/docs",
    title: "Support API",
    description: "Agents et workflows exposés par AI Kit"
  }
});
  • L’UI est servie sur route (par ex. /docs).
  • L’OpenAPI JSON est disponible sur route + ".json".
  • Passez false pour désactiver Swagger même en développement, ou true pour l’activer en production.

​
Utiliser le binaire CLI

Le package expose la commande server-kit (exécutable via npx @ai_kit/server) qui démarre une instance ServerKit en lisant les variables d’environnement suivantes : 
npx @ai_kit/server --swagger
  • PORT (défaut 8787).
  • HOST (défaut 0.0.0.0).
  • NODE_ENV influe sur l’activation automatique de Swagger.
Le binaire fourni sert surtout de point de départ : il ne déclare aucun agent ni workflow tant que vous n’instanciez pas vous-même ServerKit dans votre application (par exemple dans apps/api/server.ts) et que vous n’y passez vos modules AI Kit. Inspirez-vous du CLI pour intégrer ServerKit dans votre outil de déploiement habituel.

​
Options de configuration

OptionTypeRôle
agentsRecord<string, Agent>Enregistre les agents disponibles sous /api/agents/:id/*.
workflowsRecord<string, Workflow>Déclare les workflows exposés sous /api/workflows/:id/*.
swaggerboolean | SwaggerOptionsActive/désactive Swagger ou précise route, title, version, description.
telemetryboolean | ServerTelemetryOptionsActive l’export Langfuse et transmet les options à ensureLangfuseTelemetry.
La méthode listen({ port, hostname, signal }) accepte également un AbortSignal pour arrêter proprement le serveur. Pour une implémentation complète, consultez packages/server/src/ServerKit.ts.

​
Télémétrie Langfuse

Activez Langfuse directement via la configuration ServerKit — aucun fichier d’instrumentation séparé n’est requis : 
const server = new ServerKit({
  agents: { support: supportAgent },
  workflows: { "enrich-ticket": enrichWorkflow },
  telemetry: {
    enabled: true,
  },
});
  • telemetry accepte un booléen ou la configuration complète d’ensureLangfuseTelemetry.
  • Définissez les variables LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY (et optionnellement LANGFUSE_BASE_URL).
  • Le CLI expose les flags --telemetry / --no-telemetry pour activer ou désactiver rapidement la télémétrie.