题目与适用场景
请把一个面向人工开发者的项目管理 API 改造成适合 AI Agent 调用的 API。你会如何设计操作描述、输入输出、分页、错误、写入确认、限流和安全边界？题目参考 IETF 2026 年 6 月发布的《Agent-Friendly HTTP API Profile》Internet-Draft。该文档是 Informational、仍为 work in progress，不定义新的协议、身份认证或授权机制。
面试官考察点
- 能否把机器可读描述当作契约，而不是事后文档。
- 能否通过稳定命名、严格 schema、有限响应和游标分页减少错误选择。
- 能否让错误、重试、幂等、预览和撤销成为可执行信号。
- 能否区分 API 可用性与 Agent 身份、授权、提示注入等安全问题。
回答前需要澄清的问题
- Agent 通过 OpenAPI、MCP 工具层还是自定义目录发现 API？
- 哪些操作只读，哪些操作会通知、扣费或改变状态？
- 响应是否需要字段选择、游标分页和最大页大小？
- 超时重试时，客户端能否提供幂等键并读取原始结果？
- 哪些返回字段来自不可信用户内容，必须与控制字段隔离？
30 秒回答框架
我会把 API 描述和 HTTP 行为一起当作 Agent 的输入契约。操作名稳定且表达意图，输入 schema 严格拒绝未知字段，响应默认小且可选字段，集合使用游标分页。错误返回稳定 code、是否可重试和下一步链接；写操作支持幂等键、预览、确认和撤销。服务器强制限流、响应大小、权限与审计，不能把安全决策交给 Agent。该 IETF 文档是草案清单，不是新的认证协议。
分步骤深入解答
1. 分离 API 层与工具层
OpenAPI 等机器可读描述属于 API 层，MCP 或其他工具调用协议属于工具层。先把 API 设计成稳定、可验证的契约，多个工具层才能复用；不要把某个 Agent 的提示词或工具名称当作唯一安全边界。
2. 设计可区分的操作
操作 ID 要稳定、短且说明意图。工具面很大时，实体优先的 task_create、task_update 比只有 create_ 前缀更容易区分。描述应明确何时使用、何时不能使用、是否有副作用，以及缺少标识符时先调用哪个查询操作。
3. 严格约束输入与响应
输入 schema 设置必填字段、封闭枚举、长度和数组上限，并拒绝未知属性。响应默认返回小对象，支持字段选择或 verbosity；不要让客户端“自己少取一点”，因为服务器仍需控制成本和上下文占用。
{
"name": "task_create",
"description": "Create a task; notifies the assignee.",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"required": ["project_id", "title", "idempotency_key"],
"properties": {
"project_id": {"type": "string"},
"title": {"type": "string", "maxLength": 200},
"priority": {"type": "string", "enum": ["low", "medium", "high"]},
"idempotency_key": {"type": "string", "maxLength": 128}
}
}
}4. 让读取和分页可恢复
集合返回游标而不是要求 Agent 计算 offset；游标应是不透明、过期且绑定查询条件。响应给出 next_cursor 和可执行的下一步。稳定排序、条件请求和字段选择降低重复传输与上下文消耗。
5. 让错误成为机器信号
错误使用稳定 code、结构化详情和 retryable 标志；必要时附带下一步操作链接。429 要给出重试等待，验证错误要指出具体字段，异步任务要返回状态查询地址。自然语言可帮助人理解，但不能承担唯一控制语义。
{
"type": "https://api.example/problems/rate-limit",
"title": "Too many requests",
"status": 429,
"code": "RATE_LIMITED",
"retryable": true,
"retry_after_seconds": 30
}6. 保护写操作
写操作接受幂等键并定义有效窗口和作用域；超时重试应返回原始结果，而不是重复创建。高风险写入提供 dry-run、确认或撤销，并在描述中明确通知、扣费和外部副作用。服务器端仍要执行授权、配额和审计。
7. 处理安全边界与可观测性
用户或第三方返回的文本必须标记为数据，与可信控制字段分离，降低间接提示注入影响。限制响应大小、页大小、轮询频率和工具命名空间；高风险操作要求最小权限和人工确认。记录 correlation ID、操作者、委托信息、请求结果和重试，不记录敏感内容。
8. 验证与迭代
用固定任务集评估操作选择准确率、参数错误率、重复写入率、可恢复错误率、平均响应大小、上下文占用、429 后成功率和人工确认覆盖率。对描述、schema、错误和响应做版本化；草案建议应转成内部检查清单，而不是对外承诺标准兼容。
高质量示范回答
我会先把 API 描述视为主契约，再设计 HTTP 行为。操作 ID 稳定、表达实体和意图，描述同时写清使用条件、禁用场景和副作用；输入 schema 严格拒绝未知字段，枚举、长度、数组和页大小都有上限。集合使用不透明游标和稳定排序，响应默认小并支持字段选择。
错误返回稳定 code、是否可重试、retry_after 和下一步链接。写操作要求幂等键，超时重试返回原始结果；高风险写入支持预览、确认或撤销。服务器强制权限、限流、大小和审计，不能依赖 Agent 遵守描述。用户内容与控制字段隔离，工具按提供方隔离并保留 correlation ID。
最后用任务集测量错误选择、参数错误、重复写入、响应大小、重试成功率和人工确认覆盖率。IETF 文档是 2026 年 6 月的 Informational 草案，未定义认证或授权，因此我会把它当成设计检查清单，保留内部版本和回滚策略。
常见错误
- 把 Agent-friendly profile 说成新的身份认证或授权协议。
- 只优化提示词，不把 OpenAPI、schema、错误和副作用写入契约。
- 让 Agent 自己限制响应大小或计算分页 offset。
- 写操作没有幂等键、预览、确认和撤销，重试会重复副作用。
- 把用户返回文本放进可信指令字段，忽略间接提示注入。
追问及应对
为什么不只写一份更详细的文档？
Agent 每次根据机器可读描述和响应做选择，稳定字段、枚举、错误标志和游标比散落在长文中的建议更容易被执行；文档仍用于人类解释和迁移。
API 层和 MCP 工具层谁负责安全？
API 层必须执行认证、授权、限流和审计；工具层可以限制暴露范围、命名空间和确认流程，但不能替代服务器端访问控制。
如何决定哪些写操作需要确认？
按不可逆性、金额、数据披露、外部通知和权限范围分级。高风险操作提供 dry-run 或确认 token，低风险幂等更新可以自动执行，但始终由服务器验证。
如果描述被第三方内容污染怎么办？
把第三方文本放进明确的数据字段，禁止其改变工具定义或权限；对工具来源做命名空间隔离、指纹固定和版本审计，并在服务器端重新检查授权。