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

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

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



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

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

• Вы сейчас используете Sonnet для сложных задач: добавьте советника более высокого уровня. Opus сохраняет общую стоимость на том же уровне или ниже; Claude Fable 5 максимизирует прирост качества.
• Вы сейчас используете 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 выполняет отдельный проход инференса на модели-советнике на стороне сервера. Советник работает под собственной системной подсказкой, предоставленной 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 limits» (ограничения скорости) советника расходуются из той же корзины для модели, что и прямые вызовы модели-советника. Ограничение скорости на советнике проявляется как too_many_requests внутри результата инструмента. Ограничение скорости на исполнителе приводит к сбою всего запроса с HTTP 429.



Многоходовые разговоры

Передавайте полный контент ассистента, включая блоки advisor_tool_result, обратно в API на последующих ходах. Передавайте блоки результата дословно: с советником 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. Чтобы возобновить, добавьте это сообщение ассистента в messages с неизменённым контентом, сохранив блок server_tool_use, и отправьте запрос снова с тем же инструментом-советником и бета-заголовком. Вам не нужно добавлять пользовательское сообщение или блок tool_result. API выполняет ожидающий вызов советника и продолжает ход исполнителя в новом ответе. Возобновлённый ход может снова приостановиться. Если это произойдёт, повторите тот же шаг. Отсутствие инструмента-советника в запросе на возобновление возвращает 400 invalid_request_error, поскольку для ожидающего блока server_tool_use нет определения инструмента, с которым его можно выполнить; включайте инструмент всегда, когда есть ожидающий вызов. Если же исполнитель в том же ходе вызвал один из ваших инструментов, ответ завершается с stop_reason: "tool_use", пока вызов советника ещё ожидает выполнения. Отправьте блоки tool_result как обычно, и ожидающий вызов советника выполнится в начале следующего запроса. См. Сочетание серверных и клиентских инструментов в одном ходе.



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

Если исполнитель Haiku не вызвал советника в своём первом ходе ассистента, добавьте короткое напоминание в виде дополнительного пользовательского сообщения перед вторым ходом ассистента. Во внутренней поведенческой оценке Anthropic это повысило долю успешно выполненных задач примерно на 7 процентных пунктов на исполнителях Haiku. На исполнителях 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-4-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 == "end_turn":
        break
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it

    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})

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

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

Текстовое напоминание очень заметно для исполнителей Haiku и Sonnet: от 74 процентов (Sonnet) до 98 процентов (Haiku) попыток с напоминанием в тестировании 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, если вы включите оба. Адаптивное мышление поддерживает принудительное использование инструментов.



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

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

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

Когда советник завершает работу, 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 применяет стандартные рекомендации по советнику консервативно. Это удерживает частоту вызовов на уместно низком уровне для исследовательских и справочных рабочих нагрузок, но жертвует качеством на рабочих нагрузках программирования, где ранняя консультация с советником надёжно окупается. На внутреннем бенчмарке программирования близкий вариант следующего блока (исключение для операций только чтения в правиле Hard rule было добавлено после измерения) повысил долю успешных выполнений 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 близкий вариант этого блока (исключение для операций только чтения в правиле Hard rule было добавлено после измерения) повысил долю успешных выполнений на задачах с недостаточным числом вызовов примерно на 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, когда вам нужна гарантированная граница по стоимости или задержке. Используйте подход на основе подсказки (или оба вместе), когда хотите склонить советника к краткости без риска обрыва на середине мысли.



Сочетание с настройками effort

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



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

• Для бюджетов на уровне разговора считайте вызовы советника на стороне клиента. Когда вы достигнете своего предела, удалите инструмент-советник из 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 на AWS. В настоящее время он недоступен на Amazon Bedrock, Google Cloud и Microsoft Foundry.



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

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



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