Contract-First AI Tool / API Design with OpenAPI / AsyncAPI 解读

配对阅读：本篇的操作手册版（模板/RACI/门禁/runbook）是 docs/AI_CONTRACT_FIRST_TOOL_API_DESIGN_OPENAPI_ASYNCAPI_PLAYBOOK.md。第一遍读本篇建立原理与架构判断；第二遍做案例时再用 playbook 查表落地，两者不需要重复精读。

核心问题: AI agent 不能靠 prompt 文本“请调用正确工具”安全集成企业系统。工具、API、事件、结构化输出、权限、审批、幂等和审计都需要契约优先设计。

---

Source Anchors

核心导读

Contract-first AI integration 的核心是: 先定义 tool/API/event 的结构、权限、副作用、错误、版本和证据要求, 再让模型或 agent 在这些受控契约内行动。

Prompt 可以提出意图, 但不能成为企业系统边界。真正的边界应由 OpenAPI、AsyncAPI、JSON Schema、policy、approval、idempotency、telemetry 和 contract testing 共同形成。否则 agent 只是把自然语言不确定性直接接到了核心系统。

金融零售场景下, 契约优先尤其关键: 查询、写备注、发通知、退款、冻结、报送监管材料都不是同一类动作。每个动作必须被分级、授权、验证、审计, 并能在变更时跑回归。

问题定义

低成熟度的工具调用设计通常像这样:

System prompt: You can call account lookup, refund, email, and case update tools.

这种做法把最关键的控制边界放进自然语言约定, 会产生一组系统性风险:

企业 AI agent 的集成原则应是:

Prompt proposes.
Contract constrains.
Policy authorizes.
Telemetry proves.
Human approves when risk requires.

架构模型/核心原理

六类 AI 契约

AI 系统至少需要六类契约共同工作:

只定义 API schema 不够。AI-ready contract 必须同时定义结构、权限、副作用、错误、审批、幂等、版本和证据。

OpenAPI for tools

OpenAPI 适合描述同步 HTTP API 和 tool operations。一个 AI tool operation 应被看作业务动作, 而不是普通接口。

AI tool contract 通常需要普通 API contract 没有的扩展信息:

这些字段可以嵌入 OpenAPI extension, 也可以维护在 tool registry 中, 但不能只存在于 prompt 或会议记录。

AsyncAPI and event contracts

Agent workflow 不一定都是同步请求。很多企业 AI 场景是事件驱动:

• 文档上传后触发 extraction。
• 风险告警触发 investigation assistant。
• 客户投诉触发 triage workflow。
• 人工审批完成后恢复 agent workflow。
• model/prompt/eval 版本变更触发 regression run。

事件契约需要表达:

常见 agent event:

这些事件让 agent 从黑盒推理变成可观测工作流。

关键机制

JSON Schema for structured IO

结构化输出契约可用于工具参数、模型回答、分类结果、风险分级、eval judge 输出、人工复核表单和事件 payload。

结构化输出的关键不是方便解析, 而是把 AI 输出变成 contract-bound object, 可以验证、审计、回归测试和版本管理。

Error contract

AI agent 必须理解错误类别, 否则会盲目重试或编造结果。

错误契约必须进入 eval, 否则“失败路径”只存在于开发文档。

Versioning and compatibility

Contract versioning 对 AI agent 更敏感, 因为模型行为、tool selection、eval trajectory 和 policy decision 都可能受影响。

Contract testing

Contract testing 是把“agent 会正确使用工具”的希望, 转成可回归验证的证据。

证据与控制

Contract-first AI 的控制链可以表达为:

tool/event discovery
  -> schema validation
  -> policy decision
  -> approval if required
  -> idempotent execution
  -> telemetry/audit event
  -> eval and runtime evidence

Contract review 不应只由工程完成。需要同时检查真实任务支持、边界可复用性、攻击面、数据分类、高风险动作、错误处理、重试、SLO、审计和变更影响。

AI产品/金融零售场景

Dispute resolution agent

Agent 可做:

• 读取交易详情。
• 读取争议政策。
• 生成 case summary。
• 创建内部 note。
• 请求人工审批。

Agent 不可做:

• 自动退款。
• 直接发送客户通知。
• 修改监管报告。
• 查看无关客户数据。

Tool contract matrix:

Event flow:

case.dispute.triage.requested
  -> agent.workflow.started
  -> agent.tool.proposed(transaction.lookup)
  -> agent.tool.executed
  -> agent.tool.proposed(policy.search)
  -> agent.tool.executed
  -> agent.output.generated(case_summary)
  -> agent.approval.requested if high amount
  -> agent.workflow.completed or escalated

每个 event 都应带 traceparent、case id、workflow id、contract version、policy decision、actor/agent identity。

需求表达也要契约化。不要只写“Agent 可以查询交易”, 而要写:

Release gate 应检查 tool cards、schemas、side-effect matrix、permission tests、prompt injection tests、trajectory eval、negative cases、error behavior、retry/DLQ、idempotency、dashboard、risk approval、trace sample 和 rollback plan。

反模式

最终心智模型

Contract-first AI tool/API design 可以用一条执行链理解:

Intent
  -> contract
  -> policy
  -> approval
  -> execution
  -> telemetry
  -> evidence
  -> regression

判断一个 AI tool 是否 enterprise-ready, 看它是否回答了这些问题:

成熟的 AI agent 不是“会调用很多工具”, 而是只能发现和调用当前任务、权限、风险等级允许的工具, 并且每次调用都能被验证、阻断、审批、追踪和复盘。

---

SOTA 检查 (2026-07-01)

• OpenAPI 现役版本为 v3.2.0（2025-09 发布）：在 3.1 基础上新增嵌套 tags、流式媒体类型（SSE / JSON Lines / JSON Seq）、原生 QUERY HTTP method、OAuth 2.0 Device Authorization Flow——其中流式媒体类型对描述 LLM/agent 的 streaming tool 响应直接相关。OpenAPI 4.0 "Moonwalk" 仍处设计阶段、未发布，本篇以 OAS 为 tool contract 载体的主线不受影响。
• MCP 已成为 tool contract 的事实分发层：现行稳定版为 2025-11-25 修订版；2026-07-28 新版规范的 Release Candidate 已发布（含 breaking changes），其中 tool 的 inputSchema/outputSchema 提升为完整 JSON Schema 2020-12（支持 oneOf/anyOf/allOf、条件、$ref/$defs），structuredContent 可为任意 JSON 值——这正是本篇 "Structured output contract" 一节主张的官方化。落地时注意本仓库 AIPA 纪律：MCP server 构建应排在 2026-07-28 最终规范之后（详见 docs/aipa/day44-mcp-final-spec.md、docs/aipa/day50-mcp-server-build.md）。
• OpenAPI→MCP 自动生成已是主流工程路径（2025-2026）：Speakeasy、FastMCP（gofastmcp.com 的 OpenAPI 集成）、openapi-mcp 等工具把 OpenAPI 文档作为唯一 source of truth 生成 MCP server，避免 MCP 与 OpenAPI 契约双源分叉——印证本篇"契约不能只存在于 prompt 或 registry 之外"的判断；但社区共识也提醒直接 1:1 暴露 endpoint 语义常太细碎，仍需按业务动作（本篇的 tool card）重新聚合。
• AsyncAPI 侧结论仍成立：AsyncAPI 3.x（当前参考规范 v3.1.0）原生支持 request/reply 关联语义；2025 年社区年报显示 spec 包年下载量 54M，且官方明确把「哪些 agent 能向哪些 channel 发布、如何审计 agent 通信」列为 AsyncAPI 在企业 AI 治理中的定位——与本篇 event contract + evidence contract 的框架一致。
• 不随版本过时的框架性结论：六类契约模型（tool/event/structured output/policy/eval/evidence）、"Prompt proposes / Contract constrains / Policy authorizes / Telemetry proves" 执行链、错误分类学、幂等与审批分级、契约回归测试——这些与具体规范版本解耦，是本篇的长期价值；具体扩展字段（x-ai-*）与协议版本号需按上面三条持续复查。落地模板见配对的 docs/AI_CONTRACT_FIRST_TOOL_API_DESIGN_OPENAPI_ASYNCAPI_PLAYBOOK.md 与 docs/AI_AGENT_PROTOCOLS_MCP_A2A_PLAYBOOK.md。