> ## Documentation Index
> Fetch the complete documentation index at: https://ai.aidalinfo.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Serveur HTTP

> Déployer vos agents et workflows AI Kit derrière une API REST prête à l’emploi.

`@ai_kit/server` fournit un serveur [Hono](https://hono.dev/) 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

```bash theme={null}
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 :

```bash theme={null}
npx @ai_kit/create-ai-kit server-kit
```

## Exemple minimal

```ts theme={null}
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](./auth) 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`](https://www.npmjs.com/package/@ai_kit/client-kit) et pointez-le vers l’URL publique du serveur :

```ts theme={null}
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.

```ts theme={null}
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` :

```ts theme={null}
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 :

```bash theme={null}
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`](https://github.com/aidalinfo/ai-kit/blob/main/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 :

```ts theme={null}
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.