Responses API Recovery Workflow：把 Responses API 放进真实 agent 工程恢复路径

从 Chat Completions 到 Responses API：一个 must-know 的迁移痛点

如果你正把 agent 从 Chat Completions 迁移到 Responses API，很快就会发现：新的接口统一了文本生成、工具调用、文件处理等多个端点，但它的 recovery 逻辑并不 trivial。本文聚焦一个具体矛盾——当 API 调用失败时，怎么恢复才能不影响整个 agent 链路？

Responses API 在 recovery workflow 中的角色

Responses API 承担两个关键角色：

• 统一的响应容器：它将模型输出、工具调用结果、文件引用打包在一个 response 对象里，你只需要处理这一个对象，而不是拼凑多个端点的输出。
• 状态锚点：每个 response 都有唯一的 ID，可用于后续的追溯、重试或 fallback。这意味着你可以把 response ID 当作 recovery 的 checkpoint。

但统一也带来了耦合风险：一次请求可能同时包含文本和多个工具调用，任一个子任务失败都会导致整个 response 不符合预期。

失败模式清单：哪些情况会打破 workflow

实际操作中，以下三种失败模式最常见：

1. 工具调用超时或异常

当模型决定调用一个外部工具（如搜索数据库），而该工具没有在规定时间内返回结果，整个 response 可能被标记为 incomplete。如果你没有捕获这个状态，agent 会卡住。

2. 响应截断（truncation）

由于 max_tokens 限制，模型输出可能被截断。此时 response 对象里的 truncated 字段为 true，但很多人会忽略它，直接使用不完整的输出做下一步决策。

3. 内容过滤命中

当模型输出被 OpenAI 的内容安全策略拦截时，response 状态会是 filtered。这种情况在 agent 生成代码或敏感文本时容易发生。

Fallback 接口选择：什么时候用 Assistants API 什么时候降级到 Chat Completions

并不是所有失败都需要复杂的 recovery。我建议按以下策略分级：

• 超时 / 截断 → 直接用相同的输入重试（最多 3 次），并增加 max_tokens 或缩短工具超时阈值。
• 工具调用失败 → 如果某个工具持续失败，应从工具列表中暂时移除它，并用纯文本回复告知用户“该工具不可用”，避免 agent 死循环。
• 内容过滤 / 连续失败 → 降级到 Chat Completions API，只用简单的 system prompt，不做工具调用，确保至少能给用户一个兜底回复。

代码示意（Python）：

def run_with_recovery(messages, tools):
    try:
        response = client.responses.create(
            model="gpt-4o",
            input=messages,
            tools=tools
        )
        if response.status == "incomplete":
            # 检查 truncation
            if response.truncated:
                return retry_with_increased_tokens(messages, tools)
            # 检查工具超时
            if any(call.status == "failed" for call in response.tool_calls):
                return fallback_to_chat(messages)
        return response
    except Exception:
        return fallback_to_chat(messages)

工具调用的恢复陷阱

Responses API 的 tool_calls 数组里每个元素都有 id、type、status。最容易踩的坑是：

• 只检查 status 是否为 "completed"，忽略 "failed" 状态。
• 把失败的工具调用结果拼到 conversation history 里，导致模型后续重复尝试相同工具。

正确做法：对失败的工具调用，添加一条 assistant 消息说明“该工具暂时不可用”，并设置 output_tools 参数禁止模型再次调用。

真实场景：用户查询实时股票数据

假设 agent 需要调用一个股票价格 API。

• 正常流程：Responses API 调用股票工具，返回数据，agent 生成回答。
• 失败场景：股票 API 超时（5 秒无响应）。
• 我的 recovery：检测到工具调用状态失败 → 从 tools 列表中移除该工具 → 调用 Chat Completions 降级，回复“当前无法获取实时价格，请稍后再试”。

这个流程保证了 agent 不会因为一个下游接口失效而完全崩溃。

何时停止重试、启动 fallback

不要无限制重试。我设定了：

• 同一 input 重试最多 3 次
• 如果 3 次都失败，进入降级模式
• 降级模式持续 5 分钟，之后自动恢复原始工具列表

下一步：从普通开发者到 Agent 工程师

以上 recovery 设计只是一个起点。要真正在生产中驾驭 Responses API，你需要理解更多——比如 context 窗口管理、多 agent 协调、权限模型。这些内容在更高阶的课程中有系统讲解。