回合中調整方向可讓使用者新增需求或改變方向,無須等待回應完成。
使用 GPT-6 Astra(gpt-6-astra)時,可透過連至 Responses API 的
WebSocket 連線,在回合中調整方向。GPT-5.6 及更早的模型
不支援調整方向。
調整方向不會改寫已傳送至應用程式的輸出、復原先前的動作,或取消已開始執行的工具。
如需連線設定和一般傳輸行為的說明,請參閱 WebSocket 模式。如需事件的確切定義,請參閱 Responses WebSocket 事件參考資料。
傳送方向調整訊息
使用 response.create 啟動回應。收到該回應的 response.created 事件後,在同一條連線上傳送 response.steer,並將 previous_response_id 設為該回應的 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"。如果原始回應先正常完成,則會保留已完成狀態,且仍可產生依方向調整而建立的接續回應。
自動接續回應會沿用原始請求的設定。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 下回傳原始的 input 和 previous_response_id,並附上描述失敗情況的 error 物件。
使用 steer.id 追蹤已接受的提交內容。若之後發生失敗,會使用相同的 ID。
常見錯誤代碼:
invalid_input:請僅使用支援的事件欄位和使用者訊息輸入。steering_not_supported:模型、請求參數或兩者可能與方向調整功能不相容。response_not_found:目標回應必須仍可在同一條 WebSocket 連線上存取。too_many_pending_steers:待處理的方向調整輸入過多。請使用response.create回傳任何必要的工具結果或核准;若無此需求,請等待自動接續回應後再提交更多輸入。不要重新傳送已接受的方向調整訊息。
佇列中的方向調整輸入僅存在於目前的連線上,不會與原始回應一同儲存。請記錄你傳送的方向調整輸入,並在重新傳送前,先與回應事件和歷史記錄比對。不要假設待處理的方向調整輸入在連線中斷後仍會保留。請參閱 WebSocket 復原指引。