Serveur HTTP

@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. Besoin d’un projet clé en main ? Lancez simplement :

npx @ai_kit/create-ai-kit server-kit

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.

Besoin de verrouiller l’API ? Consultez le guide Authentification pour activer les tokens bearer et vos gardes personnalisés.

Endpoints exposés

Route	Description
`GET /api/agents`	Liste tous les agents déclarés dans la configuration du serveur.
`POST /api/agents/:id/generate`	Exécute `Agent.generate` une fois et retourne la réponse complète.
`POST /api/agents/:id/stream`	Diffuse `Agent.stream` via SSE ou l’API `DataStreamResponse` fournie par `ai`.
`GET /api/workflows`	Liste tous les workflows déclarés dans la configuration du serveur.
`POST /api/workflows/:id/run`	Démarre un run et renvoie son `runId` + l’état final (ou `waiting_human`).
`POST /api/workflows/:id/stream`	Diffuse chaque `WorkflowEvent` et l’état final via SSE.
`POST /api/workflows/:id/runs/:runId/resume`	Reprend 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).

Consommer depuis ClientKit

Pour appeler le serveur depuis un autre service Node.js ou un worker edge, installez @ai_kit/client-kit et pointez-le vers l’URL publique du serveur :

import { ClientKit } from "@ai_kit/client-kit";

const client = new ClientKit({
  baseUrl: "https://agents.internal.aidalinfo.fr",
  headers: { Authorization: `Bearer ${process.env.SERVER_TOKEN}` },
});

const generation = await client.generateAgent("support", {
  prompt: "Quelles sont les nouveautés de cette semaine ?",
  runtime: {
    metadata: { tenant: "aidalinfo" },
    ctx: { locale: "fr-FR" },
  },
});

const run = await client.runWorkflow("enrich-ticket", {
  inputData: { contactId: "123" },
  metadata: { requestId: "run_abc" },
  runtime: {
    metadata: { tenant: "aidalinfo" },
    ctx: { locale: "fr-FR" },
  },
});

Les propriétés runtime ou runtimeContext fusionnent leurs metadata/ctx avec celles passées directement (metadata, ctx).
resumeWorkflow reste disponible pour débloquer un run en attente humaine avec { stepId, data }.
Passez signal dans les options pour annuler une requête (compatible fetch standard).

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.

Middleware

Vous pouvez brancher des middlewares Hono (même syntaxe que Mastra) via l’option server.middleware. Passez soit une simple fonction (middleware global), soit un objet { path, handler } pour limiter la portée à certaines routes (path doit être une chaîne Hono valide, par exemple /api/*). Le champ middleware à la racine reste pris en charge pour compatibilité mais sera retiré à terme.

const server = new ServerKit({
  agents: { support: supportAgent },
  workflows: { "enrich-ticket": enrichWorkflow },
  server: {
    middleware: [
      {
        path: "/api/*",
        handler: async (c, next) => {
          const authHeader = c.req.header("Authorization");
          if (!authHeader) {
            return new Response("Unauthorized", { status: 401 });
          }

          await next();
        },
      },
      async (c, next) => {
        console.log(`${c.req.method} ${c.req.url}`);
        await next();
      },
    ],
  },
});

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

Option	Type	Rôle
`agents`	`Record<string, Agent>`	Enregistre les agents disponibles sous `/api/agents/:id/*`.
`workflows`	`Record<string, Workflow>`	Déclare les workflows exposés sous `/api/workflows/:id/*`.
`server.middleware`	`ServerMiddleware[]`	Ajoute des middlewares globaux ou scoped avant les routes intégrées.
`swagger`	`boolean \| SwaggerOptions`	Active/désactive Swagger ou précise `route`, `title`, `version`, `description`.
`telemetry`	`boolean \| ServerTelemetryOptions`	Active 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.

Getting started

Serveur

Agents

Workflows

Utils

RAG

Télémétrie

Providers

MCP

Installation

Exemple minimal

Endpoints exposés

Consommer depuis ClientKit

Streaming et reprise

Middleware

Swagger / OpenAPI

Utiliser le binaire CLI

Options de configuration

Télémétrie Langfuse

​Installation

​Exemple minimal

​Endpoints exposés

​Consommer depuis ClientKit

​Streaming et reprise

​Middleware

​Swagger / OpenAPI

​Utiliser le binaire CLI

​Options de configuration

​Télémétrie Langfuse

Installation

Exemple minimal

Endpoints exposés

Consommer depuis ClientKit

Streaming et reprise

Middleware

Swagger / OpenAPI

Utiliser le binaire CLI

Options de configuration

Télémétrie Langfuse