模式
一个大型市场平台已向外部 Agent 开放卖家工具，最初仅支持单一模型提供商。预订、商务和税务平台也纷纷跟进，推出各自面向 Agent 的接口。这是一种新的接口类别：主要消费者是规划器（planner），而非使用浏览器的人类。这一区别并非表面文章。人类可以从上下文中推断缺失的前置条件，容忍模糊的错误，并手动重试失败的操作。规划器则不能。它需要契约是明确的、确定性的且机器可读的。
机器调用方需要而人类 API 常忽略的内容
大多数公共 API 是为编写代码的开发者设计的，但运行时消费者仍然是阅读文档、检查响应并编写防御性逻辑的人类。Agent 调用方将人类从循环中移除。它们需要三样常常缺失的东西。
机器可读的前置条件
哪些字段在哪些状态转换下是必需的，必须以 schema 而非散文形式说明。例如，预订端点可能仅在 status 为 confirmed 时要求 guest_count，或仅对商务预订要求 tax_id。如果这些信息埋在段落中，规划器只能猜测。应发布一个状态机，包含每次转换的必需字段、允许值和副作用。JSON Schema 或等效的形式化描述不是可选项；它就是接口本身。
确定性的错误分类
错误必须按代码分类，而非按消息分类。规划器需要区分：
- 可重试：瞬时网络故障、速率限制、锁竞争。Agent 可以退避并重试。
- 终止性：无效输入、缺少权限、不支持的状态转换。重试无济于事。
- 需人工介入：模糊的业务规则、需要人工审核、争议。Agent 应升级处理。
如果唯一的信号是自由文本消息，规划器要么硬编码脆弱的字符串匹配，要么放弃。两者都是失败。应发布一组稳定的错误代码，并记录其到这三类的映射，同时在响应体中包含类别，以便无需查找表即可解析。
每个变更调用都需幂等键
规划器可能在超时、崩溃或部分失败后重试某个步骤。没有幂等键，重试的 POST /bookings 可能导致重复预订或重复扣款。该键必须由客户端生成，每个逻辑操作唯一，并由服务器在定义的窗口内遵守。服务器对重复的键应返回相同的响应，而非创建新资源。这不是新概念，但应用并不一致。对于面向 Agent 的接口，每个变更调用都必须强制使用，包括取消和退款。
配额作为契约的一部分
速率限制常常是运营上的事后考虑。对于 Agent 调用方，它们是接口的一部分。应在发现文档中发布速率限制和突发配额，以便规划器进行调度。返回剩余配额头，使 Agent 能在失败前退避。分离交互通道和批处理通道；执行对账的 Agent 不应与结账流程竞争。
一个具体机制：暴露 GET /limits 端点，以机器可读格式返回当前配额、突发窗口和重置时间。在每个响应中包含 X-RateLimit-Remaining 和 X-RateLimit-Reset。规划器随后可以实现令牌桶调度器，遵守已发布的限制，而非通过 429 响应来发现它们。
权衡：维护独立通道增加了运营复杂性，并可能导致批处理通道在交互高峰时段容
治理影响
每个面向 Agent 的端点都需要负责人、弃用策略和版本化变更日志。将 Agent 接口的破坏性变更视为下游系统的生产事故。与面向人类的 UI 变更不同，Agent 无法通过阅读横幅来适应。它会静默失败，或者更糟，采取错误行动。
保留可重放的请求日志，以便关于 Agent 行为的争议可以从证据中解决。日志应包含幂等键、完整的请求和响应、Agent 身份和时间戳。这不仅用于调试；它是信任的基础。当卖家声称 Agent 重复预订了某个时段时，平台必须能够准确展示请求了什么以及返回了什么。
关于发现
面向 Agent 的接口应无需人工干预即可被发现。在众所周知的路径（例如 /.well-known/agent-api）放置机器可读清单，列出端点、schema、错误代码、速率限制和认证方法，这是最低要求。这相当于 Agent 的站点地图。没有它，每个集成都得定制。
结论
首先为机器调用方设计并不意味着忽视人类开发者。它意味着让契约足够明确，使规划器无需猜测即可推理。幂等性、配额和错误语义不是功能；它们就是接口。将它们视为事后考虑的平台会发现，Agent 的失败方式难以调试，更难信任。而将它们作为契约一部分发布的平台，将开启一类可靠、可审计且可安全重试的新型自动化。
封面照片：panumas nikhomkhai / Pexels。