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

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

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



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

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

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

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

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



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

Модель-исполнитель (поле 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.



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

client = anthropic.Anthropic()

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

print(response)



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

Когда вы добавляете инструмент советника в ваш массив 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 в содержимом ассистента:

{
  "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 является дискриминированным объединением. Для успешных вызовов вариант зависит от модели-советника:

Советники Claude Fable 5 и Claude Mythos 5 возвращают advisor_redacted_result. Остальные модели-советники из таблицы совместимости возвращают advisor_result.

Оба варианта результата содержат поле 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"
  }
}

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

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



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

Передавайте полное содержимое ассистента, включая блоки advisor_tool_result, обратно в API на последующих ходах:

client = anthropic.Anthropic()

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

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

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    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-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Если вы опустите инструмент советника в tools на последующем ходе, в то время как история сообщений всё ещё содержит блоки advisor_tool_result, API вернёт ошибку 400 invalid_request_error.



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

Ответ может завершиться с stop_reason: "pause_turn", пока вызов советника всё ещё ожидает выполнения. Когда это происходит, ответ содержит блок server_tool_use советника без соответствующего advisor_tool_result. Чтобы возобновить, добавьте это сообщение ассистента в messages с неизменённым содержимым, сохранив блок server_tool_use, и отправьте запрос снова с тем же инструментом советника и бета-заголовком. Вам не нужно добавлять сообщение пользователя или блок tool_result. API выполняет ожидающий вызов советника и продолжает ход исполнителя в новом ответе. Возобновлённый ход может приостановиться снова. Если это произойдёт, повторите тот же шаг. Отсутствие инструмента советника в запросе на возобновление возвращает ошибку 400 invalid_request_error. Если же исполнитель вызвал один из ваших инструментов в том же ходе, ответ завершается с 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-4-8"},
    # ... ваши остальные инструменты
]
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(
        b.type == "server_tool_use" and b.name == "advisor" for b 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"} с учётом ограничений, описанных в разделе Принудительное использование инструментов. Принудительное использование инструментов нельзя сочетать с расширенным мышлением: API возвращает ошибку 400 invalid_request_error, если вы включите оба.



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

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

Блок 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": 412,
    "cache_read_input_tokens": 0,
    "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-4-8",
        "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" — по ставкам модели-исполнителя.

Правила агрегации различаются в зависимости от поля. output_tokens верхнего уровня — это сумма всех итераций исполнителя. input_tokens и cache_read_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-4-8",
        "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-4-8",
    },
    {
        "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 было добавлено после измерения) повысил показатели успешного выполнения 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 было добавлено после измерения) повысил показатели успешного выполнения для задач с недостаточным количеством вызовов примерно на 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-4-8",
        "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". API также добавляет [Advisor output truncated at max_tokens=2048.] (с указанием вашего лимита) к тексту совета, чтобы исполнитель видел усечение в своём собственном контексте. Используйте stop_reason для обнаружения усечённого совета и принятия решения о том, повысить ли лимит или позволить исполнителю продолжить с частичными рекомендациями. Оба сигнала появляются только тогда, когда вы устанавливаете max_tokens в определении инструмента.

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is\n\n[Advisor output truncated at max_tokens=2048.]",
    "stop_reason": "max_tokens"
  }
}

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

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



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

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



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

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



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