Как реализовать использование инструментов

Выбор модели

Как правило, используйте Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (устарела) или Claude Opus 3 (устарела) для сложных инструментов и неоднозначных запросов; они лучше справляются с несколькими инструментами и при необходимости запрашивают уточнения.

Используйте Claude Haiku 3.5 или Claude Haiku 3 для простых инструментов, но учтите, что они могут выводить недостающие параметры.

Если вы используете Claude Sonnet 3.7 с использованием инструментов и расширенным мышлением, обратитесь к нашему руководству здесь для получения дополнительной информации.

Указание клиентских инструментов

Клиентские инструменты (как определенные Anthropic, так и определенные пользователем) указываются в параметре верхнего уровня tools API-запроса. Каждое определение инструмента включает:

Параметр	Описание
`name`	Имя инструмента. Должно соответствовать регулярному выражению `^[a-zA-Z0-9_-]{1,64}$`.
`description`	Подробное описание в виде обычного текста того, что делает инструмент, когда его следует использовать и как он работает.
`input_schema`	Объект JSON Schema, определяющий ожидаемые параметры для инструмента.

Пример простого определения инструмента

JSON
{
  "name": "get_weather",
  "description": "Get the current weather in a given location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      },
      "unit": {
        "type": "string",
        "enum": ["celsius", "fahrenheit"],
        "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

Этот инструмент с именем get_weather ожидает входной объект с обязательной строкой location и необязательной строкой unit, которая должна быть либо “celsius”, либо “fahrenheit”.

Системный промпт для использования инструментов

Когда вы вызываете API Anthropic с параметром tools, мы создаем специальный системный промпт из определений инструментов, конфигурации инструментов и любого указанного пользователем системного промпта. Созданный промпт предназначен для инструктирования модели использовать указанные инструменты и предоставления необходимого контекста для правильной работы инструмента:

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}

Лучшие практики для определений инструментов

Чтобы получить лучшую производительность от Claude при использовании инструментов, следуйте этим рекомендациям:

Предоставляйте крайне подробные описания. Это самый важный фактор в производительности инструментов. Ваши описания должны объяснять каждую деталь об инструменте, включая:
- Что делает инструмент
- Когда его следует использовать (и когда не следует)
- Что означает каждый параметр и как он влияет на поведение инструмента
- Любые важные предостережения или ограничения, такие как какую информацию инструмент не возвращает, если имя инструмента неясно. Чем больше контекста вы можете дать Claude о ваших инструментах, тем лучше он будет решать, когда и как их использовать. Стремитесь к минимум 3-4 предложениям на описание инструмента, больше, если инструмент сложный.
Отдавайте приоритет описаниям над примерами. Хотя вы можете включить примеры использования инструмента в его описание или в сопроводительный промпт, это менее важно, чем наличие ясного и всеобъемлющего объяснения назначения и параметров инструмента. Добавляйте примеры только после того, как полностью проработали описание.

Пример хорошего описания инструмента

JSON
{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

Пример плохого описания инструмента

JSON
{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

Хорошее описание четко объясняет, что делает инструмент, когда его использовать, какие данные он возвращает и что означает параметр ticker. Плохое описание слишком краткое и оставляет Claude с множеством открытых вопросов о поведении и использовании инструмента.

Управление выводом Claude

Принуждение к использованию инструментов

В некоторых случаях вы можете захотеть, чтобы Claude использовал конкретный инструмент для ответа на вопрос пользователя, даже если Claude думает, что может дать ответ без использования инструмента. Вы можете сделать это, указав инструмент в поле tool_choice следующим образом:

tool_choice = {"type": "tool", "name": "get_weather"}

При работе с параметром tool_choice у нас есть четыре возможных варианта:

auto позволяет Claude решать, вызывать ли любые предоставленные инструменты или нет. Это значение по умолчанию, когда предоставлены tools.
any говорит Claude, что он должен использовать один из предоставленных инструментов, но не принуждает к конкретному инструменту.
tool позволяет нам принудить Claude всегда использовать конкретный инструмент.
none предотвращает использование Claude любых инструментов. Это значение по умолчанию, когда tools не предоставлены.

При использовании кэширования промптов, изменения параметра tool_choice аннулируют кэшированные блоки сообщений. Определения инструментов и системные промпты остаются кэшированными, но содержимое сообщений должно быть переобработано.

Эта диаграмма иллюстрирует, как работает каждый вариант:

Обратите внимание, что когда у вас tool_choice как any или tool, мы предварительно заполним сообщение ассистента, чтобы принудить к использованию инструмента. Это означает, что модели не будут выдавать блок содержимого text с цепочкой рассуждений перед блоками содержимого tool_use, даже если явно попросить об этом.

При использовании расширенного мышления с использованием инструментов, tool_choice: {"type": "any"} и tool_choice: {"type": "tool", "name": "..."} не поддерживаются и приведут к ошибке. Только tool_choice: {"type": "auto"} (по умолчанию) и tool_choice: {"type": "none"} совместимы с расширенным мышлением.

Наше тестирование показало, что это не должно снижать производительность. Если вы хотите сохранить цепочку рассуждений (особенно с Opus), при этом запрашивая, чтобы модель использовала конкретный инструмент, вы можете использовать {"type": "auto"} для tool_choice (по умолчанию) и добавить явные инструкции в сообщение user. Например: Какая погода в Лондоне? Используйте инструмент get_weather в своем ответе.

Вывод JSON

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

Цепочка рассуждений

При использовании инструментов Claude часто показывает свою “цепочку рассуждений”, т.е. пошаговое рассуждение, которое он использует для разбора проблемы и решения, какие инструменты использовать. Модель Claude Opus 3 (устарела) будет делать это, если tool_choice установлен в auto (это значение по умолчанию, см. Принуждение к использованию инструментов), а Sonnet и Haiku можно побудить к этому.

Например, при получении промпта “Какая погода в Сан-Франциско прямо сейчас, и который там час?”, Claude может ответить:

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "To answer this question, I will: 1. Use the get_weather tool to get the current weather in San Francisco. 2. Use the get_time tool to get the current time in the America/Los_Angeles timezone, which covers San Francisco, CA."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

Эта цепочка рассуждений дает представление о процессе рассуждения Claude и может помочь вам отладить неожиданное поведение.

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

Параллельное использование инструментов

По умолчанию Claude может использовать несколько инструментов для ответа на запрос пользователя. Вы можете отключить это поведение:

Установив disable_parallel_tool_use=true, когда тип tool_choice равен auto, что гарантирует, что Claude использует не более одного инструмента
Установив disable_parallel_tool_use=true, когда тип tool_choice равен any или tool, что гарантирует, что Claude использует ровно один инструмент

Полный пример параллельного использования инструментов

Вот полный пример, показывающий, как правильно форматировать параллельные вызовы инструментов в истории сообщений:

import anthropic

client = anthropic.Anthropic()

# Define tools
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Initial request
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=[
        {
            "role": "user",
            "content": "What's the weather in SF and NYC, and what time is it there?"
        }
    ]
)

# Claude's response with parallel tool calls
print("Claude wants to use tools:", response.stop_reason == "tool_use")
print("Number of tool calls:", len([c for c in response.content if c.type == "tool_use"]))

# Build the conversation with tool results
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    },
    {
        "role": "assistant",
        "content": response.content  # Contains multiple tool_use blocks
    },
    {
        "role": "user",
        "content": [
            {
                "type": "tool_result",
                "tool_use_id": "toolu_01",  # Must match the ID from tool_use
                "content": "San Francisco: 68°F, partly cloudy"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_02",
                "content": "New York: 45°F, clear skies"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_03",
                "content": "San Francisco time: 2:30 PM PST"
            },
            {
                "type": "tool_result",
                "tool_use_id": "toolu_04",
                "content": "New York time: 5:30 PM EST"
            }
        ]
    }
]

# Get final response
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    tools=tools,
    messages=messages
)

print(final_response.content[0].text)

Сообщение ассистента с параллельными вызовами инструментов будет выглядеть так:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the weather and time for both San Francisco and New York City."
    },
    {
      "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    },
    {
      "type": "tool_use",
      "id": "toolu_02",
      "name": "get_weather",
      "input": {"location": "New York, NY"}
    },
    {
      "type": "tool_use",
      "id": "toolu_03",
      "name": "get_time",
      "input": {"timezone": "America/Los_Angeles"}
    },
    {
      "type": "tool_use",
      "id": "toolu_04",
      "name": "get_time",
      "input": {"timezone": "America/New_York"}
    }
  ]
}

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

Вот полный, исполняемый скрипт для тестирования и проверки правильной работы параллельных вызовов инструментов:

#!/usr/bin/env python3
"""Test script to verify parallel tool calls with the Anthropic API"""

import os
from anthropic import Anthropic

# Initialize client
client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

# Define tools
tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given timezone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The timezone, e.g. America/New_York"
                }
            },
            "required": ["timezone"]
        }
    }
]

# Test conversation with parallel tool calls
messages = [
    {
        "role": "user",
        "content": "What's the weather in SF and NYC, and what time is it there?"
    }
]

# Make initial request
print("Requesting parallel tool calls...")
response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

# Check for parallel tool calls
tool_uses = [block for block in response.content if block.type == "tool_use"]
print(f"\n✓ Claude made {len(tool_uses)} tool calls")

if len(tool_uses) > 1:
    print("✓ Parallel tool calls detected!")
    for tool in tool_uses:
        print(f"  - {tool.name}: {tool.input}")
else:
    print("✗ No parallel tool calls detected")

# Simulate tool execution and format results correctly
tool_results = []
for tool_use in tool_uses:
    if tool_use.name == "get_weather":
        if "San Francisco" in str(tool_use.input):
            result = "San Francisco: 68°F, partly cloudy"
        else:
            result = "New York: 45°F, clear skies"
    else:  # get_time
        if "Los_Angeles" in str(tool_use.input):
            result = "2:30 PM PST"
        else:
            result = "5:30 PM EST"
    
    tool_results.append({
        "type": "tool_result",
        "tool_use_id": tool_use.id,
        "content": result
    })

# Continue conversation with tool results
messages.extend([
    {"role": "assistant", "content": response.content},
    {"role": "user", "content": tool_results}  # All results in one message!
])

# Get final response
print("\nGetting final response...")
final_response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=tools
)

print(f"\nClaude's response:\n{final_response.content[0].text}")

# Verify formatting
print("\n--- Verification ---")
print(f"✓ Tool results sent in single user message: {len(tool_results)} results")
print("✓ No text before tool results in content array")
print("✓ Conversation formatted correctly for future parallel tool use")

Этот скрипт демонстрирует:

Как правильно форматировать параллельные вызовы инструментов и результаты
Как проверить, что параллельные вызовы выполняются
Правильную структуру сообщений, которая поощряет будущее параллельное использование инструментов
Распространенные ошибки, которых следует избегать (например, текст перед результатами инструментов)

Запустите этот скрипт, чтобы протестировать вашу реализацию и убедиться, что Claude эффективно выполняет параллельные вызовы инструментов.

Максимизация параллельного использования инструментов

Хотя модели Claude 4 имеют отличные возможности параллельного использования инструментов по умолчанию, вы можете увеличить вероятность параллельного выполнения инструментов во всех моделях с помощью целевого промптинга:

Системные промпты для параллельного использования инструментов

Для моделей Claude 4 (Opus 4.1, Opus 4 и Sonnet 4) добавьте это в ваш системный промпт:

For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially.

Для еще более сильного параллельного использования инструментов (рекомендуется, если значения по умолчанию недостаточно), используйте:

<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Prioritize calling tools in parallel whenever possible. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. When running multiple read-only commands like `ls` or `list_dir`, always run all of the commands in parallel. Err on the side of maximizing parallel tool calls rather than running too many tools sequentially.
</use_parallel_tool_calls>

Промптинг пользовательских сообщений

Вы также можете поощрять параллельное использование инструментов в конкретных пользовательских сообщениях:

# Вместо:
"What's the weather in Paris? Also check London."

# Используйте:
"Check the weather in Paris and London simultaneously."

# Или будьте явными:
"Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time."

Параллельное использование инструментов с Claude Sonnet 3.7

Claude Sonnet 3.7 может быть менее склонен к выполнению параллельных вызовов инструментов в ответе, даже когда вы не установили disable_parallel_tool_use. Чтобы обойти это, мы рекомендуем включить эффективное по токенам использование инструментов, что помогает поощрить Claude к использованию параллельных инструментов. Эта бета-функция также снижает задержку и экономит в среднем 14% выходных токенов.

Если вы предпочитаете не включать бета-версию эффективного по токенам использования инструментов, вы также можете ввести “пакетный инструмент”, который может действовать как мета-инструмент для одновременного обертывания вызовов других инструментов. Мы обнаружили, что если этот инструмент присутствует, модель будет использовать его для одновременного параллельного вызова нескольких инструментов для вас.

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

Обработка блоков содержимого использования инструментов и результатов инструментов

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

Обработка результатов от клиентских инструментов

Ответ будет иметь stop_reason равный tool_use и один или несколько блоков содержимого tool_use, которые включают:

id: Уникальный идентификатор для этого конкретного блока использования инструмента. Он будет использоваться для сопоставления результатов инструмента позже.
name: Имя используемого инструмента.
input: Объект, содержащий входные данные, передаваемые инструменту, соответствующие input_schema инструмента.

Пример API-ответа с блоком содержимого `tool_use`

JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I need to use the get_weather, and the user wants SF, which is likely San Francisco, CA."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}

Когда вы получаете ответ об использовании инструмента для клиентского инструмента, вы должны:

Извлечь name, id и input из блока tool_use.
Запустить фактический инструмент в вашей кодовой базе, соответствующий этому имени инструмента, передав input инструмента.
Продолжить разговор, отправив новое сообщение с role равным user и блоком content, содержащим тип tool_result и следующую информацию:
- tool_use_id: id запроса на использование инструмента, для которого это результат.
- content: Результат инструмента в виде строки (например, "content": "15 degrees"), списка вложенных блоков содержимого (например, "content": [{"type": "text", "text": "15 degrees"}]) или списка блоков документов (например, "content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]). Эти блоки содержимого могут использовать типы text, image или document.
- is_error (необязательно): Установите в true, если выполнение инструмента привело к ошибке.

Важные требования к форматированию:

Блоки результатов инструментов должны непосредственно следовать за соответствующими блоками использования инструментов в истории сообщений. Вы не можете включать какие-либо сообщения между сообщением об использовании инструмента ассистентом и сообщением с результатом инструмента пользователя.
В пользовательском сообщении, содержащем результаты инструментов, блоки tool_result должны идти ПЕРВЫМИ в массиве содержимого. Любой текст должен идти ПОСЛЕ всех результатов инструментов.

Например, это вызовет ошибку 400:

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ Текст перед tool_result
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

Это правильно:

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "What should I do next?"}  // ✅ Текст после tool_result
]}

Если вы получаете ошибку типа “tool_use ids were found without tool_result blocks immediately after”, проверьте, что ваши результаты инструментов отформатированы правильно.

Пример успешного результата инструмента

Пример результата инструмента с изображениями

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "15 degrees"},
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg...",
          }
        }
      ]
    }
  ]
}

Пример пустого результата инструмента

Пример результата инструмента с документами

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        {"type": "text", "text": "The weather is"},
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 degrees"
          }
        }
      ]
    }
  ]
}

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

Обработка результатов от серверных инструментов

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

Различия от других API

В отличие от API, которые разделяют использование инструментов или используют специальные роли, такие как tool или function, API Anthropic интегрирует инструменты непосредственно в структуру сообщений user и assistant.

Сообщения содержат массивы блоков text, image, tool_use и tool_result. Сообщения user включают клиентское содержимое и tool_result, в то время как сообщения assistant содержат содержимое, сгенерированное ИИ, и tool_use.

Обработка причины остановки `max_tokens`

Если ответ Claude обрезан из-за достижения лимита max_tokens, и обрезанный ответ содержит неполный блок использования инструмента, вам нужно будет повторить запрос с более высоким значением max_tokens, чтобы получить полное использование инструмента.

# Check if response was truncated during tool use
if response.stop_reason == "max_tokens":
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-opus-4-1-20250805",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools
        )

Обработка причины остановки `pause_turn`

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

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

import anthropic

client = anthropic.Anthropic()

# Initial request with web search
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    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-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

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

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

Устранение ошибок

Существует несколько различных типов ошибок, которые могут возникнуть при использовании инструментов с Claude:

Ошибка выполнения инструмента

Если сам инструмент выбрасывает ошибку во время выполнения (например, сетевая ошибка при получении данных о погоде), вы можете вернуть сообщение об ошибке в content вместе с "is_error": true:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Claude затем включит эту ошибку в свой ответ пользователю, например: “Извините, я не смог получить текущую погоду, потому что API службы погоды недоступен. Пожалуйста, попробуйте еще раз позже.”

Неверное имя инструмента

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

Однако вы также можете продолжить разговор с tool_result, который указывает на ошибку, и Claude попытается использовать инструмент снова с заполненной недостающей информацией:

JSON
{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

Если запрос инструмента недействителен или отсутствуют параметры, Claude повторит попытку 2-3 раза с исправлениями, прежде чем извиниться перед пользователем.

Теги <search_quality_reflection>

Ошибки серверных инструментов

Параллельные вызовы инструментов не работают

Если Claude не выполняет параллельные вызовы инструментов, когда ожидается, проверьте эти распространенные проблемы:

1. Неправильное форматирование результатов инструментов

Наиболее распространенная проблема — неправильное форматирование результатов инструментов в истории разговора. Это “учит” Claude избегать параллельных вызовов.

Специально для параллельного использования инструментов:

❌ Неправильно: Отправка отдельных пользовательских сообщений для каждого результата инструмента
✅ Правильно: Все результаты инструментов должны быть в одном пользовательском сообщении

// ❌ Это снижает параллельное использование инструментов
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Отдельное сообщение
]

// ✅ Это поддерживает параллельное использование инструментов
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Одно сообщение
]

См. общие требования к форматированию выше для других правил форматирования.

2. Слабый промптинг

Промптинг по умолчанию может быть недостаточным. Используйте более сильные формулировки:

<use_parallel_tool_calls>
For maximum efficiency, whenever you perform multiple independent operations, 
invoke all relevant tools simultaneously rather than sequentially. 
Prioritize calling tools in parallel whenever possible.
</use_parallel_tool_calls>

3. Измерение использования параллельных инструментов

Для проверки работы параллельных вызовов инструментов:

# Calculate average tools per tool-calling message
tool_call_messages = [msg for msg in messages if any(
    block.type == "tool_use" for block in msg.content
)]
total_tool_calls = sum(
    len([b for b in msg.content if b.type == "tool_use"]) 
    for msg in tool_call_messages
)
avg_tools_per_message = total_tool_calls / len(tool_call_messages)
print(f"Average tools per message: {avg_tools_per_message}")
# Should be > 1.0 if parallel calls are working

4. Поведение, специфичное для модели

Claude Opus 4.1, Opus 4 и Sonnet 4: Превосходно справляются с параллельным использованием инструментов с минимальным промптингом
Claude Sonnet 3.7: Может потребовать более сильного промптинга или эффективного по токенам использования инструментов
Claude Haiku: Менее вероятно использование параллельных инструментов без явного промптинга

Обзор Токен-эффективное использование инструментов

On this page

Выбор модели
Указание клиентских инструментов
Системный промпт для использования инструментов
Лучшие практики для определений инструментов
Управление выводом Claude
Принуждение к использованию инструментов
Вывод JSON
Цепочка рассуждений
Параллельное использование инструментов
Максимизация параллельного использования инструментов
Обработка блоков содержимого использования инструментов и результатов инструментов
Обработка результатов от клиентских инструментов
Обработка результатов от серверных инструментов
Обработка причины остановки max_tokens
Обработка причины остановки pause_turn
Устранение ошибок

Первые шаги

Модели и цены

Узнать о Claude

Возможности

Инструменты

Протокол контекста модели (MCP)

Варианты использования

Инженерия промптов

Тестирование и оценка

Усилить защитные меры

Юридический центр

Как реализовать использование инструментов

Выбор модели

Указание клиентских инструментов

Системный промпт для использования инструментов

Лучшие практики для определений инструментов

Управление выводом Claude

Принуждение к использованию инструментов

Вывод JSON

Цепочка рассуждений

Параллельное использование инструментов

Максимизация параллельного использования инструментов

Обработка блоков содержимого использования инструментов и результатов инструментов

Обработка результатов от клиентских инструментов

Обработка результатов от серверных инструментов

Обработка причины остановки `max_tokens`

Обработка причины остановки `pause_turn`

Устранение ошибок

Первые шаги

Модели и цены

Узнать о Claude

Возможности

Инструменты

Протокол контекста модели (MCP)

Варианты использования

Инженерия промптов

Тестирование и оценка

Усилить защитные меры

Юридический центр

​Выбор модели

​Указание клиентских инструментов

​Системный промпт для использования инструментов

​Лучшие практики для определений инструментов

​Управление выводом Claude

​Принуждение к использованию инструментов

​Вывод JSON

​Цепочка рассуждений

​Параллельное использование инструментов

​Максимизация параллельного использования инструментов

​Обработка блоков содержимого использования инструментов и результатов инструментов

​Обработка результатов от клиентских инструментов

​Обработка результатов от серверных инструментов

​Обработка причины остановки max_tokens

​Обработка причины остановки pause_turn

​Устранение ошибок

Выбор модели

Указание клиентских инструментов

Системный промпт для использования инструментов

Лучшие практики для определений инструментов

Управление выводом Claude

Принуждение к использованию инструментов

Вывод JSON

Цепочка рассуждений

Параллельное использование инструментов

Максимизация параллельного использования инструментов

Обработка блоков содержимого использования инструментов и результатов инструментов

Обработка результатов от клиентских инструментов

Обработка результатов от серверных инструментов

Обработка причины остановки `max_tokens`

Обработка причины остановки `pause_turn`

Устранение ошибок