Сжатие по запросу

При использовании «on-demand compaction» (сжатие по запросу) ваше приложение само решает, когда разговор будет кратко изложен: вы отправляете один запрос с параметром compaction, и Claude возвращает «summary» (сводку) вместо ответа.

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

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

С этого момента блок занимает место сообщений, которые он обобщает. Он идёт первым в messages, обобщённые сообщения удаляются, а ваш следующий ход следует за ним. Claude видит сводку там, где были эти сообщения.

Запрос сводки

Отправляйте бета-заголовок compact-2026-09-04 в запросе, который запрашивает сводку, и в каждом последующем запросе, содержащем подписанный блок. Чтобы проверить, поддерживает ли модель сжатие по запросу, вызовите Models API с бета-заголовком и прочитайте capabilities.compaction каждой модели. Нельзя сочетать compaction с context_management в одном запросе.

Отправьте разговор в его текущем виде с "compaction": {"type": "summarize"}. API один раз обобщает все сообщения в запросе, не генерирует после этого ответа и возвращает только блок со stop_reason "compaction". Отправляйте ту же «system prompt» (системную подсказку) system и те же tools, которые вы используете в остальной части разговора. Модуль обобщения читает их, и если вы сохраняете ходы после блока на модели с сохранённым мышлением, мышление в этих ходах остаётся действительным, только если system и tools совпадают. В разговоре из этого примера нет системной подсказки system и инструментов, поэтому запрос не отправляет ни того, ни другого:

from anthropic.types.beta import BetaMessageParam

client = anthropic.Anthropic()

history: list[BetaMessageParam] = [
    {
        "role": "user",
        "content": "I am building a recipe app. Help me name the main entities in the data model.",
    },
    {
        "role": "assistant",
        "content": "Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.",
    },
    {"role": "user", "content": "Good. Now suggest field names for Recipe."},
]

response = client.beta.messages.create(
    model="claude-opus-5-5",
    # max_tokens ограничивает весь вызов, включая мышление, поэтому выделите несколько тысяч токенов.
    max_tokens=4096,
    betas=["compact-2026-09-04"],
    messages=history,
    compaction={"type": "summarize"},
)
print(f"Stop reason: {response.stop_reason}")

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "compaction",
      "content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
      "signature": "EuYBCkQY..."
    }
  ],
  "stop_reason": "compaction",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "iterations": [{ "type": "compaction", "input_tokens": 144, "output_tokens": 276 }]
  }
}

Вызов обобщения использует модель запроса, system, tools, настройки мышления и max_tokens. Модуль обобщения читает определения инструментов, но никогда не запускает инструменты, а ответ не содержит мышления. max_tokens ограничивает весь вызов, включая любое мышление модели перед написанием сводки, поэтому выделите несколько тысяч токенов. В разделе Подсчёт использования при сжатии показано, как тарифицируется этот вызов.

Если последний ход assistant заканчивается вызовом инструмента, для которого ещё нет результата, API отклоняет запрос. Сначала отправьте результаты инструментов для этого хода. Также не указывайте stop_sequences, output_config.format для структурированного вывода и tool_choice типа any или tool. В вызове обобщения они ничего бы не делали, и API их отклоняет. Разговор по-прежнему должен помещаться в «context window» (контекстное окно) модели, поэтому выполняйте сжатие до того, как превысите его, а не после.

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

Продолжение со сводки

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

{
  "model": "claude-opus-5-5",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "compaction",
          "content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
          "signature": "EuYBCkQY..."
        }
      ]
    },
    {
      "role": "assistant",
      "content": "For Recipe, use title, description, servings, prep_minutes, and cook_minutes. Add created_at and updated_at timestamps."
    },
    { "role": "user", "content": "Now do the same for Ingredient." }
  ]
}

Этот пример продолжает пример запроса, который заканчивался ходом user; на диаграмме показан более простой случай, когда во время написания сводки ходы не делаются. Здесь второе сообщение assistant — это ответ на последний обобщённый ход user. Он пришёл, пока писалась сводка, поэтому не вошёл в число обобщённых сообщений. Два сообщения assistant подряд здесь допустимы, потому что блок по-прежнему идёт первым.

API помещает сводку туда, где стоит блок, и передаёт Claude все последующие сообщения без изменений. Соблюдайте следующие правила:

• Помещайте блок первым в messages — либо как отдельное сообщение assistant, либо как первый блок содержимого первого сообщения, будь то сообщение user или assistant.
• Удаляйте обобщённые сообщения. Если какие-либо из них остаются перед блоком, запрос возвращает ошибку 400 (compaction_block_misplaced).
• Отправляйте ровно один блок compaction на запрос, в каждом последующем запросе.

Сжатие по порогу работает наоборот: его блок следует за сообщениями, которые он обобщает, и API удаляет их за вас. См. Обратная передача блоков сжатия.

В Python используйте client.beta.messages, как это делают примеры на этой странице. Если вы вызываете client.messages и сериализуете блоки самостоятельно, используйте to_dict() или model_dump(exclude_none=True): обычный model_dump() добавляет к блоку citations: null и text: null, и API его отклоняет.

Если вы сохраняете ходы после блока и отправляете их блоки мышления обратно, условия, при которых это мышление остаётся действительным, описаны на странице Сжатие и сохранённое мышление.

Повторное сжатие

Чтобы сжать разговор, который уже начинается с блока, снова отправьте compaction. Новый блок обобщает старую сводку и всё, что идёт после неё. С этого момента отправляйте только самый новый блок.

Сжатие в цикле

После каждого хода цикл складывает входные и выходные токены последнего ответа, потому что следующий запрос отправляет и этот ответ. Когда эта сумма превышает лимит и впереди ещё есть ход, цикл отправляет запрос на сжатие с той же моделью и системной подсказкой system, проверяет stop_reason, заменяет свою историю возвращённым сообщением и выводит ход, перед которым было выполнено сжатие. Лимит в 2 500 токенов в примере намеренно занижен, чтобы сжатие происходило даже в коротком разговоре. Установите свой лимит близко к вашему реальному бюджету входных данных.

from anthropic.types.beta import BetaMessageParam

client = anthropic.Anthropic()

# Задайте значение, близкое к реальному бюджету входных токенов. Здесь оно занижено, чтобы сжатие сработало даже в коротком диалоге.
COMPACT_AT_TOKENS = 2500
SYSTEM = "You help design a recipe app's data model. Keep answers short."

QUESTIONS = [
    "What are the main entities in the data model?",
    "Which fields should Recipe have?",
    "Which fields should Ingredient have?",
    "Which fields should RecipeIngredient have?",
    "Which fields should Step have?",
    "Which indexes should these tables have?",
    "Which fields should be required?",
    "Which fields should have default values?",
]

history: list[BetaMessageParam] = []
for turn, question in enumerate(QUESTIONS, start=1):
    history.append({"role": "user", "content": question})
    response = client.beta.messages.create(
        model="claude-opus-5-5",
        max_tokens=8192,
        system=SYSTEM,
        betas=["compact-2026-09-04"],
        messages=history,
    )
    history.append({"role": "assistant", "content": response.content})

    # Следующий запрос тоже отправит этот ответ, поэтому учитывайте его.
    conversation_tokens = response.usage.input_tokens + response.usage.output_tokens
    if conversation_tokens > COMPACT_AT_TOKENS and turn < len(QUESTIONS):
        summary = client.beta.messages.create(
            model="claude-opus-5-5",
            max_tokens=4096,
            system=SYSTEM,
            betas=["compact-2026-09-04"],
            messages=history,
            compaction={"type": "summarize"},
        )
        if summary.stop_reason == "compaction":
            history = [{"role": "assistant", "content": summary.content}]
            print(f"Compacted before turn {turn + 1}")

Проверка stop_reason выполняется до того, как код ищет блок; причина объясняется в разделе Обработка отсутствующей сводки или ошибки. История заменяется, а не дополняется: возвращённое сообщение заменяет все сообщения, которые содержал запрос, по правилам из раздела Продолжение со сводки. Если сводка не возвращается, цикл сохраняет свою историю и повторяет запрос после следующего хода.

«Tool runner» (исполнитель инструментов) SDK в Python, TypeScript, C#, Go и Java может отправлять запрос на сжатие за вас. Когда вы решите выполнить сжатие, вызовите у исполнителя метод compact_before_next_turn() (compactBeforeNextTurn() в TypeScript и Java, CompactBeforeNextTurn() в C# и Go). Как только текущий ход и его вызовы инструментов завершатся, исполнитель отправит запрос на сжатие и заменит свою историю возвращённым сообщением. Создавайте исполнитель с бета-версией compact-2026-09-04, потому что сам исполнитель её не добавляет. Исполнитель формирует запрос из собственных параметров и не включает context_management. Если эти параметры содержат stop_sequences, tool_choice типа any или tool либо output_config.format для структурированного вывода, API отклоняет запрос с ошибкой 400. Причина объясняется в разделе Запрос сводки. Исполнитель отказывается выполнять сжатие, пока его context_management содержит правку сжатия, поэтому используйте в одном исполнителе только один вид сжатия.

Когда выполнять сжатие

Вы можете отправить запрос на сжатие после любого завершённого хода, поэтому момент определяет ваш код.

Чтобы оценить размер следующего запроса, сложите input_tokens и output_tokens из usage последнего ответа, как это делает цикл. При использовании «prompt caching» (кэширования подсказок) input_tokens учитывает только токены после последней точки останова кэша, поэтому также прибавьте cache_read_input_tokens и cache_creation_input_tokens. Вы также можете отправить те же сообщения в конечную точку подсчёта токенов.

Сравните это число с выбранным вами лимитом, который меньше контекстного окна модели.

Написание собственной подсказки для обобщения

Без instructions API использует собственную подсказку для обобщения. Непустая строка instructions (до 16 384 символов) полностью заменяет эту подсказку. Например:

{
  "compaction": {
    "type": "summarize",
    "instructions": "Summarize this recipe app design conversation. Preserve every entity and field name agreed so far, and the user's latest open request. Do not call tools; respond with the summary text only."
  }
}

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

Обработка отсутствующей сводки или ошибки

Сводка создаётся только тогда, когда вызов обобщения завершается нормально с текстом и без вызова инструмента. В противном случае ответ всё равно имеет код 200 с пустым content, поэтому проверяйте stop_reason, прежде чем искать блок. Вызов всё равно тарифицируется и отражается в usage.iterations, с нулевым использованием, если вызов выполнить не удалось. stop_reason — это причина, с которой завершился вызов обобщения. В любом случае вы можете продолжить без сводки и выполнить сжатие позже.

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

Ошибки

Запрос на сжатие или запрос, содержащий блок, также может завершиться ошибкой. У большинства ошибок 400 есть сообщение, в котором сказано, что нужно удалить или отправить повторно. Некоторые также содержат error.details.error_code, начинающийся с compaction_. Ошибки параметров, например поле, которое нельзя сочетать с compaction, содержат только сообщение.

Подсчёт использования при сжатии

Вызов обобщения тарифицируется и подпадает под «rate limit» (ограничение скорости) так же, как любой другой запрос, а usage.iterations отражает его как запись compaction. Поля верхнего уровня input_tokens и output_tokens равны нулю, потому что ответ не генерировался. Чтобы подсчитать, сколько потребил разговор, суммируйте значения по usage.iterations, а не поля верхнего уровня. Отправка блока обратно в последующих запросах не добавляет затрат на сжатие.

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

Ограничения и взаимодействие с другими функциями

• Сжатие по порогу и редактирование контекста. Нельзя отправлять compaction и context_management в одном запросе. Сжатие по порогу (compact_20260112) не может выполняться в запросе, содержащем подписанный блок.
• Кэширование подсказок. cache_control на блоке устанавливает точку останова после сводки.
• Системные сообщения и изменения инструментов в середине разговора. Сообщения role: "system" внутри обобщаемого диапазона тоже обобщаются, поэтому их текстовые инструкции перестают действовать, как только блок их заменяет. Если инструкция по-прежнему важна, повторите её в сообщении role: "system". Отправьте это сообщение сразу после вашего следующего нового хода user и с этого момента оставляйте его в истории. Об изменениях инструментов, а также о том, куда помещать это сообщение, если вы сохраняете ходы после блока, см. Изменение системной подсказки или инструментов.
• Бюджеты задач. Не отправляйте значение remaining бюджета задачи (output_config.task_budget.remaining) вместе с compaction или в запросах, содержащих блок. Это приводит к ошибке 400.
• Подсчёт токенов. Конечная точка подсчёта токенов игнорирует параметр compaction.
• Содержимое, которое сводка не может передать. Изображения, документы, блоки container_upload и загруженные URL внутри обобщённых сообщений исчезают, как только блок их заменяет. Повторите или загрузите заново всё, что ещё понадобится в последующих ходах.

Compatibility