As of August 14, 2026, OpenAI's GPT-5.6 model guide maps the gpt-5.6 alias to Sol, positions Terra as the balance of intelligence and cost, and identifies Luna as the cost-sensitive, high-volume option. Start by testing explicit model IDs at each workflow step and recording quality, latency, and spend for every successful task.
If you already have a repeatable task set, keep the harness unchanged. Test the current reasoning.effort and the next lower level before adding Terra, Luna, and Sol as candidates. Upgrade only when a candidate misses the rubric or the cost of an error is high. Without a fixed task set, do not estimate savings or enable new orchestration features.
The scope is OpenAI API model routing and billing. For context cleanup in long local Claude Code or Codex sessions, see the long-session token waste guide.
Route Sol, Terra, and Luna by Workflow Step
OpenAI recommends Sol for complex professional work, Terra for balancing capability and price, and Luna for cost-sensitive, high-volume work. Production routing still depends on your own task set; model positioning does not replace evaluation.
| Step Type | First Candidates | Upgrade When |
|---|---|---|
| Classification, extraction, format conversion, code search | Terra or Luna, starting at a lower reasoning level | Field accuracy, recall, or format compliance misses the target |
| Frequent tool selection and short decisions | Evaluate Luna and Sol together | Wrong-tool rate rises or end-to-end success falls materially |
| Long-context analysis, complex orchestration, final synthesis | Use Sol as the baseline and test Terra alongside it | The smaller model fails the fixed rubric |
| Final actions with a high error cost | Use the smallest passing model and keep approval in place | Human review or business controls cannot cover the remaining risk |
Do not assign one model to the entire agent workflow. Record each step's input, allowed tools, output contract, and error cost, then route the step independently. Extraction and final judgment can use different models, and the bill remains attributable to a specific step.
Use four completion gates:
| Completion Metric | Requirement |
|---|---|
| Task outcome | Success rate does not fall below the current baseline |
| Critical behavior | Required fields and tool selection pass the rubric |
| Latency | p95 stays within budget |
| Bill | Uncached input, cache reads and writes, output tokens, and tool fees reconcile per successful task |
Price the Three Models and Long Context First
The following standard text prices were verified on August 14, 2026, in US dollars per million tokens. Pricing changes; reopen each model page before migrating.
| Model | Input | Cached Input | Output |
|---|---|---|---|
| GPT-5.6 Sol | $5.00 | $0.50 | $30.00 |
| GPT-5.6 Terra | $2.00 | $0.20 | $12.00 |
| GPT-5.6 Luna | $0.20 | $0.02 | $1.20 |
GPT-5.6 cache reads cost 0.1 times the uncached input rate, while cache writes cost 1.25 times that rate. Uncached input means tokens that are neither read from nor written to cache. When input exceeds 272K tokens, the full request is billed at twice the input rate and 1.5 times the output rate. Add per-call tool fees separately when a model tool charges for each call.
Cost per successful task =
(uncached input tokens × input rate
+ cache-read tokens × cached-input rate
+ cache-write tokens × input rate × 1.25
+ output tokens × output rate
+ tool fees) ÷ successful tasks
For asynchronous evaluations, data backfills, or other low-priority work, also compare the Batch API and Flex processing. Flex trades slower responses and occasional resource unavailability for lower cost, so keep it off production paths with strict real-time requirements.
Test Adjacent Reasoning Levels on the Same Tasks
The GPT-5.6 model guide lists six reasoning.effort levels and sets medium as the default. Keep the current level as the migration baseline, then test one level lower. Move higher only when the fixed task set shows a quality gain.
| Range | reasoning.effort Values |
|---|---|
| Lower through default | none, low, medium (default) |
| Higher | high, xhigh, max |
After setting OPENAI_API_KEY, run this Responses API request to establish a Terra + low baseline:
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5.6-terra",
"reasoning": {"effort": "low"},
"input": "Extract the priority, product, and next action from the ticket. Return JSON."
}'
Put model choice and reasoning effort in the same evaluation matrix:
| Candidate | Current Effort | Lower Effort | Higher Effort |
|---|---|---|---|
| Current production model | Preserve the baseline | Test if supported | Use only to locate the quality ceiling |
| Terra | Test | Test | Test only if it can close the quality gap |
| Luna | Test | Test | Test only if it can close the quality gap |
| Sol | Test | Prioritize this test | Reserve for hard cases with measured benefit |
| Metric Group | Record |
|---|---|
| Quality | End-to-end success rate and rubric score |
| Usage | Tool-call count plus input and output tokens |
| Latency | p50 and p95 |
| Cost | Cost per successful task |
Do not make a higher effort level the default if it adds tokens and latency without fixing failed cases.
Use standard mode as the baseline. For a difficult, high-value task with a clear quality gap, keep the same model ID and reasoning effort and test reasoning.mode: "pro". Pro mode increases latency, and tokens from the additional model work are billed at the selected model's standard rates. Stay on standard mode when the quality gain does not cover the added tokens, latency, and cost.
Inspect where failures occur. If lower reasoning effort concentrates errors in permission checks, amount verification, or irreversible actions, upgrade those steps or add human approval even when the overall success rate remains close.
Preserve Prior Reasoning and Compact Long Tasks
Persisted reasoning lets later Responses API requests use compatible prior reasoning items without exposing the raw reasoning text. GPT-5.6 defaults reasoning.context to all_turns. It has an effect only when the request receives earlier response items through previous_response_id, a conversation, or complete history; on the first request, it behaves like current_turn.
Long-running work can combine persisted reasoning with server-side compaction. Replace resp_previous below with the actual previous response ID. The compact_threshold value is illustrative; set a production threshold from context growth and regression tests.
{
"model": "gpt-5.6-terra",
"previous_response_id": "resp_previous",
"reasoning": {"context": "all_turns"},
"context_management": [
{"type": "compaction", "compact_threshold": 200000}
],
"input": "Continue with the remaining files and preserve the earlier prohibitions."
}
| Check | Stop or Roll Back When |
|---|---|
| Goal, prohibitions, and output contract | Constraint loss rises after compaction |
| IDs, amounts, and timestamps in tool results | Critical facts can no longer be traced or restored |
| Prior reasoning and task state | A bad assumption persists, or the savings do not cover debugging cost |
Set reasoning.context to current_turn when earlier reasoning is no longer relevant. Store permissions, amounts, and irreversible state in structured data rather than relying only on opaque reasoning items or compacted output.
Use Programmatic Tool Calling for Deterministic Data Work
Programmatic Tool Calling fits a bounded step that retrieves substantial structured data and then filters, aggregates, or sorts it. OpenAI runs model-generated JavaScript in a fresh, isolated V8 environment. The runtime supports top-level await, but it has no Node.js APIs or package installation. It also lacks direct network access and a general-purpose file system. State does not persist across programs, and subprocesses and a console are unavailable.
Add programmatic_tool_calling to the request's tools array and use allowed_callers to identify the tools that a program can invoke. Give stable return values an output_schema as well:
{
"tools": [
{
"type": "function",
"name": "get_records",
"description": "Return the record count for a status.",
"parameters": {
"type": "object",
"properties": {"status": {"type": "string"}},
"required": ["status"],
"additionalProperties": false
},
"output_schema": {
"type": "object",
"properties": {"record_count": {"type": "number"}},
"required": ["record_count"],
"additionalProperties": false
},
"allowed_callers": ["programmatic"]
},
{"type": "programmatic_tool_calling"}
]
}
For example, after an agent retrieves 100 files:
- The tool returns structured records and source IDs.
- Code filters by date, type, status, or numeric value.
- The aggregation layer sends only matched records, statistics, and source mappings to the model.
- The model explains differences, resolves ambiguity, and writes the conclusion.
Move deterministic processing into the program—for example, deduplication, exact sums, sorting, and pagination. Keep semantic judgment, conflicting evidence, and rule exceptions with the model, and preserve sources for review.
The isolated V8 runtime does not constrain a tool's external side effects. The application still handles program, program-issued tool calls, and program_output, linking events with call_id and caller. The tool-execution layer must continue to validate identity and arguments and retain approval for high-impact actions.
Enable Multi-agent Beta Only for Independent Workstreams
As of August 14, 2026, Responses API Multi-agent remains in beta. Raw HTTP requests must send OpenAI-Beta: responses_multi_agent=v1 and enable multi_agent in the request body:
curl https://api.openai.com/v1/responses \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-H "OpenAI-Beta: responses_multi_agent=v1" \
-d '{
"model": "gpt-5.6-terra",
"input": "Review three independent modules in parallel, then reconcile conflicts and omissions.",
"multi_agent": {
"enabled": true,
"max_concurrent_subagents": 3
}
}'
The default and recommended value of max_concurrent_subagents is 3, and it limits concurrent subagent turns across the entire tree. The API does not limit the total number of subagents or tree depth, so the application must cap total tokens, tool calls, and maximum runtime. Multi-agent also does not support max_tool_calls; do not treat that parameter as a total-budget control.
| Gate | Requirement |
|---|---|
| Parallelism | Workstreams are independent, and elapsed-time savings exceed startup and synthesis overhead |
| Dependencies and writes | Workstreams do not modify the same object or depend on an earlier result |
| Permissions | The tool layer revalidates identity, arguments, and actions |
| Synthesis | The primary agent checks sources, conflicts, and omissions instead of concatenating results |
A Multi-agent request configures one model. Every agent can see every tool configured on the request, and per-agent tool isolation is not available. Record elapsed time, total tokens, and total tool calls together. Return to a single agent if quality does not improve or merge conflicts erase the parallelism benefit.
Cache a Stable Prefix Explicitly and Audit Reads and Writes
GPT-5.6 prompt caching requires a fully rendered prefix of at least 1,024 tokens before the breakpoint. prompt_cache_options.ttl currently supports only 30m, which is also the default. Each reuse refreshes the 30-minute TTL without another cache-write charge. prompt_cache_key participates in matching alongside an identical prefix; keep aggregate traffic for one key at roughly 15 requests per minute or less.
Place the breakpoint at the end of a stable developer message and use explicit mode to stop changing user input from triggering implicit writes:
{
"model": "gpt-5.6-terra",
"prompt_cache_key": "support:knowledge-base-v1",
"prompt_cache_options": {
"mode": "explicit",
"ttl": "30m"
},
"input": [
{
"type": "message",
"role": "developer",
"content": [
{
"type": "input_text",
"text": "Stable rules, tool instructions, and knowledge-base content...",
"prompt_cache_breakpoint": {"mode": "explicit"}
}
]
},
{
"type": "message",
"role": "user",
"content": "The user's question for this turn"
}
]
}
Replace the abbreviated content with a real stable prefix that reaches 1,024 rendered tokens. The short text in the example will not create a cache entry.
| Position | Content |
|---|---|
| Before the breakpoint | Stable rules, tool definitions, structured-output schema, shared knowledge |
| After the breakpoint | Timestamps, request IDs, user input, retrieval results for this turn |
Use a stable, partitionable prompt_cache_key that does not expose personal information. Split high-volume workloads across keys with a deterministic mapping.
Responses API reports cached_tokens and cache_write_tokens in usage.input_tokens_details. If writes stay high while reads remain low, the breakpoint contains changing content or the cache is not being reused. Move the breakpoint, switch to explicit-only caching, or disable caching on that path.
Roll Out Against a Fixed Task Set
Build a fixed set from production failures, common tasks, and expensive tasks. Give every sample a success condition, allowed tools, prohibited actions, and an acceptable output. Do not use the current production model's answer as the sole ground truth.
| Stage | Action | Entry Condition for the Next Stage |
|---|---|---|
| Baseline | Record the current model, reasoning effort, quality, p95 latency, and cost | Samples and rubrics rerun consistently |
| Candidates | Keep the harness fixed; test adjacent effort levels and all three models | Task-level quality meets the threshold |
| Capabilities | Test reasoning reuse and compaction, PTC, Multi-agent, and caching separately | Benefit is attributable and failures can be replayed |
| Gradual rollout | Deploy only step-level routes that pass, with a rollback switch | Online success rate and cost per successful task remain stable |
Split gradual-rollout logs into four groups:
| Log Group | Fields |
|---|---|
| Model configuration | Model, reasoning.effort, reasoning.mode |
| Context and cache | reasoning.context, compaction, cache-read and cache-write tokens |
| Agents and tools | Subagent count, tool calls |
| Version and rollback | Pricing verification date, rollback reason |
Logging only the final model name leaves no way to locate the source of a cost or quality change.
Check Four Gates Before Expanding the Rollout
| Gate | Requirement |
|---|---|
| Models and evaluation | Fixed task set, success conditions, current baseline, and step-level routes are complete |
| State and context | Permissions, amounts, and irreversible state live in structured data; compacted context can be replayed |
| Tools and agents | PTC calls validate arguments and approvals; Multi-agent handles independent work under a total budget |
| Cache and bill | Cache reads and writes, uncached input and output, the long-context multiplier, and tool fees are included |
Traffic expansion requires recorded passes for task success, p95 latency, and cost per successful task. A failure in any one of them triggers the rollback switch, restoring the previous model and evaluation harness.