@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

``ts
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:

`bash
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:

`ts
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.

`ts
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:

`ts
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 .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:

`ts
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.