【免费下载链接】agnes-harness
Agnes Harness: A pluggable agent harness for Forward Deployed Engineering (FDE). Built for trust. Made for the real world.
Agnes Harness 的 MHS（Model Hardware Standard）设备协议，是 AI Agent 安全连接机器人、传感器、相机等物理设备的标准接口。这篇文章用通俗的语言讲清 MHS 的设计思路：双通道通信、安全机制、AI 可用的 7 个设备工具，并展示如何不接硬件直接试用。
什么是 MHS：AI Agent 的"身体"接口
Agnes Harness 把整个系统比喻成一个人：LLM 是大脑，Jev 是小脑，Harness 是记忆，而MHS 就是身体——AI 与物理世界能力之间的接口。
设备（机器人、传感器、相机）提供真实的能力，Agnes Harness 提供任务编排、人工确认和完整记录。三者分工明确：
- 设备（Device）：一台物理机器，或一个替硬件"代言"的桥接进程（比如用厂商 SDK 控制机械臂的电脑）。设备拥有自己的工具、状态、数据源，并自己负责自己的安全。
- AgnesHub：设备连接的枢纽。它验证并转发每一次调用、接收和分发数据、随时可以叫停设备。
- 大脑（AI Agent）：永远不直接和硬件对话，只通过 AgnesHub 行事，AgnesHub 会用设备注册时声明的能力来核对每一个调用。
💡 Agnes MHS 借鉴了 MCP（Model Context Protocol）的 JSON-RPC 2.0 消息格式和工具声明方式，但补充了物理设备真正需要的东西：随时可停、人工接管、实时状态、流式传感器数据。它是 Agnes 自己的协议，与 Anthropic 的同名标准相互独立。
协议完整定义见 packages/mhs/spec/mhs-spec.md，入门指南见 docs/guide/mhs.md。
双通道设计：命令和数据为什么分开
MHS 最重要的架构决策：每个设备开两条 WebSocket 通道，且都由设备主动拨出（设备不需要公网地址或开放端口）。
| 通道 | 地址 | 传什么 | 原则 |
|---|---|---|---|
| 命令通道 | /ws/mhs | 注册、状态、工具调用、进度、停止、暂停 | 消息不能丢 |
| Nerve 通道 | /ws/nerve | 摄像头画面、视频、扫描、遥测、人工操作输入 | 最新的数据最重要，旧数据可以丢 |
分开的意义很直观：一串视频画面再大，也不会延迟一个stop指令的送达。Nerve 通道由配套标准 MOS（Model Observation Standard） 定义，见 packages/mhs/spec/mos-spec.md。
设备连上后发第一条消息mhs/register，一次性自我介绍：我是谁、能做什么（工具）、报告哪些状态、传感器有哪些、能否人工遥控。注册完成后，AgnesHub 保存它的最新状态，任何人都可以随时读取，而不必"叫醒"设备。
五大安全机制：设备安全从不依赖网络
这是 MHS 与普通"设备 API"最大的区别。协议假设枢纽、网络甚至 Agent 都可能在任何时刻坏掉，而设备必须依然安全（安全要求章节）。
1. 停止是一个永远成功的"协议消息"，而不是工具
mhs/stop不是某个设备自己实现的工具，而是协议规定设备在任何时间、任何状态下都必须接受的指令：先让所有执行器零速，再打断进行中的运动调用，并在 2 秒内回复"我停下了哪些动作"。注册还没完成时收到stop，也得照办。
2. 断线自动停车
命令通道断开后，设备必须在 1 秒内停止所有运动，并且重连后不得自动恢复断线前的动作。换句话说：网线一拔，机器人自己就站住了——这不依赖 AgnesHub 是否还活着。
3. 调用先"秒级应答"，再异步执行
设备收到mhs/call后必须在 2 秒内给出接受或拒绝（理由如busy、unsafe、invalid），不能边干活边回复。之后可以上报进度，最终以恰好一个结果结束：done（完成）、interrupted（被叫停）、error（失败）。
4. 人工接管带"死人开关"（Deadman）
支持手动遥控的设备声明控制轴（前进、转向、升降等）和deadman_s：只要超过这个时间没收到输入，设备自动停止所有人工指令的运动。而且规范要求死人开关独立于协议进程运行（推荐独立看门狗）——即使跑 MHS 的进程卡死了，摇杆松手照样能刹住。
5. 参数越界时"钳制"而非报错
参数范围声明的是设备的物理和安全极限。Hub 和设备都会校验：数值超出minimum/maximum时会被钳制到边界执行，并在结果的notes里说明（"移动了 2 米——允许的最大值"），这对 Agent 来说比干脆拒绝更有用。设备还必须对 Hub 发的每一个指令再次强制执行自己的限制（[SAFE-4]）。
MOS 数据通道：传感器数据如何流向 AI
如果关心的是"当前值"（模式、电量、门锁开关），那是状态（State）——设备变化时上报，Hub 保存，随取随读。如果关心的是"随时间变化的流"（摄像头画面、电机温度曲线），那是 MOS 的数据源（Source）。
每个数据源都有类型化声明：种类（image、video、scan、values…）、安装位置mount、视场角、单位、告警阈值、标准角色role（如battery、temperature）。这意味着**一个从未见过该设备的 Hub 或模型，也能识别出"这是电机温度"**并知道它超温了。
两个设计细节值得新手注意：
- 按需流式：Hub 根据"谁在看、谁在录、谁在算"决定每个源的频率和码率。一个有十个传感器但没人关注的设备，几乎不传数据。
- 派生感知格式统一：目标检测、轨迹、定位、转写这类"算出来的结果"，无论由设备端计算还是由 Hub 计算，格式完全一致。
地图与"地点"（maps和places）也是 MOS 的一部分：机器人可以声明一张带命名地点的地图（充电桩、门口、某个房间），于是 Agent 能说"去充电桩"而不是只处理坐标。固定安装的设备（墙上相机、房间传感器）声明localization: fixed和安装位置，Hub 会把它画在地图上。
无硬件试用：4 台示例设备开箱即用
🚀 没有机器人也能完整体验 MHS。开发枢纽dev-hub内置四台示例设备：robot-01（带相机、办公室地图和手动遥控的移动机器人）、lamp-01（可写状态的小台灯）、env-01（房间传感器）、arm-01（带可开关麦克风的机械臂）。
从仓库根目录运行：
pnpm --filter @agnes/mhs build:plugin pnpm --filter @agnes/mhs dev-hub打开http://127.0.0.1:4191/就能看到 Devices（设备卡片）、Flow（Hub 与设备间的调用和数据流）、World（带区域和地标的地图）三个标签页。在终端输入health robot-01 hot或pose robot-01 lost，还能人为制造设备的健康异常和定位丢失，观察整个系统的反应。
想要更大的世界，仓库还内置了examples/mars-world：一座火星基地，浏览器里运行11 台虚拟 MHS 设备——漫游车、火箭跳伞器、实验舱机械臂、气闸、天气站，连"救援宇航员"的完整剧情都可以演练，所有设备都用真实 MHS 协议通信，见 examples/mars-world/README.md。
从 Agnes 里使用设备：7 个设备工具
AgnesHub 以可选插件@agnes/mhs的形式运行在 Agnes 内部（默认监听127.0.0.1:4180）。在插件管理页打开开关后，大脑获得 7 个工具：
| 工具 | 作用 |
|---|---|
list_devices | 列出所有设备：id、类型、可用性、健康、正在做什么 |
read_device | 读取设备状态、健康、位置，以及指定数据源的最新数据（返回图片，相机画面能直接进模型） |
call_device | 调用设备的某个工具，等待最多 50 秒；长任务结束后会唤醒会话 |
set_device | 修改可写状态（如音量） |
stop_device | 停止一台设备，或全部设备 |
watch_device/unwatch_device | 等待条件（如读数越过某个阈值），触发时唤醒会话 |
注意一个刻意的设计：设备工具不需要人工审批。因为设备安全不依赖 Hub 和审批流——设备的自保护（断线停车、死人开关、自有限制）才是安全底线，Hub 只在其之上叠加检查。
设备自身的工具作为call_device的参数传入，所以设备来了又走，大脑的工具列表永远不变。每轮对话开始时大脑还会拿到一份地图与设备的快照；会话中每次设备工具调用都会显示为一张卡片，完整时间轴可以回放审查：
AgnesHub 的完整客户端接口（非标准，仅供大脑、面板等使用）见 packages/mhs/server/hub-api.md。
合规性检查：mhs-check 测试枢纽
"设备说它安全"不等于安全。MHS 提供了自动化的合规套件 mhs-conformance.md：
- 每条消息都有 JSON Schema（2020-12 版本）约束；
mhs-check是一个测试枢纽（端口 8800）：它读取设备的注册信息，自动判断适用哪些档案（Core、Motion、Manual、Pause、Perception、Streaming、Video…），逐一跑场景，对每条需求编号（如[CTL-3]）报告pass/fail/warn/skip/manual。
cd packages/mhs/python uv run python -m agnes_mhs.check # 启动测试枢纽 uv run python examples/sensor.py # 另开终端，接入被测设备最小可运行的示例设备就是packages/mhs/python/examples/sensor.py（房间传感器）和camera.py（H.264 测试图案视频）；TypeScript 版最小设备见packages/mhs/device/example.ts（一盏台灯）。用设备库（Pythonagnes_mhs或@agnes/mhs/device）写自己的设备，注册、重连、参数钳制、死人开关等协议细节都由库代劳，见 docs/guide/mhs-device.md。
⚠️ 但要明白它的边界：通过 mhs-check 只说明设备在受测条件下遵循协议，并不等于给设备"安全认证"。
安全边界与网络建议
最后提醒新手三条红线（来自 MHS 第 14 节）：
- MHS 1.0 自身没有认证和加密。能连到 Hub 的人就能注册设备，流媒体（包括摄像头和麦克风）不加密。
- 它的设计场景是可信的局域网：实验室、工坊、家庭。Hub 和设备应隔离在独立网络或 VLAN，共享网络用
wss://，永远不要把 AgnesHub 暴露到互联网。 - 停止一个 Agnes 任务 ≠ 确认设备安全停下了。
stop_device的回复只告诉你设备停下了什么；断线或结果缺失后，先读取设备状态再重复任何结果未知的动作。
延伸阅读
| 资料 | 路径 |
|---|---|
| MHS 协议主文档 | packages/mhs/spec/mhs-spec.md |
| MOS 观测标准 | packages/mhs/spec/mos-spec.md |
| 合规套件与 mhs-check | packages/mhs/spec/mhs-conformance.md |
| 消息 JSON Schema | packages/mhs/schema/mhs-v1.json |
| MHS 用户指南 | docs/guide/mhs.md |
| 设备库开发指南 | docs/guide/mhs-device.md |
| AgnesHub 客户端 API | packages/mhs/server/hub-api.md |
| 火星基地示例（11 台虚拟设备） | examples/mars-world/README.md |
| MHS 包总览 | packages/mhs/README.md |
MHS 的核心思想一句话总结：模型从不碰硬件，设备永远自己兜底——双通道让控制不被数据淹没，而断线停车、死人开关和自有限制保证即使 AI 和网络全部失灵，物理世界依然安全。
【免费下载链接】agnes-harness
Agnes Harness: A pluggable agent harness for Forward Deployed Engineering (FDE). Built for trust. Made for the real world.
相关推荐
DB-GPT MQTT：物联网设备连接协议
DB GPT MQTT：物联网设备连接协议 引言：物联网数据与AI的完美融合 在万物互联的时代，物联网设备产生的海量数据成为AI应用的重要数据源。DB GPT作
人工智能大模型AI AgentRAG模型推理服务本地部署后端前端终极指南：如何用Odoo实现物联网设备管理与传感器数据采集
终极指南：如何用Odoo实现物联网设备管理与传感器数据采集 Odoo作为一款开源企业应用套件，不仅提供传统的ERP功能，还具备强大的物联网集成能力。本文将详细介
后端企业应用ERPCRMKlipper I2C设备支持：传感器连接指南
Klipper I2C设备支持：传感器连接指南 引言：解决3D打印机I2C传感器连接痛点 你是否曾因I2C传感器连接不稳定而困扰？在3D打印过程中，准确的环境监
嵌入式固件智能硬件
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
