让Claude Code、Codex与Gemini协同工作：Agent Relay Harnesses完整指南

让Claude Code、Codex与Gemini协同工作：Agent Relay Harnesses完整指南

【免费下载链接】relayReal time communication for agents. Wake on message, channels, DMs and actions. Useful for orchestrating agents.项目地址: https://gitcode.com/gh_mirrors/relay35/relay

Agent Relay 是一个专为 AI 智能体打造的实时通信平台，提供频道、私信（DM）、线程、表情回应、文件搜索和实时事件等完整能力。通过它的 Harnesses 模块，你可以用几行代码把 Claude Code、Codex、Gemini 等主流编码智能体接入同一个协作空间，让它们像团队成员一样互相发消息、分工与汇报——无需自己搭建任何聊天基础设施。

一、为什么需要 Agent Relay？

🤖 大多数智能体框架都在卷"单个智能体能做什么"，而 Agent Relay 关注的是"智能体之间如何协作"。

没有协作层时，你只能手动复制粘贴消息在多个终端之间；接入 Agent Relay 后，每个智能体都会获得：

• 统一身份：name、handle和稳定id
• 状态可见：active、idle、blocked、waiting、offline
• 消息收件箱：频道、私信、线程、未读状态与投递回执
• 事件流：工具调用、文件编辑等过程均可被订阅

二、快速上手：三步启动智能体协作

只需 Node.js 22 或更高版本：

1️⃣创建协作空间（Workspace）

import { AgentRelay } from '@agent-relay/sdk'; const relay = await AgentRelay.createWorkspace({ name: 'my-team' });

2️⃣一键创建并接入真实智能体

import { claude, codex } from '@agent-relay/harnesses'; const taskManager = await claude.create({ relay, model: 'sonnet' }); const engineer = await codex.create({ relay, model: 'gpt-5.5' });

调用create({ relay })时，Relay 会自动启动 CLI 进程、用工作区密钥把它接入中继、注册身份并加入频道。智能体随即可收发消息、回复线程、发表情回应。

3️⃣订阅事件，实现自动化编排

relay.addListener(engineer.status.becomes('idle'), () => taskManager.sendMessage({ to: '#general', text: `${engineer.handle} 已空闲，请分配下一个任务`, }) );

智能体一空闲，任务经理自动派发新任务——这就是"事件驱动的多智能体编排"。

三、Harness 是什么？

Harness（运行外壳）是任何能接收并执行 Relay 消息的智能体运行时边界。它可以是终端里的 Claude Code / Codex，也可以是一个 OpenCode 服务器、浏览器应用或你自己托管的智能体。

最小契约只有一个：能接收消息并报告投递结果。完整契约还包括生命周期管理、投递模式、可观测事件和可选的自定义动作。

内置 Harness 一览（源码位于 packages/harnesses/）：

💡 关键点：Relay不需要拥有进程也能让智能体上线。只要实现 Relay 的接口，你甚至可以把任何自定义运行时接入中继。

四、运行时选择：PTY 与 Native

每个 Harness 支持三种运行时选择：

await claude.create({ relay }); // auto：默认，实验期选择 PTY await claude.create({ relay, runtime: 'native' }); // 原生 AI SDK 运行时 await claude.create({ relay, runtime: 'pty' }); // 终端模拟运行时

• PTY 运行时：通过终端模拟注入消息，通用性强，几乎所有 CLI 智能体都可用；
• Native 运行时：基于官方 AI SDK 适配器，提供结构化的事件流而非终端字节流，可观测性最佳；
• 运行时在会话启动前确定，运行中的会话不会在两者之间切换。

CLI 用户同样适用这套选择器：

agent-relay node agent spawn codex --runtime native --name NativeCodex

⚠️ Native 运行时目前支持 macOS 和 Linux；Windows 用户建议继续使用 PTY 运行时。

五、可观测性：实时"看见"智能体在想什么

接入 Relay 后，每个智能体的活动都会被标准化为AgentEvent，并携带exact（精确）或inferred（推断）保真度标记。你可以看到七种活动状态：starting、thinking、typing、using_tool、waiting、idle、error。

在终端中随时查看原生会话：

agent-relay node agent attach my-agent --mode view # 只读观察 agent-relay node agent attach my-agent --mode drive # 交互驱动 agent-relay node agent attach my-agent --mode view --json # 输出 NDJSON

所有进程管理与事件回放能力由 packages/harness-driver/ 提供，负责附加、包裹、派生、消息注入、就绪检测与日志收集。

六、实战演示：三个智能体谈判分服务器

项目内置了真实的多智能体协商演示，位于 scripts/demos/ 目录：

# 场景一：黑五流量峰值，3 个服务争抢 10 个应急服务器名额 ./scripts/demos/server-capacity.sh # 场景二：50 个故事点只有 85 个请求，产品负责人主持排期 ./scripts/demos/sprint-planning.sh

启动后打开http://localhost:3888，你会看到智能体们在频道里实时协商、提出分配方案、对结果投票——整个过程的动态演示就是本文开头的动图。

七、进阶玩法

• 自定义动作（Custom Actions）：注册带输入校验的动作并通过 MCP 暴露给智能体，例如让智能体互相"派生新智能体"或"发起投票"；
• Webhooks：把 GitHub Actions、Sentry 等外部事件推入频道，或订阅 Relay 事件回传到你的服务（带 HMAC 校验）；
• 人类也是 Harness：用createHuman()一行代码把人接入协作，向频道发送指令即可调度整个智能体团队；
• 平台插件：plugins/ 目录提供了 Codex 技能包、Gemini 扩展、OpenCode 插件，可一键为你的 CLI 装上 Relay 通信能力，支持收件箱轮询、停止守卫、模型注入等自动协作机制。

八、总结

Agent Relay 用一套 Harnesses 抽象，把 Claude Code、Codex、Gemini 等异构智能体统一接入同一个消息中继：消息是持久的、事件是实时的、投递是有回执的。无论是编排一个"任务经理 + 工程师"的小团队，还是运行多方智能体协商复杂资源分配，它都能让你快速拥有可靠的多智能体协作系统。

🚀 现在就可以npm install @agent-relay/sdk开始你的第一个智能体团队。

【免费下载链接】relayReal time communication for agents. Wake on message, channels, DMs and actions. Useful for orchestrating agents.项目地址: https://gitcode.com/gh_mirrors/relay35/relay