@ agent-relay/ sdk (英语)

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

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

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

安装

npm install @agent-relay/sdk zod

概念

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

快开始

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

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.',
});

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

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

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

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

通讯

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

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工具自动被代理曝光.

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 */ 前缀通配符,或流利的上方,并总是将一个受歧视的事件对象交给处理者。 它返回一个未订阅的函数 .

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-driverSDK继续负责公共交货合同.

最低会期合同:

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();

可选的可选管理带

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

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

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

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 迁移

见 移徙指南 详细情况.

发展

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

许可证

阿帕奇 - 2.0