Серверные инструменты
Работа с инструментами, которые выполняет 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 в изолированном контейнере, чтобы анализировать данные, создавать файлы и итеративно улучшать решения.
Находите и загружайте инструменты по требованию.
Эта страница была полезной?