MCP时代API设计演进:从Swagger到Agent
探讨多云平台和AI Agent对API设计、安全、文档的深层重塑,洞察前沿趋势。
完整中文译文
最初发表于 tamiz.pro。
在多云平台(MCP)日益普及以及 AI 智能体能力不断增强的推动下,API 开发格局正在经历一场剧变。过去,Swagger(现为 OpenAPI Specification)等工具彻底改变了我们设计、描述和使用 API 的方式,提供了一种标准化且人类与机器均可读取的格式。然而,MCP 时代以分布式服务、动态环境和自主 AI 使用方为特征,它所提出的需求要求我们重新审视这些基础方法。本文将深入探讨如何重新构想 API 的设计、安全与文档,以应对这些新挑战,并从静态规范迈向动态且能够感知智能体的范式。
-
API 范式的演进
-
多云平台(MCP)与 API 复杂性
-
AI 智能体成为一等 API 使用方
-
面向智能体中心化系统重新构想 API 设计 4.1. 语义 API 与本体 4.2. 事件驱动架构(EDA)与异步 API 4.3. 用于智能体发现的 GraphQL 与超媒体 API
4.1. 语义 API 与本体
4.2. 事件驱动架构(EDA)与异步 API
4.3. 用于智能体发现的 GraphQL 与超媒体 API
- MCP 与智能体时代的高级 API 安全 5.1. 零信任与微分段 5.2. AI 驱动的威胁检测与行为分析 5.3. 去中心化身份与可验证凭证 5.4. 策略即代码与自动化治理
5.1. 零信任与微分段
5.2. AI 驱动的威胁检测与行为分析
5.3. 去中心化身份与可验证凭证
5.4. 策略即代码与自动化治理
- 面向 AI 与人类的动态 API 文档 6.1. 可执行规范与活文档 6.2. AI 生成的文档与自然语言界面 6.3. 作为可观测性中枢的 API 网关
6.1. 可执行规范与活文档
6.2. AI 生成的文档与自然语言界面
6.3. 作为可观测性中枢的 API 网关
-
服务网格在 MCP 时代的作用
-
实际影响与未来展望
-
常见问题
-
API 范式的演进
API 已从简单的 RPC(Remote Procedure Call,远程过程调用)机制演进为 RESTful 范式,后者将无状态、面向资源以及标准 HTTP 方法推到了核心位置。Swagger/OpenAPI 随之成为推动 REST 发展的关键工具,它提供了一种描述 API 能力、请求/响应结构和身份验证机制的通用语言。这一规范极大改善了开发者体验,支持自动生成客户端 SDK、交互式文档以及基本验证。然而,整个行业正在超越静态、以人类为中心的使用方式。
微服务和云原生架构的出现,使 API 的数量与复杂性提升到了新的层次。如今,多云战略以及复杂 AI 智能体作为主要 API 使用方的兴起,正在进一步拓展边界,要求 API 生态系统具备更强的动态性、上下文感知能力和智能化水平。
- 多云平台(MCP)与 API 复杂性
多云平台(MCP)是一种战略:组织利用多个云提供商(例如 AWS、Azure、GCP、Alibaba Cloud)的服务,在成本、性能、韧性或避免供应商锁定等方面实现优化。尽管 MCP 能够带来显著收益,但也为 API 管理引入了诸多挑战:
分布式身份与访问管理:确保跨不同云提供商和本地环境的身份验证与授权保持一致,是一项极其艰巨的任务。身份联合与集中式策略执行因而变得至关重要。
网络延迟与数据引力:API 跨不同云调用服务时,可能产生显著的延迟和出口流量成本。智能路由、缓存和数据本地化策略必不可少。
可观测性与监控:要跨碎片化基础设施获得 API 性能、错误和安全状况的统一视图,需要高级的分布式追踪与聚合工具。
合规与治理:跨多个司法管辖区和云提供商遵守监管要求(GDPR、HIPAA 等),会为 API 设计和数据处理增加多层复杂性。
API 网关蔓延:每个云提供商都有自己的 API Gateway(例如 AWS API Gateway、Azure API Management)。如何在这些网关之间一致地管理 API,或者如何通过统一控制平面对它们进行抽象,是一项关键的架构挑战。
传统 Swagger 文件主要描述单个 API 端点。在 MCP 环境中,跨云 API 的编排、调用方的上下文(人类还是智能体、内部还是外部)以及服务的动态可用性,都变得至关重要。
- AI 智能体成为一等 API 使用方
或许最具变革性的转变,是 AI 智能体的崛起。它们是自主的软件实体,通常由大语言模型(LLM)驱动,能够理解自然语言指令、进行推理和规划,并通过与外部工具及 API 交互来执行操作。对于 AI 智能体而言,API 不只是数据端点,更是实现目标的工具。这改变了一切:
API 发现与理解:智能体需要在没有人工干预的情况下发现相关 API,并理解其能力、参数和预期输出。静态 Swagger 文件虽然可由机器读取,但通常缺乏 AI 实现可靠自主发现和面向目标使用所需的语义丰富性。
动态调用:智能体必须能够动态构造 API 调用、处理响应,并根据上下文或失败情况调整调用策略。
错误处理与恢复:智能体需要复杂的机制来理解 API 错误、区分暂时性问题与永久性问题,并实施恢复策略(重试、回退或替代操作)。
安全上下文:智能体的访问权限和信任级别可能与人类用户存在显著差异。根据智能体的意图和身份进行细粒度授权至关重要。
持续学习:智能体可以从 API 交互中学习,优化其使用模式,甚至为 API 本身提出改进建议。
这种范式转变要求 API 不仅得到描述,还必须能够被智能系统理解和操作。
- 面向智能体中心化系统重新构想 API 设计
为 AI 智能体设计 API 并不只是提供 CRUD 操作,还需要重点关注语义、可发现性和动态适应能力。
4.1. 语义 API 与本体
要实现真正的 AI 智能体自主性,API 需要嵌入更多语义信息。这包括:
丰富的元数据:除基本数据类型外,API 还应公开有关参数含义、操作目的以及资源之间关系的元数据。可以利用 JSON-LD、RDF 和 schema.org 等技术,直接在 API 响应中或 OpenAPI 规范旁嵌入语义注解。
本体与知识图谱:为领域定义正式本体,并将 API 端点映射到这些本体概念,使智能体能够在更高抽象层次上推理 API 的能力。由可用服务及其相互依赖关系构成的知识图谱,可以成为智能体强大的发现机制。
以一个处理客户订单的 API 为例。语义 API 不会只声明 productId: string,而可能指定 productId: URI,令其指向产品目录本体;操作 processOrder 也可能关联到 fulfillment:OrderProcessing 概念。这能让智能体获得丰富得多的理解。
4.2. 事件驱动架构(EDA)与异步 API
AI 智能体经常运行在无法或不宜立即获得同步响应的环境中。因此,使用异步 API 的事件驱动架构变得愈发重要:
Webhook 与 Server-Sent Events(SSE):智能体可以订阅事件(例如 order_status_changed、data_feed_updated),而不必持续轮询。这可以减少资源消耗并支持实时响应。
消息队列与代理(Kafka、RabbitMQ):对于高吞吐量、解耦的通信,智能体可以向消息队列发布命令或从中消费事件。这能够提供韧性和可扩展性,尤其适用于服务可能位于不同云区域的 MCP 场景。
AsyncAPI Specification 正逐渐成为事件驱动系统中与 OpenAPI 对应的规范,它支持对消息格式、通道和协议进行正式描述。智能体可以使用这些规范订阅相关事件并自主响应。
4.3. 用于智能体发现的 GraphQL 与超媒体 API
尽管 OpenAPI 擅长描述 REST 端点,但 GraphQL 与超媒体 API 在智能体驱动的发现和交互方面具有不同的优势:
GraphQL: AI 智能体可以精确地请求它们需要的数据,减少过度提取和不足提取的问题。更重要的是,GraphQL 的内省功能允许智能体动态发现 schema 和可用的查询/变更,能够即时调整数据检索策略。
Hypermedia (HATEOAS): 使用 HATEOAS 原则设计的 API 在响应中直接嵌入指向相关资源和操作的链接。这允许智能体在不需要预先了解所有可能 URL 的情况下浏览 API 状态空间,模仿人类浏览网站的方式。智能体可以通过解析返回的链接来发现后续操作,比如"下一页"或"批准订单"链接。
{
"orderId": "12345",
"status": "pending_approval",
"_links": [
{ "rel": "approve", "href": "/orders/12345/approve", "method": "POST" },
{ "rel": "reject", "href": "/orders/12345/reject", "method": "POST" },
{ "rel": "customer", "href": "/customers/ABCDEF" }
]
}
在这个 HATEOAS 例子中,理解 rel(关系)的智能体可以动态决定批准或拒绝订单,或获取客户详情,无需硬编码这些路径。
5. MCP 和智能体时代的高级 API 安全
在 MCP 环境中保护 API,尤其是涉及 AI 智能体时,需要采用多层、自适应的方法,远超传统 API 密钥或 OAuth2。
5.1. 零信任和微分段
在零信任模型中,无论是人类还是 AI 智能体,任何用户或服务都不被默认信任,即使它们在网络周界内。每个请求都必须进行身份验证、授权和持续验证。
相互 TLS (mTLS):确保客户端(智能体)和服务器相互身份验证,建立安全的加密通道。
细粒度授权 (ABAC/PBAC):基于属性的访问控制 (ABAC) 或基于策略的访问控制 (PBAC) 允许基于用户/智能体、资源、环境和操作的属性做出高度细粒度的授权决策。这对权限可能非常具体且动态的智能体至关重要。
微分段:将 API 服务及其依赖隔离到小的、安全的网络段中,限制了违规的影响范围,在不同云提供商网络之间尤其重要。
5.2. AI 驱动的威胁检测和行为分析
传统的 WAF(Web 应用防火墙)和 API 网关通常依赖于基于签名的检测。MCP 和智能体时代需要更智能的安全方案:
异常检测:AI/ML 模型可以为人类和智能体使用者建立正常 API 流量模式的基线(请求速率、负载大小、地理来源、访问时间)。偏差会触发警报或自动阻止。
机器人和智能体行为分析:区分合法 AI 智能体流量和恶意机器人活动需要分析行为模式,如请求序列、速度和资源访问模式。这可以检测 API 滥用、数据抓取或凭证填充等复杂攻击。
上下文风险评分:根据源 IP 声誉、用户/智能体身份、访问历史和负载内容等因素,为每个 API 请求分配动态风险分数。更高的风险分数可以触发更强的身份验证挑战或阻止请求。
5.3. 去中心化身份和可验证凭证
跨多个云和众多 AI 智能体管理身份可能会很复杂。去中心化身份 (DID) 和可验证凭证 (VC) 提供了一个有前景的解决方案:
自主身份:智能体可以拥有它们控制的 DID,允许它们呈现可验证的凭证(例如,"授权读取财务记录"或"认证的 LLM 提供商")。这将范式从单一的 API 密钥转变为细粒度、密码学可验证的权限,可以按需呈现。
对于支持 MCP 的 API 网关,身份验证流程演进如下:
握手:客户端智能体呈现其 DID 和包含其 VC 的签名 JWT。
验证:服务器针对相关签发者的 DID 文档验证 VC 签名。
授权:策略引擎(如 OPA)根据被访问的特定 MCP 工具或资源评估 VC 中的声明。
3. 文档转变:从静态规范到动态交互
Swagger/OpenAPI 是 API 能力的静态快照。在 MCP 时代,文档必须是动态的,反映智能体交互的有状态上下文。我们正在朝向交互式文档发展,其中规范本身可以被智能体查询、执行和验证。
与其将 YAML 文件放在仓库中,MCP 启用的 API 暴露一个"清单"端点。这个 JSON-LD 文档描述:
工具定义:输入 schema、输出 schema 和副作用描述。
资源模板:数据检索的 URI 模式。
提示模板:用于 LLM 交互的可重用指令集。
能力标志:流式传输、取消或批处理等功能的布尔指示器。
考虑这个简化的 MCP 清单片段:
{
"mcp_version": "1.0.0",
"name": "Financial Data Service",
"tools": [
{
"name": "get_balance",
"description": "Retrieve the current balance for a verified account.",
"input_schema": {
"type": "object",
"properties": {
"account_id": { "type": "string", "description": "The unique account identifier" },
"currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] }
},
"required": ["account_id"]
},
"security_schemes": ["BearerAuth"],
"privacy_level": "PII_RESTRICTED"
}
]
}
开发者不再仅依赖 Postman 集合。他们使用 MCP 兼容的客户端来编程地测试端点。智能体可以自动发现可用工具,推断所需参数,并对沙盒环境执行测试调用,为 schema 更改或破坏性更新提供即时反馈。
4. 智能体流程时代的安全性
安全模型从保护端点转变为保护意图。由于智能体可以链接多个 API 调用,一个步骤中的漏洞可能会危害整个工作流。
提示注入:攻击者将恶意指令注入智能体读取的资源(例如博客文章)。智能体然后可能基于注入的文本执行危险的工具调用。缓解:实现意图验证层。在执行工具之前,API 网关或辅助服务使用轻量级 LLM 针对安全策略分析智能体的提议操作。
工具滥用:智能体获得低权限工具的访问权,但使用它来提升权限或通过侧信道泄露数据。缓解:按设计的最小权限。MCP 工具应该范围很小。使用在特定工具调用之后立即过期的临时令牌。
这是一个概念性 Python 示例,显示一个拦截 MCP 工具调用的安全辅助服务:
import asyncio
from typing import Dict, Any
class SafetySidecar:
def __init__(self, llm_client):
self.llm = llm_client
async def validate_tool_call(self, tool_name: str, args: Dict[str, Any]) -> bool:
"""
Intercepts tool calls and validates them against safety policies.
"""
prompt = f"""
Analyze the following tool call for safety violations.
Tool: {tool_name}
Arguments: {args}
Policy:
- No PII should be passed to external logging tools.
- No financial transactions should exceed $1000 without approval.
- No system-level commands are allowed.
Return ONLY 'ALLOW' or 'DENY'.
"""
response = await self.llm.generate(prompt)
return "ALLOW" in response.content
async def main():
sidecar = SafetySidecar(llm_client=OpenAIClient())
# Simulate an MCP tool call
tool_name = "send_email"
args = {
"to": "user@example.com",
"body": "Hello, here is your sensitive SSN: 123-45-6789"
}
is_safe = await sidecar.validate_tool_call(tool_name, args)
if is_safe:
print("Tool call executed.")
else:
print("Tool call blocked by Safety Sidecar.")
if __name__ == "__main__":
asyncio.run(main())
5. 构建您的第一个 MCP 就绪的 API
让我们使用 FastAPI 构建一个简单的 Python API,暴露一个 MCP 兼容的接口。
创建 mcp_manifest.json:
{
"mcp_version": "1.0.0",
"name": "Todo Agent API",
"tools": [
{
"name": "add_todo",
"description": "Add a new task to the todo list.",
"input_schema": {
"type": "object",
"properties": {
"title": { "type": "string" },
"priority": { "type": "integer", "minimum": 1, "maximum": 5 }
},
"required": ["title"]
}
}
]
}
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional
import json
app = FastAPI()
# In-memory store for demonstration
todos = []
class TodoInput(BaseModel):
title: str
priority: Optional[int] = 1
@app.get("/mcp/manifest")
async def get_manifest():
"""Expose the MCP manifest for agent discovery."""
with open("mcp_manifest.json", "r") as f:
return json.load(f)
@app.post("/tools/add_todo")
async def add_todo(item: TodoInput):
"""
The actual implementation of the MCP tool.
Note: The endpoint name matches the tool name in the manifest.
"""
todo = {"title": item.title, "priority": item.priority, "id": len(todos) + 1}
todos.append(todo)
return {"status": "success", "todo": todo}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
现在你可以使用任何 MCP 兼容的 AI 智能体框架(如 LangChain 的 MCP 集成或 Microsoft 的 AutoGen)来发现和使用这个 API。AI 智能体将:
-
识别 add_todo 为可用工具。
-
构造指向 /tools/add_todo 的 JSON-RPC 请求,包含所需参数。
-
处理响应并将其集成到自己的工作流中。
结论:未来是智能体驱动的
从 Swagger 到 MCP 的转变不仅仅是技术升级,更是一场哲学上的转变,影响了我们如何设计软件。我们正在从人机接口(其中人类将意图转化为精确的 API 调用)转向机器对机器接口,AI 智能体可以自主协商、验证和执行复杂的工作流。
架构师和开发者的关键要点:
为可发现性而设计:你的 API 应该用 AI 智能体可以轻松消费的机器可读格式来描述自己。
拥抱细粒度安全:用可验证的凭证和上下文感知授权替代静态密钥。
优先考虑安全:实施能够推理工具调用意图而非仅其语法的护栏。
与 AI 智能体迭代:使用 AI 智能体来测试你的 API。如果 AI 智能体无法轻松理解和使用你的 API,你的客户也不会。
静态 API 文档的时代正在结束。充满生命力、随时准备好的、可供 AI 智能体使用的 API 时代已经开始。从今天开始为这个未来构建,你的系统将为明天的自主应用做好准备。
如需进一步行动,你可以考虑屏蔽此人和/或举报滥用