Claude Platform Docs
MessagesУправление контекстом

Компактизация

Серверная компактизация контекста для управления длинными разговорами, приближающимися к пределам контекстного окна.

Компактизация увеличивает эффективную длину контекста для длительных разговоров и задач, автоматически суммируя более старый контекст при приближении к пределу «context window» (контекстного окна). Она также поддерживает активный контекст небольшим: по мере роста разговора качество ответов снижается, поэтому компактизация заменяет более старое содержимое кратким резюме.

Это идеально подходит для:

  • Многоходовых разговоров в формате чата, где вы хотите, чтобы пользователи использовали один чат в течение длительного времени
  • Ориентированных на задачи подсказок, требующих большого объёма последующей работы (часто с использованием инструментов), которая может превысить контекстное окно

Как работает компактизация

Когда компактизация включена, Claude автоматически суммирует ваш разговор, когда он достигает настроенного порога токенов. API:

  1. Определяет, когда входные токены достигают указанного вами порога срабатывания.
  2. Генерирует резюме текущего разговора.
  3. Создаёт блок compaction, содержащий резюме.
  4. Продолжает ответ с компактизированным контекстом.

В последующих запросах добавляйте ответ к вашим сообщениям. API автоматически отбрасывает все блоки содержимого, предшествующие блоку compaction, продолжая разговор с резюме.

Поток компактизации (compaction flow): когда входные токены достигают порога срабатывания (trigger), Claude записывает резюме в блок compaction и продолжает

Базовое использование

Включите компактизацию, добавив стратегию compact_20260112 в context_management.edits в вашем запросе к Messages API.

client = anthropic.Anthropic()

messages = [{"role": "user", "content": "Help me build a website"}]

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

# Добавьте ответ (включая любой блок компактизации), чтобы продолжить разговор
messages.append({"role": "assistant", "content": response.content})

Параметры

ПараметрТипПо умолчаниюОписание
typestringОбязательныйДолжен быть "compact_20260112"
triggerobject{"type": "input_tokens", "value": 150000}Когда запускать компактизацию. input_tokens — единственный поддерживаемый тип триггера. value должно быть не менее 50 000 токенов.
pause_after_compactionbooleanfalseДелать ли паузу после генерации резюме компактизации
instructionsstringnullПользовательская подсказка для суммаризации. При указании полностью заменяет подсказку по умолчанию.

Настройка триггера

Настройте момент срабатывания компактизации с помощью параметра trigger:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 150000},
            }
        ]
    },
)

Пользовательские инструкции по суммаризации

Подсказка для суммаризации по умолчанию различается в зависимости от модели. Каждая подсказка по умолчанию предписывает Claude написать резюме внутри тегов <summary></summary> с информацией, необходимой для продолжения задачи в будущем контекстном окне. Например, некоторые модели используют следующую подсказку:

You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

Вы можете предоставить пользовательские инструкции через параметр instructions. Пользовательские инструкции не дополняют подсказку по умолчанию. Они полностью её заменяют:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
            }
        ]
    },
)

На Claude Fable 5.1 и Claude Mythos 5.1 запрос с пользовательскими instructions суммирует только видимый разговор: более ранние блоки мышления не входят во входные данные суммаризатора.

Пауза после компактизации

Используйте pause_after_compaction, чтобы приостановить API после генерации резюме компактизации. Это позволяет вам добавить дополнительные блоки содержимого (например, сохранить недавние сообщения или конкретные сообщения с инструкциями), прежде чем API продолжит ответ.

Когда параметр включён, API возвращает сообщение с причиной остановки compaction после генерации блока компактизации:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Проверяем, вызвало ли уплотнение паузу
if response.stop_reason == "compaction":
    # Ответ содержит только блок уплотнения
    messages.append({"role": "assistant", "content": response.content})

    # Продолжаем запрос
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

Соблюдение общего бюджета токенов

Когда модель работает над длинными задачами со множеством итераций использования инструментов, общее потребление токенов может значительно вырасти. Вы можете объединить pause_after_compaction со счётчиком компактизаций, чтобы оценивать совокупное использование и корректно завершать задачу по достижении бюджета.

Этот пример приведён только на языках SDK: его ценность — в логике отслеживания бюджета вокруг запроса. Сам запрос объединяет trigger из раздела Настройка триггера с pause_after_compaction из раздела Пауза после компактизации.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
n_compactions = 0

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                "pause_after_compaction": True,
            }
        ]
    },
)

if response.stop_reason == "compaction":
    n_compactions += 1
    messages.append({"role": "assistant", "content": response.content})

    # Оценить общий расход токенов; запросить завершение при превышении бюджета
    if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
        messages.append(
            {
                "role": "user",
                "content": "Please wrap up your current work and summarize the final state.",
            }
        )

Работа с блоками компактизации

Когда срабатывает компактизация, API возвращает блок compaction в начале ответа ассистента.

Длительный разговор может привести к нескольким компактизациям. Последний блок компактизации отражает итоговое состояние подсказки, заменяя предшествующее ему содержимое сгенерированным резюме.

Output
{
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: The user requested help building a web scraper..."
    },
    {
      "type": "text",
      "text": "Based on our conversation so far..."
    }
  ]
}

Передача блоков компактизации обратно

Вы должны передавать блок compaction обратно в API в последующих запросах, чтобы продолжить разговор с сокращённой подсказкой. Самый простой подход — добавить всё содержимое ответа к вашим сообщениям:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# После получения ответа с блоком компактизации
messages.append({"role": "assistant", "content": response.content})

# Продолжаем разговор
messages.append({"role": "user", "content": "Now add error handling"})

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Когда API получает блок compaction, все блоки содержимого перед ним игнорируются. Вы можете либо:

  • Оставить исходные сообщения в вашем списке и позволить API самостоятельно удалить компактизированное содержимое
  • Вручную отбросить компактизированные сообщения и включать только блок компактизации и всё, что следует за ним

На Claude Fable 5.1 и Claude Mythos 5.1 блоки мышления, предшествующие блоку compaction, не переносятся дальше, поэтому резюме — это всё, что остаётся у модели от той более ранней работы. Если вы пишете собственные instructions, укажите модели, что должно сохраниться в резюме; см. Укажите модели, что сохранять в резюме компактизации.

Потоковая передача

При «streaming» (потоковой передаче) блок компактизации передаётся иначе, чем текстовые блоки. Вы получаете событие content_block_start, затем одно событие content_block_delta с полным содержимым резюме (без промежуточной потоковой передачи), а затем событие content_block_stop.

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]

with client.beta.messages.stream(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            if event.content_block.type == "compaction":
                print("Compaction started...")
            elif event.content_block.type == "text":
                print("Text response started...")

        elif event.type == "content_block_delta":
            if event.delta.type == "compaction_delta":
                print(f"Compaction complete: {len(event.delta.content or '')} chars")
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

    # Получить итоговое накопленное сообщение
    message = stream.get_final_message()
    messages.append({"role": "assistant", "content": message.content})

Кэширование подсказок

Компактизация хорошо сочетается с кэшированием подсказок (prompt caching). Вы можете добавить точку останова cache_control на блоки компактизации, чтобы кэшировать суммированное содержимое.

{
  "role": "assistant",
  "content": [
    {
      "type": "compaction",
      "content": "[summary text]",
      "cache_control": { "type": "ephemeral" }
    },
    {
      "type": "text",
      "text": "Based on our conversation..."
    }
  ]
}

Максимизация попаданий в кэш с помощью системных подсказок

Когда происходит компактизация, резюме становится новым содержимым, которое необходимо записать в кэш. Без дополнительных точек останова кэша это также сделало бы недействительной любую кэшированную системную подсказку (system prompt), потребовав её повторного кэширования вместе с резюме компактизации.

Чтобы максимизировать долю попаданий в кэш, добавьте точку останова cache_control в конце вашей системной подсказки. Это позволяет кэшировать системную подсказку отдельно от разговора, так что при компактизации:

  • Кэш системной подсказки остаётся действительным и читается из кэша
  • Только резюме компактизации нужно записать как новую запись кэша
client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    max_tokens=4096,
    system=[
        {
            "type": "text",
            "text": "You are a helpful coding assistant...",
            "cache_control": {
                "type": "ephemeral"
            },  # Cache the system prompt separately
        }
    ],
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

Это позволяет сохранять длинные системные подсказки в кэше на протяжении нескольких событий компактизации в ходе разговора.

Понимание использования

Компактизация требует дополнительного шага сэмплирования, который учитывается в ограничениях скорости и при выставлении счетов. API возвращает подробную информацию об использовании в ответе:

Output
{
  "usage": {
    "input_tokens": 23000,
    "output_tokens": 1000,
    "iterations": [
      {
        "type": "compaction",
        "input_tokens": 180000,
        "output_tokens": 3500
      },
      {
        "type": "message",
        "input_tokens": 23000,
        "output_tokens": 1000
      }
    ]
  }
}

Массив iterations показывает использование для каждой итерации сэмплирования. Когда происходит компактизация, вы увидите итерацию compaction, за которой следует основная итерация message. Поля верхнего уровня input_tokens и output_tokens в этом примере точно совпадают с итерацией message, поскольку есть только одна итерация, не являющаяся компактизацией. Количество токенов в последней итерации отражает эффективный размер контекста после компактизации.

Сочетание с другими функциями

Серверные инструменты

При использовании серверных инструментов (таких как веб-поиск) триггер компактизации проверяется в начале каждой итерации сэмплирования. Компактизация может произойти несколько раз в рамках одного запроса в зависимости от вашего порога срабатывания и объёма сгенерированного вывода.

Подсчёт токенов

Конечная точка подсчёта токенов (/v1/messages/count_tokens) применяет существующие блоки compaction в вашей подсказке, но не запускает новые компактизации. Используйте её, чтобы проверить эффективное количество токенов после предыдущих компактизаций:

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
    betas=["compact-2026-01-12"],
    model="claude-opus-5",
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")

Примеры

Вот полный пример длительного разговора с компактизацией:

client = anthropic.Anthropic()

messages: list[dict] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                }
            ]
        },
    )

    # Добавляем ответ (блоки компактизации включаются автоматически)
    messages.append({"role": "assistant", "content": response.content})

    # Возвращаем текстовое содержимое
    return next(block.text for block in response.content if block.type == "text")


# Запускаем длинный разговор
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Продолжайте вызывать chat() столько, сколько требует разговор

На Claude Fable 5.1 удалите блоки thinking и redacted_thinking из любого хода ассистента, который вы повторно вставляете после блока компактизации, либо отправьте thinking.block_binding.prefix_mismatch_behavior: "drop_block" с бета-заголовком thinking-binding-controls-2026-08-01. Эти блоки были созданы, когда присутствовала полная история, поэтому они больше не проходят проверку разговора. Там, где эта проверка применяется принудительно, запрос на продолжение отклоняется с ошибкой 400. Сохранённые текстовые блоки и блоки инструментов могут оставаться как есть. Если позволить API суммировать всё, не вставляя повторно более ранние ходы, этой проблемы можно избежать.

Вот пример, использующий pause_after_compaction, чтобы сохранить предыдущий обмен репликами и текущее сообщение пользователя (всего три сообщения) дословно вместо их суммаризации:

from typing import Any

client = anthropic.Anthropic()

messages: list[dict[str, Any]] = []


def chat(user_message: str) -> str:
    messages.append({"role": "user", "content": user_message})

    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Проверяем, произошло ли сжатие и была ли пауза
    if response.stop_reason == "compaction":
        # Получаем блок сжатия из ответа
        compaction_block = response.content[0]

        # Сохраняем предыдущий обмен + текущее сообщение пользователя (3 сообщения)
        # включая их после блока сжатия
        preserved_messages = messages[-3:] if len(messages) >= 3 else messages

        # Формируем новый список сообщений: сжатие + сохранённые сообщения
        new_assistant_content = [compaction_block]
        messages_after_compaction = [
            {"role": "assistant", "content": new_assistant_content}
        ] + preserved_messages

        # Продолжаем запрос со сжатым контекстом + сохранёнными сообщениями
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-5",
            max_tokens=4096,
            messages=messages_after_compaction,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )

        # Обновляем список сообщений с учётом сжатия
        messages.clear()
        messages.extend(messages_after_compaction)

    # Добавляем финальный ответ
    messages.append({"role": "assistant", "content": response.content})

    # Возвращаем текстовое содержимое
    return next(block.text for block in response.content if block.type == "text")


# Запускаем длинный разговор
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Продолжаем вызывать chat() столько, сколько требует разговор

Текущие ограничения

  • Та же модель для суммаризации: Для суммаризации используется модель, указанная в вашем запросе. Возможности использовать другую (например, более дешёвую) модель для резюме нет.

  • Компактизация может завершиться неудачей, если определены инструменты: Когда ваш запрос включает tools, модель иногда вызывает инструмент на внутреннем шаге суммаризации вместо написания резюме. Когда это происходит, ответ содержит блок compaction с content: null. Чтобы предотвратить это, задайте в instructions подсказку, которая явно указывает модели не вызывать инструменты, например:

    Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.

Следующие шаги

Редактирование контекста

Автоматически управляйте контекстом разговора по мере его роста с помощью редактирования контекста.

Контекстные окна

Узнайте о размерах контекстных окон и стратегиях управления ими.

Cookbook по компактизации памяти сеанса

Изучите практическую реализацию, которая управляет длительными разговорами с мгновенной компактизацией памяти сеанса, используя фоновые потоки и кэширование подсказок.

Compatibility

Supported models
  • Fable 5 and 5.1
  • Mythos 5, 5.1, and Preview
  • Opus 4.6, 4.7, 4.8, and 5
  • Sonnet 4.6 and 5
Supported platforms
  • Claude APIBeta
  • Claude Platform on AWSBeta
  • Amazon BedrockBeta
  • Google CloudBeta
  • Microsoft FoundryBeta

Was this page helpful?