@ai_kit/server

@ai_kit/server exposes a thin HTTP facade over the agents and workflows defined in @ai_kit/core. It wraps a Hono application that can be embedded inside your own runtime or started directly via the bundled CLI script.

Quick start

import { Agent, createWorkflow } from "@ai_kit/core";
import { ServerKit } from "@ai_kit/server";
import { serve } from "@hono/node-server";

const echoAgent = new Agent({
  name: "echo",
  model: /* configure an ai-sdk LanguageModel here */ {} as any,
});

const workflow = createWorkflow({
  id: "demo",
  description: "Echoes input data",
  steps: [],
});

const server = new ServerKit({
  agents: { echo: echoAgent },
  workflows: { demo: workflow },
});

await server.listen({ port: 8787 });

Need a ready-made project? Scaffold one with the template:

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

The server registers the following endpoints:

• GET /api/agents — list registered agents.
• POST /api/agents/:id/generate — synchronously invoke Agent.generate.
• POST /api/agents/:id/stream — stream the result of Agent.stream.
• GET /api/workflows — list registered workflows.
• POST /api/workflows/:id/run — execute a workflow to completion.
• POST /api/workflows/:id/stream — stream workflow events (Server-Sent Events).
• POST /api/workflows/:id/runs/:runId/resume — resume a suspended workflow run that awaits human input.

See src/ServerKit.ts for the complete implementation and error-handling behaviour.

Calling the server from ClientKit

Reach these endpoints from any JavaScript runtime with @ai_kit/client-kit:

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: "What changed this week?",
  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" },
  },
});

runtime / runtimeContext payloads merge their metadata/ctx with the top-level fields so you can reuse shared values while overriding per request.

Middleware

ServerKit lets you register Hono middleware the same way Mastra does: pass either plain middleware functions or { handler, path } tuples via the server.middleware option. Path-scoped entries accept any string your Hono app would use (e.g. /api/*). The legacy top-level middleware field still works but is deprecated.

const server = new ServerKit({
  agents: { echo: echoAgent },
  workflows: { demo: workflow },
  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 documentation

ServerKit can expose an autogenerated OpenAPI document and Swagger UI that mirrors the endpoints above. Swagger is enabled by default in non-production environments and can be configured via the swagger option:

const server = new ServerKit({
  agents: { echo: echoAgent },
  workflows: { demo: workflow },
  swagger: {
    enabled: true,
    route: "/docs",
    title: "Demo API",
  },
});

When enabled, the UI is served from route (default /swagger) and the raw spec is available from <route>.json.

The bundled CLI also accepts --swagger / --no-swagger flags to force-enable or disable the documentation regardless of NODE_ENV.

Langfuse telemetry

Enable Langfuse directly from the ServerKit configuration:

const server = new ServerKit({
  agents: { echo: echoAgent },
  telemetry: {
    enabled: true,
  },
});

• telemetry accepts either true/false or the full set of ensureLangfuseTelemetry options if you want to customize the exporter.
• Set the environment variables LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY (and optionally LANGFUSE_BASE_URL) for the exporter to authenticate.
• The CLI exposes --telemetry / --no-telemetry flags to toggle the option quickly.