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

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Редактирование контекста доступно на всех поддерживаемых моделях Claude.

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

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Search for recent developments in AI"}],
    tools=[{"type": "web_search_20250305", "name": "web_search"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

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

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Create a simple command line calculator app using Python",
        }
    ],
    tools=[
        {
            "type": "text_editor_20250728",
            "name": "str_replace_based_edit_tool",
            "max_characters": 10000,
        },
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
    ],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                # Запускать очистку при превышении порога
                "trigger": {"type": "input_tokens", "value": 30000},
                # Количество использований инструментов, сохраняемых после очистки
                "keep": {"type": "tool_uses", "value": 3},
                # Необязательно: очистить не менее этого количества токенов
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Исключить эти инструменты из очистки
                "exclude_tools": ["web_search"],
            }
        ]
    },
)

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

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

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
    thinking={"type": "enabled", "budget_tokens": 10000},
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

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

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

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

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

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

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

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

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

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

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
    thinking={"type": "enabled", "budget_tokens": 10000},
    tools=[...],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            },
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 50000},
                "keep": {"type": "tool_uses", "value": 5},
            },
        ]
    },
)

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

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

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

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    // ...
  ],
  "usage": {
    // ...
  },
  "context_management": {
    "applied_edits": [
      // When using `clear_thinking_20251015`
      {
        "type": "clear_thinking_20251015",
        "cleared_thinking_turns": 3,
        "cleared_input_tokens": 15000
      },
      // When using `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": [
      // ...
    ]
  }
}

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

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

response = client.beta.messages.count_tokens(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    tools=[...],  # Your tool definitions
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_tool_uses_20250919",
                "trigger": {"type": "input_tokens", "value": 30000},
                "keep": {"type": "tool_uses", "value": 5},
            }
        ]
    },
)

print(f"Original tokens: {response.context_management['original_input_tokens']}")
print(f"After clearing: {response.input_tokens}")
print(
    f"Savings: {response.context_management['original_input_tokens'] - response.input_tokens} tokens"
)

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

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

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

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

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

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

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

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

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # Ваши другие инструменты
    ],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

Полную справку по инструменту памяти, включая команды и примеры, см. в разделе Инструмент памяти.

Клиентское сжатие (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, чтобы включить автоматическое резюмирование, когда использование токенов превышает порог.

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

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

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

[
  { "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 more exchanges like this ...
]

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

После сжатия (снова ~2–3 тыс. токенов):

[
  {
    "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_creation_input_tokens": 0,
    "cache_read_input_tokens": 270000,
    "output_tokens": 1400
  }
}

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

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

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

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

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

Мониторинг сжатия

Понимание того, когда срабатывает сжатие, помогает вам настраивать пороги и проверять ожидаемое поведение.

Когда использовать сжатие

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

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

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

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