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

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

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



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

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

• Вы сейчас используете 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, Claude Fable 5 или Claude Mythos 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 является размеченным объединением. Для успешных вызовов вариант зависит от модели-советника:

Советники Claude Opus 5, 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 на последующих ходах. В этом примере используется claude-opus-4-8 в качестве советника, чтобы совет в открытом виде был виден в response.content; механика идентична для любой модели-советника.

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-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, если вы включаете оба. Адаптивное мышление поддерживает принудительное использование инструментов.



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

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

Блок 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 применяет рекомендации советника по умолчанию консервативно. Это поддерживает частоту вызовов на соответствующе низком уровне для исследовательских и поисковых рабочих нагрузок, но жертвует качеством на рабочих нагрузках кодирования, где ранняя консультация с советником надёжно окупается. На внутреннем бенчмарке кодирования близкий вариант следующего блока (исключение для операций только чтения в жёстком правиле было добавлено после измерения) повысил долю успешных выполнений 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-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 из истории сообщений (см. примечание в разделе Многоходовые разговоры).
• Включайте 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": ...} в мультиагентный реестр агента, и основной поток сессии сможет консультироваться с этой моделью в середине хода. Запись реестра не принимает параметры max_uses, max_tokens или caching, а советы доставляются как события потока в потоке событий сессии, а не как блоки advisor_tool_result в ответе. См. Назначение советника для сессии.



Дальнейшие шаги