# @backendkit-labs/agent-web 中文文档

规范地址：https://npmcn.com/package/%40backendkit-labs/agent-web/

版本：0\.6\.4
npm 元数据更新时间：2026-10-28T14:44:58.547Z
中文译文更新时间：2026-11-07T21:22:48.121Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40backendkit-labs/agent-web
原文对照：https://npmcn.com/package/%40backendkit-labs/agent-web/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：237 kB，63 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：4 个
- peer 依赖：@backendkit-labs/agent-core \>=0\.24\.0 \<0\.38\.0
- 首次发布：2026-06-11T10:12:31.475Z
- 最新版本发布：2026-10-28T14:44:58.322Z
- 近 30 天下载量：2453（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

HTTP/ WebSocket 服务器层用于代理核心——浏览器已准备好的流媒体代理会话

## 安装

```sh
npm install @backendkit-labs/agent-web
```

也可以使用：`pnpm add @backendkit-labs/agent-web`、`yarn add @backendkit-labs/agent-web`、`bun add @backendkit-labs/agent-web`

## README

# @backendkit-labs/代理网络

> **状态 : `stable`** ——保持并做好生产准备. `TriggerBus` (cron/webhook/BullMQ)为: `experimental` 并在试验阶段被冻结.

HTTP/ WebSocket 服务器层 [@ backendkit-labs/ 代理核心](https://www.npmjs.com/package/@backendkit-labs/agent-core)。 。 。 .

环绕 `AgentEngine` 在一个有流式WebSocket会话,JWT认证,Prometheus度量衡,速率限制,实时显示器总线,以及灵活的触发系统(cron jobs,webhoks,BullMQ队列)的快取5服务器中.

[![npm](https://img.shields.io/npm/v/@backendkit-labs/agent-web)](https://www.npmjs.com/package/@backendkit-labs/agent-web)

## 目录

-   [安装](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-installation)
-   [快开始](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-quick-start)
-   [代理服务器选项](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-agentserver-options)
-   [HTTP 和 WebSocket 路线](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-http-and-websocket-routes)
-   [WebSocket 协议](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-websocket-protocol)
-   [引擎阵型](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-enginefactory-pattern)
-   [会话管理器](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-sessionmanager)
-   [JWT 认证](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-jwt-authentication)
-   [普罗米修斯度量衡](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-prometheus-metrics)
-   [限制费率](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-rate-limiting)
-   [会话元数据存储](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-session-metadata-store)
-   [监视器Bus](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-monitorbus)
-   [触发Bus — cron, webhooks, 队列](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-triggerbus--cron-webhooks-queues)
-   [无头运输](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-headlesstransport)
-   [全面生产实例](https://npmcn.com/package/%40backendkit-labs/agent-web/#readme-full-production-example)

* * *

## 安装

```bash
npm install @backendkit-labs/agent-web @backendkit-labs/agent-core
```

可选融合(仅安装所需):

```bash
npm install jsonwebtoken          # JWT auth
npm install prom-client           # Prometheus metrics
npm install @fastify/rate-limit   # rate limiting
npm install node-cron             # cron triggers
npm install bullmq                # queue triggers
npm install ioredis               # Redis session store
```

* * *

## 快开始

```typescript
import { AgentServer } from '@backendkit-labs/agent-web';
import type { EngineFactory } from '@backendkit-labs/agent-web';
import { AgentEngine, AgentRegistry, ToolRegistry, ProviderRegistry } from '@backendkit-labs/agent-core';

const engineFactory: EngineFactory = (sessionId, transport) =>
  new AgentEngine({
    transport,
    sessionId,
    // ...your engine config
  });

const server = new AgentServer({
  port:          3000,
  engineFactory,
  cors:          '*',
});

await server.start();
// WS  /chat      — streaming chat sessions
// WS  /monitor   — real-time read-only observer
// GET /health    — { status, sessions, monitors }
// GET /sessions  — active session list
// DELETE /sessions/:id — close a session
```

* * *

## 代理服务器选项

```typescript
interface AgentServerOptions {
  // Required
  engineFactory: EngineFactory;       // creates a new AgentEngine per session

  // Network
  port?:   number;                    // default: 3000
  host?:   string;                    // default: '127.0.0.1' (use '0.0.0.0', with auth, for remote callers)
  cors?:   string | string[];         // default: '*' (none with strict)
  strict?: boolean;                   // fail-closed defaults, see "Strict mode"
  logger?: boolean | object;          // Fastify logger, default: false

  // Auth
  auth?: AuthHook;                    // called on every request before handlers

  // Rate limiting (requires @fastify/rate-limit)
  rateLimiting?: {
    max?:        number;              // max requests per IP per window, default: 100
    timeWindow?: string;             // e.g. '1 minute', '30 seconds'
  };

  // Prometheus metrics (requires prom-client)
  metrics?: {
    enabled:          boolean;        // must be true to activate
    path?:            string;         // default: '/metrics'
    prefix?:          string;         // metric name prefix
    collectNodeMetrics?: boolean;     // include Node.js process metrics
  };

  // Session management
  maxIdleMs?:   number;               // idle timeout before session is closed
  maxSessions?: number;               // max concurrent sessions
  store?:       SessionMetaStore;     // durable metadata store (default: in-memory)

  // Triggers
  triggers?: TriggerBus;             // wires webhook routes and starts cron jobs
}
```

* * *

## HTTP 和 WebSocket 路线

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/health` | 服务器健康: `{ status, sessions, monitors, uptime }` |
| `GET` | `/sessions` | 活动会话元数据阵列 |
| `DELETE` | `/sessions/:id` | 强制关闭会话 |
| `GET` | `/metrics` | Prometheus 度量衡( 如果启用) |
| `WS` | `/chat` | 流畅聊天——每次连接一个会话 |
| `WS` | `/monitor` | 所有会议的只读观察员 |
| `POST` | `/webhooks/:name` | Webhook 触发器( 通过触发程序注册) |

* * *

## WebSocket 协议

### `/chat` - 聊天会

**客户端 – 服务器 :**

```json
{ "type": "input",  "content": "Your message here" }
{ "type": "abort" }
```

**服务器 – 客户端** (编) `AgentEvent` 边框 :

```json
{ "type": "run_start",     "sessionId": "abc-123" }
{ "type": "token",         "content": "Hello" }
{ "type": "tool_call",     "name": "search", "args": { "query": "..." } }
{ "type": "tool_result",   "name": "search", "result": "..." }
{ "type": "agent_switch",  "from": "general", "to": "security-reviewer" }
{ "type": "done",          "final": "Full assistant response" }
{ "type": "error",         "message": "Something went wrong" }
```

### `/monitor` ——实时观察员

连接以观察所有会话而不发送任何消息 :

```json
{ "type": "monitor_hello",         "sessionIds": ["abc-123", "def-456"] }
{ "type": "monitor_session_open",  "sessionId": "ghi-789" }
{ "type": "monitor_session_close", "sessionId": "ghi-789" }
{ "sessionId": "abc-123", "type": "run_input", "content": "..." }
{ "sessionId": "abc-123", "type": "token",     "content": "..." }
{ "sessionId": "abc-123", "type": "done",      "final": "..." }
```

* * *

## 引擎阵型

`EngineFactory` 是函数 `(sessionId: string, transport: Transport) => AgentEngine`。每个进入的WebSocket连接都获得自己的孤立引擎实例.

### 最小工厂

```typescript
import type { EngineFactory } from '@backendkit-labs/agent-web';
import { AgentEngine } from '@backendkit-labs/agent-core';

const engineFactory: EngineFactory = (sessionId, transport) =>
  new AgentEngine({
    transport,
    sessionId,
    model:           { provider: 'openai', id: 'gpt-4o' },
    agents,
    tools,
    providers,
    defaultProvider: 'openai',
    defaultAgentId:  'general',
    maxIterations:   50,
    iterationMode:   'auto',
  });
```

### 每会场记忆的工厂

```typescript
import { createMemorySystem } from '@backendkit-labs/agent-core';
import * as path from 'path';
import * as os from 'os';

const engineFactory: EngineFactory = (sessionId, transport) => {
  // Isolated memory per session
  const sessDir = path.join(os.homedir(), '.bk-agent', 'sessions', sessionId);
  const memory = createMemorySystem({
    episodic:  { provider: 'json', path: path.join(sessDir, 'episodes.json') },
    semantic:  { provider: 'json', path: path.join(sessDir, 'knowledge.json') },
    procedural:{ provider: 'json', path: path.join(sessDir, 'patterns.json') },
  });

  return new AgentEngine({
    transport,
    sessionId,
    memorySystem: memory,
    ...baseConfig,
  });
};
```

### 使用 JWT 的工厂

当 JWT 认证被启用时 `sessionId` 带有认证用户的上下文。 也可以输入用户特定数据:

```typescript
const engineFactory: EngineFactory = (sessionId, transport) => {
  // sessionId is set to the JWT 'sub' claim when JwtAuth is used
  const userConfig = getUserConfig(sessionId); // look up per-user settings

  return new AgentEngine({
    transport,
    sessionId,
    projectContext: `User: ${userConfig.name}\nRole: ${userConfig.role}`,
    ...baseConfig,
  });
};
```

* * *

## 会话管理器

`SessionManager` 创建、跟踪和清理会话。 它是由内部创建的 `AgentServer`,但也可以单独使用.

```typescript
import { SessionManager } from '@backendkit-labs/agent-web';

const sessions = new SessionManager({
  engineFactory,
  maxIdleMs:   30 * 60 * 1000,  // close after 30 min of inactivity
  maxSessions: 100,
  monitorBus:  myMonitorBus,
  metrics:     myMetricsCollector,
  store:       myMetaStore,
});

// Lifecycle
const session = await sessions.getOrCreate('session-id', myTransport);
await sessions.close('session-id');
const all = sessions.list(); // SessionMeta[]
```

* * *

## JWT 认证

`JwtAuth` 验证 `Authorization` 页眉或 `?token=` 查询参数(用于无法设置自定义头的浏览器 WebSocket连接).

### 严格模式

对于其他人接触到的服务器,打开两个开关:

```ts
const auth = new JwtAuth({ secret: process.env.JWT_SECRET!, allowQueryToken: false }).hook();
new AgentServer({ engineFactory, host: '0.0.0.0', auth, strict: true, cors: ['https://app.example.com'] });
```

-   `allowQueryToken: false` 忽略 `?token=` (一个在URL中的标志在日志,代理和历史中登陆). 浏览器发送 作为 WebSocket 子协议的符号 : `new WebSocket(url, ['bearer', jwt])`· ; `useAgentSession({ url, token })` 内 `agent-web-ui` 为了你.
-   `strict: true` 除非 `cors` 列出它,添加 `X-Content-Type-Options`, (中文(简体) ), `X-Frame-Options: DENY` 财务报告和审定财务报表 `Referrer-Policy: no-referrer`他们不肯听从 `host` 无 `auth`。 。 。 .

### 设置

```typescript
import { AgentServer, JwtAuth } from '@backendkit-labs/agent-web';

const jwt = new JwtAuth({
  secret:        process.env.JWT_SECRET!,  // or use publicKey for RS256
  algorithm:     'HS256',                  // default
  sessionIdClaim:'sub',                    // JWT claim to use as sessionId
  expiresIn:     '24h',
});

const server = new AgentServer({
  port:          3000,
  engineFactory,
  auth:          jwt.hook(),               // AuthHook applied to all routes
});
```

### 发布令牌( 您的登录端点)

```typescript
import { JwtAuth } from '@backendkit-labs/agent-web';

const jwt = new JwtAuth({ secret: process.env.JWT_SECRET! });

// Issue a token for an authenticated user
const token = jwt.sign({
  sub:  'user-123',
  role: 'admin',
  name: 'Alice',
});

// Return to client — they send it as:
// Authorization: Bearer <token>
// or ws://host/chat?token=<token>
```

### 用户会议隔离

何时 `sessionIdClaim` 实值 `'sub'`,每个用户自动获得自己的会话。 两个相同的请求总是打在同一会话:

```typescript
const jwt = new JwtAuth({
  secret:         process.env.JWT_SECRET!,
  sessionIdClaim: 'sub',  // user ID as session key
});
```

### 自定义认证钩钩

如果您使用不同的认证系统( API 密钥, OAuth 令牌) , 则执行 `AuthHook` 直接 :

```typescript
import type { AuthHook } from '@backendkit-labs/agent-web';

const apiKeyAuth: AuthHook = async (req, reply) => {
  const key = req.headers['x-api-key'];
  if (!key || !validApiKeys.has(key as string)) {
    reply.code(401).send({ error: 'Unauthorized' });
  }
};

const server = new AgentServer({ auth: apiKeyAuth, ...opts });
```

* * *

## 普罗米修斯度量衡

要求数 `prom-client` 将安装。 显示 a `/metrics` 端点有标准普罗米修斯计数器和直方图.

```typescript
const server = new AgentServer({
  ...opts,
  metrics: {
    enabled:            true,
    path:               '/metrics',         // default
    prefix:             'bk_agent_',        // prepended to all metric names
    collectNodeMetrics: true,               // include Node.js process metrics
  },
});
```

### 暴露的衡量标准

| 度量衡 | 类型 | 说明 |
| --- | --- | --- |
| `bk_agent_sessions_active` | 高盖 | 目前公开会议 |
| `bk_agent_runs_total{status}` | 计数器 | 按状况分列的运行总数`success`, (中文(简体) ), `error`(中文(简体) ) |
| `bk_agent_run_duration_seconds` | 直方图 | 运行延迟分布 |
| 节点.js 度量衡 | 各种 | 内存、 CPU、 GC( 当 `collectNodeMetrics: true`(中文(简体) ) |

### 直接使用计量工具

```typescript
import { MetricsCollector } from '@backendkit-labs/agent-web';

const collector = new MetricsCollector({ prefix: 'my_agent_' });

// Record a completed run
const endRun = collector.startRun('session-abc');
// ... after run completes:
endRun('success');   // or endRun('error')

// Get Prometheus text format
const text = await collector.getMetrics();
// # HELP my_agent_runs_total ...
// my_agent_runs_total{status="success"} 42
```

* * *

## 限制费率

要求数 `@fastify/rate-limit`全球适用于所有路线:

```typescript
const server = new AgentServer({
  ...opts,
  rateLimiting: {
    max:        60,          // max 60 requests per IP
    timeWindow: '1 minute',  // sliding window
  },
});
```

当超过限制时,服务器会回复:

```json
{ "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded" }
```

* * *

## 会话元数据存储

默认情况下,会话元数据生活在内存中,并在重启时丢失. 使用 `RedisSessionMetaStore` 用于跨越重启和水平缩放的持久元数据.

### 内存( 默认)

```typescript
import { InMemorySessionMetaStore } from '@backendkit-labs/agent-web';

const server = new AgentServer({
  ...opts,
  store: new InMemorySessionMetaStore(),
});
```

### Redis 商店( 需要 ioredis 或 node- redis)

`RedisSessionMetaStore` 是鸭式的 —— 它接受任何执行的 Redis 客户端 `.get()`, (中文(简体) ), `.set()`,以及 `.del()`数字 :

```typescript
import { RedisSessionMetaStore } from '@backendkit-labs/agent-web';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);

const server = new AgentServer({
  ...opts,
  store: new RedisSessionMetaStore(redis, {
    ttlSeconds: 86400,    // keep session metadata for 24h
    prefix:     'bk:sess:', // key prefix
  }),
});
```

* * *

## 监视器Bus

`MonitorBus` 将所有会话活动广播到连接 `/monitor` WebSocket观察者. 由Kanban董事会使用于 `@backendkit-labs/agent-web-ui`。 。 。 .

### 独立使用

```typescript
import { MonitorBus } from '@backendkit-labs/agent-web';

const monitor = new MonitorBus();

// Subscribe to all events (e.g. for logging or alerting)
const unsub = monitor.subscribe((frame) => {
  if (frame.type === 'done') {
    console.log(`[${frame.sessionId}] run completed`);
  }
  if (frame.type === 'error') {
    alerting.notify(`Agent error in session ${frame.sessionId}: ${frame.message}`);
  }
});

// Clean up
unsub();
```

* * *

## 触发Bus — cron, webhooks, 队列

`TriggerBus` 让自动代理运行没有 WebSocket 客户端。 Kanban 显示器显示运行情况 .

### 克龙触发器( 要求) `node-cron`(中文(简体) )

```typescript
import { TriggerBus } from '@backendkit-labs/agent-web';

const triggers = new TriggerBus(engineFactory)
  .addCron({
    name:        'daily-report',
    schedule:    '0 8 * * 1-5',     // weekdays at 8 AM
    buildPrompt: () => 'Generate the daily engineering standup summary from recent commits.',
    runOnStart:  false,              // set true to fire immediately on server start
    onResult:    (out) => slack.send('#daily', out),
    onError:     (err) => logger.error('[daily-report]', err),
  })
  .addCron({
    name:        'health-check',
    schedule:    '*/15 * * * *',    // every 15 minutes
    buildPrompt: () => 'Check all API endpoints and report any that are down.',
    onResult:    (out) => { if (out.includes('DOWN')) pagerduty.alert(out); },
  });

const server = new AgentServer({ triggers, ...opts });
await server.start();
// Cron jobs start automatically with the server
```

### Webhook 触发

```typescript
const triggers = new TriggerBus(engineFactory)
  .addWebhook({
    name:        'github-pr',
    path:        '/webhooks/github',             // registered as POST /webhooks/github
    secret:      process.env.GITHUB_SECRET,      // HMAC X-Hub-Signature-256 validation (optional)
    buildPrompt: (body) => {
      const pr = body.pull_request;
      return `Review PR #${pr.number}: "${pr.title}"\n${pr.diff_url}`;
    },
    onResult: (out, body) => github.postReview(body.pull_request.number, out),
    onError:  (err) => logger.error('[github-pr]', err),
  })
  .addWebhook({
    name:        'jira-issue',
    path:        '/webhooks/jira',
    buildPrompt: (body) => `Analyze Jira issue ${body.issue.key}: ${body.issue.fields.summary}`,
    onResult:    (out) => jira.addComment(body.issue.key, out),
  });
```

**测试一个网点 :**

```bash
curl -X POST http://localhost:3000/webhooks/github \
  -H "Content-Type: application/json" \
  -H "X-Hub-Signature-256: sha256=<hmac>" \
  -d '{ "pull_request": { "number": 42, "title": "Add auth module" } }'
```

### 队列触发器( BallMQ —— 需要) `bullmq`(中文(简体) )

```typescript
import { TriggerBus } from '@backendkit-labs/agent-web';

const triggers = new TriggerBus(engineFactory)
  .addQueue({
    name:        'document-processor',
    queueName:   'documents',           // BullMQ queue name
    connection:  process.env.REDIS_URL!, // Redis URL or connection object
    concurrency: 3,                     // process 3 jobs in parallel
    buildPrompt: (job) => {
      return `Summarize and extract key points from this document:\n\n${job.data.content}`;
    },
    onResult: (out, job) => {
      db.documents.update(job.data.id, { summary: out });
    },
    onError: (err, job) => {
      logger.error(`[queue] Failed to process document ${job?.data?.id}:`, err);
      // The error is re-thrown so BullMQ marks the job as failed and applies retry policy
    },
  });
```

**发布一份工作(从系统中的任何地方) :**

```typescript
import { Queue } from 'bullmq';

const queue = new Queue('documents', { connection: process.env.REDIS_URL! });

await queue.add('process-doc', {
  id:      'doc-456',
  content: 'Full document text...',
}, {
  attempts:    3,
  backoff:     { type: 'exponential', delay: 2000 },
  removeOnComplete: 100,
  removeOnFail:     50,
});
```

### 队列连接选项

```typescript
// URL string
connection: 'redis://localhost:6379'
connection: 'redis://:password@redis-host:6380/1'

// Connection object
connection: {
  host:     'redis-host',
  port:     6380,
  password: 'mypassword',
  username: 'default',
  db:       1,
  tls:      {},            // enable TLS
}
```

### 带有所有选项的 CronTriggerDef

```typescript
interface CronTriggerDef {
  name:         string;                        // unique name for the trigger
  schedule:     string;                        // standard cron expression
  buildPrompt:  (ts: Date) => string;          // returns the prompt to run
  agentId?:     string;                        // override default agent
  runOnStart?:  boolean;                       // fire immediately on server start
  onResult?:    (output: string) => void;
  onError?:     (err: Error) => void;
}
```

* * *

## 无头运输

`HeadlessTransport` 是一个 `Transport` 缓冲所有 `AgentEvent` 对象在内存中而不是在套接字上流出。 内部使用 `TriggerBus` 用于自动运行.

```typescript
import { HeadlessTransport } from '@backendkit-labs/agent-web';

const transport = new HeadlessTransport();

const engine = new AgentEngine({ ...opts, transport });
await engine.run('Generate a daily report');

// All events are buffered
const events = transport.getEvents();
const tokens = events
  .filter(e => e.type === 'chunk')
  .map(e => e.content)
  .join('');

console.log('Final output:', tokens);
```

* * *

## 全面生产实例

完整的生产服务器, 包括 JWT auth, Redis 会话, Prometheus 度量衡, cron 任务, webhook 触发器, 以及 BullMQ 队列处理 :

```typescript
import { AgentServer, JwtAuth, TriggerBus, RedisSessionMetaStore } from '@backendkit-labs/agent-web';
import { createEnterpriseSetup } from '@backendkit-labs/agent-enterprise';
import { ProviderRegistry, DeepSeekProvider } from '@backendkit-labs/agent-core';
import Redis from 'ioredis';

// LLM providers
const providers = new ProviderRegistry();
providers.register('deepseek', new DeepSeekProvider({
  apiKey: process.env.DEEPSEEK_API_KEY!,
  model:  'deepseek-chat',
}));

// Enterprise setup (RAG + 6 agent profiles)
const enterprise = createEnterpriseSetup({
  vaultPath:       process.env.VAULT_PATH!,
  providers,
  defaultProvider: 'deepseek',
});
await enterprise.indexAll();

// Redis
const redis = new Redis(process.env.REDIS_URL!);

// JWT auth
const jwt = new JwtAuth({
  secret:         process.env.JWT_SECRET!,
  sessionIdClaim: 'sub',
});

// Autonomous triggers
const triggers = new TriggerBus(enterprise.engineFactory)
  .addCron({
    name:        'weekly-digest',
    schedule:    '0 9 * * 1',   // Mondays at 9 AM
    buildPrompt: () => 'Generate a weekly digest of all knowledge base changes.',
    onResult:    (out) => slack.send('#general', out),
  })
  .addWebhook({
    name:        'support-ticket',
    path:        '/webhooks/support',
    secret:      process.env.WEBHOOK_SECRET,
    buildPrompt: (body) => `Handle support ticket #${body.id}: ${body.subject}\n${body.description}`,
    onResult:    (out, body) => helpdesk.reply(body.id, out),
  })
  .addQueue({
    name:        'email-processor',
    queueName:   'emails',
    connection:  process.env.REDIS_URL!,
    concurrency: 5,
    buildPrompt: (job) => `Draft a professional reply to this email:\n\n${job.data.body}`,
    onResult:    (out, job) => emailService.send({ to: job.data.from, body: out }),
  });

// Server
const server = new AgentServer({
  port:          3000,
  engineFactory: enterprise.engineFactory,
  auth:          jwt.hook(),
  store:         new RedisSessionMetaStore(redis),
  cors:          ['https://app.company.com'],
  logger:        { level: 'info' },
  rateLimiting:  { max: 60, timeWindow: '1 minute' },
  metrics:       { enabled: true, prefix: 'bk_' },
  maxIdleMs:     30 * 60 * 1000,
  triggers,
});

await server.start();
console.log('Agent server running on :3000');

// Graceful shutdown
process.on('SIGTERM', () => server.stop());
```

## 常见问题

### @backendkit-labs/agent-web 是什么？

HTTP/ WebSocket 服务器层用于代理核心——浏览器已准备好的流媒体代理会话

### 如何安装 @backendkit-labs/agent-web？

在项目目录运行 npm install @backendkit-labs/agent-web，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@backendkit-labs/agent-core（\>=0\.24\.0 \<0\.38\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @backendkit-labs/agent-web 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @backendkit-labs/agent-web 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @backendkit-labs/agent-web 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @backendkit-labs/agent-web 可以商用吗？

@backendkit-labs/agent-web 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @backendkit-labs/agent-web 的下载量有多少？

根据 npm 官方下载统计，@backendkit-labs/agent-web 在 2026/10/08 – 2026/11/06 这 30 天内被下载 2,453 次，日均约 82 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @backendkit-labs/agent-web 还在维护吗？

最新版本 0\.6\.4 发布于 2026/10/28（10 天前）；至今共发布 25 个版本，其中过去 12 个月发布了 25 个；首次发布于 2026/06/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。