AI Agent如何连接物理设备？一文读懂Anthropic的plumbing spec

前一阵子圈子里有个颇具冲击力的判断下一阶段最值得关注的不是模型本身而是模型调得动什么。ChatGPT 和 Claude 已经证明了大模型能说、能写、能推理可一旦想让 AI 去操作实验室里的离心机、机械臂或化学反应器前面的所有“智能”立刻被一根根物理数据线卡住。几乎每个做 AI 自动实验或机器人控制的团队都在同一个地方消耗了大量时间设备不通接口不匹配协议七零八落。Anthropic 提出的这套被戏称为 plumbing spec 的连接规范恰好撞在这个痛点上。它的目标可以一句话讲完让 AI Agent 不再需要逐一适配各种仪器 SDK 和机器人驱动而是通过一套统一描述和调用方式接入物理设备。换句话说过去你的 Agent 想控制一个机械臂需要先搞定厂商 SDK、串口协议、权限模型、回调机制未来如果这套规范成熟设备只需要暴露一份标准能力描述Agent 就能“看懂”它、调用它。这篇文章会讲清楚几个问题plumbing spec 到底解决什么它和 MCP 是什么关系为什么实验仪器和机器人是这套规范最合适的试验场以及我们作为开发者可以按什么思路提前准备。文章里给出的示例都是教学层面的最小实现用来演示连接思路不是某个官方 SDK 的固定写法。看完之后你至少能判断自己的设备接入项目要不要拥抱这类规范以及从哪一步开始改造最划算。1. 这篇文章真正要解决的问题如果你过去半年做过 AI Agent 相关的项目大概率也遇到过这种情况Agent 的对话能力、推理能力都很成熟但一旦要它执行真实操作比如读取一台示波器的数据、控制机械臂抓取工件、调一台温控设备的参数整个工程就从“写 prompt”退化成了“写驱动兼容层”。真正拖慢开发进度的不是模型而是设备和模型之间的那层“水管”。这套连接规范要解决的核心问题不是“模型能不能理解设备”而是“Agent 用什么标准方式发现设备、描述能力、传递操作指令、接收结果”。这句话拆开看有四层意思第一设备发现。Agent 应当知道当前环境里有哪些设备可用而不是靠人把 IP、端口、设备型号写死在代码里。第二能力描述。设备要能把自己的能力用机器可读的方式暴露出来例如“我有三个通道可以测量温度采样率上限是 100Hz”。能力描述就是一种语义层面的 API 文档。第三操作调用。Agent 需要以统一的方式去调用设备能力而不是每接一台设备就写一套新的 request/response 逻辑。第四结果回传与异常处理。设备执行结果要可靠地回到 Agent错误要有标准格式Agent 才能基于返回结果决定下一步操作。如果只从“API 标准化”的角度看这不算新问题Web 世界早就有 REST、GraphQL、gRPC。但实验室设备和机器人有它特殊的地方很多设备压根没有 HTTP 接口有的是串口、USB、GPIB有的是私有 TCP 协议有的设备能力不能轻易并发调用同一时刻只能做一个物理动作有的设备操作不可逆一旦执行就可能损坏样品或伤害人员。这套规范真正要啃的硬骨头是在这种“混乱而高危险”的环境里抽象出一层让 Agent 能安全调用的公共接口。所以这篇文章的读者我建议分成三类一类是正在做 AI 自动实验、AI 辅助科研的工程团队你们会发现很多痛点被点破了第二类是机器人领域做上层控制的开发者你们会理解为什么 Agent 时代需要重新设计工具接口第三类是对 Agent 行业趋势敏感的架构师你们能从这里判断互操作协议在整个 AI 工具链里会占据什么位置。2. 基础概念plumbing spec 到底是什么先解释为什么叫 plumbing spec。在英文里plumbing 原意是水管系统、管道工程也常被用来比喻“底层支撑系统”。Anthropic 用这个词很符合这套规范的本质它不做决策不产生智能它就像实验室背后管网里的水管和阀门让水能顺畅到达需要的地方。模型是水厂Agent 是调度系统plumbing spec 就是标准化水管接头。用一种更贴近日常的说法这套规范想做的事相当于给实验室设备和机器人装上一排标准化的电源插座。过去每个国家的电器都有不同插头出差要带一堆转换头现在这个规范要统一插孔形状和电压标准让任何 Agent 带着一个“转换器”就能接上任何设备。这个比喻也揭示了一个关键设计哲学它不想接管设备只想定义“交接面”。设备还是由原厂商的驱动和程序控制但对外暴露的接口形式是统一的。Agent 不需要关心设备内置的 PID 控制算法、不需要知道机械臂的逆运动学怎么做它只需要按规范发出“移动到坐标、夹取物体、读取结果”这类高层指令底层的复杂逻辑由设备端保留。在这里必须提一下 MCP也就是 Model Context Protocol。Material 里的信息显示MCP 同样是 Anthropic 推动的开放协议它解决的是模型与外部工具、数据源之间的连接问题让 AI 应用可以通过统一协议调用 API、访问数据库、操作网页。从趋势看plumbing spec 更像是把 MCP 这套“模型-工具”抽象思路延伸到物理设备域MCP 让模型能调 SaaS 工具plumbing spec 让 Agent 能调硬件。它们不是替代关系而是互补关系。可以这样理解MCP 定义的是“AI 与数字工具的会话方式”plumbing spec 定义的是“AI 与物理设备的操作方式”。很多开发者第一次看到这套概念时会把它误解为一个新的框架或 SDK。它确实可能包含参考实现但规范和框架的定位完全不同。框架是你写的代码跑在里面的平台规范是大家都要遵守的接口约定。框架可以各自为战规范必须形成行业共识。Anthropic 如果只是自己搞一套 SDK那充其量是自家产品的工具链只有把它做成开放规范让仪器厂商、机器人厂商都愿意采纳才能真正解决设备碎片化问题。{ schemaVersion: 1.0, deviceId: thermo-001, deviceType: temperature-control, capabilities: [ { name: set_temperature, input: { targetCelsius: { type: number, min: -20, max: 120 } }, executionMode: blocking, timeoutMs: 30000, safety: requires_confirmation }, { name: read_temperature, input: { channel: { type: integer, min: 1, max: 8 } }, executionMode: immediate, timeoutMs: 5000 } ] }上面这段 JSON 是一种“设备能力描述”的示意。你没有看错这个思路本质上就是把设备的 API 文档变成机器可读的配置文件。Agent 拿到这份描述后不需要在代码里写死“调用这台设备的方法”而是动态解析出它支持的操作、参数范围、执行模式和超时时间。这个能力描述文件就是 plumbing spec 最核心的组成部分之一。3. 为什么先拿实验室设备和机器人“开刀”看到标题里的 lab kit 和 robots你可能会问为什么不是先统一工厂设备或者先统一智能家居这里其实藏着很现实的产品策略。实验室器材和机器人这两个领域都有着极高的设备碎片化程度和极强的自动化需求它们是最需要标准化、也最容易验证标准价值的场景。先看实验室设备。科学研究领域有个长期痛点仪器自动化程度低各种仪器之间很难联动。做一轮药物筛选实验可能要同时控制液体处理工作站、酶标仪、培养箱、离心机。这些设备来自不同厂商通信方式五花八门有的用串口有的用 USB有的只提供 Windows 下的动态链接库有的只能通过打印机并口输出结果。实验室里最先进的设备和技术最原始的连接方式并存这是常态。如果只靠一个团队去对接所有这些设备工程量巨大而只要转换思路让设备厂商按标准暴露能力描述上游开发者就能基于一套规范编写通用调度逻辑。这才是 plumbing spec 真正的价值洼地不是让某一家设备自动化而是让整个实验室的异构设备都能成为 Agent 的“可调用工具”。再看机器人。机器人的问题更复杂但也更典型。大家熟知的 ROS、ROS 2 已经是机器人领域事实上的中间件标准但它解决的是节点通信问题不是“Agent 调用设备”的问题。你想让一个大模型 Agent 控制一台机械臂仍然需要理解机器人的话题结构、服务接口、坐标系、运动学库等一大堆知识。这对 Agent 来说负担太重而且容易出错。更重要的是机器人操作比调用普通软件工具更危险。机器人一旦接收错误指令可能造成物理损坏甚至人身伤害。所以在机器人场景里规范设计必须特别考虑安全边界光有“能不能调”还不够还要解决“能不能轻轻调、能不能停下来、能不能回滚”的问题。这也解释了为什么连接规范需要在抽象层里单独把安全机制作为一等公民来设计。从商业角度看这两个领域还有一个共同点愿意为自动化付钱。科研机构追求实验效率制造业和物流业追求机器人部署速度。对它们来说统一的连接规范不是锦上添花而是能够显著压缩工期、降低集成成本的刚需。Anthropic 选择从最难的场景切入一旦这套规范能在这两个场景站稳脚跟向其他设备域扩展就只是时间问题。4. 核心架构一条从 Agent 到设备的数据通路基于现有材料的描述和行业常理推断一个完整的 plumbing spec 架构应该包含几个层次。虽然我们拿不到官方文档的全部细节但这几个层是任何设备连接规范都绕不开的可以作为理解框架。第一层是设备发现层。设备连接到网络之后需要向某个注册中心或者 Agent 广播自己的存在。在实验室环境里发现可以通过 mDNS、MQTT 等协议实现在机器人场景里可能是通过 ROS 2 的节点发现机制。这层要解决的核心问题是Agent 怎么知道“现在有哪些设备在线”。如果设备数量和类型很多这层还需要支持按能力和位置过滤。第二层是能力描述层这是整个规范的信息基础。设备用统一的 schema 描述自己支持哪些操作、参数范围、功耗要求、安全性要求等。能力描述的好坏直接决定 Agent 能否正确调用设备。比如一件液体处理设备它可能支持“吸取液体”“排放液体”“移动移液头”这些操作每个操作都有参数要求和允许的取值范围。能力描述要做到精确、完备、机器可读。第三层是会话与执行层。Agent 通过标准化的指令格式向设备发送操作请求设备端执行后返回结构化结果。这一层还应该定义同步和异步两种模式快速读取用同步请求长时间运转的设备操作比如培养箱加热到指定温度用异步任务加状态轮询。执行层还必须处理超时、取消、进度上报等运维语义。第四层是安全与权限层。物理世界的设备调用必须有比普通 API 调用更严格的权限控制。这层至少要做三件事一是身份认证确认调用者是谁二是操作授权确认调用者有没有权限执行某个物理操作三是风险干预遇到危险操作时可以要求人工确认、限流或者自动熔断。第五层是审计与观测层。所有指令和结果都应记录日志方便事后审计。在科研场景审计日志本身就是实验记录的一部分在工业场景审计日志是合规要求。观测层还要收集设备健康状态帮 Agent 判断当前是否适合执行操作。这五层组合在一起才构成一条完整的“数据通路”Agent 发现设备读取能力描述通过授权后发送指令设备执行并回报结果全程记录审计日志。用一句话总结架构的核心设计思想让 Agent 与硬件之间的交互向人类操作员看齐。人类操作设备时会先看设备铭牌和说明书再确认按钮功能按下按钮后观察反应遇到危险先停手。plumbing spec 就是把这套人类操作员的心智模型翻译成 Agent 可以执行的协议。5. 一个最小实现思路Agent 如何协调一台实验设备理论讲得再多不如一个实际演示印象深。为了让你对这套连接方式有直观理解我们假设要写一个最小 Demo一个 Agent 通过“plumbing 风格”的设备描述控制一台温控设备先读取当前温度再设置新温度然后确认设置结果。这个例子是教学演示不依赖任何真实的官方 SDK。如果你用的是 OpenAI、Anthropic 或其他模型思路是一致的模型不会直接调用硬件而是通过工具调用机制触发我们实现的设备客户端。第一步准备好设备描述文件。我们在上一节的 JSON 基础上把 read_temperature 和 set_temperature 作为两个能力暴露出来。设备客户端启动时加载这个文件并注册到 Agent 的工具列表里。第二步编写设备客户端。设备客户端负责把标准化的能力调用翻译成设备厂商的私有协议。这是一个非常关键的分层上层统一下层适配。设备厂商 SDK 的事情由客户端完成Agent 不需要知道。# 文件路径device_client.py # 演示代码只说明分层思路不依赖特定协议 import json class ThermoController: def __init__(self, descriptor_path): with open(descriptor_path, r, encodingutf-8) as f: self.descriptor json.load(f) def get_tool_schemas(self): # 将设备能力描述转成 Agent 能识别的工具 schema tools [] for cap in self.descriptor[capabilities]: tools.append({ name: cap[name], description: f调用 {self.descriptor[deviceId]} 的 {cap[name]} 能力, parameters: cap[input] }) return tools def call(self, capability_name, params): # 实际项目中这里需要把调用翻译成设备厂商的私协议 cap self._find_capability(capability_name) if cap is None: raise ValueError(funknown capability: {capability_name}) # 第 1 步参数校验确保在设备允许范围内 self._validate_params(cap, params) # 第 2 步执行请求这里用 mock 数据模拟设备返回 if capability_name read_temperature: # 模拟从设备读取温度 return {channel: params[channel], temperatureCelsius: 23.5} elif capability_name set_temperature: # 模拟设置温度这里应该有真实指令下发 return {status: accepted, targetCelsius: params[targetCelsius]} raise ValueError(funsupported capability: {capability_name})这段代码里最值得注意的地方是get_tool_schemas方法它把设备的 JSON 能力描述动态转换成 Agent 工具调用框架需要的 schema。这意味着将来接入一台新设备时只要设备提供符合规范的能力描述文件我们不需要改 Agent 的调度逻辑直接加载新客户端即可。这就是统一抽象层带来的改变从“每台设备写一套集成代码”变成“每台设备写一个翻译器”。第三步搭建 Agent 主流程。Agent 收到用户请求后需要判断当前任务涉及哪些设备。为了让过程简单这里用一个非常轻量的方法把工具 schema 交给大模型让模型自己决定调用哪个工具。# 文件路径agent_demo.py # 演示代码模拟 Agent 调用温控设备 import json from device_client import ThermoController def run_agent(user_query): controller ThermoController(device_descriptor.json) tools controller.get_tool_schemas() print(Agent 可用的工具能力) for tool in tools: print(f - {tool[name]}: {tool[description]}) # 实际项目里这里会把 tools 交给大模型让模型生成 tool call # 我们在这里模拟模型的决定用户要求读温度所以先读通道 1 mock_tool_call {name: read_temperature, params: {channel: 1}} print(f\n模型决定调用: {mock_tool_call[name]} {mock_tool_call[params]}) result controller.call(mock_tool_call[name], mock_tool_call[params]) print(设备返回:, json.dumps(result, ensure_asciiFalse, indent2)) # 模型看到结果后决定设置温度到 37 度 mock_tool_call_2 {name: set_temperature, params: {targetCelsius: 37.0}} print(f\n模型决定调用: {mock_tool_call_2[name]} {mock_tool_call_2[params]}) result_2 controller.call(mock_tool_call_2[name], mock_tool_call_2[params]) print(设备返回:, json.dumps(result_2, ensure_asciiFalse, indent2)) if __name__ __main__: run_agent(请先读取 1 号通道温度然后设置仪器温度为 37 摄氏度)这里我故意简化了模型调用环节没有直接调任何模型 API因为重点不是模型调参而是设备接入的触发链路。真实项目里你会把tools列表交给模型 API在返回的 tool_call 里解析函数名和参数然后再调用controller.call。第三步的验证也很直接。运行这段脚本预期输出类似下面这样Agent 可用的工具能力 - set_temperature: 调用 thermo-001 的 set_temperature 能力 - read_temperature: 调用 thermo-001 的 read_temperature 能力 模型决定调用: read_temperature {channel: 1} 设备返回: { channel: 1, temperatureCelsius: 23.5 } 模型决定调用: set_temperature {targetCelsius: 37.0} 设备返回: { status: accepted, targetCelsius: 37.0 }能走到这一步说明最小流程已经跑通Agent 感知到设备能力按统一格式发出调用设备客户端翻译并执行再返回结构化结果。如果你要把它接上真实设备需要替换的只有controller.call里的模拟逻辑把读取温度和设置温度翻译成真实设备 SDK 或串口指令。其他部分包括能力描述加载、工具 schema 生成、Agent 调度都可以复用。6. 安全边界的优先级必须高于功能开发如果你把这个 Demo 直接搬到真实设备上第一件需要考虑的事情不是功能完整性而是安全边界。因为软件 API 调用失败顶多报错硬件操作失败可能导致设备损坏、实验失败甚至人员受伤。这里要明确一个底线Agent 不应该拥有对物理设备不受限制的控制权。在 autopilot 式的自动实验系统里模型天然会尝试连续执行多个步骤这本身就是风险。设想一下一个 Agent 在执行化学实验时如果某个步骤发生了意外反应它应该有能力察觉到异常并停止操作而不是继续执行下一步。因此plumbing spec 的安全设计至少要覆盖这几个方面。第一确认模式分级。并不是所有工具调用都需要人工介入否则自动化的意义就消失了。合理做法是把设备操作按风险分为三个等级低风险的直接执行比如读取传感器数值中风险的自动执行但记录日志比如设置允许范围内的温度高风险的必须人工确认比如开始运行一个可能持续数小时且涉及危险样品的实验流程。第二全链路参数校验。模型生成的参数必须经过设备描述文件中的声明范围校验。如果你只做代码层面判断很容易漏掉一些边界条件比如设置的升温速率是否超出设备支持上限。设备能力描述文件里的每一项参数限制都应该成为运行时校验的依据。第三熔断与急停。物理操作链路必须有“急停”语义。在协议层这意味着要支持取消正在执行的任务在执行层这意味着设备客户端要具备某种停止机制不管是通过厂商 SDK 的 stop 方法还是通过发送串口指令。急停动作应该比普通操作有更高的优先级。第四审计日志完整。每次 Agent 调用需要记录调用者、时间、执行参数、返回结果、异常信息。这不仅是事后追责也是实验可复现性的基础。可以让模型在执行任务前先说明“我打算做哪几步”执行过程中再逐步执行每一步都留痕。第五权限隔离。设备控制服务应该和 Agent 主服务保持网络隔离Agent 只通过指定的网关访问设备不直接暴露设备内部端口。这个思路和微服务架构里的 API 网关是一致的但在硬件场景里更加重要因为设备固件往往没有现代网络安全能力。如果把这几点落实Agent 操作设备的行为才算是被“约束在安全护栏里”。否则你得到的不是一个自动实验系统而是一个能够自行移动机械臂的潜在风险源。7. 常见问题与排查思路无论采用 Anthropic 提出的这套思路还是自建一套设备接入规范开发过程中都会遇到类似问题。这里列出几个高频问题对照排查可以省不少时间。问题现象可能原因排查方式解决方案Agent 无法连接设备服务IP 配置错误或端口未开放先 ping 排查网络连通性再用 telnet 或 nc 测试端口修正连接配置确认设备服务开启调用 API 时连接超时网络代理配置异常或目标地址不可达用 curl 直接请求测试接口观察错误码检查代理设置和防火墙规则设备能力描述加载失败JSON 格式错误或字段版本不兼容本地解析 JSON打印报错信息用 schema 校验工具检查描述文件模型调用了不存在的工具名工具 schema 没有正确注册打印 Agent 拿到的 tools 列表检查设备客户端 get_tool_schemas 返回内容参数越界但设备没有拒绝设备客户端缺少参数校验逻辑查看调用日志中的入参在客户端按能力描述声明范围做校验设备返回结果无法解析底层协议返回格式不标准抓包查看原始报文在客户端适配层转换成统一结果格式操作执行到一半无法停止协议层缺少取消语义查看设备状态和任务队列实现急停接口加入取消任务机制高权限操作被误执行缺少确认模式分级检查权限配置和确认机制高风险操作强制走人工确认流程这里重点说一个很多人忽略的点连接超时问题。搜索热词里出现了 “unable to connect to anthropic services” 这类报错很多开发者第一反应是代码问题。但实际上这类连接错误绝大多数发生在网络层DNS 解析失败、网络代理设置异常、目标服务当前不可用、公司内网对特定域名做了策略限制。排查顺序是先确认网络能否访问目标服务再确认代理环境是否设置正确然后检查 API Key 权限最后才看代码逻辑。不要一上来就质疑 SDK 有 bug。另外一个容易被忽视的问题是设备客户端的状态管理。真实设备往往不能像 HTTP 服务那样无状态并发处理请求。比如温控设备同一时间只能接受一个设置指令机械臂正在移动时新指令要么排队要么拒绝。因此设备客户端必须有指令序列化或排队的机制否则并发调用会破坏设备状态产生难以排查的间歇性故障。8. 最佳实践与工程建议不管 Anthropic 这套规范最终能走多远它背后揭示的开发思路是值得提前吸收的。如果你正在规划 Agent 接入硬件设备下面这几条实践可以帮你少走弯路。第一设备描述先行。不要等代码写完了再补描述文件。先从设备里抽象出能力模型定义好“它支持哪些操作、参数范围、执行模式、安全级别”再做实现。能力模型定义清楚了后面的客户端开发就是在填翻译细节。第二所有物理调用都走统一网关。不要让 Agent 直接持有设备驱动实例更不要让 Agent 直接访问设备内网。统一网关是权限控制、审计日志、熔断机制的天然落点。如果一开始就把 Agent 和设备直连后期要加安全层会非常痛苦。第三把设备适配器做成插件。每个设备一个适配器包通过统一接口注入系统。这样接入新设备时核心调度代码不用改只需要新增一个适配器并注册设备描述。这套做法是软件工程里依赖倒置原则在硬件集成上的应用。第四日志结构化带上 request_id。Agent 一次任务会连续多次调用设备。如果日志没有全局关联 ID出了问题很难还原整个操作链路。建议每次 Agent 任务生成一个 trace_id所有设备调用日志都携带这个 ID方便追踪。第五异常路径要设计成第一公民。很多 Agent 项目做 happy path 很顺利一旦设备返回错误Agent 就陷入了死循环或直接放弃。好的做法是定义一套设备错误枚举把“设备忙”“设备未就绪”“参数越界”“超时”等错误明确区分并给 Agent 提供错误处理策略比如重试、换方案、请求人工介入。第六先在新环境小规模试点。物理世界有太多不可控变量哪怕模拟环境里跑通了一百次第一次接真机也建议在受控环境里先跑。可以先让 Agent 只读设备状态不执行写操作确认稳定后再放开低风险操作最后再开放高权限操作。这叫灰度上线对机器人控制尤其重要。第七保持对 MCP 等协议演进的关注。plumbing spec 不是孤立出现的它和 MCP 共同指向一个趋势AI 应用的接口层正在从“每个项目各写一套”走向“行业级开放协议”。提前学习 MCP 的工具调用规范、资源访问模型会让你对接未来协议时更容易理解设计意图。9. 总结与后续学习方向现在回看文章开头的问题为什么 Intelligent Agent 离物理世界总差一步答案就藏在 plumbing 这个词里。模型负责聪明而让聪明能落地的那几千行设备适配代码才是真正的成本所在。Anthropic 提议这套规范的意义是试图把“给 Agent 接水管”这件脏活累活标准化。本文没有给出一个可以立即拿到的官方 SDK 文档因为从现有信息看这套规范还处于行业推动阶段具体实现细节会继续演进。但它的架构方向已经清晰设备发现、能力描述、统一调用、安全边界、审计日志这些是任何设备接入 Agent 的系统都需要的核心能力。如果你想提前掌握主动权下一步可以这样做先去跑通一个 MCP 的最小工具调用示例理解模型如何通过工具 schema 调用外部能力然后把你手头最常用的一台设备用能力描述 JSON 写出它的“能力清单”不用急着写代码先梳理清楚它到底能做什么、不能做什么最后选一个只有读取权限的开放接口写一个最小客户端完成一个“读取设备状态 → 返回给模型 → 模型判断结果”的闭环。这套路线做完你手里的不是某个具体厂商的绑定技能而是一种通用的设备接入思路。将来无论业界最终采纳的是 Anthropic 的 plumbing spec还是其他类似标准你都能快速迁移和适应。对工程师来说理解趋势比追逐某个 API 名称更有价值。