For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

轮次中途引导

在响应运行期间发送用户的更新要求。

轮次中途引导让用户无需等待响应结束,即可添加要求或改变方向。

通过连接 Responses API 的 WebSocket 连接,您可以在 GPT-6 Astra(gpt-6-astra)中使用轮次中途引导。GPT-5.6 及更早的模型 不支持引导。

引导不会改写已发送到您应用的输出、撤销之前的操作,也不会取消已启动的工具。

有关连接设置和常规传输行为,请参阅 WebSocket 模式。有关事件的确切定义,请参阅 Responses WebSocket 事件参考资料

发送引导消息

使用 response.create 启动响应。收到该响应的 response.created 事件后,在同一连接上发送 response.steer,并将该响应的 ID 用作 previous_response_id

{
  "type": "response.steer",
  "previous_response_id": "resp_1",
  "input": "Keep the scope small enough for one developer to finish in two weeks."
}

该事件仅接受 typeprevious_response_idinput。将 input 设为字符串,或由用户消息组成的非空数组,消息须使用受支持的内容类型。

API 通过 response.steer.accepted 确认输入已加入队列:

{
  "type": "response.steer.accepted",
  "sequence_number": 4,
  "steer": {
    "id": "steer_0123456789abcdef0123456789abcdef",
    "previous_response_id": "resp_1"
  }
}

接受输入表示输入已加入队列,并不意味着模型已据此采取行动。除非需要您的应用提供工具结果或审批,否则 API 会自动创建包含您更新要求的新响应。

在自动创建这一后续响应之前,服务器会先完成当前输出项以及已在运行的托管工具任务。请继续读取事件,以接收包含您更新要求的响应;不要再次发送 response.create

如果引导中断了原始响应,该响应会以 response.incompleteincomplete_details.reason: "steered" 结束。如果原始响应先正常完成,则会保留已完成状态,之后仍可生成由引导触发的后续响应。

自动创建的后续响应会继承原始请求的设置。Token 和工具调用限制分别适用于每个响应。

运行完整示例

.NET SDK 不提供 Responses WebSocket 客户端,因此本示例没有 C# SDK 版本。

在运行过程中更新项目计划
import asyncio

from openai import AsyncOpenAI


async def main():
    client = AsyncOpenAI()
    initial_response_id = None
    successor_response_id = None

    async with client.responses.connect() as connection, asyncio.timeout(120):
        await connection.response.create(
            model="gpt-6-astra",
            reasoning={"effort": "medium"},
            input="Draft a project plan for building a task-tracking app.",
        )
        async for event in connection:
            if event.type == "response.created":
                if initial_response_id is None:
                    initial_response_id = event.response.id
                    # Simulate a user adding instructions while the response runs.
                    await connection.response.steer(
                        previous_response_id=initial_response_id,
                        input="Keep the scope small enough for one developer to finish in two weeks.",
                    )
                else:
                    successor_response_id = event.response.id
            elif event.type in {"response.steer.failed", "response.failed", "error"}:
                raise RuntimeError(event.to_json())
            elif event.type == "response.incomplete":
                response = event.response
                if (
                    response.id != initial_response_id
                    or response.incomplete_details is None
                    or response.incomplete_details.reason != "steered"
                ):
                    raise RuntimeError(event.to_json())
            elif (
                event.type == "response.completed"
                and event.response.id == successor_response_id
            ):
                print(event.response.output_text)
                return
            # Acceptance only queues the input. Keep reading past the first response.
        raise RuntimeError("Connection closed before the steered response finished.")


asyncio.run(main())

此示例在第一个 response.created 事件之后发送更新要求。在您的应用中,请在用户提供更新要求时发送。收到后续响应的 response.created 事件后,请使用该后续响应的 ID 发送新的引导。

返回工具结果或审批

如果响应需要客户端工具结果或审批,API 会让引导输入继续排队。请在同一连接上继续正常的工具或审批流程。

例如,原始响应完成时可以包含对 get_project_status 的调用。以下载荷仅展示相关字段:

{
  "type": "response.completed",
  "response": {
    "id": "resp_1",
    "status": "completed",
    "output": [
      {
        "type": "function_call",
        "call_id": "call_project",
        "name": "get_project_status",
        "arguments": "{\"project\":\"task-tracker\"}"
      }
    ]
  }
}

原始响应完成后,对于已接受但仍需输入的引导,API 会发送 response.steer.pending。其中的 required_input 字段列出 API 在应用更新要求之前所需的工具结果或审批:

{
  "type": "response.steer.pending",
  "sequence_number": 12,
  "steer": {
    "id": "steer_0123456789abcdef0123456789abcdef",
    "previous_response_id": "resp_1"
  },
  "reason": "waiting_for_required_input",
  "required_input": [
    {
      "type": "function_call_output",
      "call_id": "call_project",
      "name": "get_project_status"
    }
  ]
}

在同一连接上使用 response.create 返回所需输入,并将 previous_response_id 设为 resp_1。不要重复发送已接受的引导。显式发送的 response.create 使用其自身的工具、指令及其他设置。

此 JSONC 示例中的注释展示了服务器在何处添加排队的更新要求:

{
  "type": "response.create",
  "model": "gpt-6-astra",
  "previous_response_id": "resp_1",
  "input": [
    // The server implicitly prepends your accepted steer here:
    // "Keep the scope small enough for one developer to finish in two weeks."
    {
      "type": "function_call_output",
      "call_id": "call_project",
      "output": "Design is complete. Development has not started.",
    },
    {
      "role": "user",
      "content": "Show me the updated plan before starting any work.",
    },
  ],
}

您无需等待 response.steer.pending 即可返回工具结果。如果服务器已收到匹配的 response.create,则可以直接继续,无需先发送此通知。

处理失败和连接断开

response.steer.failed 表示 API 未通过引导应用该输入,之后也不会自动应用。该事件在 steer 下返回原始的 inputprevious_response_id,并通过 error 对象描述失败原因。

使用 steer.id 跟踪已接受的提交。后续若发生失败,会使用同一 ID。

常见错误代码:

  • invalid_input:请仅使用受支持的事件字段和用户消息输入。
  • steering_not_supported:模型、请求参数或两者可能与引导不兼容。
  • response_not_found:目标响应必须在同一 WebSocket 连接上仍然可用。
  • too_many_pending_steers:待处理的引导输入过多。如果需要返回工具结果或审批,请使用 response.create 返回;否则,请等待自动创建的后续响应,再提交更多输入。不要重新发送已接受的引导。

排队的引导输入仅存在于当前连接中,不会与原始响应一起存储。请记录您发送的引导输入,并在重放前将其与响应事件及历史记录进行核对。不要假定待处理的引导在连接断开后仍会保留。请参阅 WebSocket 恢复指南