Server API

Complete API reference for @ag-kit/server

Server API Reference

The @ag-kit/server package exposes minimal helpers for serving agents over HTTP.

Quick start

run (recommended)

import { run } from '@ag-kit/server';

run({
  agent: () => ({ agent: myAgent }),           // AbstractAgent
  cors: true,               // enable CORS (or pass CorsOptions)
  port: 3000,               // server port
});

Framework‑agnostic HTTP handler

import { agui } from '@ag-kit/server';

const handler = agui.sendMessage.createServerAdapter(() => ({ myAgent }));
// Use with Bun.serve, Node 18+ (Fetch), Workers, etc.

This adapter is built on @whatwg-node/server and returns a Fetch-compatible handler with Node helpers. See the upstream adapter capabilities for more details: whatwg-node/server.

node

import http from 'node:http';
import { agui } from '@ag-kit/server';

const handler = agui.sendMessage.createServerAdapter(() => ({ myAgent }));

const server = http.createServer((req, res) => handler.handleNodeRequest(req, res));
server.listen(3000);

Exports

• run(props)
• createExpressServer(props): Express
• createExpressRoutes(props): Express
• agui.sendMessage.createServerAdapter(createAgent): (request) => Promise<Response>
• agui.sendMessage.handler(input, agent): AsyncIterable<SendMessageEvent> — low‑level generator used by the adapter
• agui.healthz.serverAdapter: (request) => Promise<Response>

API

run

Starts an Express server in one call.

type AgentCreatorRet = {
  agent: AbstractAgent | { toAGUIAgent(): AbstractAgent };
  cleanup?: () => void;
};

export type AgentCreator = () => AgentCreatorRet | Promise<AgentCreatorRet>;

interface ICreateServer {
  agent: AgentCreator;
  basePath?: `/${string}/`;
  cors?: boolean | import('cors').CorsOptions;
}

function run(props: ICreateServer & { port?: number | string }): void

Behavior:

• Auto‑converts non‑abstract agents via toAGUIAgent()
• Registers send-message, healthz, openai/chat/completions routes
• Uses / as default basePath

createExpressServer

Creates and configures an Express app with agent routes.

function createExpressServer(props: ICreateServer): import('express').Express

createExpressRoutes

Adds agent routes to an existing Express app.

interface ICreateExpressRoutes extends ICreateServer {
  express: import('express').Express;
}

function createExpressRoutes(props: ICreateExpressRoutes): import('express').Express

agui.sendMessage.createServerAdapter

Creates a Fetch‑compatible handler that validates input and streams SSE events.

function createServerAdapter(createAgent: AgentCreator): (request: Request) => Promise<Response>

agui.sendMessage.handler

Low‑level function that drives the agent and yields events.

function handler(input: SendMessageInput, agent: AbstractAgent): AsyncIterable<SendMessageEvent>

agui.healthz.serverAdapter

Simple health probe endpoint returning OK.

const serverAdapter: (request: Request) => Promise<Response>

Endpoints (Express helpers)

• POST {basePath}send-message — body is SendMessageInput; response is text/event-stream
• GET {basePath}healthz — returns OK

basePath defaults to /.

Request and events

These types come from @ag-kit/shared and are enforced at runtime with Zod:

type SendMessageInput = {
  conversationId: string;
  messages?: Array<
    | { role: 'system'; content: string }
    | { role: 'user'; content: string }
    | { role: 'tool'; content: string; toolCallId: string }
    | { role: 'assistant'; content?: string; toolCalls?: Array<{ id: string; type: 'function'; function: { name: string; arguments: string } }>} 
  >;
  resume?: { interruptId: string; payload: unknown };
  tools?: Array<{ name: string; description: string; parameters: any }>;
};

type SendMessageEvent =
  | { type: 'text'; content: string }
  | { type: 'tool-call-start'; toolCallId: string; toolCallName: string }
  | { type: 'tool-call-args'; toolCallId: string; delta: string }
  | { type: 'tool-call-end'; toolCallId: string }
  | { type: 'tool-result'; toolCallId: string; result: string }
  | { type: 'interrupt'; id: string; reason: string; payload: unknown };

CORS

CORS is enabled by default. Pass cors: false to disable CORS or provide CorsOptions to configure it.