给 AI Agent 设计接口别只套 REST 了，这套新规范前端团队也该懂了

给 AI Agent 设计接口别只套 REST 了，这套新规范前端团队也该懂了

导语

你有没有遇到过这种场景：前端团队辛辛苦苦把 REST API 设计得很规范，结果 AI Agent 接进来的时候到处踩坑——上下文丢失、工具调用格式不兼容、多 Agent 协作时互相听不懂？问题不是 REST 不好，而是 AI Agent 的调用方式和人类开发者完全不同。2026 年，MCP 和 A2A 这两套新规范正在重新定义”给 AI 设计的接口”长什么样，前端团队该提前布局了。

问题：REST 是为人类设计的，不是为 Agent

传统 REST API 的核心假设是：调用方是人类开发者，他们会看文档、处理错误、理解上下文。但 AI Agent 不一样：

• **自然语言输入，结构化输出**：模型”说人话”，但执行时需要精确的结构化指令
• **上下文窗口有限**：Agent 不能每次都带全量文档，接口需要自描述
• **多步推理**：一个任务往往需要多次调用，接口要支持工作流编排
• **多 Agent 协作**：Agent A 调 Agent B 的接口，中间没有人类中转

用 REST 硬套这些问题，就会出现：

• 每个 API 都要单独写适配层，工具碎片化严重
• Agent 容易在长上下文中丢失关键信息
• 多 Agent 之间没有标准通信协议，容易”鸡同鸭讲”

MIT Technology Review 的报道指出，Anthropic 的 Theo Chu 说得很直白：”Models speak a natural language. For a model to get context and do something with that context, a translation layer has to happen.” 这个翻译层，就是新规范要解决的核心问题。

方案：三条新路径

1. MCP（Model Context Protocol）：AI 领域的 USB-C 接口

MCP 是 Anthropic 在 2024 年底开源的协议，目标是把 AI 与外部工具的集成标准化。截至 2026 年 7 月，MCP 服务器聚合器上已经列出了 15,000+ 个服务器，覆盖从数据库、文件系统到企业级 SaaS 的全场景。

核心设计：

传统架构：AI 应用 → [自定义集成层] → 工具 A
                        ↓
                   [自定义集成层] → 工具 B
                        ↓
                   [自定义集成层] → 工具 C

MCP 架构：AI 应用 (MCP Client) → MCP 协议 → MCP Server (工具 A/B/C)

MCP 的三层架构：

• **Host（主机）**：运行 AI 模型的应用（如 Claude Desktop、IDE 插件）
• **Client（客户端）**：Host 内部与 Server 通信的组件
• **Server（服务器）**：暴露工具、数据源或上下文的外部服务

MCP 解决的关键问题：

1. 工具发现：Server 在初始化时自动暴露可用工具列表，Agent 按需加载

2. 上下文传递：统一的 JSON-RPC 格式，模型能理解输入输出

3. 权限控制：Host 层统一管理授权，Server 不需要关心认证逻辑

代码示例：MCP Server 定义一个简单的工具

# 一个 FastAPI 转 MCP Server 的最小示例
from mcp.server import Server
from mcp.server.models import InitializationOptions
from mcp.types import Tool, TextContent

app = Server("weather-service")

@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="get_weather",
            description="获取指定城市的天气信息",
            inputSchema={"type": "object", "properties": {"city": {"type": "string"}}}
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_weather":
        city = arguments.get("city", "")
        return [TextContent(type="text", text=f"{city}今天晴，25°C")]
    raise ValueError(f"Unknown tool: {name}")

这段代码的核心价值：你写的是业务逻辑，MCP 负责把业务逻辑翻译成 Agent 能理解的格式。不需要再为每个 AI 工具单独写 prompt 适配层。

2. A2A（Agent-to-Agent Protocol）：Agent 之间的”对话语言”

MCP 解决的是 Agent ↔ 工具 的通信，A2A 解决的是 Agent ↔ Agent 的通信。这是 Google 在 2025 年 4 月推出的协议，目前已有 150+ 家企业（包括 Adobe、Salesforce）加入合作。

A2A 的核心设计：

与 MCP 的关系：

A2A 和 MCP 不是竞争关系，而是互补。每个参与 A2A 通信的 Agent，内部可以用 MCP 来调用工具。A2A 管”Agent 之间怎么对话”，MCP 管”Agent 怎么用工具”。

3. Agent-Ready API 设计原则

除了协议层，Google 最近还推出了 Agent-Ready Toolkit（集成到 Lighthouse 中），帮助前端团队评估现有站点/API 对 AI Agent 的友好度。

五项核心原则：

1. 自描述性：API 返回的 Schema 要足够详细，Agent 不需要额外文档就能理解

2. 上下文感知：支持在请求头或 body 中传递上下文，减少 Agent 的窗口压力

3. 幂等性：Agent 的多步推理可能会重复调用，接口要支持幂等操作

4. 可观察性：提供清晰的日志和状态查询，方便 Agent 自我修正

5. 安全边界：明确哪些操作需要人工确认，防止 Agent “越权”

Google 工程师 Saboo_Shubham_ 总结了 5 种 Agent Skill 设计模式，这套模式同样适用于 API 设计：

代码实战：从 REST 到 MCP 的迁移思路

假设你有一个现有的 REST API：

# 传统 REST：前端调用 /api/weather?city=Beijing
@app.get("/api/weather")
async def get_weather(city: str):
    return {"city": city, "temp": 25, "condition": "sunny"}

Agent 面临的问题：

• 不知道这个接口存在（没有自描述）
• 不知道 `city` 参数的类型和格式
• 不知道返回的 JSON 结构，需要额外 prompt 来解析

用 MCP 改造后：

from mcp.server import Server

app = Server("weather-service")

@app.list_tools()
async def list_tools():
    # Agent 启动时自动发现可用工具
    return [
        Tool(
            name="get_weather",
            description="获取指定城市的当前天气",
            inputSchema={
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "城市名称，如 Beijing、Shanghai"
                    }
                },
                "required": ["city"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_weather":
        city = arguments["city"]
        # 业务逻辑不变
        result = fetch_weather(city)
        # 返回结构化的、Agent 能直接理解的结果
        return [TextContent(
            type="text",
            text=f"{city}当前温度 {result['temp']}°C，天气 {result['condition']}"
        )]

对比：

结论：前端团队该怎么做

1. 短期（1-3 个月）：给现有 API 补充 OpenAPI/Swagger Schema，至少让 Agent 能自动发现接口结构。这是成本最低的”Agent-Ready”改造。

2. 中期（3-6 个月）：在内部工具/平台试点 MCP Server，把常用的内部 API 封装成 MCP 格式，给 Claude Code、Cursor 等 AI 编程工具使用。

3. 长期（6-12 个月）：评估 A2A 协议，如果团队有多个 Agent 协作场景（如代码审查 Agent + 测试 Agent + 部署 Agent），提前布局 A2A 通信层。

判断标准：如果你的团队已经在用 AI 编程工具，且遇到”工具调用格式不统一””上下文经常丢失””多个 Agent 无法协作”这三个问题中的任何一个，就该开始考虑 MCP/A2A 了。

下一步

• 读一下 Anthropic 的 [MCP 官方文档](https://modelcontextprotocol.io/docs/getting-started/intro)，15 分钟能搞懂核心概念
• 用 `mcp-server` 模板跑一个本地 Demo，给 Claude Desktop 加个自定义工具
• 关注 Google A2A 协议的后续更新，目前还在快速迭代中

参考来源：MIT Technology Review《These protocols will help AI agents navigate our messy lives》、Google Cloud《5 种 Agent Skill 设计模式》、MCP 官方文档、腾讯云开发者社区