当 API 的调用方从固定程序扩展到 AI 智能体，企业 API 项目面对的就不再只是版本管理、认证和可用性问题。智能体需要发现工具、理解能力边界、组合多个服务，并在执行过程中遵守组织级治理规则。
在这场演进中，Morgan Stanley 的实践把三个方向放在了同一条工程链路上：用 Architecture as Code 和 CALM 描述架构，用 Model Context Protocol（MCP）和 Agent-to-Agent（A2A）支持智能体协作，再把治理检查嵌入部署门禁。这样，API 平台升级和 AI 能力扩展就不必依赖人工审批与一次性迁移，而可以变成可验证、可回滚的交付流程。
API 程序正在从“接口目录”变成“能力系统”
传统 API 管理通常围绕几个对象展开：服务、端点、消费者、凭证和版本。智能体场景增加了新的要求：
- 能力可发现：智能体需要知道某个服务能做什么，而不是只拿到一串 URL。
- 调用可解释：工具的输入、输出、权限和副作用必须有结构化描述。
- 组合可控：一个任务可能跨越多个 API 或多个智能体，调用链需要受到策略约束。
- 变更可验证：接口升级不仅影响应用，也可能改变智能体的决策和执行结果。
MCP 可以作为模型或智能体访问工具与上下文的标准化边界；A2A 则适合描述智能体之间的任务委派与协作。它们并不意味着现有 REST 或事件接口会消失。更实际的做法是，在已有 API 能力之上增加面向智能体的发现、描述、权限和审计层。
这也解释了为什么 API 项目需要从“发布接口”升级为“发布可治理的能力”。
用 Architecture as Code 描述架构约束
Architecture as Code 的核心不是把设计文档换成另一种格式，而是让架构约束进入版本控制、自动检查和部署流程。CALM 可以作为一种结构化架构描述方式，用来表达系统、接口、依赖和治理要求。
下面是一个示意性的 CALM 风格 YAML。具体字段应根据组织采用的 CALM 版本和工具链调整；示例重点是展示如何把 API、MCP 能力、身份认证和数据分类放进同一个可检查的架构声明中。
name: payments-agent-capability
version: 1.0.0
owner: payments-platform
nodes:
- name: payment-api
type: service
protocol: https
data_classification: confidential
authentication: oauth2
capabilities:
- name: get_payment_status
exposure: mcp-tool
input_schema: schemas/payment-status-input.json
output_schema: schemas/payment-status-output.json
side_effect: read-only
- name: fraud-agent
type: agent
protocol: a2a
allowed_dependencies:
- payment-api
policies:
require_tls: true
require_owner: true
require_audit_events: true
deny_unclassified_data: true
这类声明可以驱动多种自动化检查：是否为每项能力指定了负责人，是否使用了组织认可的认证方式，是否标记了数据分类，是否明确了工具的副作用，以及某个智能体是否越过了允许的依赖边界。
关键点在于，架构规则应该检查“智能体可执行的行为”，而不只是检查 OpenAPI 文档是否存在。一个声明为只读的工具，如果实际请求可以修改数据，就应当在部署前被拒绝。
把治理变成部署门禁
治理如果只存在于评审会议中，通常无法跟上智能体能力的发布速度。更可靠的方式是把架构验证、契约测试、安全扫描和策略检查放进 CI/CD，在部署前形成明确的通过条件。
下面的 Bash 示例展示了一条简化的部署门禁流程。calm-validate、contract-test 和 policy-check 是示意命令，实际项目中可以替换成组织内部工具或对应的开源实现。
#!/usr/bin/env bash
set -euo pipefail
ARCHITECTURE_FILE="architecture/payment-agent.yaml"
SERVICE_URL="${SERVICE_URL:?SERVICE_URL is required}"
calm-validate "$ARCHITECTURE_FILE"
contract-test --spec openapi/payment.yaml --base-url "$SERVICE_URL"
policy-check --architecture "$ARCHITECTURE_FILE" \
--rules policies/agent-api-rules.yaml
# 检查 MCP 工具描述与实际接口行为是否一致
mcp-check --manifest mcp/payment-tools.json \
--endpoint "$SERVICE_URL/mcp"
# 只有全部检查通过，才允许进入部署阶段
deploy-service payments-agent-capability
一条可执行的门禁至少应覆盖以下边界：
- 架构完整性：服务、负责人、协议、依赖和数据分类是否齐全。
- 接口兼容性：新版本是否破坏已有消费者或工具调用约定。
- 权限最小化：智能体是否只获得完成任务所需的工具和数据权限。
- 行为一致性：工具描述中的输入、输出和副作用是否与实际服务一致。
- 审计可追踪：模型、智能体、工具、用户和请求之间是否能关联起来。
对于高风险操作，还应增加人工批准、双重确认或隔离执行环境。自动化门禁不是把所有决策交给流水线，而是把可机械验证的规则尽量提前执行，把人的注意力留给真正需要判断的例外。
MCP 与 A2A 接入时要划清边界
MCP 和 A2A 解决的问题不同，接入时不宜把它们混成一个“智能体 API”。可以采用下面的分工：
- MCP 面向工具与上下文：一个智能体通过标准化机制发现和调用企业工具。
- A2A 面向智能体协作：一个智能体向另一个智能体委派任务、交换状态或请求结果。
- 企业 API 面向业务能力：系统继续通过稳定的业务接口承载核心数据和操作。
- 治理层横切所有调用：认证、授权、限流、审计、敏感数据处理和策略评估不应只存在于某一种协议中。
实践中可以把 MCP 工具映射到现有 API，但不要只做协议包装。需要补充调用者身份、用户授权范围、幂等要求、超时策略、失败重试和副作用说明。对于 A2A 调用，则要进一步考虑任务是否可转移、结果是否可信、如何防止循环委派，以及跨智能体调用如何传递审计上下文。
零停机升级依赖可回退的运行模型
当 API 平台本身需要升级时，智能体调用会放大兼容性风险。一个普通客户端可能在几分钟内失败一次；一个自动规划任务则可能在错误重试后产生更长的调用链或重复操作。
因此，零停机升级不能只理解为“新旧实例同时运行”。还需要准备：
- 版本化的 API 和工具描述。
- 新旧协议或字段的兼容窗口。
- 按租户、消费者或流量比例逐步切换。
- 可观测的错误率、延迟、工具调用成功率和策略拒绝率。
- 快速回退到上一版本的路由和配置。
- 对写操作提供幂等键、去重机制或事务补偿。
一个可落地的发布顺序可以是：先部署兼容的新服务，再发布新工具描述，执行影子流量或只读验证，然后逐步扩大真实流量，最后再移除旧契约。任何一步出现异常，都应能够只回退路由或工具版本，而不必整体回滚平台。
落地时的检查清单
企业不需要一次性重写全部 API。可以从一条低风险、只读的业务能力开始，建立完整闭环：
- 将服务和依赖写入可版本控制的架构文件。
- 为一个只读 API 发布结构化的 MCP 工具描述。
- 明确工具输入、输出、权限和副作用。
- 为智能体调用增加身份、审计和关联 ID。
- 在 CI/CD 中执行架构、契约和策略检查。
- 用灰度发布验证平台或工具版本升级。
- 为失败调用设计超时、幂等和回退策略。
- 记录哪些规则可以自动拒绝，哪些场景必须人工批准。
MCP 和 A2A 让 API 能力更容易被智能体发现和组合，但它们也让架构质量、权限边界和发布纪律变得更加重要。把架构写成代码，把治理放进部署门禁，再用可回退的方式升级平台，企业才能在扩大智能体使用范围的同时，保留对系统行为的控制力。