Выбор модели

Мы рекомендуем использовать последнюю модель Claude Sonnet (4.5) или Claude Opus (4.1) для сложных инструментов и неоднозначных запросов; они лучше справляются с несколькими инструментами и запрашивают уточнения при необходимости. Используйте модели Claude Haiku для простых инструментов, но имейте в виду, что они могут выводить отсутствующие параметры.
Если вы используете Claude с использованием инструментов и расширенным мышлением, обратитесь к нашему руководству здесь для получения дополнительной информации.

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

Клиентские инструменты (как определённые 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 Claude с параметром 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 их вызывает
  • Обрабатывает цикл запроса/ответа
  • Управляет состоянием беседы
  • Обеспечивает безопасность типов и валидацию
Мы рекомендуем использовать средство запуска инструментов для большинства реализаций использования инструментов.
Средство запуска инструментов в настоящее время находится в бета-версии и доступно только в Python и TypeScript SDK.

Базовое использование

Используйте декоратор @beta_tool для определения инструментов и client.beta.messages.tool_runner() для их выполнения.
Если вы используете асинхронный клиент, замените @beta_tool на @beta_async_tool и определите функцию с async def.
import anthropic
import json
from anthropic import beta_tool

# Initialize client
client = anthropic.Anthropic()

# Define tools using the decorator
@beta_tool
def get_weather(location: str, unit: str = "fahrenheit") -> str:
    """Get the current weather in a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA
        unit: Temperature unit, either 'celsius' or 'fahrenheit'
    """
    # In a full implementation, you'd call a weather API here
    return json.dumps({"temperature": "20°C", "condition": "Sunny"})

@beta_tool
def calculate_sum(a: int, b: int) -> str:
    """Add two numbers together.

    Args:
        a: First number
        b: Second number
    """
    return str(a + b)

# Use the tool runner
with client.beta.messages.tool_runner(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[get_weather, calculate_sum],
    messages=[
        {"role": "user", "content": "What's the weather like in Paris? Also, what's 15 + 27?"}
    ]
) as runner:
    for message in runner:
        print(message.content[0].text)
Декорированная функция должна возвращать блок содержимого или массив блоков содержимого, включая текст, изображения или блоки документов. Это позволяет инструментам возвращать богатые многомодальные ответы. Возвращаемые строки будут преобразованы в блок содержимого текста. Если вы хотите вернуть структурированный объект JSON в Claude, закодируйте его в строку JSON перед возвратом. Числа, логические значения или другие примитивы, не являющиеся строками, также должны быть преобразованы в строки.Декоратор @beta_tool будет проверять аргументы функции и строку документации для извлечения представления json schema данной функции, в приведённом выше примере calculate_sum будет преобразован в:
{
  "name": "calculate_sum",
  "description": "Adds two integers together.",
  "input_schema": {
    "additionalProperties": false,
    "properties": {
      "left": {
        "description": "The first integer to add.",
        "title": "Left",
        "type": "integer"
      },
      "right": {
        "description": "The second integer to add.",
        "title": "Right",
        "type": "integer"
      }
    },
    "required": ["left", "right"],
    "type": "object"
  }
}
Средство запуска инструментов SDK находится в бета-версии. Остальная часть этого документа охватывает ручную реализацию инструментов.

Управление выводом 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, мы предварительно заполним сообщение помощника, чтобы принудить использование инструмента. Это означает, что модели не будут выдавать естественный языковой ответ или объяснение перед блоками содержимого tool_use, даже если об этом явно попросить.
При использовании расширенного мышления с использованием инструментов tool_choice: {"type": "any"} и tool_choice: {"type": "tool", "name": "..."} не поддерживаются и приведут к ошибке. Совместимы только tool_choice: {"type": "auto"} (по умолчанию) и tool_choice: {"type": "none"}.
Наше тестирование показало, что это не должно снижать производительность. Если вы хотите, чтобы модель предоставила естественный языковой контекст или объяснения при этом запрашивая использование конкретного инструмента, вы можете использовать {"type": "auto"} для tool_choice (по умолчанию) и добавить явные инструкции в сообщение user. Например: What's the weather like in London? Use the get_weather tool in your response.

Вывод JSON

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

Ответы модели с инструментами

При использовании инструментов Claude часто комментирует то, что он делает, или естественно отвечает пользователю перед вызовом инструментов. Например, при наличии запроса “What’s the weather like in San Francisco right now, and what time is it there?”, Claude может ответить:
JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}
Этот естественный стиль ответа помогает пользователям понять, что делает Claude, и создаёт более разговорное взаимодействие. Вы можете направлять стиль и содержание этих ответов через ваши системные запросы и предоставляя <examples> в ваших запросах. Важно отметить, что Claude может использовать различные формулировки и подходы при объяснении своих действий. Ваш код должен рассматривать эти ответы как любой другой текст, сгенерированный помощником, и не полагаться на определённые соглашения форматирования.

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

По умолчанию Claude может использовать несколько инструментов для ответа на запрос пользователя. Вы можете отключить это поведение, выполнив следующие действия:
  • Установка disable_parallel_tool_use=true когда тип tool_choice является auto, что гарантирует, что Claude использует максимум один инструмент
  • Установка disable_parallel_tool_use=true когда тип tool_choice является any или tool, что гарантирует, что Claude использует ровно один инструмент
Проще с Tool runner: Приведённый ниже пример показывает ручную обработку параллельных инструментов. Для большинства случаев использования tool runner автоматически обрабатывает параллельное выполнение инструментов с гораздо меньшим количеством кода.
Вот полный пример, показывающий, как правильно форматировать параллельные вызовы инструментов в истории сообщений:
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-sonnet-4-5",
    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-sonnet-4-5",
    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 Claude 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-sonnet-4-5",
    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-sonnet-4-5",
    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>
Вы также можете поощрять параллельное использование инструментов в конкретных пользовательских сообщениях:
# Instead of:
"What's the weather in Paris? Also check London."

# Use:
"Check the weather in Paris and London simultaneously."

# Or be explicit:
"Please use parallel tool calls to get the weather for Paris, London, and Tokyo at the same time."
Параллельное использование инструментов с Claude Sonnet 3.7Claude Sonnet 3.7 может быть менее вероятно выполнять параллельные вызовы инструментов в ответе, даже если вы не установили disable_parallel_tool_use. Чтобы обойти это, мы рекомендуем включить эффективное использование инструментов по токенам, что помогает поощрять Claude использовать параллельные инструменты. Эта бета-функция также снижает задержку и экономит в среднем 14% выходных токенов.Если вы предпочитаете не использовать бета-версию эффективного использования инструментов по токенам, вы также можете ввести “пакетный инструмент”, который может действовать как мета-инструмент для обёртывания вызовов других инструментов одновременно. Мы обнаружили, что если этот инструмент присутствует, модель будет использовать его для одновременного вызова нескольких инструментов параллельно для вас.См. этот пример в нашей кулинарной книге для того, как использовать этот обходной путь.

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

Проще с Tool runner: Ручная обработка инструментов, описанная в этом разделе, автоматически управляется tool runner. Используйте этот раздел, когда вам нужен пользовательский контроль над выполнением инструментов.
Ответ Claude отличается в зависимости от того, использует ли он клиентский или серверный инструмент.

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

Ответ будет иметь stop_reason из tool_use и один или несколько блоков содержимого tool_use, которые включают:
  • id: Уникальный идентификатор для этого конкретного блока использования инструмента. Это будет использоваться для сопоставления результатов инструмента позже.
  • name: Имя используемого инструмента.
  • input: Объект, содержащий входные данные, передаваемые инструменту, соответствующие input_schema инструмента.
JSON
{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-sonnet-4-5",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA", "unit": "celsius"}
    }
  ]
}
Когда вы получаете ответ использования инструмента для клиентского инструмента, вы должны:
  1. Извлечь name, id и input из блока tool_use.
  2. Запустить фактический инструмент в вашей кодовой базе, соответствующий этому имени инструмента, передав входные данные инструмента.
  3. Продолжить беседу, отправив новое сообщение с 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:"},  // ❌ Text before 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?"}  // ✅ Text after 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": "15 degrees"
    }
  ]
}
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",
    }
  ]
}
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 Claude интегрирует инструменты непосредственно в структуру сообщений user и assistant.Сообщения содержат массивы блоков text, image, tool_use и tool_result. Сообщения user включают содержимое клиента и tool_result, а сообщения assistant содержат содержимое, сгенерированное AI, и 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-sonnet-4-5",
            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 продолжить свой ход
  • Измените при необходимости: Вы можете опционально изменить содержимое перед продолжением, если хотите прервать или перенаправить беседу
  • Сохраните состояние инструмента: Включите те же инструменты в запрос продолжения, чтобы сохранить функциональность

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

Встроенная обработка ошибок: Tool runner обеспечивает автоматическую обработку ошибок для большинства распространённых сценариев. Этот раздел охватывает ручную обработку ошибок для продвинутых случаев использования.
Существует несколько различных типов ошибок, которые могут возникнуть при использовании инструментов с 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 затем включит эту ошибку в свой ответ пользователю, например: “I’m sorry, I was unable to retrieve the current weather because the weather service API is not available. Please try again later.”
Если попытка 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 раза с исправлениями перед извинением перед пользователем.
Чтобы предотвратить отражение Claude о качестве возвращённых результатов поиска с помощью тегов <search_quality_reflection>, добавьте “Do not reflect on the quality of the returned search results in your response” в ваш запрос.
Когда серверные инструменты встречают ошибки (например, проблемы с сетью при веб-поиске), Claude прозрачно обрабатывает эти ошибки и пытается предоставить альтернативный ответ или объяснение пользователю. В отличие от клиентских инструментов, вам не нужно обрабатывать результаты is_error для серверных инструментов.Для веб-поиска в частности, возможные коды ошибок включают:
  • too_many_requests: Превышен лимит скорости
  • invalid_input: Неверный параметр поискового запроса
  • max_uses_exceeded: Превышено максимальное количество использований инструмента веб-поиска
  • query_too_long: Запрос превышает максимальную длину
  • unavailable: Произошла внутренняя ошибка
Если Claude не выполняет параллельные вызовы инструментов, когда ожидается, проверьте эти распространённые проблемы:1. Неправильное форматирование результатов инструментовНаиболее распространённая проблема — неправильное форматирование результатов инструментов в истории беседы. Это “учит” Claude избегать параллельных вызовов.В частности, для параллельного использования инструментов:
  • Неправильно: Отправка отдельных пользовательских сообщений для каждого результата инструмента
  • Правильно: Все результаты инструментов должны быть в одном пользовательском сообщении
// ❌ This reduces parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1]},
  {"role": "user", "content": [tool_result_2]}  // Separate message
]

// ✅ This maintains parallel tool use
[
  {"role": "assistant", "content": [tool_use_1, tool_use_2]},
  {"role": "user", "content": [tool_result_1, tool_result_2]}  // Single message
]
См. общие требования к форматированию выше для других правил форматирования.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: Менее вероятно использовать параллельные инструменты без явного запроса