GPT-6 Astra Streaming Guide: Responses API Events, Tools and Error Handling

Streaming improves perceived latency by delivering events while GPT-6 Astra is working. It does not make the underlying computation free or remove failure cases. A production client must assemble incremental output, render tool progress, distinguish terminal states, and recover when a connection fails.

Start with typed events

Set stream: true and iterate over the SDK’s typed event stream.

const stream = await client.responses.create({
  model: "gpt-6-astra",
  input: "Explain the migration plan in five steps.",
  stream: true
});

for await (const event of stream) {
  switch (event.type) {
    case "response.output_text.delta":
      process.stdout.write(event.delta);
      break;
    case "response.completed":
      console.log("\nComplete");
      break;
    case "response.failed":
      console.error("Failed", event.response.error);
      break;
    case "error":
      console.error(event.message);
      break;
  }
}

Common text lifecycle events include response.created, response.output_text.delta, response.completed, and error. The full event union also contains output-item, content-part, annotation, refusal, failure, and other events. Handle unknown event types safely so a newly added event does not crash an older client.

Build an assembler, not a text append loop

A response can contain multiple output items and content parts. Index state by response, output item, and content part rather than appending every delta to one global string. Deduplicate using documented identifiers or sequence data where available, and render only committed local state.

Annotations and citations may arrive separately from text. Preserve their offsets or associations rather than stripping them during concatenation. Treat a final response object as authoritative when available.

Terminal states are not interchangeable

response.completed means successful completion. response.failed carries a failure. response.incomplete may reflect token limits or another reason and can contain useful partial output. A transport-level error can occur without a normal response terminal event.

Never mark a request successful just because the socket closed. Persist the response ID as soon as response.created arrives, then save the terminal status separately.

Stream tool activity honestly

Tool calls introduce phases: model planning, argument generation, server or client execution, tool result, and resumed generation. Your UI should say “Searching” or “Waiting for approval” only when the corresponding event/state exists. Do not fabricate progress percentages.

For client-executed functions, assemble complete arguments before parsing unless the API contract explicitly supports incremental consumption. Validate them, execute once, and return the result using the call ID. Streaming a duplicate event must not trigger a duplicate side effect.

Backpressure and UI performance

Token-sized deltas can arrive faster than a browser should render. Buffer briefly and update the UI at a controlled cadence. This reduces layout work without materially harming perceived latency. Bound in-memory buffers and pause downstream processing if your framework supports it.

Separate the raw event log from the view model. The event log supports debugging; the view model combines deltas into stable user-visible content. Redact sensitive tool payloads before logging.

Disconnects, timeouts, and cancellation

On disconnect, classify the operation as unknown until you recover state. A model response may have continued server-side, and an external tool may already have acted. Avoid automatically replaying writes.

Use request deadlines and idle-stream timers, but distinguish “no text delta” from “no activity”; a long tool call may still be healthy. Cancellation should propagate to your own cancellable tools. It cannot guarantee rollback of completed effects.

If you continue through response state, preserve the last committed response and tool results. WebSocket-specific recovery may report previous_response_not_found; the official error guide recommends retrying with full input context and previous_response_id: null when state cannot be resolved.

Observability

Record time to response.created, first text delta, first tool event, and terminal event; total duration; event counts; terminal status; disconnects; retries; and user cancellation. Correlate all events with one application request ID and the OpenAI response ID.

Test malformed order, duplicate delivery, unknown events, a tool timeout, a late failure after visible text, and loss of connection after a write. Streaming correctness is state-machine correctness.

Browser and server implementation pattern

In many products, the application server should hold the OpenAI connection and relay a sanitized event stream to the browser. This keeps API credentials off the client, centralizes authorization, and lets the server hide internal tool arguments. The browser receives only events needed for rendering: status, safe text deltas, citations, approval prompts, and terminal outcome.

Persist coarse checkpoints rather than every character. Saving every delta creates excessive writes; saving only at completion loses too much on disconnect. A short interval or content-part boundary is usually a better compromise. On reconnect, send the latest committed view and continue from the next known event according to your transport design.

Moderation and safety need a streaming policy. Partial text reaches users before the final response exists, so downstream review that runs only at completion may be too late. Choose pre-generation controls, incremental safeguards, buffering, or restricted streaming according to risk. High-stakes workflows may intentionally trade some immediacy for review.

Finally, ensure analytics do not double-count a response resumed after a browser refresh. The OpenAI response ID and your stable application request ID should join every segment into one logical task.

FAQ

Does streaming reduce token cost?

No. It changes delivery, not the number of generated tokens.

Can I show partial output immediately?

Yes, but mark it as in progress and be prepared for refusal, incomplete, or failure outcomes.

Should I retry when the connection closes?

Recover or reconcile first, especially if tools can cause side effects. Blind replay can duplicate actions.

Are SSE and WebSocket event handling identical?

They share Responses concepts but transport and continuation behavior differ. Follow the guide for the selected mode.

Conclusion

Reliable GPT-6 Astra streaming requires typed event handling, a structured assembler, explicit terminal states, idempotent tool execution, backpressure, and recovery. Optimize the user’s perception of progress without turning partial text or a closed connection into a false claim of success.