Plan a beta-to-GA Realtime migration

Real workflow example

A team built a realtime support prototype during a beta period. It works for demos, but production usage depends on fragile event names, temporary model choices, custom transcript parsing, and a client connection flow nobody has revisited.

The migration should not be a single dependency bump. Realtime behavior touches connection setup, audio devices, event handling, transcript storage, tool calls, and user experience. The safe path is to run the old and new paths side by side behind a feature flag until call quality and operational metrics are stable.

Implementation approach

Inventory the current realtime surface first. List session creation, client connection, event listeners, audio input, audio output, interruption handling, transcript handling, tool calls, and cleanup.

Then create a compatibility map. For every old event or payload shape, document the new equivalent and the local code path that consumes it. Keep this map close to the adapter code so future migrations are smaller.

Roll out by workflow, not by entire application. Start with internal users, then a small customer segment, then full production. Track connection failures separately from model quality because they have different causes and fixes.

Code or config snippet

type RealtimeEventMap = {
  oldName: string;
  newName: string;
  localHandler: string;
  migrationStatus: "mapped" | "changed" | "removed" | "needs_test";
};

export const realtimeMigrationMap: RealtimeEventMap[] = [
  {
    oldName: "transcript.delta",
    newName: "response.audio_transcript.delta",
    localHandler: "appendTranscriptDelta",
    migrationStatus: "needs_test",
  },
];

Mistakes to avoid

• Do not migrate event names without testing actual microphone and speaker behavior.
• Do not assume transcript timing is unchanged.
• Do not change the model, voice, tools, and event parser in one release.
• Do not remove the old path until real calls pass acceptance tests.
• Do not combine connection errors and answer-quality errors in one metric.

Ready checklist

• Current session creation flow is documented.
• Event names and payload shapes are mapped.
• Audio input, output, interruption, and silence are tested.
• Transcript and summary storage are verified.
• The new path is behind a rollout flag.
• Metrics track connection, latency, interruption, escalation, and call completion.

Practical tip

Record short internal test calls for the migration, then compare transcript completeness and operator summaries between old and new paths. The comparison exposes behavior changes that unit tests rarely catch.