REST 已老，AI 时代的智能体需要怎样的 API？(本篇免费）

大家好我是Tony Bai。在过去的十几年里如果你问任何一位后端工程师“我们应该如何设计 API”得到的答案几乎是统一的RESTful。我们将世界抽象为一个个“资源Resources”用名词来命名 URI比如/users,/orders用 HTTP 动词GET, POST, PUT, DELETE来表达对这些资源的操作。这套基于 CRUD创建、读取、更新、删除的法则优雅地统治了移动互联网和微服务时代。然而时代变了。当我们步入 AI 时代尤其是当各种大语言模型LLM驱动的智能体AI Agent开始接管我们的软件系统时一个尖锐的矛盾浮出水面这群“硅基同事”在面对我们精心设计的 REST API 时表现得像个无所适从的笨蛋。今天我想和你探讨一个极其现实的工程问题为什么在 AI 时代统治后端十年的 REST 架构正在失效我们又该如何为 AI 智能体设计下一代接口——Agentic APIAI 智能体的“认知障碍”REST API 的三大罪状为了理解 REST 的局限性我们不妨先来做个角色互换。假设你现在不是一个人类工程师而是一个被赋予了任务的 AI Agent。你的主人对你说“帮我把昨天那个发错的订单取消掉并给客户退款。”作为 Agent你拥有一个极其强大的大脑比如 GPT-5.x 或 DeepSeek-V3.x并且你被授权访问公司内部的订单系统 API。你兴冲冲地查看了该系统的 Swagger 文档看到了以下几个端点GET /orders/{id}(获取订单)PUT /orders/{id}(更新订单)DELETE /orders/{id}(删除订单)POST /refunds(创建退款)这时候你的“认知障碍”出现了。罪状一意图的丢失你要“取消订单”但在 REST 的世界里并没有一个叫“取消”的操作。你应该调用DELETE /orders/{id}吗如果你真的这么做了你可能就把这条订单的物理记录从数据库里抹掉了这在真实的电商系统中是灾难性的通常我们需要软删除或者状态流转。还是说你应该调用PUT /orders/{id}并在 JSON Payload 里传一个{status: CANCELLED}这听起来合理一些但如果你传的是{status: DELETED}呢API 会报错吗REST API 强迫调用者去猜测后端的业务逻辑映射。对于人类开发者我们可以通过阅读厚厚的 API 接入文档或者直接去问写这个接口的同事来澄清。但对于 AI Agent它只能基于常识去“猜”。当 AI 开始猜你的系统设计时就是灾难的开始。罪状二原子性与编排的噩梦更糟糕的是主人的任务是“取消订单并退款”。在 REST 架构下订单资源/orders和退款资源/refunds通常是分离的。AI Agent 必须自己完成以下编排调用PUT /orders/{id}将状态改为CANCELLED。解析步骤 1 的响应确认成功。调用POST /refunds并小心翼翼地把订单的金额、支付流水号等信息拼装到 Payload 中。如果步骤 1 成功了但步骤 2 因为网络超时失败了怎么办AI Agent 需要具备复杂的错误恢复机制和分布式事务处理能力比如发起撤销操作。我们把极其复杂的系统状态一致性问题推给了客户端AI。罪状三权限的过度宽泛为了让 AI 能够完成上述操作你需要给它分配什么样的权限在传统的 OAuth 2.0 体系中你可能不得不给它order:write和refund:write权限。这意味着这个 AI Agent 不仅能取消订单它还能修改订单金额甚至能随意发起退款REST API 以“资源”为粒度划分权限这对于非确定性的 AI 来说权限敞口太大了。我们真正想给 AI 的权限是“仅限取消特定状态的订单”但这在传统的 REST 模型中极难优雅地表达。破局之道从“面向资源”到“面向任务”面对上述痛点业界最近非常流行一种解决方案让 AI 使用工具Tool Calling / Function Calling。比如 Anthropic 推出的 MCPModel Context Protocol协议它的核心思想是在 AI 和系统之间架设一个中间件MCP Server将系统的能力包装成一个个具体的 Tool工具暴露给 AI。这确实缓解了部分问题AI 可以直接调用名为cancel_order_and_refund的工具了。但请注意这治标不治本。这相当于我们在后端依然写着糟糕的、极难编排的 REST API然后派人写了一堆中间层胶水代码Glue Code来适配 AI。随着系统变得复杂维护这些“胶水工具”的成本将呈指数级上升状态同步和权限控制的难题依然存在。我们真正需要的是一场后端架构范式的革命从源头上设计对 AI 友好的 API。这就是本微专栏要向你隆重介绍的Agentic API理念。Agentic API 的核心思想是放弃将世界强行扭曲为“资源名词”回归人类和 AI 最自然的交流方式——“任务与意图动词”。我们来看一个对比。传统 REST API 的思维模式这里有一个Order资源。你可以对它执行POST,GET,PUT,DELETE。Agentic API 的思维模式这里有一个业务系统。你可以执行CANCEL取消订单,REFUND发起退款,NOTIFY发送通知等明确的任务。我们用一张简单的时序图来对比一下这两种模式下AI Agent 完成“取消并退款”任务的复杂度差异在 Agentic API 模式下意图极其明确API 端点本身就是一个清晰的动词或动词组合AI 不需要猜测PUT到底意味着什么。后端掌控状态复杂的编排逻辑改状态、调退款接口、处理分布式事务被收敛到了后端。后端永远是状态的最终防线。权限精准控制我们可以给 AI 颁发一个名为action:cancel_and_refund的细粒度 Token即使 AI 产生幻觉想去改订单金额也会被 API 网关直接拦截。实战演练用 Go 构建你的第一个 Agentic API光说不练假把式。接下来我们将用 Go 语言从零开始将一个传统的 REST 接口改造为 Agentic API。假设我们正在开发一个博客系统我们需要一个接口让 AI 帮我们“总结一篇文章的核心观点”。项目目录准备请确保你已安装 Go 1.21 或以上版本。我们将使用标准库net/http来保持代码最简。创建一个新目录并初始化模块mkdir agentic-api-demo cd agentic-api-demo go mod init agentic-demo touch main.go传统的 RESTful 实现 (反模式)在传统的 CRUD 思维下很多开发者可能会这么设计让客户端发送一个POST /documents/{id}/summary请求或者使用一个万能的PATCH /documents/{id}带上一个actionsummarize的字段。这虽然能工作但语义不够清晰扩展性极差如果明天需要翻译、提取关键字呢。Agentic API 的实现思路在 Agentic API 的设计中我们提倡使用明确的动词驱动路由。针对这种数据处理类的任务我们可以定义一个COMPUTE或ANALYZE大类。让我们在main.go中写下这段优雅的代码// ch01/agentic-api-demo/main.go package main import ( encoding/json fmt log net/http strings ) // AgenticRequest 代表了 AI 智能体发来的标准任务请求 type AgenticRequest struct { // 明确的意图动作 Action stringjson:action // 动作的目标上下文 (例如文档ID) ContextID stringjson:context_id // 动作需要的特定参数 Parameters map[string]interface{} json:parameters,omitempty } // AgenticResponse 代表了返回给 AI 的标准结构化响应 type AgenticResponse struct { Status string json:status// SUCCESS, FAILED, REQUIRE_CONFIRM Result interface{} json:result,omitempty Message string json:message,omitempty } func main() { // 定义一个面向动作的路由前缀 http.HandleFunc(/api/v1/actions, actionHandler) fmt.Println(Agentic API Server started on :8080) log.Fatal(http.ListenAndServe(:8080, nil)) } // actionHandler 充当了“任务调度中心” func actionHandler(w http.ResponseWriter, r *http.Request) { if r.Method ! http.MethodPost { http.Error(w, Only POST is allowed for actions, http.StatusMethodNotAllowed) return } var req AgenticRequest if err : json.NewDecoder(r.Body).Decode(req); err ! nil { sendResponse(w, http.StatusBadRequest, FAILED, nil, Invalid JSON payload) return } // 核心基于 Action (动词) 进行路由分发而不是基于资源名词 switch strings.ToUpper(req.Action) { caseSUMMARIZE: handleSummarize(w, req) caseTRANSLATE: // handleTranslate(w, req) sendResponse(w, http.StatusNotImplemented, FAILED, nil, Action TRANSLATE not implemented yet) default: sendResponse(w, http.StatusBadRequest, FAILED, nil, fmt.Sprintf(Unknown action: %s, req.Action)) } } // handleSummarize 处理具体的总结任务 func handleSummarize(w http.ResponseWriter, req AgenticRequest) { docID : req.ContextID if docID { sendResponse(w, http.StatusBadRequest, FAILED, nil, context_id (Document ID) is required) return } // 解析可选参数 (Agentic API 应该允许 AI 传入控制参数) maxLength : 100// 默认值 if ml, ok : req.Parameters[max_length].(float64); ok { maxLength int(ml) } // 模拟从数据库获取文档并进行总结的复杂逻辑 log.Printf(Executing SUMMARIZE for doc: %s, max length: %d\n, docID, maxLength) // 模拟生成的摘要 mockSummary : fmt.Sprintf(这是关于文档 %s 的核心总结长度被限制在 %d 字以内Agentic API 是未来的趋势。, docID, maxLength) // 返回标准化响应 sendResponse(w, http.StatusOK, SUCCESS, mockSummary, Document summarized successfully) } // 统一的响应封装助手 func sendResponse(w http.ResponseWriter, statusCode int, status string, result interface{}, message string) { w.Header().Set(Content-Type, application/json) w.WriteHeader(statusCode) resp : AgenticResponse{ Status: status, Result: result, Message: message, } json.NewEncoder(w).Encode(resp) }运行与验证在终端运行该代码go run main.go现在假设你是一个 AI Agent你决定执行“总结文章”的任务你可以构造如下清晰的 Payload 发送给后端curl -X POST http://localhost:8080/api/v1/actions \ -H Content-Type: application/json \ -d { action: SUMMARIZE, context_id: doc_9527, parameters: { max_length: 50 } }你会得到一个标准化的、极易解析的响应{ status: SUCCESS, result: 这是关于文档 doc_9527 的核心总结长度被限制在 50 字以内Agentic API 是未来的趋势。, message: Document summarized successfully }看出区别了吗我们建立了一个统一的/actions门户。AI 只需要指明它想做什么Action: SUMMARIZE针对什么目标ContextID: doc_9527以及有何要求Parameters。后端完全掌控了路由分发、参数校验和复杂的业务实现。如果你明天需要增加一个“翻译”功能对于 AI 来说只是换了一个动词TRANSLATE它的交互模式Schema没有任何改变。这种一致性极大地降低了 AI 的试错成本和代码生成复杂度。专栏剧透我们将如何系统性地驯服 AI 智能体刚才的实战只是开胃菜。要让你的整个微服务集群、成百上千个接口都变成“Agent-ReadyAI 就绪”我们需要一套完整的架构方法论。这就引出了我们这个《Agentic API 实战为 AI 智能体设计下一代接口》微专栏以及后续安排。在接下来的 5 讲中我将摒弃那些空洞的 AI 概念从一名后端架构师的视角出发带你一步步把这套理念落地为真实的生产级能力。所有核心模式都会配备详实的 Go 语言可运行代码。以下是我们接下来的“作战路线图”第 02 讲 | 重新定义动作掌握 ACTION 接口分类法我们会深入探讨 Agentic API 的“六大核心动词”获取、计算、交易、集成、编排、通知。你会学到如何彻底抛弃 CRUD 思维用 AI 最容易理解的意图来重塑你的路由设计。第 03 讲 | 语义可发现性让 AI 自己“读懂”你的系统能力当你有 100 个接口时把文档全部喂给 AI 是愚蠢且昂贵的。我们将用 Go 实现一个动态的DISCOVER端点让 AI 能够像人类查字典一样按需、动态地探索你系统的能力边界和前置条件。第 04 讲 | OpenAPI 进化用 Agentic 扩展赋能机器阅读我们不需要推翻现有的基础设施。这一讲我将教你如何利用 OpenAPI (Swagger) 的x-自定义扩展机制把“不可逆风险”、“副作用”等业务约束“藏”进标准文档里让死文档变成 AI 的“行动护栏”。第 05 讲 | 复杂任务编排链式调用 (Chaining) 与测试模式 (Dry Run)这是保证 AI 绝对安全的核心当 AI 需要连续调用三个接口完成扣款时如何在网络抖动中保全业务状态我们将设计基于后端的链式调用并引入价值连城的“Dry Run安全演习”模式把 AI 犯错的成本降到最低。第 06 讲 | 演进与落地如何将现有系统平滑升级为 Agentic API现实是骨感的你的公司里堆满了 5 年前写的陈旧 REST 接口。大结局中我将演示一种优雅的“代理与适配器Proxy Adapter”架构教你在不修改任何一行老代码的前提下为遗留系统穿上“AI 外骨骼”。这是一次从思维方式到工程实现的全面升级。如果你准备好了迎接 AI 带来的自动化红利并且希望成为团队里那个“最懂如何让机器调接口”的架构师那么请扫描下方二维码紧跟我的步伐本讲小结今天我们站在了一个新时代的起点。认知翻新传统的 RESTful API 围绕着“静态资源名词”展开要求调用方无论人还是机器了解系统的内在状态流转。这在 AI 时代变成了沉重的认知负担导致意图丢失、编排复杂、权限泛滥。范式转移Agentic API 提倡转向“任务驱动动词”。API 端点应该直接表达操作意图如SUMMARIZE,CANCEL_ORDER由后端收敛复杂的业务编排和状态管理。实战起航我们用 Go 构建了一个极简的动作分发网关展示了如何用统一的结构Action, Context, Parameters来响应 AI 智能体的请求。这仅仅是冰山一角。在接下来的专栏中我们将深入探讨 Agentic API 的骨架六大核心 ACTION 分类法。我们将学习如何让 AI 自动“发现”你的系统能力如何通过扩展 OpenAPI 规范生成完美的智能体说明书以及如何设计让 AI 执行复杂连锁任务的“沙盒测试模式”。世界正在不可逆转地走向自动化懂 AI 调用的 API 架构师将成为下个十年最稀缺的资源。我们下一讲见本讲涉及的示例代码和脚本可以在这里下载 -https://github.com/bigwhite/publication/tree/master/micro-column/agentic-api-in-action/ch01思考题在你的日常开发中有没有遇到过一个传统的 REST API比如一个修改用户状态的 PUT 接口它的内部逻辑其实非常复杂包含了发邮件、写审计日志、调起其他微服务等操作如果让你用 Agentic API 的思维动词驱动重新设计这个接口的访问方式你会怎么命名这个 Action它的 Payload 结构会是什么样的欢迎在评论区留下你的思考和设计我会和你一起讨论。如果本文对你有所帮助请帮忙点赞、推荐和转发点击下面标题干货- API 设计之道 - 资源导向设计 (ROD)告别 RPC 风格的“动词地狱”- 标准方法论CRUD 的哲学与 HTTP 动词的精准语义- 降低 74% 的 P99 尾延迟揭秘 Go HTTP 客户端的“请求对冲”魔法- 告别单打独斗Claude Code 全新“Agent Team”模式当 AI 开始组队干活- 当机器开始“剁手”详解 Google UCP 与 Agentic Commerce 的架构革命- 为什么你必须把 Agent Skills 开发变成严谨的软件工程?- 停止“氛围编程”Vibe Coding拥抱新一代软件工程 原「Gopher部落」已重装升级为「Go AI 精进营」知识星球快来加入星球开启你的技术跃迁之旅吧我们致力于打造一个高品质的Go 语言深度学习与AI 应用探索平台。在这里你将获得体系化 Go 核心进阶内容:深入「Go原理课」、「Go进阶课」、「Go避坑课」等独家深度专栏夯实你的 Go 内功。前沿 GoAI 实战赋能:紧跟时代步伐学习「GoAI应用实战」、「Agent开发实战课」、「Agentic软件工程课」、「Claude Code开发工作流实战课」、「OpenClaw实战分享」、「构建工业级Agent Skills」等掌握 AI 时代新技能。星主 Tony Bai 亲自答疑:遇到难题星主第一时间为你深度解析扫清学习障碍。高活跃 Gopher 交流圈:与众多优秀 Gopher 分享心得、讨论技术碰撞思想火花。独家资源与内容首发:技术文章、课程更新、精选资源第一时间触达。衷心希望「Go AI 精进营」能成为你学习、进步、交流的港湾。让我们在此相聚享受技术精进的快乐欢迎你的加入