Responses context compaction

Compact complete history and continue with the returned context window.

Handle growing history before it exceeds the model’s context window. The standalone compaction endpoint returns a new context window; it does not produce the final answer and is not a universal summarization API. Confirm that the same model and channel support both /responses/compact and /responses, including preservation and replay of compaction items.

Compact and continue

Install the existing Python example dependencies. The script uses a fixed demonstration conversation, compacts it, then appends a question and generates text: two requests. In a real application, supply your complete saved inputs, outputs, tool results, and reasoning items.

export API_BASE_URL="https://gateway.example.com/v1"
export API_KEY="YOUR_API_KEY"
export API_MODEL="YOUR_MODEL_ID"
.venv/bin/python examples/compaction.py

import os
from openai import OpenAI, APIConnectionError, APIStatusError

history = [
    {"role": "user", "content": "Plan a two-day visit to Kyoto without driving."},
    {"role": "assistant", "content": "Day one: eastern temples. Day two: Arashiyama by train."},
]
instructions = "Answer briefly in plain text. Preserve the user's travel constraints."
with OpenAI(base_url=os.environ["API_BASE_URL"].rstrip("/"),
            api_key=os.environ["API_KEY"], timeout=60.0, max_retries=0) as client:
    try:
        compacted = client.post("/responses/compact", cast_to=dict, body={
            "model": os.environ["API_MODEL"], "input": history,
            "instructions": instructions,
        })
        if (not isinstance(compacted, dict) or compacted.get("error")
                or compacted.get("object") != "response.compaction"):
            raise ValueError("Invalid compaction response.")
        window = compacted.get("output")
        if not isinstance(window, list) or not window:
            raise ValueError("Empty compacted window.")
        found_compaction = False
        for item in window:
            if not isinstance(item, dict) or not isinstance(item.get("type"), str) or not item["type"]:
                raise ValueError("Invalid context item.")
            if item["type"] == "compaction":
                encrypted = item.get("encrypted_content")
                if not isinstance(encrypted, str) or not encrypted.strip():
                    raise ValueError("Missing encrypted content.")
                found_compaction = True
        if not found_compaction:
            raise ValueError("Missing compaction item.")
        # Keep every returned item, in order, including unknown metadata.
        next_input = [*window, {"role": "user", "content": "Add a rainy-day alternative."}]
        result = client.responses.create(
            model=os.environ["API_MODEL"], input=next_input,
            instructions=instructions, store=False,
        )
        if result.status != "completed" or not result.output_text.strip():
            raise ValueError("No complete text reply.")
        for item in result.output:
            if item.type == "reasoning":
                continue
            if (item.type != "message" or item.status != "completed"
                    or any(part.type != "output_text" for part in item.content)):
                raise ValueError("Unexpected or incomplete output item.")
        print(result.output_text)
    except APIStatusError as error:
        raise SystemExit(f"Request failed (HTTP {error.status_code}). No automatic retry.")
    except APIConnectionError:
        raise SystemExit("Connection failed. Original history must be retained.")
    except (ValueError, TypeError, AttributeError):
        raise SystemExit("Invalid compaction or continuation. Original history must be retained.")

Retention and replay

Standalone compaction returns object: response.compaction and output; do not read it using the usual Responses status / output_text contract. Preserve the entire ordered output, including additional fields. Use it as the next context window and append new input. Do not keep only the compaction item or append the old transcript again.

encrypted_content is opaque state, not a readable summary to decode or modify. The input to compaction must still fit the model’s context window. See the OpenAI compaction guide for these protocol rules.

The example supplies instructions explicitly on each request and continues with store: false. That is not a retention guarantee for the gateway, logs, or upstream. Compaction does not synchronize your database, business state, or permission rules.

Failure and compatibility

• Keep the original history if compaction fails or returns an empty window. Do not continue generation or automatically delete history.
• If compaction succeeds but continuation fails, retain the original history and valid compacted window so the application can choose a recovery point. Do not automatically rerun the entire flow.
• Load balancing may send the two requests to incompatible upstreams. Confirm routing, credentials, and state compatibility with the administrator; the same model ID alone does not guarantee replay.
• Automatic context_management, stored response IDs, and background execution are separate capabilities. Responses retrieval covers only plugin task responses, not general upstream retrieval or REST deletion / cancellation. See API coverage.

This text example checks window structure and final text completion, not preservation of every fact. Evaluate important constraints, tool associations, and long-conversation quality against a real deployment. The local fixture does not validate encrypted state.

Multi-turn conversations · Production integration

阅读中文

Prompt caching · Reasoning models · Context management