Agent Relay事件驱动实战5个addListener技巧让Agent在idle瞬间被唤醒【免费下载链接】relayReal time communication for agents. Wake on message, channels, DMs and actions. Useful for orchestrating agents.项目地址: https://gitcode.com/gh_mirrors/relay35/relayAgent Relay 是一个面向 AI Agent 的实时通信编排工具提供频道Channels、私信DMs和动作Actions并支持消息即唤醒Wake on Message机制。本文用 5 个addListener事件监听技巧教你以事件驱动方式编排多 Agent 协作让 Agent 在 idle 空闲的瞬间被精准唤醒彻底告别轮询与忙等 上图是 Agent Relay 的一个真实演示planner、reviewer、adversarial 三个 Agent 围绕同一个 broker 实时辩论所有消息收发与状态流转都由事件驱动完成。这种消息到达 → 立即唤醒 → 继续工作的体验正是addListener要解决的问题。为什么是事件驱动先认识 addListener 这个单一入口轮询每隔几秒问一次有新消息吗是最常见的反面模式浪费 token、响应延迟高还可能漏掉消息。Agent Relay 的答案是把所有事件收敛到一个入口const unsubscribe relay.addListener(message.created, (event) { console.log(${event.envelope.from.handle}: ${event.message.text}); }); unsubscribe(); // 随时干净离场addListener(selector, handler)的 selector 支持三种写法处理器永远收到一个可判别的事件对象写法示例适用场景点分事件名message.created监听某类具体事件前缀通配符action.*、*监听一整族事件流式谓词Predicateagent.status.becomes(idle)按 Agent、频道、提及精准过滤三种 selector 的分发与通配匹配逻辑都在 listeners.ts 中实现SDK 主入口见 agent-relay.ts。上手技巧先跑一句relay.addListener(*, (e) console.log(e.type))给整个系统照一次 X 光看清正在发生哪些事件再决定精确订阅什么。技巧1用点分事件名订阅快速接管消息事件流Agent Relay 把事件按前缀分成四大族用通配符一次订阅一族是搭建观测面observer plane最快的方式relay.addListener(message.*, (event) console.log(event.type)); // 所有消息事件 relay.addListener(action.*, (event) console.log(event.type)); // 所有动作事件事件族事件名何时触发消息message.created/message.updated/thread.reply频道新消息、更新、话题回复私信dm.received/group_dm.received收到一对一或群组私信回执message.read/message.reacted对方已读、添加或移除表情回应动作action.invoked/action.completed/action.failed/action.denied动作被调用、完成、失败或被拒绝状态agent.status.idle/active/blocked/waiting/offlineAgent 会话状态变化活动agent.activity.changedAgent 正在做什么思考、调工具等完整的 selector 到事件类型的映射表定义在 listeners.ts 的 RelayEventMap它同时为 TypeScript 处理器提供了精确的类型推导。技巧2监听 idle 状态让空闲 Agent 在瞬间被唤醒这是标题承诺的核心技巧。Agent Relay 的唤醒机制分两层Broker 层消息被持久化排队投递模式支持immediate、next-tool-call和on-idle。Agent 忙的时候消息不会丢而是等到它 idle 的那一刻自动注入——这就是在 idle 瞬间被唤醒的底层保障投递逻辑见 delivery.rs。SDK 层订阅 Agent 的状态谓词在它变 idle 的瞬间接手下一步工作// 流式谓词只关心 reviewer 这一个 Agent 变 idle 的时刻 relay.addListener(reviewer.status.becomes(idle), () { assignNextReview(); // 立刻派发下一个任务零延迟接力 }); // 等价的点分写法监听任意 Agent 的 idle relay.addListener(agent.status.idle, (event) { console.log(event.agentId, 已空闲可以派活了); });状态谓词的匹配实现见 listeners.ts 的 StatusPredicate。相比发送后 sleep 30 秒再问一次状态事件让编排者的响应时间从秒级降到事件到达即触发 ⚡技巧3频道 提及双重过滤避免 Agent 被无效唤醒在大群里所有消息都唤醒我会导致 Agent 被无关噪音反复打断。Agent Relay 的message.created()谓词支持链式过滤只有目标频道里的、 了我的消息才触发处理器relay.addListener( relay.events.message.created().in(#general).mentions(me), (event) respond(event.message) // 只有真正 我时才动手 );该谓词会先比对频道名再检查mentions列表和正文中的名字两层过滤的实现见 listeners.ts 的 MessageCreatedPredicate。搭配dm.received事件你还能区分群聊里被点名与私聊直接找我两种唤醒路径。经验法则编排者只订阅 提及 关键状态事件普通 Worker 只订阅自己的 DM。唤醒次数少一个量级token 成本同步下降。技巧4用 Typed Action 事件串联多 Agent 协作流水线Agent 之间除了聊天还能互相调用动作Actions。动作是 fire-and-forget 的调用方立刻拿到确认结果稍后以事件形式广播。registerAction返回的句柄自带带类型的谓词构建器处理器里的event.output直接是注册时 schema 推导出的类型无需任何断言const handle relay.registerAction({ name: github.open_pr, description: 为准备好的分支创建 PR, input: z.object({ repository: z.string(), branch: z.string() }), handler: async ({ input }) openPR(input), }); relay.addListener(handle.completed(), (event) { console.log(event.output.url); // 类型完整零断言 });由此可以搭出接力棒流水线Agent A 的动作完成 → 事件触发编排者 → 编排者立刻给 Agent B 发消息 → B 被唤醒继续。四个阶段事件invoked / completed / failed / denied让失败路径同样可编排——监听handle.failed()就能实现自动重试。完整示例见 SDK README 的 Actions 一节。技巧5once() 一次性订阅 错误隔离防止监听器泄漏长时运行的编排程序里两类事故最伤忘了退订的监听器越积越多某个处理器抛异常把整条事件流搞崩。Agent Relay 对两者都有内建答案// 一次性监听首个匹配事件到达后自动退订 relay.once(agent.status.idle, (event) { console.log(${event.agentId} 就绪开始第一轮); });once()在首次命中后自动解除订阅实现见 listeners.ts 的 once特别适合等第一个信号的启动握手场景。常规订阅务必保留返回的unsubscribe函数在 Agent 释放、流水线结束时调用。每个处理器都在 try/catch 中执行异常通过onError钩子上报默认打印警告不会影响其他监听器和事件源——事件流的熔断是内建的。总结把 5 个技巧装进你的编排蓝图技巧一句话口诀关键 API1. 点分事件名 通配符先全景后聚焦addListener(message.*, ...)2. idle 状态唤醒空闲瞬间即派活agent.status.becomes(idle)3. 频道 提及过滤不关我事不唤醒.in(#ch).mentions(me)4. Typed Action 事件完成即接力handle.completed()5. once() 错误隔离一次性、可熔断relay.once(...)/unsubscribe()想继续深入这些文件是事件驱动路径上的路标监听器核心实现packages/sdk/src/listeners.tsSDK 主入口含 addListener 定义packages/sdk/src/agent-relay.tsSDK 官方文档与示例packages/sdk/README.md观测平面设计规格specs/observer-plane.md事件总线harness-driverpackages/harness-driver/src/event-bus.ts多 Agent 演示脚本scripts/demos/sprint-planning.sh、scripts/demos/server-capacity.sh掌握这 5 个技巧后你的编排代码将从不停地问变成被事件推着走——Agent 在该醒的时候醒在无关时保持安静这正是事件驱动多 Agent 系统的全部精髓 【免费下载链接】relayReal time communication for agents. Wake on message, channels, DMs and actions. Useful for orchestrating agents.项目地址: https://gitcode.com/gh_mirrors/relay35/relay创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
