Skip to main content

​
Server API Reference

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

​
Quick start

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