GPT-5.4：Responses API 工具搜索与 Phase 配置

一句话结论

GPT-5.4 的长程工具 Agent 应优先使用 Responses API，明确保存 phase，用 tool search 延迟加载大型工具定义，并按任务形状设置 reasoning/verbosity，而不是把全部 MCP schema 塞进每次请求。

适用场景

• 适合的任务：拥有大量函数/MCP 工具的 Agent、计算机使用、长上下文代码库、跨工具专业工作流。

• 不适合的任务：只需一个短回答却启用 1M 长上下文或全量工具定义；高风险 UI 操作也不适合无人确认。

• 适用的模型版本：gpt-5.4，快照 gpt-5.4-2026-03-05。

• 适用的客户端、Agent 或 API：Responses API、Codex；模型页列出 web/file search、code interpreter、computer use、MCP、tool search、apply patch、hosted shell 等支持。

• 推荐的推理档位和参数：默认 reasoning.effort="none"；研究/多步任务从 medium，复杂 Agent 可 high；text.verbosity 默认 medium，按交付物设 low/medium/high。

可直接使用的内容

基础 Responses 请求

from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-5.4",
    input="完成 <任务>。先说明目标和验收标准，再执行并验证。",
    reasoning={"effort": "medium"},
    text={"verbosity": "medium"},
)
print(response.output_text)

长程 Agent 的 phase 回放骨架

const response = await client.responses.create({
  model: "gpt-5.4",
  input: [
    {
      role: "assistant",
      phase: "commentary",
      content: "我会先检查日志，再总结根因和修复方案。",
    },
    {
      role: "assistant",
      phase: "final_answer",
      content: "根因：缓存失效竞态。",
    },
    { role: "user", content: "现在给出可安全上线的修复计划。" },
  ],
});

限制当前可用工具

{
  "tool_choice": {
    "type": "allowed_tools",
    "mode": "auto",
    "tools": [
      { "type": "function", "name": "get_weather" },
      { "type": "function", "name": "search_docs" }
    ]
  }
}

工具搜索的具体 hosted/client-executed schema 应按官方工具搜索文档接入；本文件只保留核心策略，不猜测完整 schema。

测试/工作流步骤

1. 先在 Responses API 中固定快照、reasoning、verbosity 和 max_output_tokens。

2. 将全部工具注册为可搜索集合，只在选中后加载完整定义；对安全敏感工具再用 allowed_tools 限制当前回合。

3. 运行长任务时把中间更新标为 phase="commentary"，最终交付标为 phase="final_answer"；回放 assistant history 时保留原 phase，不给 user 消息添加 phase。

4. 若使用 previous_response_id，优先让 API 保留前序状态；手动回放时完整保留 assistant 状态和 phase。

5. 超过 272K 输入 token 时单独记录长上下文价格/限额，并在里程碑后使用 compaction；用 Graphwalks/业务长文档测试信息召回而非只看窗口大小。

原始证据与数据

• 模型页：GPT-5.4 上下文 1,050,000、最大输出 128,000、reasoning none/low/medium/high/xhigh；标准价格每百万输入 $2.50、缓存 $0.25、输出 $15。

• 超过 272K 输入时，模型页说明标准/batch/flex 全 session 按 2× 输入和 1.5× 输出计价；regional processing 另有 10% uplift。

• 官方发布页在 36 个 MCP servers 的 MCP Atlas 250-task 平均中报告，tool search 在准确率保持相当时将总 token 使用降低 47%。

• 官方 guidance 要求长程/工具密集流程显式保留 phase；缺失或丢弃可能让 preamble 被当作 final answer。

• 模型支持文本/图像输入、文本输出；音频/视频不支持。Responses 工具列表支持 web search、file search、image generation、code interpreter、computer use、MCP 和 tool search。

适用边界

• 1M 是上下文上限，不代表在 1M 位置仍有恒定召回率；官方 Graphwalks 结果已显示超长区间准确率下降，应做业务长上下文 eval。

• tool search 减少工具定义 token，不保证工具选择正确；工具描述、allowed list 和服务器端校验仍需设计。

• phase 是长程 Responses 运行时契约，不是普通 Chat Completions 字段；迁移时不可只复制 prompt。

• temperature/top_p/logprobs 在 GPT-5.4 reasoning 非 none 时不兼容；应使用 reasoning、verbosity 和 max_output_tokens 调整行为。

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

OpenAI 将 tool search 概括为 “deferred tool loading”，并建议在长程流程显式使用 phase；两者共同解决工具面过大和中间消息误终止的问题。