GPT-5.2 Chat's Responses, Reasoning, and Tool-Calling Configuration

一句话结论

对多轮 Agent，优先用 Responses API 保存跨轮状态，显式设置推理和 verbosity，并用 allowed_tools 限制当前回合可用工具，通常比把所有工具和调用顺序硬编码进提示更易控。

适用场景

• 适合的任务：多轮检索、代码/文件处理、需要工具前置说明和审计的 Agent。

• 不适合的任务：只需一次短文本回复的聊天；此时 Chat Completions 或更低成本模型可能更简单。

• 适用的模型版本：官方页面中的 gpt-5.2、gpt-5.2-pro 与 gpt-5.2-chat-latest；具体参数支持要按 endpoint 核对。

• 适用的客户端、Agent 或 API：OpenAI Responses API；Chat Completions 迁移时需重新核对消息/工具参数映射。

• 推荐的推理档位和参数：低延迟从 reasoning: {"effort":"none"} 开始；复杂任务逐级尝试 medium/high/xhigh；text.verbosity 默认 medium，按输出目的调节。

可直接使用的内容

下面是按官方示例整理的最小 Responses 配置骨架；不是把 Chat 版本的所有能力都保证为可用，部署前必须用目标模型做 schema 检查。

{
  "model": "gpt-5.2",
  "input": "完成任务后给出可核验的结果。调用工具前先用一句话说明目的；每次写入后说明改动位置并验证。",
  "reasoning": { "effort": "none" },
  "text": { "verbosity": "medium" },
  "tools": [
    {
      "type": "function",
      "name": "search_docs",
      "description": "Search the approved document corpus and return source IDs. Validate input and never invent results."
    },
    {
      "type": "function",
      "name": "write_record",
      "description": "Write one validated record. Return the exact record ID and path after success."
    }
  ],
  "tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
      { "type": "function", "name": "search_docs" }
    ]
  }
}

若工具需要模型发送原始文本（例如 SQL、代码或 DSL），官方还支持 custom tool；但服务端必须做注入、权限和语法校验：

{
  "type": "custom",
  "name": "code_exec",
  "description": "Executes only sandboxed Python code; reject filesystem, network, and credential access."
}

测试/工作流步骤

1. 先在 Responses API 中登记完整工具集；按当前阶段把只读工具放入 allowed_tools。

2. 对同一任务分别跑 none、medium，记录完成率、工具调用数、延迟、token 和错误类型。

3. 让每个工具描述明确说明用途、何时调用和返回值；写工具必须在服务端返回 ID/路径并重新读取验证。

4. 对跨轮任务保存 response 状态；上下文接近上限时按官方 compaction 方案压缩，并在压缩后重跑关键断言。

5. 如果从 Chat Completions 迁移，保持任务提示不变先做 baseline，再单独改 API、推理档位和工具限制。

原始证据与数据

• 官方 guidance 建议 GPT-5.2 复杂推理/多步 Agent 使用 gpt-5.2，而 gpt-5.2-chat-latest 用于 ChatGPT 对齐行为；gpt-5.2-pro 适合更难但可等待更久的问题。

• 官方说明 none 是 GPT-5.2 的最低推理档位/默认起点，并建议需要更多思考时逐步增加到 medium。

• 官方明确 allowed_tools 可从完整工具列表中限制当前回合的可调用子集，模式可为 auto 或 required。

• 官方称 named apply_patch 在其测试中使失败率下降 35%，但没有公开完整 harness、任务集和置信区间，不能外推为所有应用的保证。

• 官方称 Responses API 可跨轮传递推理上下文并减少重复推理 token；具体收益取决于应用状态管理和请求实现。

适用边界

• 该骨架把官方 API 示例和安全约束组合在一起；其中工具名、权限和校验逻辑是示例，不是 OpenAI 托管工具的默认安全策略。

• gpt-5.2-chat-latest 模型页当前标记 deprecated，且 Chat Completions 的上下文和输出限制不同于 gpt-5.2；不能直接复制所有 Responses 参数。

• temperature/top_p/logprobs 仅在 GPT-5.2 的 reasoning.effort=none 时受官方指南支持，其他档位使用 reasoning/verbosity/max output 等控制。

• custom tool 可以发送自由文本，但官方强调必须服务端验证，不能让模型直接获得未沙箱化的 shell、网络或凭证。

来源摘录或观察（仅做合规短引）

官方指南建议工具描述“concise, explicit”，并要求服务端验证 freeform 输出；这是配置工具 Agent 时最重要的安全边界。