GPT-6 Astra Migration Guide: Upgrading From Older Models

OpenAI's official GPT-6 Astra migration steps: model name, prompt_cache_options.ttl, dropped sampling params, the Responses API, and reasoning-effort updates.

GPT-6 Astra changes enough about the request shape that a straight model-name swap will break existing integrations. OpenAI's migration quickstart lists five concrete changes; this guide walks through each one and why it matters, so the cutover is a checklist rather than a debugging session.

What changes when you move to Astra

Astra is positioned as OpenAI's most advanced model for computer use, browsing, software engineering, and professional workflows, with new mechanics — async tool calling, mid-turn steering, dynamic reasoning adjustment, misalignment monitoring — that don't exist on older models. Some of those mechanics require different request parameters, which is why this is a migration, not just a version bump.

Set the model name and update prompt caching

The first two changes are the ones every caller needs regardless of use case:

• Set model to gpt-6-astra.
• Replace prompt_cache_retention with prompt_cache_options.ttl, set to "30m".

The cache-option rename isn't cosmetic — prompt_cache_retention is not accepted on Astra requests, so leaving it in place will fail rather than silently no-op. Audit every call site that sets prompt cache behavior before flipping the model name in production.

Remove temperature, top_p, and top_logprobs

OpenAI's migration guidance is explicit: remove the temperature, top_p, and top_logprobs parameters entirely. If your current integration tunes generation behavior through these knobs, that tuning needs to move elsewhere — through prompting (the best-practices guide above covers the instruction-level levers OpenAI recommends) rather than sampling parameters. Leaving these parameters in the request is the most likely single cause of a failed migration test, since older SDKs and wrapper libraries often set them by default even when the caller never touches them explicitly.

Switch tool calling to the Responses API

Astra's tool calling is documented against the Responses API, not the older chat-completions-style tool-calling path. If your integration currently drives tools through a different API surface, that call path needs to move to the Responses API as part of this migration — it's the interface async tool calling and mid-turn steering are built on, so it isn't optional for anyone using those features.

Adjust reasoning effort mid-conversation

Astra supports dynamic reasoning adjustment: you can change reasoning effort mid-conversation without invalidating the cache, which is new relative to older models where effort was fixed for the life of a session. To use it, employ a configuration_update item rather than restarting the conversation or re-sending prior context — that's the documented mechanism for effort changes mid-stream.

Limitations to plan around before you cut over

Two constraints affect migration planning specifically: Astra has no none reasoning mode, so any integration that explicitly disabled reasoning needs a fallback plan; and Fast mode is unavailable for EU data residency deployments, which matters if your current setup relies on Fast mode and serves EU-resident data. Check both against your current configuration before scheduling the cutover, not after.

Neither limitation is a reason to delay the migration on its own — most integrations don't rely on disabled reasoning or on Fast mode specifically — but both are quick to check and expensive to discover mid-rollout. Add them to the same pre-cutover audit as the parameter changes above rather than treating them as a separate, optional pass.

Migration checklist

• Set model to gpt-6-astra everywhere it's hardcoded or configured.
• Replace every prompt_cache_retention reference with prompt_cache_options.ttl: "30m".
• Strip temperature, top_p, and top_logprobs from request bodies and SDK defaults.
• Move tool-calling call sites onto the Responses API.
• Replace any mid-session restart hack for reasoning-effort changes with a configuration_update item.
• Confirm you're not depending on none reasoning mode or Fast mode in an EU data residency deployment.

Once the request shape is migrated, the prompting layer is a separate pass — see our GPT-6 Astra best practices guide for the instruction-level changes OpenAI recommends on top of this, and GPT-6 Astra best use cases for where the new capabilities change what's worth building.