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

Обзор

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

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

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

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

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

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

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

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

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

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

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

В моделях Claude Fable 5.1, Claude Opus 5.5 и Claude Sonnet 5.5 серверное управление контекстом никогда не делает блоки размышлений недействительными. Клиентские изменения более ранних ходов могут сделать недействительными блоки размышлений во всех последующих ходах ассистента. Для новых аккаунтов, созданных 31 августа 2026 года или позже, запрос, который повторно передаёт недействительный блок, отклоняется, если вы не включили его отбрасывание. См. Сохранение префикса без изменений.

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

Взаимодействие редактирования контекста с кэшированием подсказок («prompt caching») зависит от стратегии:

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

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

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

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

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

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    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-5-5",
    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-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 2},
            }
        ]
    },
)

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

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

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

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": {"type": "thinking_turns", "value": 3},
            }
        ]
    },
)

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[{"role": "user", "content": "Hello"}],
    betas=["context-management-2025-06-27"],
    context_management={
        "edits": [
            {
                "type": "clear_thinking_20251015",
                "keep": "all",
            }
        ]
    },
)

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

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

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    messages=[
        {
            "role": "user",
            "content": "Search for the latest developments in quantum error correction and summarize the key breakthroughs.",
        }
    ],
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5,
        }
    ],
    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},
            },
        ]
    },
)

print(response)

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

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

Вы можете увидеть, какие правки контекста были применены к вашему запросу, с помощью поля ответа 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-5-5",
    messages=[{"role": "user", "content": "Continue our conversation..."}],
    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-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Hello"}],
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
)

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

Компактизация на стороне клиента (SDK)

«Compaction» (компактизация) — это функция 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 продолжает работу с этого резюме, как если бы это была исходная история разговора.

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

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

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

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

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

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

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

Подсказка для резюме по умолчанию

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

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

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

You have been working on the task described above but have not yet completed it. Write a continuation summary that will allow you (or another instance of yourself) to resume work efficiently in a future context window where the conversation history will be replaced with this summary. Your summary should be structured, concise, and actionable. Include:

1. Task Overview
The user's core request and success criteria
Any clarifications or constraints they specified

2. Current State
What has been completed so far
Files created, modified, or analyzed (with paths if relevant)
Key outputs or artifacts produced

3. Important Discoveries
Technical constraints or requirements uncovered
Decisions made and their rationale
Errors encountered and how they were resolved
What approaches were tried that didn't work (and why)

4. Next Steps
Specific actions needed to complete the task
Any blockers or open questions to resolve
Priority order if multiple steps remain

5. Context to Preserve
User preferences or style requirements
Domain-specific details that aren't obvious
Any promises made to the user

Be concise but complete—err on the side of including information that would prevent duplicate work or repeated mistakes. Write in a way that enables immediate resumption of the task.

Wrap your summary in <summary></summary> tags.

Ограничения

Инструменты на стороне сервера

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

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

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

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

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

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

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

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

Следующие шаги