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

Обзор

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

• Очистка результатов инструментов — лучше всего подходит для агентских рабочих процессов с интенсивным использованием инструментов, где старые результаты инструментов больше не нужны
• Очистка блоков мышления — для управления блоками мышления при использовании расширенного мышления, с опциями сохранения недавнего мышления для непрерывности контекста
• Компактирование 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-7",
    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-7",
    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 clearing when threshold is exceeded
                "trigger": {"type": "input_tokens", "value": 30000},
                # Number of tool uses to keep after clearing
                "keep": {"type": "tool_uses", "value": 3},
                # Optional: Clear at least this many tokens
                "clear_at_least": {"type": "input_tokens", "value": 5000},
                # Exclude these tools from being cleared
                "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": [
      // При использовании `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": [
      // ...
    ]
  }
}

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

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

response = client.beta.messages.count_tokens(
    model="claude-opus-4-7",
    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).

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

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

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

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

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

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

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[...],
    tools=[
        {"type": "memory_20250818", "name": "memory"},
        # Your other tools
    ],
    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, чтобы включить автоматическое суммирование, когда использование токенов превышает порог.

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

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

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

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

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

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

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

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

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

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