Инструмент-советник

Инструмент советника позволяет более быстрой и дешевой «executor model» (модели-исполнителю) в процессе генерации обращаться за стратегическими рекомендациями к более интеллектуальной «advisor model» (модели-советнику). Советник читает весь диалог, составляет план или корректирует курс, а исполнитель продолжает выполнение задачи.

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

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

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

• Вы сейчас используете Sonnet для сложных задач: добавьте советника более высокого уровня. С Opus общая стоимость останется примерно такой же или снизится; Claude Fable 5.1 дает максимальный прирост качества.
• Вы сейчас используете Haiku и хотите повысить уровень интеллекта: добавьте советника Opus или Fable. Стоимость будет выше, чем у одного Haiku, но ниже, чем при переходе исполнителя на более крупную модель.

Результаты зависят от задачи. Проводите оценку на собственной рабочей нагрузке.

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

Быстрый старт

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-5",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

Поле content ответа содержит блок advisor_tool_result с рекомендациями советника. Если советником выступает claude-opus-5, как в этом быстром старте, поле content блока содержит вариант advisor_redacted_result. Он зашифрован: исполнитель читает его на стороне сервера, а ваш клиент — нет. Чтобы видеть текст рекомендаций прямо в ответе, используйте в качестве модели-советника claude-opus-4-8: она возвращает вариант advisor_result в открытом виде. Обе структуры и то, какие модели-советники какой вариант возвращают, описаны в разделе Варианты результата. Полный список допустимых пар приведен в разделе Совместимость моделей.

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

Когда вы добавляете инструмент советника в массив tools, модель-исполнитель сама решает, когда его вызвать, как и любой другой инструмент. Когда исполнитель вызывает советника:

1. Исполнитель выдает блок server_tool_use с name: "advisor" и пустым input. Исполнитель определяет момент вызова, а контекст предоставляет сервер.
2. Anthropic выполняет на сервере отдельный проход вывода на модели-советнике. Советник работает со своей собственной «system prompt» (системной подсказкой), предоставленной Anthropic. На вход он получает полную стенограмму исполнителя в виде цитируемого контекста. Эта стенограмма включает вашу системную подсказку, определения инструментов, предыдущие ходы и результаты инструментов, а также текст, который исполнитель уже сгенерировал в текущем ходе.
3. Ответ советника возвращается исполнителю в виде блока advisor_tool_result.
4. Исполнитель продолжает генерацию с учетом рекомендаций.

Все это происходит внутри одного запроса /v1/messages, без дополнительных обращений с вашей стороны. Исключение — ход, приостановленный посреди вызова: его нужно возобновить последующим запросом (см. Возобновление приостановленного хода).

Сам советник работает без инструментов и без управления контекстом. Его блоки размышлений отбрасываются до возврата результата. До исполнителя доходит только текст рекомендаций.

Параметры инструмента

Объект caching имеет вид {"type": "ephemeral", "ttl": "5m" | "1h"}. В отличие от cache_control в блоках контента, это не маркер точки останова, а переключатель «вкл./выкл.». Границы кэша определяет сервер.

Инструмент советника также принимает общие свойства, доступные в любом определении инструмента: cache_control, allowed_callers, defer_loading и strict (описано в разделе структурированные выводы). Их семантика описана в справочнике по инструментам.

Структура ответа

Успешный вызов советника

При вызове советника в контенте ассистента за блоком server_tool_use следует блок advisor_tool_result. В примере ниже показан вариант advisor_result в открытом виде, который возвращает советник Claude Opus 4.8. В быстром старте используется Claude Opus 5, который вместо этого возвращает зашифрованный вариант advisor_redacted_result. Обе структуры приведены в разделе Варианты результата.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me consult the advisor on this."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "advisor",
      "input": {}
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "advisor_result",
        "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
    }
  ]
}

Поле server_tool_use.input всегда пустое. Сервер автоматически формирует представление для советника из полной стенограммы. Ничто из того, что исполнитель помещает в input, до советника не доходит.

Варианты результата

Поле advisor_tool_result.content представляет собой размеченное объединение. Для успешных вызовов вариант зависит от модели-советника:

Ниже приведен один и тот же запрос, отправленный дважды и отличающийся только model советника в определении инструмента, — он демонстрирует оба варианта.

С "model": "claude-opus-4-8" рекомендации представлены открытым текстом:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
  }
}

С "model": "claude-opus-5" рекомендации зашифрованы:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
  }
}

Оба варианта результата содержат поле stop_reason, если вы задаете max_tokens в определении инструмента, и не содержат его, если не задаете. В нем хранится причина остановки подвызова советника — обычно "end_turn" или "max_tokens" при достижении лимита. Значения совпадают с stop_reason верхнего уровня в Messages API.

В advisor_result поле text содержит рекомендации в удобочитаемом виде. В advisor_redacted_result поле encrypted_content содержит непрозрачный блок данных, который вы не можете прочитать. На следующем ходе сервер расшифровывает его и подставляет открытый текст в подсказку исполнителя.

В обоих случаях передавайте контент обратно без изменений на последующих ходах. Если вы меняете модель-советника посреди диалога, используйте ветвление по content.type, чтобы обрабатывать обе структуры.

Результаты с ошибками

Если вызов советника завершается неудачей, результат содержит ошибку:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_tool_result_error",
    "error_code": "overloaded"
  }
}

Исполнитель видит ошибку и продолжает работу без новых рекомендаций. Сам запрос при этом не завершается ошибкой.

Вызовы советника расходуют «rate limit» (ограничение скорости) из того же пула для каждой модели, что и прямые вызовы модели-советника. Срабатывание ограничения скорости на советнике отображается как too_many_requests внутри результата инструмента. Срабатывание ограничения скорости на исполнителе приводит к сбою всего запроса с HTTP 429.

Многоходовые диалоги

В последующих ходах передавайте в API весь контент ассистента, включая блоки advisor_tool_result. Передавайте блоки результатов без изменений. С советником Claude Opus 5 поле content блока результата содержит зашифрованный вариант advisor_redacted_result: на следующем ходе сервер расшифровывает его и подставляет рекомендации в подсказку исполнителя (см. Варианты результата). Механика одинакова для любой модели-советника.

client = anthropic.Anthropic()

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
    }
]

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Добавьте полное содержимое ответа, включая все блоки advisor_tool_result
messages.append({"role": "assistant", "content": response.content})

# Продолжите диалог
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

В последующем ходе можно убрать инструмент советника из tools, даже если история сообщений все еще содержит блоки advisor_tool_result. Запрос будет принят, а исторические блоки сохранятся, но в этом ходе модель не сможет вызвать советника. Бета-заголовок advisor-tool-2026-03-01 по-прежнему нужно отправлять, иначе эти блоки истории не будут приняты.

Возобновление приостановленного хода

Ответ может завершиться с stop_reason: "pause_turn", пока вызов советника еще не выполнен. В этом случае ответ содержит блок server_tool_use советника без соответствующего advisor_tool_result.

Чтобы возобновить ход:

1. Добавьте это сообщение ассистента в messages без изменений, сохранив блок server_tool_use.
2. Отправьте запрос повторно с тем же инструментом советника и бета-заголовком.

Добавлять сообщение пользователя или блок tool_result не нужно. API выполнит ожидающий вызов советника и продолжит ход исполнителя в новом ответе. Возобновленный ход может снова приостановиться — в этом случае повторите те же действия.

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

Если же исполнитель в том же ходе вызвал один из ваших инструментов, ответ завершится с stop_reason: "tool_use", а вызов советника останется ожидающим. Отправьте блоки tool_result как обычно — ожидающий вызов советника выполнится в начале следующего запроса. См. Сочетание серверных и клиентских инструментов в одном ходе.

Напоминание посреди диалога для исполнителей, редко вызывающих советника

Если исполнитель Haiku не вызвал советника в своём первом ходе ассистента, добавьте короткое напоминание в виде дополнительного сообщения пользователя перед вторым ходом ассистента. Во внутренней поведенческой оценке Anthropic на исполнителях Claude Haiku 4.5 это повысило долю успешно выполненных задач примерно на 7 процентных пунктов. На исполнителях Sonnet текстовое напоминание не дало измеримого эффекта в тестах Anthropic. Приведённые далее соображения о моменте вызова особенно актуальны для Sonnet. Не применяйте напоминание к исполнителям Opus: на Opus оно немного снизило долю успешных выполнений.

При значении NUDGE_TURN по умолчанию, равном 2, напоминание обычно поступает после того, как модель сориентировалась в задаче, но до того, как она выбрала подход.

client = anthropic.Anthropic()

NUDGE_TURN = 2  # inject before this assistant turn if no advisor call yet
NUDGE_TEXT = (
    "You have not consulted the advisor yet. If the task has a non-obvious "
    "design decision or a failure mode you haven't ruled out, call advisor "
    "now before committing to an approach."
)
MAX_TURNS = 10  # agent loop cap


def run_your_tools(content):
    # Замените на свою диспетчеризацию инструментов. Возвращает по одному блоку tool_result на каждый блок tool_use.
    return [
        {
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": "Replace with your tool output.",
        }
        for block in content
        if block.type == "tool_use"
    ]


tools = [
    {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},
    # ... ваши другие инструменты
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{"role": "user", "content": task}]
advisor_called = False

for turn in range(1, MAX_TURNS + 1):
    response = client.beta.messages.create(
        model="claude-haiku-5-5",
        max_tokens=4096,
        betas=["advisor-tool-2026-03-01"],
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})
    advisor_called = advisor_called or any(
        block.type == "server_tool_use" and block.name == "advisor"
        for block in response.content
    )
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it
    if response.stop_reason != "tool_use":
        break  # end_turn, or a stop such as max_tokens that needs handling (see below)

    results = run_your_tools(response.content)  # list of tool_result blocks
    if results:
        messages.append({"role": "user", "content": results})
    # Пропустите это, если ваша системная подсказка уже указывает модели вызывать инструменты экономно.
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

Цикл завершается при любой причине остановки, кроме tool_use или pause_turn. Если max_tokens обрывает ответ, удалите усечённый ход ассистента из messages и повторите попытку с более высоким max_tokens. Если этот ход не содержит блока tool_use, вы можете вместо этого сохранить его и продолжить ответ новым сообщением пользователя. Повторная отправка усечённого хода ассистента в качестве последнего сообщения является предзаполнением («prefill»), которое Claude 4.6 и более поздние модели отклоняют.

Добавляйте напоминание отдельным сообщением пользователя после результатов инструментов, а не соседним блоком в том же сообщении. Последовательные сообщения пользователя допустимы. В тестах Anthropic на исполнителях Claude Haiku 4.5 и Sonnet они вели себя так же, как соседний блок. Форма отдельного сообщения также чётко отделяет напоминание от вывода инструментов.

Компромиссы: напоминание повышает частоту вызовов, что может привести к ненужной консультации на тривиально простых задачах. Если ваша рабочая нагрузка сочетает простые и сложные задачи, рассмотрите возможность увеличить NUDGE_TURN до 3, чтобы задачи из двух ходов завершались до срабатывания напоминания, или включайте напоминание по сигналу сложности задачи, который вы уже вычисляете. Если ваша системная подсказка уже содержит сдерживающие формулировки («используйте советника только при реальной неопределенности»), полностью откажитесь от напоминания, поскольку эти две инструкции противоречат друг другу.

Текстовое напоминание очень заметно для исполнителей Claude Haiku 4.5 и Sonnet: от 74 процентов (Sonnet) до 98 процентов (Claude Haiku 4.5) попыток с напоминанием в тестах Anthropic вызывали советника сразу на ходе 2. Если это происходит до того, как исполнитель прочитал задачу или собрал контекст, итоговый вызов советника получается малоконтекстным и может вытеснить более своевременный последующий вызов. Прежде чем добавлять напоминание, измерьте базовый ход первого вызова вашего исполнителя. Если исполнитель уже надёжно вызывает советника и его первый вызов обычно приходится на ход N, установите NUDGE_TURN больше N. В тестах Anthropic напоминание на ходе 2 в рабочих нагрузках, где базовый первый вызов приходился на ход 7 или позже, коррелировало со снижением эффективности выполнения задач на 3–4 процентных пункта. В рабочей нагрузке с просмотром веб-страниц, где базовая частота вызовов составляла 86 процентов, то же напоминание повысило вовлечённость без потерь в эффективности выполнения задач.

Чтобы принудительно вызвать консультацию в конкретном запросе вместо напоминания, установите tool_choice в {"type": "tool", "name": "advisor"} с учетом ограничений, описанных в разделе Принудительное использование инструментов. Принудительное использование инструментов нельзя сочетать с ручными расширенными размышлениями (thinking: {type: "enabled"}): если включить и то, и другое, API вернет 400 invalid_request_error. Адаптивные размышления поддерживают принудительное использование инструментов. Исполнители Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 и Claude Mythos 5.1 отклоняют типы tool_choice tool и any, поэтому для этих моделей используйте напоминание в подсказке.

Потоковая передача

Подвывод советника не поддерживает «streaming» (потоковую передачу). Пока работает советник, поток исполнителя приостанавливается, а затем полный результат приходит одним событием.

Блок server_tool_use с name: "advisor" сигнализирует о начале вызова советника. Пауза начинается, когда этот блок закрывается (content_block_stop). Во время паузы в потоке приходят только стандартные SSE-сообщения ping для поддержания соединения, примерно каждые 30 секунд. При коротких вызовах советника ping-сообщений может не быть вовсе.

Когда советник завершает работу, advisor_tool_result приходит полностью сформированным в одном событии content_block_start (без дельт). Затем потоковая передача вывода исполнителя возобновляется.

Далее следует событие message_delta с обновленным массивом usage.iterations, отражающим количество токенов советника.

Использование и оплата

Вызовы советника выполняются как отдельный подвывод и оплачиваются по тарифам модели-советника. Использование отражается в массиве usage.iterations[]:

{
  "usage": {
    "input_tokens": 1760,
    "cache_read_input_tokens": 412,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 412,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 89
      },
      {
        "type": "advisor_message",
        "model": "claude-opus-5",
        "input_tokens": 823,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "cache_creation_input_tokens": 0,
        "output_tokens": 442
      }
    ]
  }
}

Поля usage верхнего уровня отражают только токены исполнителя. Токены советника не включаются в итоговые значения верхнего уровня, поскольку оплачиваются по другому тарифу. Итерации с type: "advisor_message" оплачиваются по тарифам модели-советника, а итерации с type: "message" — по тарифам модели-исполнителя.

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

Вывод советника обычно составляет от 400 до 700 текстовых токенов, или от 1 400 до 1 800 токенов в сумме с размышлениями. Экономия достигается за счет того, что советник не генерирует весь итоговый вывод: это делает исполнитель по более низкому тарифу.

Параметр max_tokens верхнего уровня применяется только к выводу исполнителя и не ограничивает токены подвывода советника. Чтобы напрямую ограничить вывод советника, задайте max_tokens в определении инструмента. Токены советника также не расходуют бюджет задачи, назначенный исполнителю.

Priority Tier применяется к каждой модели независимо. Обязательство Priority Tier для модели-исполнителя не распространяется на советника. Вызовы советника выполняются в Priority Tier, только если у вашей организации есть обязательство и для модели-советника.

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

Существует два независимых уровня кэширования.

Кэширование на стороне исполнителя

Блок advisor_tool_result кэшируется так же, как любой другой блок контента. Точка останова cache_control, размещенная после него в последующем ходе, дает попадание в кэш. Подсказка исполнителя всегда содержит рекомендации в открытом виде, независимо от того, получил ли ваш клиент text или encrypted_content. Поэтому кэширование работает одинаково для обоих вариантов результата.

Кэширование на стороне советника

Задайте caching в определении инструмента, чтобы включить кэширование подсказок для собственной стенограммы советника между вызовами в рамках одного диалога:

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

Подсказка советника при N-м вызове — это подсказка (N-1)-го вызова с добавленным еще одним сегментом, поэтому префикс стабилен между вызовами. При включенном caching каждый вызов советника записывает запись в кэш, а следующий вызов читает до этой точки и платит только за разницу. Вы увидите, что cache_read_input_tokens становится ненулевым на второй и последующих итерациях advisor_message.

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

Сохраняйте согласованность: задайте caching один раз и не меняйте его на протяжении всего диалога. Выключение и повторное включение посреди диалога приводит к промахам кэша.

Сочетание с другими инструментами

Инструмент советника сочетается с другими серверными и клиентскими инструментами. Добавьте их все в один массив tools:

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

Исполнитель может искать в интернете, вызывать советника и использовать ваши пользовательские инструменты в одном и том же ходе. План советника может влиять на то, к каким инструментам исполнитель обратится дальше.

Рекомендации

Подсказки для задач программирования и агентных задач

Инструмент советника поставляется со встроенным описанием, которое побуждает исполнителя вызывать его в начале сложных задач и при возникновении трудностей. Для исследовательских задач дополнительные подсказки обычно не нужны.

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

1. Ранний первый вызов советника, после того как в стенограмме появилось несколько ознакомительных чтений.
2. Для сложных задач — финальный вызов советника, после того как в стенограмме появились записи файлов и результаты тестов.

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

Рекомендуемая системная подсказка для задач программирования

Без указаний в системной подсказке исполнитель в некоторых областях, особенно в программировании, вызывает советника реже, чем нужно. Если в задачах программирования вам нужны стабильные моменты вызова и примерно два-три вызова на задачу, добавьте следующие блоки в начало системной подсказки исполнителя. Они должны стоять перед любыми другими предложениями, упоминающими советника.

Указания по моменту вызова:

You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.

Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.

Как исполнителю следует относиться к рекомендациям (разместите сразу после блока о моменте вызова):

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

Альтернативная системная подсказка для Haiku на нагрузках программирования

Claude Haiku 4.5 применяет стандартные указания по советнику консервативно. Благодаря этому на исследовательских и справочных нагрузках частота вызовов остается уместно низкой. Однако на нагрузках программирования, где ранняя консультация с советником стабильно окупается, качество страдает. На внутреннем бенчмарке по программированию близкий вариант следующего блока повысил долю успешных задач Haiku примерно на 7,5 процентных пункта по сравнению со встроенным поведением по умолчанию. Исключение для операций только на чтение в жестком правиле было добавлено уже после измерений.

Используйте этот блок вместо приведенных выше блоков о моменте вызова и рекомендациях, если ваш исполнитель Haiku выполняет преимущественно задачи программирования или записи:

Consult a stronger reviewer who sees your full conversation transcript.

No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.

Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck -- errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

Оговорка: на внутреннем бенчмарке понимания при веб-поиске (n = 1 266) близкий вариант этого блока снизил точность примерно на 4 процентных пункта по сравнению со встроенным поведением по умолчанию. Если ваша нагрузка сочетает программирование со значительным объемом поиска или извлечения информации, используйте рекомендуемые блоки. Другой вариант — переключаться на этот блок по уже вычисляемому вами признаку типа нагрузки.

Увеличение числа вызовов советника у исполнителей Opus

Исполнители Opus обычно вызывают советника с уместной частотой без дополнительных подсказок. Если ваш исполнитель Opus на вашей нагрузке вызывает советника слишком редко, добавьте в системную подсказку следующую контрольную точку:

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

Оговорка: в тестах Anthropic близкий вариант этого блока повысил долю успешных задач, где советника вызывали слишком редко, примерно на 7–10 процентных пунктов. Исключение для операций только на чтение в жестком правиле было добавлено уже после измерений. Однако Opus стал вызывать советника слишком часто в задачах, где первое действие не требует планирования. На смешанной нагрузке итоговый эффект оказался примерно нулевым. Добавляйте этот блок, только если вы заметили, что Opus пропускает советника в задачах, где консультация помогла бы. Не добавляйте его по умолчанию.

Сокращение длины вывода советника

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

(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)

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

Для наилучшего баланса стоимости и качества сочетайте этот подход с указаниями по моменту вызова из раздела Рекомендуемая системная подсказка для задач программирования (или с альтернативным блоком для Haiku, если вы используете его). Если нужен жесткий предел, а не мягкая просьба, см. Ограничение вывода советника.

Ограничение вывода советника

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

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "max_tokens": 2048,
    }
]

Минимальное значение — 1024. Если задать max_tokens выше собственного лимита вывода модели-советника, вернется ошибка 400. Лимит применяется к каждому вызову советника независимо и не делится между вызовами в одном запросе.

Это не просто жесткое обрезание. Сервер также сообщает советнику оставшийся бюджет токенов, и советник подстраивает ответ под него.

Рекомендуемое начальное значение: max_tokens: 2048. В тестах Anthropic на сложном бенчмарке рассуждений (n = 40 на конфигурацию) это значение сократило средний вывод советника примерно в 7 раз по сравнению с отсутствием лимита. Обрезание при этом было почти нулевым, а заметного снижения качества не наблюдалось. Минимальное значение 1024 сократило вывод примерно в 10 раз, но обрезало около 10 процентов вызовов. При таком размере выборки различия в точности между всеми конфигурациями оставались в пределах шума. Проверяйте на собственной нагрузке.

Сложные задачи на рассуждение вызывают у советника значительно более длинный вывод, чем типичные 1 400–1 800 токенов, указанные выше для более легких нагрузок. Используйте эту таблицу для оценки коэффициента экономии, а не как универсальный ориентир для объема вывода советника.

Когда советник достигает лимита, блок результата содержит stop_reason: "max_tokens" в обоих вариантах результата, независимо от модели-советника. По stop_reason можно обнаружить обрезанные рекомендации и решить, повысить ли лимит или позволить исполнителю продолжить с частичными указаниями. API также добавляет к тексту рекомендаций [Advisor output truncated at max_tokens=2048.] (с указанием вашего лимита), чтобы исполнитель видел обрезание в своем контексте. Если советник возвращает advisor_result в открытом виде, этот маркер виден и вашему клиенту. Оба сигнала появляются, только если вы задали max_tokens в определении инструмента.

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
    "stop_reason": "max_tokens"
  }
}

Чтобы узнать, насколько близко каждый вызов подошел к лимиту, проверьте output_tokens в соответствующей записи advisor_message в usage.iterations.

В отличие от подхода на основе подсказки, max_tokens — это жесткий предел, а не мягкая просьба. Используйте max_tokens, когда нужна гарантированная граница по стоимости или задержке. Используйте подход на основе подсказки (или оба вместе), когда хотите склонить советника к краткости, не рискуя обрывом на полуслове.

Сочетание с настройками усилия

Для задач программирования сочетание Sonnet в роли «executor» (исполнитель) со средним уровнем «effort» (усилие) и Opus в роли «advisor» (советник) обеспечивает интеллект, сопоставимый с Sonnet при уровне усилия по умолчанию, но с меньшими затратами. Для максимального интеллекта оставьте для исполнителя уровень усилия по умолчанию.

Контроль затрат

• Чтобы ограничить бюджет на уровне разговора, подсчитывайте вызовы советника на стороне клиента. Когда вы достигнете своего лимита, удалите инструмент советника из tools. Удалять блоки advisor_tool_result из истории сообщений не нужно (см. примечание в разделе Многоходовые разговоры).
• Включайте caching только для разговоров, в которых вы ожидаете три или более вызовов советника.

Совместимость моделей

Модель-исполнитель (поле model верхнего уровня) и модель-советник (поле model внутри определения инструмента) должны образовывать допустимую пару. Советником должна быть Claude Sonnet 4.6 или более мощная модель, и она должна быть как минимум столь же мощной, как исполнитель. Модели с равными возможностями (например, Claude Opus 4.7 и Claude Opus 4.8) могут выступать советниками друг для друга.

Если вы запросите недопустимую пару, API вернёт 400 invalid_request_error с указанием неподдерживаемой комбинации.

Доступность на платформах

Инструмент советника доступен в бета-версии в Claude API и на Claude Platform on AWS. В настоящее время он недоступен в Amazon Bedrock, Google Cloud и Microsoft Foundry.

Советник в Claude Managed Agents

Сессии Claude Managed Agents также поддерживают советника, который настраивается как часть агента, а не как определение инструмента: задайте "advisor": {"type": "enabled", "model": ...} в блоке multiagent агента, и основной поток сессии сможет консультироваться с этой моделью посреди хода. Эта настройка не принимает параметры max_uses, max_tokens или caching, а советы доставляются как события потока в потоке событий сессии, а не как блоки advisor_tool_result в ответе. См. Предоставление сессии советника.

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