本文永久链接 – https://tonybai.com/2026/04/03/agentic-api-in-action
大家好，我是Tony Bai。
在过去的十几年里，如果你问任何一位后端工程师：“我们应该如何设计 API？”得到的答案几乎是统一的：RESTful。
我们将世界抽象为一个个“资源（Resources）”，用名词来命名 URI（比如 /users, /orders），用 HTTP 动词（GET, POST, PUT, DELETE）来表达对这些资源的操作。这套基于 CRUD（创建、读取、更新、删除）的法则，优雅地统治了移动互联网和微服务时代。
然而，时代变了。
当我们步入 AI 时代，尤其是当各种大语言模型（LLM）驱动的智能体（AI Agent）开始接管我们的软件系统时，一个尖锐的矛盾浮出水面：这群“硅基同事”在面对我们精心设计的 REST API 时，表现得像个无所适从的笨蛋。
今天，作为本专栏的开篇，我想和你探讨一个极其现实的工程问题：为什么在 AI 时代，统治后端十年的 REST 架构正在失效？我们又该如何为 AI 智能体设计下一代接口——Agentic API？
为了理解 REST 的局限性，我们不妨先来做个角色互换。
假设你现在不是一个人类工程师，而是一个被赋予了任务的 AI Agent。你的主人对你说：“帮我把昨天那个发错的订单取消掉，并给客户退款。”
作为 Agent，你拥有一个极其强大的大脑（比如 GPT-5.x 或 DeepSeek-V3.x），并且你被授权访问公司内部的订单系统 API。你兴冲冲地查看了该系统的 Swagger 文档，看到了以下几个端点：
这时候，你的“认知障碍”出现了。
你要“取消订单”，但在 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 必须自己完成以下编排：
如果步骤 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 推出的 MCP（Model 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 模式下：
光说不练假把式。接下来，我们将用 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
在传统的 CRUD 思维下，很多开发者可能会这么设计：
让客户端发送一个 POST /documents/{id}/summary 请求，或者使用一个万能的 PATCH /documents/{id}，带上一个 action=summarize 的字段。
这虽然能工作，但语义不够清晰，扩展性极差（如果明天需要翻译、提取关键字呢？）。
在 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 string json:"action"
// 动作的目标上下文 (例如文档ID)
ContextID string json:"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) {
case "SUMMARIZE":
handleSummarize(w, req)
case "TRANSLATE":
// 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 的试错成本和代码生成复杂度。
刚才的实战只是开胃菜。要让你的整个微服务集群、成百上千个接口都变成“Agent-Ready（AI 就绪）”，我们需要一套完整的架构方法论。
这就引出了我们这个《Agentic API 实战：为 AI 智能体设计下一代接口》微专栏，以及后续的安排。
在接下来的 5 讲中，我将摒弃那些空洞的 AI 概念，从一名后端架构师的视角出发，带你一步步把这套理念落地为真实的生产级能力。所有核心模式都会配备详实的 Go 语言可运行代码。
以下是我们接下来的“作战路线图”：
这是一次从思维方式到工程实现的全面升级。如果你准备好了迎接 AI 带来的自动化红利，并且希望成为团队里那个“最懂如何让机器调接口”的架构师，那么，请扫描下方二维码，紧跟我的步伐。
今天，我们站在了一个新时代的起点。
这仅仅是冰山一角。在接下来的专栏中，我们将深入探讨 Agentic API 的骨架：六大核心 ACTION 分类法。我们将学习如何让 AI 自动“发现”你的系统能力，如何通过扩展 OpenAPI 规范生成完美的智能体说明书，以及如何设计让 AI 执行复杂连锁任务的“沙盒测试模式”。
世界正在不可逆转地走向自动化，懂 AI 调用的 API 架构师，将成为下个十年最稀缺的资源。我们下一讲见！
本讲涉及的示例代码和脚本可以在这里下载。
在你的日常开发中，有没有遇到过一个传统的 REST API（比如一个修改用户状态的 PUT 接口），它的内部逻辑其实非常复杂（包含了发邮件、写审计日志、调起其他微服务等操作）？
如果让你用 Agentic API 的思维（动词驱动）重新设计这个接口的访问方式，你会怎么命名这个 Action？它的 Payload 结构会是什么样的？
欢迎在评论区留下你的思考和设计，我会和你一起讨论。
还在为“复制粘贴喂AI”而烦恼？我的新专栏 《AI原生开发工作流实战》 将带你：
扫描下方二维码，开启你的AI原生开发之旅。
原「Gopher部落」已重装升级为「Go & AI 精进营」知识星球，快来加入星球，开启你的技术跃迁之旅吧！
我们致力于打造一个高品质的 Go 语言深度学习 与 AI 应用探索 平台。在这里，你将获得：
衷心希望「Go & AI 精进营」能成为你学习、进步、交流的港湾。让我们在此相聚，享受技术精进的快乐！欢迎你的加入！
商务合作方式：撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。如有需求，请扫描下方公众号二维码，与我私信联系。
© 2026, bigwhite. 版权所有.
Related posts:
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。