如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

在回應途中調整方向

在回應進行時傳送使用者的更新。

使用者可以在回應途中補充需求或調整方向,無須等到回應結束。

透過 WebSocket 連線至 Responses API 時,GPT-6 系列模型支援在回應途中調整方向。 GPT-5.6 和更早的模型不支援這項功能。

調整方向不會改寫已傳送至應用程式的輸出,也不會撤銷先前的動作或取消已開始執行的工具。

Java 範例需要 Java 17 或更新版本。如需瞭解如何設定連線以及一般的資料傳輸行為,請參閱 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."
}

這個事件只接受 type、previous_response_id 和 input 三個欄位。請將 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.incomplete 事件結束,並標示 incomplete_details.reason: "steered"。如果原始回應先正常結束,則會保留已完成狀態,API 仍可根據引導訊息建立後續回應。

自動建立的後續回應會沿用原始請求的設定。每個回應都會單獨計算 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:
        await connection.response.create(
            model="gpt-6-astra",
            store=False,
            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.")


async def run():
    await asyncio.wait_for(main(), timeout=120)


asyncio.run(run())

這個範例會在收到第一個 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 未能透過引導訊息套用輸入,之後也不會自動套用。事件會傳回原始的 input 和 previous_response_id,這兩個欄位都位於 steer 物件內。error 物件會說明失敗原因。

請使用 steer.id 追蹤已接受的引導訊息。如果後續處理失敗,失敗事件會使用相同的 ID。

常見錯誤碼:

  • invalid_input:請只使用支援的事件欄位,並以使用者訊息作為輸入。
  • steering_not_supported:模型或請求參數可能與引導功能不相容,也可能兩者都不相容。
  • response_not_found:目標回應必須仍可透過同一條 WebSocket 連線存取。
  • too_many_pending_steers:待處理的引導訊息過多。如果需要提供工具結果或核准,請使用 response.create 傳回。否則,請等到 API 自動建立後續回應,再傳送更多引導訊息。請勿重新傳送已接受的引導訊息。

排入佇列的引導訊息只存在於目前的連線中,不會與原始回應一起儲存。請記錄你傳送的引導訊息,並在重新傳送前,將這些訊息與回應事件和歷史記錄比對。請勿假設連線中斷後仍會保留待處理的引導訊息。請參閱 WebSocket 連線復原指南。