跳转到主要内容

​
服务端应用程序接口参考

@ag-kit/server 包提供了通过 HTTP 服务 Agent 的最小化辅助工具。

​
快速开始

​
run (推荐方式)

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

run({
  agent: () => ({ agent: myAgent }),           // AbstractAgent
  cors: true,               // 启用 CORS (或传递 CorsOptions)
  port: 3000,               // 服务端口
});

​
框架无关的 HTTP 处理器

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

const handler = agui.sendMessage.createServerAdapter(() => ({ myAgent }));
// 可配合 Bun.serve、Node 18+ (Fetch)、Workers 等使用
该适配器基于 @whatwg-node/server 构建，返回一个兼容 Fetch 的处理器并包含 Node 辅助工具。详见上游适配器能力：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);

​
导出项

  • run(props)
  • createExpressServer(props): Express
  • createExpressRoutes(props): Express
  • agui.sendMessage.createServerAdapter(createAgent): (request) => Promise<Response>
  • agui.sendMessage.handler(input, agent): AsyncIterable<SendMessageEvent> — 适配器使用的底层生成器
  • agui.healthz.serverAdapter: (request) => Promise<Response>

​
应用程序接口

​
run

通过单次调用启动 Express 服务。 
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
行为特性:
  • 通过 toAGUIAgent() 自动转换非抽象 Agent
  • 注册 send-message、healthz、openai/chat/completions 路由
  • 默认使用 / 作为 basePath

​
createExpressServer

创建并配置带有 Agent 路由的 Express 应用。 
function createExpressServer(props: ICreateServer): import('express').Express

​
createExpressRoutes

向现有 Express 应用添加 Agent 路由。 
interface ICreateExpressRoutes extends ICreateServer {
  express: import('express').Express;
}

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

​
agui.sendMessage.createServerAdapter

创建兼容 Fetch 的处理器，用于验证输入并流式传输 SSE 事件。 
function createServerAdapter(createAgent: AgentCreator): (request: Request) => Promise<Response>

​
agui.sendMessage.handler

驱动 Agent 并生成事件的底层函数。 
function handler(input: SendMessageInput, agent: AbstractAgent): AsyncIterable<SendMessageEvent>

​
agui.healthz.serverAdapter

返回 OK 的简易健康检查端点。 
const serverAdapter: (request: Request) => Promise<Response>

​
端点 (Express 辅助工具)

  • POST {basePath}send-message — 请求体为 SendMessageInput；响应为 text/event-stream
  • GET {basePath}healthz — 返回 OK
basePath 默认为 /。

​
请求与事件

以下类型来自 @ag-kit/shared 并通过 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。传递 cors: false 禁用 CORS 或提供 CorsOptions 进行配置。