# @agent-relay/sdk 中文文档

规范地址：https://npmcn.com/package/%40agent-relay/sdk/

版本：17\.0\.0
npm 元数据更新时间：2026-11-05T07:53:25.431Z
中文译文更新时间：2026-11-05T17:45:01.841Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40agent-relay/sdk
原文对照：https://npmcn.com/package/%40agent-relay/sdk/?lang=original
项目主页：https://github.com/AgentWorkforce/relay#readme
源码仓库：https://github.com/AgentWorkforce/relay

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

- 包体积（解压后）：107 MB，131 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：3 个
- 首次发布：2026-01-23T12:03:15.327Z
- 最新版本发布：2026-11-05T07:53:25.055Z
- 近 30 天下载量：159376（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：394（近 12 个月 394 个）

## 中文简介

用于代理中继通信的核心类型SDK. SDK赋予特工和应用程序三种公共能力:信息传递,交付,和行动.

## 安装

```sh
npm install @agent-relay/sdk
```

也可以使用：`pnpm add @agent-relay/sdk`、`yarn add @agent-relay/sdk`、`bun add @agent-relay/sdk`

## README

# @ agent-relay/ sdk (英语)

用于代理中继通信的核心类型SDK. SDK赋予特工和应用程序三种公共能力:信息传递,交付,和行动.

使用 `@agent-relay/sdk` 当你的应用程序,服务, 牵引,或工人 已经拥有它的运行时间 并且需要参与代理中继。 使用 `@agent-relay/harness-driver` 当你想要代理Relay启动并监督克洛德,Codex,双子座,OpenCode,或者其他本地取用程序时.

完整文档 : [extrelay.com/docs (英语)](https://agentrelay.com/docs/typescript-sdk) (用于代理和CLI工具的标记下镜像) [agentrelay.com/llms.txt (英语)](https://agentrelay.com/llms.txt)) (中文(简体) ).

## 安装

```bash
npm install @agent-relay/sdk zod
```

## 概念

-   **通讯** 是耐用代理通信:身份,渠道,DM,组DM,线程,反应,收件箱,读取状态,存在,搜索,以及事件.
-   **交付** 是运行时的交接:从Agent Relay中取出耐用信息并注入活的代理程序,服务,应用服务器,浏览器工人,或被取用.
-   **行动** 可发现的业务,包括Zod计划、火灾和遗忘的援引、审计事件,以及 `action.completed` 向听众提供结果.
-   **运行时间** 是可选管理的执行。 守护进程启动、PTY/无头会话、产卵/释放、操纵默认、日志、准备状态和工作流程监督都属于 `@agent-relay/harness-driver`。 。 。 .

## 快开始

`relay.workspace.register(...)` 返回 a **代理客户端** 由注册参与者发送 `relay.addListener(...)` 是单个事件切入点.

```ts
import { AgentRelay } from '@agent-relay/sdk';

const relay = new AgentRelay({
  workspaceKey: process.env.RELAY_WORKSPACE_KEY!,
});

const reviewer = await relay.workspace.register({ name: 'reviewer', type: 'agent' });

await reviewer.channels.join('reviews');

relay.addListener('message.created', async ({ message, envelope }) => {
  if (envelope.channel?.name !== 'reviews') return;

  await reviewer.reply({
    messageId: message.messageId,
    text: 'Received. I will review this thread.',
  });
});

await reviewer.sendMessage({
  to: '#reviews',
  text: 'Reviewer is online.',
});
```

您也可以直接创建新的工作空间 :

```ts
const relay = await AgentRelay.createWorkspace({
  name: 'review-workspace',
});
// persist relay.workspaceKey to reconnect later
```

在一个新过程中将注册代理重新连接到其持续存在的标志上:

```ts
const reviewer = await relay.workspace.reconnect({ apiToken: process.env.REVIEWER_TOKEN! });
```

## 通讯

直播代理客户端覆盖运行期间的通信表面代理需求:频道,DM,组DM,线程,反应,收件箱,和搜索.

```ts
const lead = await relay.workspace.register({ name: 'lead', type: 'agent' });

await lead.channels.create({
  name: 'release',
  topic: 'Release readiness',
});

// `to` is '#channel', '@handle' (DM), or ['@a', '@b'] (group DM)
const { messageId } = await lead.sendMessage({
  to: '#release',
  text: 'Please review the migration guide.',
});

const reply = await lead.reply({
  messageId,
  text: 'Tracking docs feedback here.',
});

await lead.react({
  messageId: reply.messageId,
  emoji: ':eyes:',
});

const thread = await lead.threads.get(messageId, { limit: 50 });
```

何时 `RELAY_ATTEST_SESSION_ID` 存在, 频道帖子, 线索回复, 直接 信件,并且分组信件会自动坚持 `metadata.session_ref` 所以完成的会话重放可以恢复交叉代理的对话. 通过 明确 `metadata.session_ref` 发送或回复时保留该值.

## 行动

动作是 **火灾和遗忘**: 立即引用返回确认, 处理器在注册它的 SDK 过程中运行, 中继器会发出 `action.completed` (或 `action.failed`)给听者——不是对被引用的代理人的暗示. 已注册的动作作为打入的MCP工具自动被代理曝光.

```ts
import { z } from 'zod';

const handle = relay.registerAction({
  name: 'github.open_pr',
  description: 'Open a GitHub pull request for a prepared branch.',
  input: z.object({
    repository: z.string(),
    branch: z.string(),
    title: z.string(),
    body: z.string().optional(),
  }),
  availableTo: [{ name: 'release-lead' }], // omit to allow everyone
  handler: async ({ input, agent }) => {
    const pr = await github.openPullRequest(input);
    // The return value reaches listeners, not the caller — message the caller directly.
    await coordinator.sendMessage({ to: `@${agent.handle}`, text: `Opened ${pr.url}` });
    return { url: pr.url, number: pr.number }; // becomes the action.completed payload
  },
});

relay.addListener(relay.action('github.open_pr').completed(), (event) => {
  console.log(event.output);
});

// Later, if this process should stop exposing the action:
handle.unregister();
```

## 安置情况

`placement.spawn` 需要一个有现场操作处理器的在线直播节点 默认失败 。 队列明确:通过 `failFast: false` 一起行动 带边框 `ttlMs` 等待节点加入是故意的.

设定 `placementSandboxOnly: true` 打开 `RelaycastMessagingClient` 让云 JIT 沙盒出处是全客户的资格要求,或通过 `sandboxOnly: true` 在一个安置请求。 两个沙盒政策开关 默认为 `false`,因此现有的本地和耐用舰队节点仍然符合条件 除非呼叫者选择进入.

对于不受限制的自动安置,已解决 `node` 元数据存在于 当引擎识别可以匹配当前时的结果 名册。 如果可选元数据是 缺少或名册读取滞后;原始识别身份仍然可用.

## 活动

`relay.addListener(selector, handler)` 接受已点出事件名称, a `*`/ 前缀通配符,或流利的上方,并总是将一个受歧视的事件对象交给处理者。 它返回一个未订阅的函数 .

```ts
const unsubscribe = relay.addListener('message.created', ({ message, envelope }) => {
  console.log(`${envelope.from.handle}: ${message.text}`);
});

relay.addListener('action.*', (event) => console.log(event.type));
relay.addListener(reviewer.status.becomes('idle'), () => assignNextReview());

unsubscribe();
```

## 交付

交付是会话交接合同. 中继存储信件; 会话是可以在代理、服务、浏览器工作者或管理下使用中接收信件的东西:

-   Harneses创建具有稳定代理身份的会话.
-   会话宣布了交付模式,可观测事件,动作,生命周期操作等能力.
-   会话收到具有传送内容的持久中继信息并返回明确收件: `accepted`, (中文(简体) ), `delivered`, (中文(简体) ), `deferred`,或 `failed`。 。 。 .
-   `DeliveryRunner` 可将收件箱项目排入会话 `receiveMessage(...)` 合同或遗产 `inject(...)` 适配器.
-   发送操作支持等效键, 因此重试不会重复信件 .

管理着的带子传送,例如向PTY或无头应用程序服务器注入消息,属于 `@agent-relay/harness-driver`SDK继续负责公共交货合同.

最低会期合同:

```ts
import {
  DeliveryRunner,
  MINIMAL_AGENT_SESSION_CAPABILITIES,
  normalizeAgentIdentity,
  type AgentSession,
} from '@agent-relay/sdk';

const session: AgentSession = {
  identity: normalizeAgentIdentity({ id: 'agent_reviewer', name: 'reviewer', handle: '@reviewer' }),
  capabilities: {
    ...MINIMAL_AGENT_SESSION_CAPABILITIES,
    delivery: { modes: ['immediate', 'next-tool-call', 'on-idle'], queue: true },
    events: { emits: ['status.changed', 'tool.called', 'tool.completed', 'file.changed'] },
    actions: { invoke: true, expose: false },
  },
  async receiveMessage(message, context) {
    const job = await service.enqueue({
      id: message.id,
      text: message.text,
      threadId: message.threadId,
      priority: context.priority ?? 'normal',
      deliveryMode: context.mode,
    });

    return job.ready
      ? { status: 'delivered', deliveryId: job.id }
      : { status: 'deferred', deliveryId: job.id, availableAt: job.availableAt };
  },
  onEvent(emit) {
    return service.onStatus((status) => emit({ type: 'status.changed', status }));
  },
  async release(reason) {
    await service.release(reason);
  },
};

await new DeliveryRunner({
  messaging: reviewer.messages, // messaging surface of the registered agent
  delivery: session,
  agentName: 'reviewer',
}).start();
```

## 可选的可选管理带

安装本地执行管理的套接字 :

```bash
npm install @agent-relay/harnesses @agent-relay/harness-driver
```

`create({ relay })` 产出毒剂 **财务报告和审定财务报表** 自动注册,返回相同的客户端形状 `relay.workspace.register(...)`数字 :

```ts
import { claude, codex } from '@agent-relay/harnesses';

const planner = await claude.create({ relay, model: 'sonnet' });
const engineer = await codex.create({ relay, model: 'gpt-5.5' });

await planner.sendMessage({ to: '#reviews', text: `${engineer.handle} let's pair on the migration.` });
```

`@agent-relay/harness-driver` 拥有 :

-   本地经纪人进程启动和连接文件 .
-   PTY和无头吊带运输.
-   Claude 克德克思 双子座 OpenCode 和自定义 CLI 产卵默认.
-   代理生命周期钩,会话元数据,闲置检测,管理放出,并关闭.
-   协调多产卵带的工作流量和监督帮助者.

保留应用程序级消息代码 `@agent-relay/sdk`; 仅在拥有本地代理工艺的边界上添加被套件.

## 从前 V8 SDK 迁移

| 上一个 SDK 表面 | 第8版替换 |
| --- | --- |
| `relay.agents.register(...)` + 键 `relay.as(agent)` 代号交接 | `relay.workspace.register(...)` 返回当前客户端. |
| `relay.sendMessage(...)`, (中文(简体) ), `relay.system()` | 注册与会者的函件: `agent.sendMessage(...)`。 。 。 . |
| `agent.events.on(...)`, (中文(简体) ), `relay.on(...)` | `relay.addListener(selector, handler)` ——单一收听器入站点. |
| `relay.actions.register(...)` 编号 : `relay.actions.invoke(...)` 返回内行结果 | `relay.registerAction(...)`;结果通过 `action.completed`。 。 。 . |
| 喷出方法 `AgentRelay` (单位:千美元)`spawnAgent()`、PTY/无头助手) | `@agent-relay/harnesses` `create({ relay })` + 键 `@agent-relay/harness-driver`。 。 。 . |

见 [移徙指南](https://agentrelay.com/docs/migration) 详细情况.

## 发展

```bash
npm --prefix packages/sdk run build
npm --prefix packages/sdk test
```

## 许可证

阿帕奇 - 2.0

## 常见问题

### @agent-relay/sdk 是什么？

用于代理中继通信的核心类型SDK\. SDK赋予特工和应用程序三种公共能力:信息传递,交付,和行动\.

### 如何安装 @agent-relay/sdk？

在项目目录运行 npm install @agent-relay/sdk，或使用 pnpm add / yarn add / bun add。

### @agent-relay/sdk 支持 TypeScript 吗？

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

### @agent-relay/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @agent-relay/sdk 需要什么版本的 Node\.js？

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

### @agent-relay/sdk 可以商用吗？

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

### @agent-relay/sdk 的下载量有多少？

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

### @agent-relay/sdk 还在维护吗？

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