Сжатие контекста при достижении порога токенов

«Threshold compaction» (сжатие по порогу) — это автоматическая разновидность «compaction» (сжатия): вы задаёте порог токенов в своих обычных запросах, и API суммирует более старый контекст посреди запроса, как только порог достигнут. Этот вариант поддерживается наряду со сжатием по запросу, при котором вы сами решаете, когда создаётся сводка (см. Сжатие по запросу). Чтобы выбрать между ними, см. Выбор способа сжатия.

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

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

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

Как работает сжатие

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

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

В последующих запросах добавляйте ответ к своим сообщениям. API автоматически отбрасывает все блоки содержимого, предшествующие блоку 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-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

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

Параметры

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

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

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

В моделях Claude 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-5",
    max_tokens=4096,
    messages=messages,
    context_management={
        "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
    },
)

# Проверяем, вызвало ли сжатие (compaction) паузу
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-5",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )

API приостанавливается, даже если сводка не сгенерирована. В этом случае content блока compaction равен null, поэтому при продолжении сохраняйте исходные сообщения. Если меры защиты блокируют сводку, content также равен null, а причиной остановки будет refusal вместо compaction. Поле stop_details указывает категорию политики, если она есть. В обоих случаях продолжайте одинаково: ищите блок compaction вместо проверки stop_reason, как это делает пример, сохраняющий недавние сообщения.

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

Когда модель работает над длительными задачами с множеством итераций использования инструментов, общее потребление токенов может значительно вырасти. Вы можете объединить 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-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 в начале ответа ассистента.

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

{
  "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-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)
# После получения ответа с блоком сжатия (compaction)
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-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
)

В Python используйте client.beta.messages, как это сделано в примерах на этой странице. Если вы вызываете client.messages и сериализуете блоки самостоятельно, обычный model_dump() добавляет text: null и citations: null в блок compaction. В этом случае API отклоняет запрос с ошибкой 400 (Extra inputs are not permitted). Вместо этого используйте to_dict() или model_dump(exclude_none=True). В разделе Продолжение со сводки даётся такой же совет для сжатия по запросу.

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

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

Если сводка не сгенерирована, content блока равен null, и API игнорирует этот блок. Ничего не сжимается, поэтому сохраняйте исходные сообщения.

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

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

Блок сжатия передаётся в потоке иначе, чем текстовые блоки. Вы получаете событие 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-5",
    max_tokens=4096,
    messages=messages,
    context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
    for event in stream:
        match event.type:
            case "content_block_start":
                block = event.content_block
                match block.type:
                    case "compaction":
                        print("Compaction started...")
                    case "text":
                        print("Text response started...")

            case "content_block_delta":
                delta = event.delta
                match delta.type:
                    case "compaction_delta":
                        print(f"Compaction complete: {len(delta.content or '')} chars")
                    case "text_delta":
                        print(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-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"}]},
)

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

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

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

{
  "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-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-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("Briefly, help me build a Python web scraper"))
print(chat("Briefly, add support for JavaScript-rendered pages"))
print(chat("Briefly, add rate limiting and error handling"))
# Продолжайте вызывать chat() столько, сколько требуется диалогу

В моделях Claude 5.1 и более поздних блоки размышлений в любом ходе ассистента, который вы повторно вставляете после блока сжатия, не проходят проверку префикса, поскольку они были созданы, когда в контексте присутствовала полная история. Удалите блоки thinking и redacted_thinking из этих ходов. В качестве альтернативы отправьте thinking.block_binding.prefix_mismatch_behavior: "drop_block" вместе с «beta header» (бета-заголовком) thinking-binding-controls-2026-08-01. Сохранённые текстовые блоки и блоки инструментов можно оставить без изменений. Этого можно избежать, если позволить API резюмировать всё, не вставляя повторно предыдущие ходы. В Claude Sonnet 5.5 и Claude Haiku 5.5 block_binding работает только с thinking: {"type": "adaptive"}. При любой другой настройке размышлений в этих моделях удаляйте блоки.

Вот пример, в котором pause_after_compaction используется для сохранения предыдущего обмена репликами и текущего сообщения пользователя (всего три сообщения) вместо их суммирования. Он оставляет их текстовые блоки и блоки инструментов без изменений, удаляет блоки thinking и redacted_thinking из сохранённого хода ассистента и отбрасывает этот ход, если в нём больше ничего не осталось:

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-5",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 100000},
                    "pause_after_compaction": True,
                }
            ]
        },
    )

    # Ищем блок сжатия, а не причину остановки:
    # stop_reason равен "refusal", а не "compaction", если сводка была заблокирована
    compaction_block = next(
        (block for block in response.content if block.type == "compaction"), None
    )

    # Заменяем историю, только если сводка была сгенерирована
    if compaction_block is not None and compaction_block.content is not None:
        # Сохраняем предыдущий обмен + текущее сообщение пользователя (3 сообщения)
        # включая их после блока сжатия, без блоков размышлений;
        # ход ассистента, оставшийся без содержимого, отбрасывается
        preserved_messages = [
            {
                **message,
                "content": [
                    block
                    for block in message["content"]
                    if block.type not in ("thinking", "redacted_thinking")
                ],
            }
            if message["role"] == "assistant"
            else message
            for message in messages[-3:]
        ]
        preserved_messages = [m for m in preserved_messages if m["content"]]

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

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

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

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

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


# Запускаем длинный диалог
print(chat("Briefly, help me build a Python web scraper"))
print(chat("Briefly, add support for JavaScript-rendered pages"))
print(chat("Briefly, 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.

  

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

Доступность

Сжатие по порогу находится в бета-версии для некоторых моделей и подпадает под нулевое хранение данных.

Поддержка API

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