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

Обзор

Редактирование контекста позволяет вам выборочно очищать определённый контент из истории разговора по мере её роста. Это помогает оптимизировать затраты и оставаться в пределах лимитов контекстного окна. На этой странице рассматриваются:

• Очистка результатов инструментов - лучше всего подходит для агентских рабочих процессов с интенсивным использованием инструментов, где старые результаты инструментов больше не нужны
• Очистка блоков мышления - для управления блоками мышления при использовании расширенного мышления с опциями сохранения недавнего мышления для непрерывности контекста
• Компактирование 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.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"
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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