Como orientar uma resposta em andamento

Ao orientar uma resposta em andamento, o usuário pode acrescentar requisitos ou mudar de direção sem esperar que a resposta termine.

Os modelos da família GPT-6 permitem orientar respostas em andamento por uma conexão WebSocket com a Responses API. O GPT-5.6 e os modelos anteriores não oferecem esse recurso.

Uma nova orientação não altera a saída já enviada ao aplicativo, não desfaz ações anteriores nem cancela a execução de ferramentas que já foram acionadas.

O exemplo em Java requer a versão 17 ou posterior do Java. Para saber como configurar a conexão e como funciona o transporte de dados, consulte o modo WebSocket. Para ver a definição exata de cada evento, 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 e use o ID da resposta como valor de 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 os campos type, previous_response_id e input. Use como valor de input uma string ou um array não vazio de mensagens do usuário com tipos de conteúdo compatíveis.

A API confirma que a entrada foi adicionada à fila com response.steer.accepted:

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

A confirmação indica apenas que a entrada está na fila. O modelo pode ainda não ter agido com base nela. A API cria automaticamente uma nova resposta com a atualização, a menos que precise receber do aplicativo o resultado de uma ferramenta ou uma aprovação.

Antes de criar essa continuação automática, o servidor conclui o item de saída atual e aguarda a conclusão de qualquer tarefa já em execução nas ferramentas hospedadas. Continue lendo os eventos para receber a resposta com a atualização. Não envie outro response.create.

Se a orientação interromper a resposta original, a resposta terminará com response.incomplete e incomplete_details.reason: "steered". Se a resposta original terminar normalmente antes disso, ela manterá o status de concluída e ainda poderá ter uma continuação com a nova 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 inclui um cliente WebSocket para a Responses API. Por isso, este exemplo não tem uma versão que use o SDK em C#.

Atualize um plano de projeto enquanto ele está sendo gerado

Python

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
84// 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",
      store: false,
      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
48
49
50
51
52
53import 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())

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
61ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
client := openai.NewClient()
conn, err := client.Responses.Connect(ctx, responses.ResponseConnectionOptions{})
if err != nil {
	log.Fatal(err)
}
defer conn.Close()
if err := conn.Create(ctx, responses.ResponsesClientEventResponseCreateParam{
	Model: "gpt-6-astra",
	Reasoning: shared.ReasoningParam{
		Effort: shared.ReasoningEffortMedium,
	},
	Store: openai.Bool(false),
	Input: responses.ResponsesClientEventResponseCreateInputUnionParam{
		OfString: openai.String("Draft a project plan for building a task-tracking app."),
	},
}); err != nil {
	log.Fatal(err)
}
initialID, successorID := "", ""
for {
	event, err := conn.Recv(ctx)
	if err != nil {
		log.Fatal(err)
	}
	switch event.Type {
	case "response.created":
		id := event.OfResponsesServerEventResponseWsCreated.Response.ID
		if initialID == "" {
			initialID = id
			err := conn.Send(ctx, responses.ResponsesClientEventUnionParam{
				OfResponseSteer: &responses.ResponseSteerEventParam{
					PreviousResponseID: id,
					Input: responses.ResponseSteerInputUnionParam{
						OfString: openai.String("Keep the scope small enough for one developer to finish in two weeks."),
					},
				},
			})
			if err != nil {
				log.Fatal(err)
			}
		} else {
			successorID = id
		}
	case "response.steer.failed", "response.failed", "error":
		log.Fatal(event.RawJSON())
	case "response.incomplete":
		r := event.OfResponsesServerEventResponseWsIncomplete.Response
		if r.ID != initialID || r.IncompleteDetails.Reason != "steered" {
			log.Fatal(event.RawJSON())
		}
	case "response.completed":
		r := event.OfResponsesServerEventResponseWsCompleted.Response
		if successorID != "" && r.ID == successorID {
			fmt.Println(r.OutputText())
			return
		}
	}
	// Steering acceptance only queues input. Wait for the successor to complete.
}

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
67import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.*;
import java.util.*;

var client = OpenAIOkHttpClient.fromEnv();

long deadline = System.nanoTime() + java.util.concurrent.TimeUnit.SECONDS.toNanos(120);
try (var conn =
    client.async().responses().connect().get(10, java.util.concurrent.TimeUnit.SECONDS)) {
  conn.send(
      ResponsesClientEvent.ofResponseCreate(
          ResponsesClientEvent.ResponseCreate.builder()
              .model("gpt-6-astra")
              .reasoning(
                  com.openai.models.Reasoning.builder()
                      .effort(com.openai.models.ReasoningEffort.MEDIUM)
                      .build())
              .store(false)
              .input("Draft a project plan for building a task-tracking app.")
              .build()));
  String initialId = null, successorId = null;
  while (true) {
    var event =
        conn.receive()
            .get(
                Math.max(1, deadline - System.nanoTime()),
                java.util.concurrent.TimeUnit.NANOSECONDS);
    if (event.responseCreated().isPresent()) {
      var id = event.responseCreated().orElseThrow().response().id();
      if (initialId == null) {
        initialId = id;
        conn.send(
            ResponsesClientEvent.ofResponseSteer(
                ResponseSteerEvent.builder()
                    .previousResponseId(id)
                    .input(
                        "Keep the scope small enough for one developer to finish in two weeks.")
                    .build()));
      } else {
        successorId = id;
      }
    } else if (event.responseSteerFailed().isPresent()
        || event.responseFailed().isPresent()
        || event.error().isPresent()) {
      throw new IllegalStateException(event.toString());
    } else if (event.responseIncomplete().isPresent()) {
      var response = event.responseIncomplete().orElseThrow().response();
      if (!response.id().equals(initialId)
          || !response
              .incompleteDetails()
              .flatMap(Response.IncompleteDetails::reason)
              .map(r -> r.toString().equals("steered"))
              .orElse(false)) throw new IllegalStateException(event.toString());
    } else if (event.responseCompleted().isPresent()
        && event.responseCompleted().orElseThrow().response().id().equals(successorId)) {
      event.responseCompleted().orElseThrow().response().output().stream()
          .flatMap(item -> item.message().stream())
          .flatMap(message -> message.content().stream())
          .flatMap(content -> content.outputText().stream())
          .forEach(text -> System.out.println(text.text()));
      break;
    }
    // Acceptance only queues input; follow the successor through completion.
  }
} finally {
  client.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
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", store: false, 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 atualização quando o usuário a fornecer. Depois de receber o evento response.created da continuação, use o ID dessa continuação para enviar novas orientações.

Retorne resultados de ferramentas ou uma aprovação

Se a resposta precisar do resultado de uma ferramenta do cliente ou de uma aprovação, a API manterá a orientação na fila. Siga o fluxo habitual de execução de ferramentas ou de aprovação na mesma conexão.

Por exemplo, a resposta original pode terminar com uma chamada a get_project_status. Os exemplos 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 a orientação aceita que ainda depende de dados adicionais. O campo required_input desse evento indica quais resultados de ferramentas ou aprovações a API precisa receber para 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 os dados solicitados com response.create pela mesma conexão e defina previous_response_id como resp_1. Não repita a orientação já aceita. Uma chamada explícita a response.create usa suas próprias ferramentas, instruções e demais configurações.

Os comentários neste exemplo em JSONC mostram onde o servidor insere 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ê pode retornar os resultados das ferramentas sem esperar pelo evento response.steer.pending. Se o servidor já tiver recebido o response.create correspondente, poderá prosseguir sem enviar essa notificação antes.

Trate falhas e desconexões

response.steer.failed indica que a API não aplicou a entrada como orientação e não a aplicará automaticamente mais tarde. O evento retorna os valores originais de input e previous_response_id dentro de steer, com um objeto error que descreve a falha.

Use steer.id para acompanhar cada orientação aceita. Se ocorrer uma falha depois, o evento de falha usará o mesmo ID.

Códigos de erro comuns:

invalid_input: Use apenas os campos aceitos pelo evento e envie somente mensagens do usuário como entrada.
steering_not_supported: O modelo, os parâmetros da solicitação ou ambos podem ser incompatíveis com o envio de orientações.
response_not_found: A resposta à qual se destina a orientação precisa continuar disponível na mesma conexão WebSocket.
too_many_pending_steers: Há orientações demais na fila. Retorne os resultados de ferramentas ou as aprovações solicitadas usando response.create. Se não houver nada a retornar, aguarde a continuação automática antes de enviar mais orientações. Não reenvie orientações já aceitas.

As orientações na fila existem apenas na conexão atual. Elas não ficam armazenadas com a resposta original. Registre as orientações que enviar e compare esses registros com os eventos e o histórico de respostas antes de reenviá-las. Após uma desconexão, não presuma que as orientações pendentes continuam na fila. Consulte as orientações para recuperar uma conexão WebSocket.

Sugestões

Primeiros passos

Conceitos fundamentais

SDKs e CLI

Provedores de nuvem

Recursos

APIs legadas

Escolha um modelo

Texto e código

Como escrever prompts

Raciocínio

Imagens

Tempo real e áudio

Modelos especializados

API de agentes

SDK de agentes

ChatKit

Busca e recuperação de informações

Conecte ferramentas e dados

Crie fluxos de trabalho com ferramentas

Computador e código

Mídia

GPT-Live

Realtime API

Desenvolver aplicações de voz

Conexões

Processamento de áudio

Coloque em produção

Desempenho e qualidade

Avaliação

Custo e taxa de processamento

Segurança e governança

Infraestrutura e acesso

Operações

Conceitos fundamentais

Planejar

Desenvolver

Testar e publicar

Especificações de conversão

Guias

Recursos

Identidade

Uso do plano do ChatGPT

Guias

Envio de arquivos

API

Mensuração

API para anunciantes

Referência da API

Primeiros passos

Primeiros passos

Fundamentos

Explorar

Disponível em

Versões

Fluxos de trabalho

Capacidades

Sites

dots

ChatGPT Space

Referência

Personalização

Arquivo de configuração

Configuração de agentes

Ampliar os recursos do ChatGPT e do Codex

Linux

Windows

Fluxos de trabalho de desenvolvimento

Ampliar recursos e automatizar tarefas

Ambientes

Codex Cloud

Desenvolver com o Codex

Integrações de terceiros

Referência

Permissões

Codex Security

Segurança cibernética

Primeiros passos

Configuração de recursos

Identidade e acesso