Claude Platform Docs
MessagesСжатие

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

Настройте API так, чтобы он автоматически суммировал более старый контекст в рамках обычного запроса, когда разговор достигает заданного вами порога токенов.

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

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

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

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

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

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

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

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

ServerInput tokens exceed trigger thresholdConversation is summarizedCompaction block created with summaryResponse continues with compacted contextnext requestClientAppend response to messagesMessages before the compaction block are dropped on next request

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

Включите сжатие, добавив стратегию 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})

Параметры

ПараметрТипПо умолчаниюОписание
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-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"}]},
    )

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

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

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

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-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 самостоятельно удалить сжатое содержимое
  • Вручную удалить сжатые сообщения и включать только содержимое, начиная с блока сжатия

В Claude Fable 5.1, Claude Mythos 5.1 и Claude Opus 5.5 блоки мышления, предшествующие блоку 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 возвращает подробную информацию об использовании в ответе:

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-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("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 и Claude Opus 5.5 удаляйте блоки 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-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-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.

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

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

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

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

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

Руководство по сжатию памяти сеанса

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

Compatibility

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

Was this page helpful?