Системные сообщения и изменения инструментов в середине разговора

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

Системные сообщения в середине разговора закрывают этот пробел. Вы добавляете сообщение {"role": "system"} в ту точку разговора, где новая инструкция становится актуальной, вместо редактирования поля верхнего уровня system. Кэшированный префикс остаётся прежним, поэтому следующий запрос по-прежнему читает его из кэша, а новая инструкция всё равно применяется как системная инструкция, а не как обычный пользовательский текст.

Эта страница охватывает две функции: системные сообщения в середине разговора, которые общедоступны, и изменения инструментов в середине разговора — бета-функцию, представленную вместе с Claude Opus 5, которая применяет тот же подход к массиву tools.



Изменения инструментов в середине разговора

Массив tools находится в хэшируемом префиксе запроса ещё раньше, чем поле верхнего уровня system, поэтому его редактирование инвалидирует кэш подсказок для всего разговора. Изменения инструментов в середине разговора — бета-функция, представленная вместе с Claude Opus 5, — это аналог системных сообщений в середине разговора для инструментов. Вместо того чтобы фиксировать список инструментов на всё время жизни разговора, вы изменяете, какие инструменты предлагаются модели между ходами: объявите полный набор инструментов в tools заранее, затем используйте блоки tool_addition и tool_removal, чтобы предложить инструмент модели или отозвать его начиная с определённой точки разговора. Сам массив tools никогда не меняется, поэтому кэшированный префикс остаётся нетронутым.

tool_addition и tool_removal — это блоки содержимого в массиве content сообщения с role: "system", и их можно смешивать с блоками text в одном сообщении. Сообщение следует тем же правилам размещения, что и любое системное сообщение в середине разговора (см. Ограничения), и изменение применяется с этой точки разговора и далее. Поле tool каждого блока ссылается на инструмент, а не определяет его: {"type": "tool_reference", "name": "..."} именует инструмент, объявленный в массиве tools запроса, а на инструменты MCP connector можно ссылаться индивидуально с помощью mcp_tool_reference (server_name и name) или как на целый набор инструментов с помощью mcp_toolset_reference (server_name). Ссылка на имя, не объявленное в tools, возвращает ошибку 400.

Каждый инструмент, объявленный в tools, предлагается модели с начала разговора, если только он не объявлен с defer_loading: true, что удерживает его скрытым до тех пор, пока блок tool_addition не сделает его доступным. tool_addition также повторно предлагает инструмент, который был отозван более ранним tool_removal.

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    betas=["mid-conversation-tool-changes-2026-07-01"],
    # Полный набор инструментов объявляется заранее и никогда не меняется, поэтому
    # кэшированный префикс остаётся нетронутым.
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a location.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"},
                },
                "required": ["location"],
            },
        },
    ],
    messages=[
        {
            "role": "user",
            "content": "Say OK.",
        },
        # Отзываем get_weather начиная с этого момента. Блок ссылается на
        # инструмент по имени вместо редактирования `tools`, поэтому предыдущие ходы остаются
        # байт-в-байт идентичными, и кэш по-прежнему срабатывает.
        {
            "role": "system",
            "content": [
                {
                    "type": "tool_removal",
                    "tool": {"type": "tool_reference", "name": "get_weather"},
                },
            ],
        },
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Изменения инструментов в середине разговора находятся в бета-версии. Чтобы использовать их, включите бета-заголовок mid-conversation-tool-changes-2026-07-01 в ваши запросы. Они доступны в Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 и Claude Opus 5, в Claude API, Amazon Bedrock и Google Cloud.



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

Кэширование подсказок хэширует префикс запроса по порядку: tools, затем system, затем messages. Попадание в кэш требует, чтобы префикс точно, байт в байт, совпадал с недавним запросом вплоть до точки останова кэша.

Такой порядок означает, что поле верхнего уровня system находится почти в самом начале хэшируемого префикса. Любое его изменение, даже добавление одного предложения, даёт другой хэш, и запрос промахивается мимо кэша для системной подсказки и каждого кэшированного сообщения после неё.

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

Несколько ситуаций, когда это важно:

• Изменения политики или персоны в середине сессии. Длинной агентной сессии требуется новое ограничение («с этого момента пишите все SQL-запросы как параметризованные») после десятков кэшированных ходов. Добавление его в поле верхнего уровня system привело бы к повторной обработке всей истории.
• Контекст для каждого хода, который должен быть авторитетным. Вы хотите внедрить заметку о свежести данных, дедлайн сессии или изменение доступности инструментов с весом системного уровня, и это меняется слишком часто, чтобы находиться в кэшированном префиксе.
• Изменения состояния, которые наблюдает ваше приложение. Ваше приложение замечает что-то, что Claude должен воспринимать как факт уровня оператора: файлы на диске изменились, пользователь переключил настройку автоодобрения, доступные инструменты изменились или оставшийся бюджет токенов упал ниже порога.
• Пользовательский ввод, который не должен прерывать агентный цикл. Пользователь вводит дополнение, пока Claude всё ещё выполняет инструменты для предыдущего запроса. Передача его как системного сообщения после следующего результата инструмента позволяет Claude включить новый ввод в уже выполняемую работу, вместо того чтобы рассматривать его как новый запрос, на который нужно переключиться. См. Размещение после результатов инструментов ниже.
• Переключения режимов, предоставляющие постоянные разрешения. Режим уровня сессии может использовать системное сообщение в середине разговора, чтобы предоставить постоянное согласие на дорогостоящую возможность, такую как автоматический запуск мультиагентных рабочих процессов, с кратким напоминанием каждые несколько ходов и уведомлением о выходе при отключении режима. Проработанный пример см. в разделе Создание режима оркестрации.

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



Как это работает

Добавьте сообщение с "role": "system" в массив messages. Используйте обычную строку или блоки содержимого для content, так же как для хода user или assistant. Инструкция применяется с этой точки разговора и далее. Когда инструкции конфликтуют, более поздние системные сообщения имеют приоритет над более ранними, а системные сообщения в середине разговора имеют приоритет над полем верхнего уровня system для следующих за ними ходов.

Вы по-прежнему можете задавать поле верхнего уровня system для инструкций, которые должны применяться ко всему разговору. Оставьте системные сообщения в середине разговора для инструкций, которые становятся актуальными только позже, или которые вы хотите добавить без инвалидации кэшированного префикса.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    # Автоматическое кэширование подсказок: каждый запрос кэширует разговор на текущий момент,
    # а следующий запрос читает неизменённый префикс из кэша.
    cache_control={"type": "ephemeral"},
    system="You are a code review assistant. Be concise.",
    messages=[
        {
            "role": "user",
            "content": "Review process() in utils.py for performance issues.",
        },
        {
            "role": "assistant",
            "content": "The list comprehension is fine for small inputs. For large inputs, consider a generator to avoid materializing the full list.",
        },
        {
            "role": "user",
            "content": "Now review the calling code that invokes process().",
        },
        # Посреди сессии ревьюер понимает, что все предложения должны
        # также соответствовать строгой политике типизации команды. Добавление
        # инструкции в конец сохраняет предыдущие реплики байт-в-байт, поэтому
        # префикс, закэшированный предыдущим запросом, по-прежнему читается из кэша.
        {
            "role": "system",
            "content": "From now on, every suggestion must include explicit type annotations.",
        },
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Этот пример включает автоматическое кэширование с помощью поля верхнего уровня cache_control. Кэширование подсказок включается явно: если в запросе нет поля cache_control (автоматического или явной точки останова), ничего не кэшируется, и каждый запрос оплачивается по обычной цене входных токенов за весь разговор. При включённом кэшировании добавление системного сообщения оставляет уже кэшированные ходы неизменными, поэтому запрос, несущий новую инструкцию, по-прежнему читает их из кэша вместо повторной обработки. Кэширование также требует, чтобы разговор соответствовал минимальной длине кэшируемой подсказки; такой короткий пример, как этот, не достигает её, поэтому cache_creation_input_tokens и cache_read_input_tokens остаются равными 0, пока разговор не вырастет.

Системное сообщение в середине разговора должно непосредственно следовать за ходом user (или ходом assistant, заканчивающимся результатом серверного инструмента), и должно быть либо последним элементом в messages, либо непосредственно предшествовать ходу assistant. Сообщение user, содержащее блоки tool_result, тоже считается: в агентном цикле вы можете разместить системное сообщение сразу после результатов инструментов, перед следующим ходом Claude. Любая другая позиция, включая позицию между блоком tool_use в assistant и отвечающим ему tool_result, возвращает ошибку 400.



Размещение после результатов инструментов

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

[
  { "role": "user", "content": "Run the test suite and fix any failures." },
  {
    "role": "assistant",
    "content": [{ "type": "tool_use", "id": "toolu_01", "name": "run_tests", "input": {} }]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "12 passed, 0 failed" }
    ]
  },
  {
    "role": "system",
    "content": "The user sent the following message while you were working: also update the changelog before you finish."
  }
]

Формулируйте системное содержимое как контекст, а не как команду, которая отменяет пользователя. Изложите факт («от пользователя поступил новый ввод: X», «оставшийся бюджет токенов теперь Y») и позвольте Claude действовать на его основе. Claude обучен сопротивляться инструкциям, которые, по-видимому, работают против пользователя, и эта защита по-прежнему применяется к системной роли, поэтому формулировки вроде «игнорируй то, что сказал пользователь» менее эффективны, чем изложение того, что изменилось.

Этот шаблон предназначен для передачи ввода от собственного конечного пользователя разговора. Не используйте его для передачи вывода инструментов, извлечённых документов или другого стороннего содержимого; держите такое содержимое в блоках tool_result (см. Ограничения).



Сочетание с кэшированием подсказок

Системные сообщения в середине разговора и кэширование подсказок предназначены для совместного использования:

• Включайте кэширование явно. Кэширование происходит только тогда, когда запрос включает cache_control — либо поле верхнего уровня для автоматического кэширования, либо явную точку останова на блоке содержимого. Системное сообщение в середине разговора само по себе не создаёт запись кэша, а без включённого кэширования нет экономии, которую нужно сохранять.
• Кэшируйте стабильный префикс как обычно. Размещайте cache_control на последнем блоке, который остаётся неизменным между запросами, будь то конец поля верхнего уровня system, конец ваших определений инструментов или стабильная точка в истории сообщений.
• Добавляйте системное сообщение после точки останова. Поскольку оно идёт после кэшированного префикса, оно не изменяет хэш префикса, и кэш по-прежнему срабатывает.
• Системное сообщение в середине разговора само по себе кэшируемо. Как только оно оказывается в разговоре, оно становится частью стабильной истории. На следующем ходу вы можете переместить точку останова кэша за него (или положиться на автоматическое кэширование, которое сделает это), и системное сообщение будет читаться из кэша, как любой другой ход.

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



Ограничения

• Не для первого сообщения. Сообщение system не может быть первым элементом в messages. Используйте поле верхнего уровня system для инструкций, которые применяются с самого начала.
• Размещение ограничено. Сообщение system должно непосредственно следовать за ходом user (включая ход user, содержащий блоки tool_result) или ходом assistant, заканчивающимся результатом серверного инструмента, и должно предшествовать ходу assistant или завершать массив. Оно не может находиться между блоком tool_use и его tool_result. Размещение его в другом месте возвращает ошибку 400.
• Не место для недоверенного содержимого. Claude рассматривает системное содержимое как инструкции оператора и следует им. Не помещайте текст извне разговора, такой как необработанный вывод инструментов, извлечённые документы или веб-содержимое, непосредственно в системное сообщение; это придаёт такому тексту авторитет уровня оператора. Держите такие данные в блоках tool_result и продолжайте следовать рекомендациям Смягчение джейлбрейков и инъекций в подсказки.



Связанные материалы