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

Обзор

Редактирование контекста позволяет выборочно очищать определённый контент из истории разговора по мере её роста. Помимо оптимизации затрат и соблюдения ограничений, речь идёт об активном управлении тем, что видит Claude: контекст — это конечный ресурс с убывающей отдачей, а нерелевантный контент снижает фокус модели. Редактирование контекста даёт вам детальный контроль во время выполнения над этим управлением. Для ознакомления с более широкими принципами управления контекстом см. Effective context engineering. Эта страница охватывает:

• Очистка результатов инструментов — лучше всего подходит для агентных рабочих процессов с интенсивным использованием инструментов, где старые результаты инструментов больше не нужны
• Очистка блоков размышлений — для управления блоками размышлений при использовании расширенного мышления с возможностью сохранения последних размышлений для непрерывности контекста
• Клиентское сжатие SDK — альтернатива на основе SDK для управления контекстом на основе резюме (серверное сжатие обычно предпочтительнее)

Серверные стратегии

Очистка результатов инструментов

Стратегия clear_tool_uses_20250919 очищает результаты инструментов, когда контекст разговора превышает настроенный порог. Это особенно полезно для агентных рабочих процессов с интенсивным использованием инструментов. Старые результаты инструментов (например, содержимое файлов или результаты поиска) больше не нужны после того, как Claude их обработал.

При активации API автоматически очищает самые старые результаты инструментов в хронологическом порядке. Каждый очищенный результат заменяется текстом-заполнителем, чтобы Claude знал, что он был удалён. По умолчанию очищаются только результаты инструментов. При желании можно очищать как результаты инструментов, так и вызовы инструментов (параметры использования инструментов), установив clear_tool_inputs в true.

Очистка блоков размышлений

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

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

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

Редактирование контекста применяется на стороне сервера до того, как запрос достигает Claude. Ваше клиентское приложение сохраняет полную, немодифицированную историю разговора. Вам не нужно синхронизировать состояние клиента с отредактированной версией. Продолжайте управлять полной историей разговора локально, как обычно.

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

Взаимодействие редактирования контекста с кэшированием запросов варьируется в зависимости от стратегии:

• Очистка результатов инструментов: Аннулирует кэшированные префиксы запросов при очистке контента. Чтобы учесть это, очищайте достаточно токенов, чтобы аннулирование кэша было оправданным. Используйте параметр clear_at_least, чтобы гарантировать минимальное количество очищаемых токенов каждый раз. Вы будете нести расходы на запись в кэш каждый раз при очистке контента, но последующие запросы смогут повторно использовать новый кэшированный префикс.

• Очистка блоков размышлений: Когда блоки размышлений сохраняются в контексте (не очищаются), кэш запросов сохраняется, обеспечивая попадания в кэш и снижая затраты на входные токены. Когда блоки размышлений очищаются, кэш аннулируется в точке, где происходит очистка. Настройте параметр keep в зависимости от того, хотите ли вы приоритизировать производительность кэша или доступность контекстного окна.

Поддерживаемые модели

Редактирование контекста доступно для:

• Claude Opus 4.6 (claude-opus-4-6)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

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

Самый простой способ включить очистку результатов инструментов — указать только тип стратегии. Все остальные параметры конфигурации используют значения по умолчанию:

Расширенная конфигурация

Вы можете настроить поведение очистки результатов инструментов с помощью дополнительных параметров:

Использование очистки блоков размышлений

Включите очистку блоков размышлений для эффективного управления контекстом и кэшированием запросов при включённом расширенном мышлении:

Параметры конфигурации для очистки блоков размышлений

Стратегия clear_thinking_20251015 поддерживает следующую конфигурацию:

Примеры конфигураций:

Сохранить блоки размышлений из последних 3 ходов ассистента:

{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

Сохранить все блоки размышлений (максимизирует попадания в кэш):

{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

Комбинирование стратегий

Вы можете использовать как очистку блоков размышлений, так и очистку результатов инструментов вместе:

Параметры конфигурации для очистки результатов инструментов

Ответ редактирования контекста

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

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // При использовании `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // При использовании `clear_tool_uses_20250919`
      {
        "type": "clear_tool_uses_20250919",
        "cleared_tool_uses": 8,
        "cleared_input_tokens": 50000
      }
    ]
  }
}

Для потоковых ответов правки контекста будут включены в финальное событие message_delta:

{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "stop_sequence": null
  },
  "usage": {
    "output_tokens": 1024
  },
  "context_management": {
    "applied_edits": [
      // ...
    ]
  }
}

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

Конечная точка подсчёта токенов поддерживает управление контекстом, позволяя вам предварительно просмотреть, сколько токенов будет использовать ваш запрос после применения редактирования контекста.

{
  "input_tokens": 25000,
  "context_management": {
    "original_input_tokens": 70000
  }
}

Ответ показывает как итоговое количество токенов после применения управления контекстом (input_tokens), так и исходное количество токенов до какой-либо очистки (original_input_tokens).

Использование с инструментом памяти

Редактирование контекста можно комбинировать с инструментом памяти. Когда контекст разговора приближается к настроенному порогу очистки, Claude получает автоматическое предупреждение о необходимости сохранить важную информацию. Это позволяет Claude сохранять результаты инструментов или контекст в файлы памяти до их очистки из истории разговора.

Эта комбинация позволяет вам:

• Сохранять важный контекст: Claude может записывать важную информацию из результатов инструментов в файлы памяти до их очистки
• Поддерживать длительные рабочие процессы: Обеспечивать агентные рабочие процессы, которые иначе превысили бы ограничения контекста, выгружая информацию в постоянное хранилище
• Получать доступ к информации по запросу: Claude может искать ранее очищенную информацию в файлах памяти при необходимости, вместо того чтобы хранить всё в активном контекстном окне

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

Чтобы использовать обе функции вместе, включите их в ваш API-запрос:

Клиентское сжатие (SDK)

Сжатие — это функция SDK, которая автоматически управляет контекстом разговора, генерируя резюме, когда использование токенов становится слишком большим. В отличие от серверных стратегий редактирования контекста, которые очищают контент, сжатие инструктирует Claude суммировать историю разговора, а затем заменяет полную историю этим резюме. Это позволяет Claude продолжать работу над длительными задачами, которые иначе превысили бы контекстное окно.

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

Когда сжатие включено, SDK отслеживает использование токенов после каждого ответа модели:

1. Проверка порога: SDK вычисляет общее количество токенов как input_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokens.
2. Генерация резюме: Когда порог превышен, запрос на резюме вводится как ход пользователя, и Claude генерирует структурированное резюме, обёрнутое в теги <summary></summary>.
3. Замена контекста: SDK извлекает резюме и заменяет всю историю сообщений им.
4. Продолжение: Разговор возобновляется с резюме, и Claude продолжает с того места, где остановился.

Использование сжатия

Добавьте compaction_control в ваш вызов tool_runner:

Что происходит во время сжатия

По мере роста разговора история сообщений накапливается:

До сжатия (приближается к 100k токенов):

[
  { "role": "user", "content": "Analyze all files and write a report..." },
  { "role": "assistant", "content": "I'll help. Let me start by reading..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "Based on file1.txt, I see..." },
  {
    "role": "user",
    "content": [{ "type": "tool_result", "tool_use_id": "...", "content": "..." }]
  },
  { "role": "assistant", "content": "After analyzing file2.txt..." }
  // ... ещё 50 подобных обменов ...
]

Когда токены превышают порог, SDK вводит запрос на резюме, и Claude генерирует резюме. Вся история затем заменяется:

После сжатия (возврат к ~2-3k токенов):

[
  {
    "role": "assistant",
    "content": "# Task Overview\nThe user requested analysis of directory files to produce a summary report...\n\n# Current State\nAnalyzed 52 files across 3 subdirectories. Key findings documented in report.md...\n\n# Important Discoveries\n- Configuration files use YAML format\n- Found 3 deprecated dependencies\n- Test coverage at 67%\n\n# Next Steps\n1. Analyze remaining files in /src/legacy\n2. Complete final report sections...\n\n# Context to Preserve\nUser prefers markdown format with executive summary first..."
  }
]

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

Параметры конфигурации

Выбор порога токенов

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

# Более частое сжатие для сценариев с ограниченной памятью
compaction_control = {"enabled": True, "context_token_threshold": 50000}

# Менее частое сжатие, когда нужно больше контекста
compaction_control = {"enabled": True, "context_token_threshold": 150000}

Использование другой модели для резюме

Вы можете использовать более быструю или дешёвую модель для генерации резюме:

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "model": "claude-haiku-4-5",
}

Пользовательские запросы для резюме

Вы можете предоставить пользовательский запрос для нужд конкретной предметной области. Ваш запрос должен инструктировать Claude обернуть резюме в теги <summary></summary>.

compaction_control = {
    "enabled": True,
    "context_token_threshold": 100000,
    "summary_prompt": """Summarize the research conducted so far, including:
- Sources consulted and key findings
- Questions answered and remaining unknowns
- Recommended next steps

Wrap your summary in <summary></summary> tags.""",
}

Стандартный промпт для резюмирования

Встроенный промпт для резюмирования инструктирует Claude создавать структурированное резюме продолжения, включающее:

1. Обзор задачи: Основной запрос пользователя, критерии успеха и ограничения.
2. Текущее состояние: Что было выполнено, какие файлы изменены и какие артефакты созданы.
3. Важные открытия: Технические ограничения, принятые решения, устранённые ошибки и неудавшиеся подходы.
4. Следующие шаги: Конкретные действия, необходимые для выполнения задачи, блокирующие факторы и порядок приоритетов.
5. Контекст для сохранения: Предпочтения пользователя, специфические детали предметной области и взятые обязательства.

Эта структура позволяет Claude эффективно возобновить работу, не теряя важного контекста и не повторяя ошибок.

Ограничения

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

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

Например, после операции веб-поиска ответ API может выглядеть следующим образом:

{
  "usage": {
    "input_tokens": 63000,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

SDK рассчитывает общее использование как 63 000 + 270 000 = 333 000 токенов. Однако значение cache_read_input_tokens включает накопленные считывания из нескольких внутренних вызовов API, выполненных серверным инструментом, а не фактический контекст вашего разговора. Реальная длина контекста может составлять всего 63 000 input_tokens, но SDK видит 333k и преждевременно запускает компактизацию.

Обходные решения:

• Используйте конечную точку подсчёта токенов для получения точной длины контекста
• Избегайте компактизации при активном использовании серверных инструментов

Граничные случаи при использовании инструментов

Когда компактизация запускается в то время, когда ожидается ответ на вызов инструмента, SDK удаляет блок вызова инструмента из истории сообщений перед созданием резюме. Claude повторно выполнит вызов инструмента после возобновления работы из резюме, если это всё ещё необходимо.

Мониторинг компактизации

Включите логирование для отслеживания момента срабатывания компактизации:

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("anthropic.lib.tools").setLevel(logging.INFO)

# Logs will show:
# INFO: Token usage 105000 has exceeded the threshold of 100000. Performing compaction.
# INFO: Compaction complete. New token usage: 2500

Когда использовать компактизацию

Подходящие случаи использования:

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

Менее подходящие случаи использования:

• Задачи, требующие точного воспроизведения ранних деталей разговора
• Рабочие процессы с активным использованием серверных инструментов
• Задачи, которым необходимо поддерживать точное состояние множества переменных