17 篇博文 含有标签「api-design」

你的客服智能体稳定运行了三个月。一次例行模型更新在周二悄然上线。到周三下午，三个下游服务已在静默地解析智能体响应中的错误字段——JSON 键值发生了微妙变化，但没有任何报错。到周四，你追溯到订单完成率下降，原因是某个 JSON 字段从 "status" 被重命名为 "current_state"。模型更新了，智能体版本号仍是 v2.1.0，没有人收到告警。

这正是传统 API 设计从未需要解决的版本管理空白。语义化版本控制（Semver）在能够从规范中确定性地复现输出时才有效。AI 智能体无法做出这种承诺。然而下游服务对其行为的依赖程度，与对任何微服务 API 的依赖一样关键。"我们打了一个发布标签"与"下游消费者受到了保护"之间的鸿沟，从未如此之大。

你的文档说 /summarize 端点会返回一个简明扼要的摘要。这没错。但它每次返回的摘要都不一样，有时会遗漏关键点，偶尔在你忘记在提示词（prompt）中指定格式时返回结构化的 JSON，并在你毫不知情的模型更新后发生无声的性能退化。而这些都没有出现在文档中。

传统的 API 文档记录的是契约：给定输入 X，预期输出 Y。而 AI 驱动的功能从根本上打破了这一模式。这里没有稳定的契约可供记录。同样的提示词、同样的模型、同样的参数 —— 却会产生不同的输出。然而，团队在发布这些功能时，使用的文档风格仍与编写数据库查询文档时如出一辙：一个函数签名、一个返回类型，或许还有一句关于错误代码的说明。

你的文档所描述的内容与功能的实际表现之间的鸿沟，正是开发者信任消亡的地方。

你的 AI agent 在推理、规划和生成自然语言方面表现出色。然后你把它指向企业的 SAP 端点，它接下来花了 4,000 个 token 试图理解一个 SOAP 信封。欢迎来到阻抗失配的世界——这个隐性税收把每一次企业 AI 集成都变成了 token 的焚烧炉。

这种失配不仅仅是 XML 与 JSON 的问题。它是 LLM 思维方式（自然语言、扁平的键值结构、简洁的上下文）与企业系统通信方式（深层嵌套的 schema、特定于实现的命名、分页游标以及数十年积累的协议约定）之间的根本冲突。与人类开发者只需阅读一次 WSDL 文档就可以继续工作不同，你的 agent 在每次调用时都要重新解析这种复杂性。

2023 年，斯坦福大学和加州大学伯克利分校的研究团队做了一项受控实验：他们在 3 月和 6 月分别向 GPT-4 提交了完全相同的提示词，任务非常基础——判断一个数字是否为质数。3 月时，GPT-4 的准确率为 84%。到了 6 月，使用完全相同的 API 端点和完全相同的模型别名，准确率已跌至 51%。没有变更日志，没有通知，没有传统意义上的破坏性变更。

这项实验清晰地揭示了一个在多服务架构中部署 LLM 的团队迟早都会遇到的问题：模型别名不是稳定的契约。当你的下游支付处理器、推荐引擎或合规系统依赖 LLM 生成的结构化 JSON 时，你就建立了一个隐式的 API 契约——而隐式契约会悄无声息地崩溃。

在 2024 年，自动化机器流量在互联网上首次超过了人类流量。Gartner 预测，到 2026 年，超过 30% 的新 API 需求将来自 AI Agent 和 LLM 工具。然而，只有 24% 的组织在设计 API 时明确考虑了 AI 客户端。

这一差距正是生产系统崩溃的地方。并不是因为 LLM 本身表现不佳，而是因为为人类开发者构建的 API 包含了一些默认假设，当调用者是自主 Agent 时，这些假设会悄无声息地失效。Agent 无法请求澄清，无法阅读文档网站，也无法自行判断 422 错误是指“修改你的请求”还是“几秒钟后重试”。

这篇文章是写给那些刚刚发现自己的服务正被 AI Agent 调用，或者即将构建此类服务的后端工程师的。