Orientação durante o turno

A orientação durante o turno permite que os usuários adicionem requisitos ou mudem de direção sem esperar que uma resposta termine.

A orientação durante o turno não reescreve saídas já enviadas ao seu aplicativo, não desfaz ações anteriores nem cancela ferramentas cuja execução já começou.

Para saber como configurar a conexão e entender o comportamento geral do transporte, consulte Modo WebSocket. Para as definições exatas dos eventos, consulte a referência de eventos WebSocket da Responses API.

Envie uma mensagem de orientação

Inicie uma resposta com response.create. Depois de receber o evento response.created dessa resposta, envie response.steer pela mesma conexão, usando o ID da resposta como previous_response_id:

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

O evento aceita apenas type, previous_response_id e input. Defina input como uma string ou um array não vazio de mensagens do usuário com tipos de conteúdo compatíveis.

A API confirma a inclusão da entrada na fila com response.steer.accepted:

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

A aceitação significa que a entrada está na fila, não que o modelo já agiu com base nela. A API cria automaticamente uma nova resposta com sua atualização, a menos que precise de um resultado de ferramenta ou aprovação do seu aplicativo.

Antes de criar essa continuação automática, o servidor conclui o item de saída atual e qualquer trabalho de ferramenta hospedada que já esteja em execução. Continue lendo os eventos para receber a resposta com sua atualização; não envie outro response.create.

Se a orientação interromper a resposta original, ela termina com response.incomplete e incomplete_details.reason: "steered". Se a resposta original terminar normalmente antes disso, ela mantém o status de concluída e ainda pode ter uma continuação com a orientação.

As continuações automáticas herdam as configurações da solicitação original. Os limites de tokens e de chamadas de ferramentas se aplicam separadamente a cada resposta.

Execute um exemplo completo

O SDK do .NET não oferece um cliente WebSocket para Responses, por isso não há uma versão deste exemplo com o SDK de C#.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83// Set OPENAI_API_KEY before running this example.
// Install the SDK and WebSocket transport: npm install openai ws

import OpenAI from "openai";
import { ResponsesWS } from "openai/resources/responses/ws";

const client = new OpenAI();
const ws = new ResponsesWS(client, {
  handshakeTimeout: 10_000,
});
let initialResponseId = "";
let successorResponseId = "";
let timeout;

try {
  const output = await new Promise((resolve, reject) => {
    timeout = setTimeout(() => {
      reject(new Error("Timed out waiting for the steered response."));
      ws.close();
    }, 120_000);
    ws.once("error", reject);
    ws.once("close", () => {
      reject(
        new Error("Connection closed before the steered response finished.")
      );
    });
    ws.on("event", (event) => {
      try {
        if (event.type === "response.created") {
          if (!initialResponseId) {
            initialResponseId = event.response.id;
            // Simulate a user adding instructions while the response runs.
            ws.send({
              type: "response.steer",
              previous_response_id: initialResponseId,
              input:
                "Keep the scope small enough for one developer to finish in two weeks.",
            });
          } else {
            successorResponseId = event.response.id;
          }
        } else if (
          ["response.steer.failed", "response.failed", "error"].includes(
            event.type
          )
        ) {
          reject(new Error(JSON.stringify(event)));
        } else if (
          event.type === "response.incomplete" &&
          (event.response.id !== initialResponseId ||
            event.response.incomplete_details?.reason !== "steered")
        ) {
          reject(new Error(JSON.stringify(event)));
        } else if (
          event.type === "response.completed" &&
          event.response.id === successorResponseId
        ) {
          let text = "";
          for (const item of event.response.output) {
            if (item.type !== "message") continue;
            for (const part of item.content) {
              if (part.type === "output_text") text += part.text;
            }
          }
          resolve(text);
        }
        // Acceptance only queues the input. Keep reading past the first response.
      } catch (error) {
        reject(error);
      }
    });
    ws.send({
      type: "response.create",
      model: "gpt-6-astra",
      reasoning: { effort: "medium" },
      input: "Draft a project plan for building a task-tracking app.",
    });
  });
  console.log(output);
} finally {
  clearTimeout(timeout);
  ws.close();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48import 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())

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45require "async"
require "openai"

client = OpenAI::Client.new
Sync do |task|
  task.with_timeout(120) do
    client.responses.connect(request_options: { timeout: 10 }) do |connection|
      connection.response.create(
        model: "gpt-6-astra", reasoning: { effort: "medium" },
        input: "Draft a project plan for building a task-tracking app."
      )
      state = {}
      while (event = connection.receive)
        case event
        when OpenAI::Responses::ResponseCreatedEvent
          response = event.response
          if !state[:initial_id]
            state[:initial_id] = response.id
            connection.send_event(
              type: "response.steer", previous_response_id: state[:initial_id],
              input: "Keep the scope small enough for one developer to finish in two weeks."
            )
          else
            state[:successor_id] = response.id
          end
        when OpenAI::Responses::ResponseSteerFailedEvent, OpenAI::Responses::ResponseFailedEvent, OpenAI::Responses::ResponsesServerEvent::ResponseWsError
          raise "Steering failed: #{event.to_json}"
        when OpenAI::Responses::ResponseIncompleteEvent
          response = event.response
          unless response.id == state[:initial_id] && response.incomplete_details&.reason.to_s == "steered"
            raise "Response incomplete: #{event.to_json}"
          end
        when OpenAI::Responses::ResponseCompletedEvent
          response = event.response
          next unless state[:successor_id] && response.id == state[:successor_id]

          puts(response.output_text)
          state[:completed] = true
          break
        end
      end
      raise "Connection closed before the steered response finished" unless state[:completed]
    end
  end
end

O exemplo envia a atualização após o primeiro evento response.created. No seu aplicativo, envie-a quando um usuário fornecer uma atualização. Use o ID da continuação para enviar novas orientações assim que o evento response.created dela chegar.

Retorne resultados de ferramentas ou aprovação

Se a resposta precisar de um resultado de ferramenta do cliente ou de aprovação, a API mantém a orientação na fila. Continue seu fluxo normal de ferramentas ou aprovação na mesma conexão.

Por exemplo, a resposta original pode terminar com uma chamada a get_project_status. Os payloads a seguir mostram apenas os campos relevantes:

123456789101112131415{
  "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\"}"
      }
    ]
  }
}

Depois que a resposta original termina, a API envia response.steer.pending para uma orientação aceita que ainda precisa de entrada. O campo required_input desse evento identifica os resultados de ferramentas ou as aprovações de que a API precisa antes de aplicar a atualização:

12345678910111213141516{
  "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"
    }
  ]
}

Retorne a entrada necessária com response.create pela mesma conexão, definindo previous_response_id como resp_1. Não repita a orientação aceita. Um response.create explícito usa suas próprias ferramentas, instruções e demais configurações.

Os comentários neste exemplo em JSONC mostram onde o servidor adiciona a atualização que está na fila:

123456789101112131415161718{
  "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.",
    },
  ],
}

Você não precisa esperar por response.steer.pending para retornar resultados de ferramentas. Se o servidor já tiver recebido um response.create correspondente, poderá prosseguir sem enviar essa notificação antes.

Trate falhas e desconexões

response.steer.failed significa que a API não aplicou a entrada por meio da orientação e não a aplicará automaticamente depois. O evento retorna os valores originais de input e previous_response_id dentro de steer, com um objeto error que descreve a falha.

Acompanhe os envios aceitos por steer.id. Uma falha posterior usa o mesmo ID.

Códigos de erro comuns:

• invalid_input: Use apenas os campos de evento compatíveis e mensagens do usuário como entrada.
• steering_not_supported: O modelo, os parâmetros da solicitação ou ambos podem ser incompatíveis com a orientação durante o turno.
• response_not_found: A resposta de destino ainda precisa estar disponível na mesma conexão WebSocket.
• too_many_pending_steers: Há entradas de orientação pendentes demais. Retorne os resultados de ferramentas ou as aprovações necessários usando response.create; caso contrário, aguarde a continuação automática antes de enviar mais entradas. Não reenvie orientações já aceitas.

As entradas de orientação na fila existem apenas na conexão atual; elas não são armazenadas com a resposta original. Registre as entradas de orientação que você envia e compare-as com os eventos e o histórico de respostas antes de reenviá-las. Não presuma que as orientações pendentes foram preservadas após a desconexão. Consulte as orientações de recuperação de WebSocket.