Claude Platform Docs
СообщенияИнструменты

Серверные инструменты

Работа с инструментами, которые выполняет Anthropic: блоки server_tool_use, продолжение после pause_turn, ходы со смешанными серверными и клиентскими инструментами и фильтрация доменов.

Инструменты, выполняемые на сервере, используют общие механизмы: блок server_tool_use, продолжение после pause_turn, ходы, в которых смешиваются серверные и клиентские инструменты, соответствие требованиям «Zero Data Retention» (нулевое хранение данных), или ZDR, и фильтрацию доменов. Сведения об отдельных инструментах см. в справочнике по инструментам.

Блок server_tool_use

Блок server_tool_use появляется в ответе Claude, когда выполняется серверный инструмент. Его поле id использует префикс srvtoolu_, чтобы отличать его от вызовов клиентских инструментов:

{
  "type": "server_tool_use",
  "id": "srvtoolu_01A2B3C4D5E6F7G8H9",
  "name": "web_search",
  "input": { "query": "latest quantum computing breakthroughs" }
}

API выполняет инструмент самостоятельно. Вы видите вызов и его результат в ответе, но не занимаетесь выполнением. В отличие от клиентских блоков tool_use, вам не нужно отвечать блоком tool_result. Блок результата инструмента (например, web_search_tool_result для веб-поиска) следует за блоком server_tool_use в том же ходе ассистента и связывается с ним по tool_use_id. Если Claude одновременно вызывает один из ваших клиентских инструментов, блок server_tool_use появляется без результата, а ответ завершается с stop_reason: "tool_use". API выполняет инструмент, когда вы возвращаете клиентские блоки tool_result в следующем запросе.

Серверный цикл и pause_turn

При использовании серверных инструментов, таких как веб-поиск, API выполняет вызовы инструментов в серверном «agentic loop» (агентном цикле). Во время длительного хода API может приостановить этот цикл и вернуть причину остановки pause_turn.

Вот как обработать причину остановки pause_turn:

client = anthropic.Anthropic()

# Начальный запрос с веб-поиском
response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        }
    ],
    tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
)

# Проверяем, имеет ли ответ причину остановки pause_turn
if response.stop_reason == "pause_turn":
    # Продолжаем диалог с приостановленным содержимым
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Отправляем запрос на продолжение
    continuation = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)

При обработке pause_turn:

  • Продолжите разговор: передайте приостановленный ответ без изменений в следующем запросе, чтобы Claude продолжил свой ход.
  • Сохраните состояние инструментов: включите те же инструменты в запрос продолжения. Приостановленный ход может завершиться блоком server_tool_use, инструмент которого ещё не запускался. Если этого инструмента нет в продолжении, API возвращает ошибку валидации.
  • Сохраняйте контейнер: если ответ содержит container, как это бывает с инструментом выполнения кода, отправьте его ID обратно в запросе на продолжение. Без него запрос выполняется в новом контейнере, и файлы, появившиеся ранее в этом ходе, теряются.
  • Повторяйте по мере необходимости: продолженный ход может снова приостановиться. Проверяйте stop_reason в каждом ответе и продолжайте, пока не получите другую причину остановки. Ограничьте число продолжений, как в любом цикле повторных попыток. Сохраняйте каждый приостановленный ответ в messages по порядку. Продолжение содержит только новый контент, поэтому запрос, в котором пропущен более ранний приостановленный ответ, теряет эту работу и может вернуть ошибку 400.

Другие значения stop_reason и общие шаблоны обработки см. в разделе Причины остановки и резервные варианты.

Сочетание серверных и клиентских инструментов в одном ходе

Claude может вызвать серверный инструмент и клиентский инструмент в одной группе параллельных вызовов инструментов, например web_fetch вместе с пользовательским инструментом. Клиентский инструмент — это любой инструмент, который выполняет ваш код и который порождает блок tool_use, будь то пользовательский инструмент или клиентский инструмент со схемой Anthropic, например инструмент Bash. В этом случае API не выполняет серверный инструмент. Он сразу возвращает ответ, чтобы вы могли сначала выполнить клиентский инструмент:

  • stop_reason равен "tool_use", а не "pause_turn".
  • content содержит блок server_tool_use и клиентский блок tool_use, но не содержит блока результата для серверного инструмента: этот вызов не завершён.
  • Других маркеров нет. Определяйте это состояние по наличию блока server_tool_use, для id которого в ответе нет соответствующего блока результата. Блок mcp_tool_use от коннектора MCP ведёт себя так же. Вызовы серверных инструментов, у которых уже есть блок результата в том же ответе, завершены и ничего от вас не требуют.
{
  "stop_reason": "tool_use",
  "content": [
    {
      "type": "text",
      "text": "I'll fetch the article and check your system at the same time."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "name": "web_fetch",
      "input": { "url": "https://example.com/article" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "name": "run_command",
      "input": { "command": "uname -a" }
    }
  ]
}

Чтобы продолжить ход, выполните клиентские инструменты и отправьте сообщение пользователя, содержимое которого состоит только из блоков tool_result — по одному на каждый блок tool_use в этом ответе. Сохраните тот же массив tools: запрос на возобновление, в котором больше не определён ожидающий серверный инструмент, завершается ошибкой 400, сообщение которой заканчивается на but no `web_fetch` tool was provided.

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01PjgRJLbXrXEMZwDNYLnBqk",
      "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux"
    }
  ]
}

API присоединяет ваши результаты к ещё открытому ходу ассистента, выполняет отложенный серверный инструмент (для приостановленного выполнения кода — возобновляет его), а затем позволяет Claude продолжить. Для серверного инструмента, который Claude вызвал напрямую, следующий ответ начинается с блока результата, отвечающего на id блока server_tool_use из предыдущего ответа, за которым следуют вновь сгенерированное содержимое и новое значение stop_reason:

{
  "stop_reason": "end_turn",
  "content": [
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01HxbWnMRmbWyMfUtJKC45rA",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          }
        }
      }
    },
    {
      "type": "text",
      "text": "The article argues that... and your machine is running Linux..."
    }
  ]
}

Блок server_tool_use и его блок результата связываются по tool_use_id, а не по позиции: в этом сценарии они приходят в двух разных ответах, и блок server_tool_use не повторяется во втором. В последующих запросах сохраняйте весь обмен в массиве messages по порядку: первый ответ как сообщение assistant, сообщение пользователя с tool_result, а затем следующий ответ как ещё одно сообщение assistant — так же, как вы накапливаете любой другой обмен с использованием инструментов.

Чем это отличается от pause_turn: ответ pause_turn также может завершаться блоком server_tool_use, который ещё не выполнялся, но он никогда не оставляет клиентский блок tool_use, ожидающий вас, поэтому вы продолжаете его, повторно отправляя содержимое ассистента как есть. Ответ, который оставляет клиентский блок tool_use, ожидающий вас, никогда не имеет stop_reason со значением pause_turn: когда Claude останавливается, чтобы вызвать ваши инструменты, stop_reason равен tool_use, и вы продолжаете его, отправляя ответ обратно вместе с новым сообщением пользователя, содержащим клиентские блоки tool_result. В обоих случаях API запускает ожидающий серверный инструмент в начале следующего запроса.

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

client = anthropic.Anthropic()

tools = [
    {"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5},
    {
        "name": "run_command",
        "description": "Run a shell command on this computer and return its output.",
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The command to run"}
            },
            "required": ["command"],
        },
    },
]
messages = [
    {
        "role": "user",
        "content": "Summarize https://example.com/article and run uname -a to tell me what system this is on.",
    }
]

response = client.messages.create(
    model="claude-opus-5-5", max_tokens=4096, tools=tools, messages=messages
)

tool_results = [
    {
        "type": "tool_result",
        "tool_use_id": block.id,
        # Запустите здесь свой инструмент. В этом примере возвращается фиксированная строка.
        "content": "Linux demo-host 6.8.0-52-generic x86_64 GNU/Linux",
    }
    for block in response.content
    if block.type == "tool_use"
]

if response.stop_reason == "tool_use" and tool_results:
    # Блок server_tool_use без блока результата в этом ответе не завершён; его результат придёт в одном из следующих ответов.
    # Отправьте обратно только клиентские блоки tool_result с теми же инструментами.
    continuation = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        tools=tools,
        messages=[
            *messages,
            {"role": "assistant", "content": response.content},
            {"role": "user", "content": tool_results},
        ],
    )
    # Если web_fetch был отложен, он выполняется в этом запросе, и его
    # web_fetch_tool_result будет первым блоком в continuation.content.
    print(continuation)
else:
    print(response)

Этот код корректен и тогда, когда Claude не смешивает два вида вызовов. Ход только с клиентскими блоками tool_use идёт по тому же пути продолжения. Ход только с вызовами серверных инструментов не требует от вас клиентских блоков tool_result, поскольку его блоки результатов обычно уже присутствуют. Если такой ход возвращается приостановленным, например как ответ pause_turn, вместо этого отправьте его повторно без изменений.

ZDR и allowed_callers

Базовые версии веб-поиска (web_search_20250305) и веб-загрузки (web_fetch_20250910) соответствуют требованиям нулевого хранения данных (ZDR).

Версии _20260209 и более поздние с динамической фильтрацией по умолчанию не соответствуют требованиям ZDR, поскольку динамическая фильтрация внутренне опирается на выполнение кода.

Чтобы использовать серверный инструмент версии _20260209 или более поздней с ZDR, отключите динамическую фильтрацию, задав для инструмента "allowed_callers": ["direct"]:

{
  "type": "web_search_20260209",
  "name": "web_search",
  "allowed_callers": ["direct"]
}

Это ограничивает инструмент только прямыми вызовами, минуя внутренний этап выполнения кода.

allowed_callers определяет, как может вызываться инструмент: напрямую Claude ("direct"), изнутри контейнера выполнения кода (например, "code_execution_20260120") или обоими способами. Версии веб-инструментов _20260209 по умолчанию допускают только вызов из выполнения кода; более ранние версии по умолчанию используют ["direct"]. На моделях, которые не поддерживают программный вызов инструментов, эти версии требуют allowed_callers: ["direct"]; без этого API возвращает ошибку валидации с указанием задать этот параметр.

Фильтрация доменов

Серверные инструменты, обращающиеся к вебу, принимают параметры allowed_domains и blocked_domains для управления тем, к каким доменам Claude может обращаться. Оба являются полями объекта инструмента:

{
  "type": "web_search_20250305",
  "name": "web_search",
  "allowed_domains": ["example.com", "docs.python.org"]
}

При использовании фильтров доменов:

  • Домены не должны включать схему HTTP/HTTPS (используйте example.com вместо https://example.com).
  • Поддомены включаются автоматически (example.com охватывает docs.example.com).
  • Конкретные поддомены ограничивают результаты только этим поддоменом (docs.example.com возвращает результаты только с этого поддомена, а не с example.com или api.example.com).
  • Подпути поддерживаются для веб-поиска и соответствуют всему, что следует после пути (example.com/blog соответствует example.com/blog/post-1).
  • Веб-загрузка сопоставляет только домен: запись, включающая путь, никогда не соответствует URL веб-загрузки.
  • Вы можете использовать либо allowed_domains, либо blocked_domains, но не оба параметра в одном запросе.

Поддержка подстановочных знаков:

  • Подстановочные знаки (*) не допускаются в самом домене, только в пути после него.
  • Допустимо: example.com/*, example.com/*/articles
  • Недопустимо: *.example.com, ex*.com

Недопустимые форматы доменов отклоняются во время запроса с ошибкой 400 invalid_request_error.

Сведения о списках доменов и настройках вашей организации в сеансах Claude Managed Agents см. в разделе Ограничение доменов для веб-поиска и веб-загрузки.

Динамическая фильтрация с выполнением кода

Версии _20260209 и более поздние веб-поиска и веб-загрузки внутренне используют выполнение кода для применения динамических фильтров к результатам поиска.

Потоковая передача событий серверных инструментов

События серверных инструментов передаются в рамках обычного потока «server-sent events» (события, отправляемые сервером), или SSE. Блок server_tool_use, который Claude вызывает напрямую, передаётся потоком так же, как клиентский блок tool_use: событие content_block_start, за которым следуют события input_json_delta. Блок результата приходит целиком в одном событии content_block_start, без дельт.

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

Пакетные запросы

Все серверные инструменты поддерживают пакетную обработку. В пакете агентный цикл работает так же, как и для синхронных запросов, но с более высоким лимитом итераций на ход. Если цикл достигает этого лимита, ответ завершается с stop_reason: "pause_turn"; вы можете продолжить его, отправив последующий запрос с возвращённым содержимым. Подробности см. в разделе Серверные инструменты и агентный цикл.

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

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

Исправьте наиболее распространённые ошибки использования инструментов с помощью диагностических таблиц «симптом — решение».

Ищите в вебе и цитируйте результаты.

Загружайте и читайте содержимое по конкретным URL, чтобы дополнить контекст Claude актуальным веб-содержимым.

Выполняйте код Python и Bash в изолированном контейнере, чтобы анализировать данные, создавать файлы и итеративно улучшать решения.

Находите и загружайте инструменты по требованию.

Эта страница была полезной?