跳转到内容
Agentic Engineering Fieldbook

模型 API、工具调用与结构化输出

观察日期与维护状态

Section titled “观察日期与维护状态”

观察日期：2026-07-23。

适用范围：OpenAI Responses API 及相关的 function calling、结构化输出、会话状态和评估文档；Anthropic Messages API、工具使用文档和 API 版本管理文档。

维护状态：持续维护的领域笔记。当提供方调整主要请求格式、严格 schema 行为、工具结果表示、会话状态语义或 API 版本策略时，应重新审阅。

当前观察

Section titled “当前观察”

主要模型 API 正在收敛到一种清晰的使用模式：应用把指令、上下文和一组声明好的工具交给模型；模型可以选择某个工具并生成结构化参数；应用在模型之外执行操作；然后把结果交回后续模型步骤。

OpenAI 当前 API 文档把 function calling 和结构化输出描述为模型接口的一部分，Responses API 文档也包含会话状态机制。Anthropic 的 Messages API 和工具使用文档呈现出相近的整体形态，并围绕 API 行为提供明确的版本管理控制。它们的术语、请求结构、角色名称、结果表示和严格性保证并不相同。工程模式相似，不代表契约可以互换。

当前最重要的结论并不复杂：工具声明和 schema 已经是一等的行为塑造资产。它们应该像代码、提示词、策略和路由规则一样被审查、版本管理、测试和观测。即使应用二进制文件没有变化，只要改变工具描述、枚举值、嵌套 schema、响应格式或会话状态策略，也可能改变模型行为。

持久工程含义

Section titled “持久工程含义”

按 schema 约束输出，可以改善模型介导行为与确定性软件之间的交接。它能减少解析脆弱性，让无效值更容易被拒绝，也能让下游系统依赖更明确的数据结构。但它不能证明答案真实、已授权、完整、新鲜、安全，或适合用户目标。

把每一次工具调用都视为转换提议。模型可以提出操作和参数；执行边界决定这个操作是否有效、已授权、及时、幂等、可观测并且在预算内。严格 schema 可以说明 amount 是数字，却不能决定当前策略和证据是否允许这个账户退还这笔金额。

结构化最终输出也是如此。一个 JSON 对象可以格式合法，但仍然缺乏证据支撑。引用字段可以存在，却指向错误来源。风险分类可以匹配枚举值，但语义上仍然错误。用 schema 控制结构；用评估、验证、来源检查和人工复核控制含义与后果。

不要这样理解

Section titled “不要这样理解”

不要因为多个提供方提供相似概念，就断定工具调用已经是统一的协议标准。不同提供方的 API 在消息结构、支持的 schema 子集、状态归属、流式事件、并行工具行为、版本管理和错误处理上都有差异。

不要把提供方托管的会话状态推断为系统的权威状态。它可能是有用的上下文存储，但除非有更窄的契约另行规定，任务状态、已接受结果、审批、审计记录和外部影响仍由应用拥有。

不要把结构化输出理解成“有了它就不需要评估”。它只是把一部分失败从解析问题变成语义问题。这是进步，但问题也从“程序能不能读出来？”变成了“这个决策能不能信它？”

操作清单

Section titled “操作清单”
  • 在发布证据中记录提供方、API 版本或接口表面、模型标识符、请求模式、响应格式、工具声明和 schema 版本。
  • 将工具 schema 和结构化输出 schema 纳入代码审查和变更控制。
  • 在模型之外验证工具参数的类型、范围、租户、主体、目的、当前状态、幂等性和策略。
  • 用确定性测试覆盖畸形、缺失、未知、过期、重复和过宽的工具参数。
  • 将提供方托管的会话状态与权威应用状态区分开，除非状态归属边界已经明确。
  • 将提示词和工具描述一起版本管理；描述会影响模型如何选择工具和形成参数。
  • 即使每个输出都是合法 JSON，也要在代表性任务上评估语义成功。
  • 捕获能够连接模型决策、工具调用提议、验证、执行结果和最终已接受结果的追踪记录。
  • 将 schema 严格性、流式行为和工具调用限制视为带日期的依赖，而不是所有平台通用的属性。

参考文献及其使用方式

Section titled “参考文献及其使用方式”