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

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

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

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

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

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

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

Несколько ситуаций, в которых это важно:

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

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

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

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

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

В этом примере включено автоматическое кэширование с помощью поля 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.

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

В агентном цикле системное сообщение идёт после сообщения 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 и продолжайте следовать рекомендациям из раздела .

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