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

Обзор

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

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

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

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

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

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

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

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

• 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.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)

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

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

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

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

Обзор

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

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

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

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

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

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

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

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

• 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.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 поддерживает следующую конфигурацию:

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

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

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

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

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

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

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

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

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

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

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

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

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

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

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

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

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

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

// Keep thinking blocks from the last 3 assistant turns
{
  "type": "clear_thinking_20251015",
  "keep": {
    "type": "thinking_turns",
    "value": 3
  }
}

// Keep all thinking blocks (maximizes cache hits)
{
  "type": "clear_thinking_20251015",
  "keep": "all"
}

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

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

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

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

Вы можете увидеть, какие редактирования контекста были применены к вашему запросу, используя поле ответа 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": [...]
    }
}

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

Стратегия 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 more exchanges like this ...
]

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

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

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

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

# More frequent compaction for memory-constrained scenarios
compaction_control={
    "enabled": True,
    "context_token_threshold": 50000
}

# Less frequent compaction when you need more context
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 получает автоматическое предупреждение о сохранении важной информации. Это позволяет 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 more exchanges like this ...
]

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

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

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

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

# More frequent compaction for memory-constrained scenarios
compaction_control={
    "enabled": True,
    "context_token_threshold": 50000
}

# Less frequent compaction when you need more context
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

Когда использовать компактирование

Хорошие варианты использования:

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

Менее идеальные варианты использования:

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