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

На этой странице рассматриваются общие механики инструментов, выполняемых на сервере: блок server_tool_use, продолжение pause_turn, рассмотрение 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. Блок результата появляется сразу после блока server_tool_use в том же ходе помощника.

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

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

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

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

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

ZDR и allowed_callers

Базовые версии веб-поиска (web_search_20250305) и веб-выборки (web_fetch_20250910) имеют право на Zero Data Retention (ZDR).

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

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

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

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

Хотя сам инструмент веб-выборки имеет право на ZDR, издатели веб-сайтов могут сохранять любые параметры, передаваемые в URL, если Claude получает содержимое с их сайта.

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

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

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

Домены не должны включать схему 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)
Вы можете использовать либо allowed_domains, либо blocked_domains, но не оба в одном запросе

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

Только один подстановочный знак (*) разрешен на запись домена, и он должен появляться после части домена (в пути)
Допустимо: example.com/*, example.com/*/articles
Недопустимо: *.example.com, ex*.com, example.com/*/news/*

Недопустимые форматы доменов возвращают ошибку инструмента invalid_tool_input.

Ограничения доменов на уровне запроса должны быть совместимы с ограничениями доменов на уровне организации, настроенными в Console. Домены на уровне запроса могут только дополнительно ограничивать домены, а не переопределять или расширяться за пределы списка на уровне организации. Если ваш запрос включает домены, которые конфликтуют с параметрами организации, API возвращает ошибку валидации.

Помните, что символы Unicode в названиях доменов могут создавать уязвимости безопасности через атаки омографов, где визуально похожие символы из разных скриптов могут обойти фильтры доменов. Например, аmazon.com (используя кириллицу 'а') может выглядеть идентично amazon.com, но представляет другой домен.

При настройке списков разрешения/блокировки доменов:

Используйте только ASCII-домены, когда это возможно
Учитывайте, что парсеры URL могут обрабатывать нормализацию Unicode по-разному
Протестируйте фильтры доменов с потенциальными вариантами омографов
Регулярно проверяйте конфигурации доменов на предмет подозрительных символов Unicode

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

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

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

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

События серверного инструмента передаются как часть обычного потока SSE. Блок server_tool_use и его результат поступают как события content_block_start и content_block_delta, так же как текст и вызовы клиентских инструментов.

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

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

Все серверные инструменты поддерживают пакетную обработку. См. Пакетная обработка.

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

Веб-поиск

Поиск в веб и цитирование результатов.

Веб-выборка

Получение содержимого с конкретных URL.

Выполнение кода

Запуск Python в изолированном контейнере.

Поиск инструментов

# Initial request with web search
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    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}],
)

# Check if the response has pause_turn stop reason
if response.stop_reason == "pause_turn":
    # Continue the conversation with the paused content
    messages = [
        {
            "role": "user",
            "content": "Search for comprehensive information about quantum computing breakthroughs in 2025",
        },
        {"role": "assistant", "content": response.content},
    ]

    # Send the continuation request
    continuation = client.messages.create(
        model="claude-opus-4-7",
        max_tokens=1024,
        messages=messages,
        tools=[{"type": "web_search_20250305", "name": "web_search", "max_uses": 10}],
    )

    print(continuation)
else:
    print(response)