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

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

Изучите все, что вам нужно для освоения использования инструментов с Claude в рамках наших новых курсов! Пожалуйста, продолжайте делиться своими идеями и предложениями, используя эту форму.

Вот пример того, как предоставить инструменты Claude с помощью Messages API:

Shell

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "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"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in San Francisco?"
      }
    ]
  }'

---

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

Claude поддерживает два типа инструментов:

1. Клиентские инструменты: Инструменты, которые выполняются в ваших системах, включая:

   • Пользовательские инструменты, созданные и реализованные вами
   • Инструменты, определенные Anthropic, такие как использование компьютера и текстовый редактор, которые требуют клиентской реализации

2. Серверные инструменты: Инструменты, которые выполняются на серверах Anthropic, такие как инструменты веб-поиска и веб-извлечения. Эти инструменты должны быть указаны в API-запросе, но не требуют реализации с вашей стороны.

Инструменты, определенные Anthropic, используют версионированные типы (например, web_search_20250305, text_editor_20250124) для обеспечения совместимости между версиями моделей.

Клиентские инструменты

Интегрируйте клиентские инструменты с Claude в следующие шаги:

1. Предоставьте Claude инструменты и пользовательский запрос

   • Определите клиентские инструменты с именами, описаниями и схемами входных данных в вашем API-запросе.
   • Включите пользовательский запрос, который может потребовать эти инструменты, например, “Какая погода в Сан-Франциско?”
2. Claude решает использовать инструмент

   • Claude оценивает, могут ли какие-либо инструменты помочь с запросом пользователя.
   • Если да, Claude создает правильно отформатированный запрос на использование инструмента.
   • Для клиентских инструментов API-ответ имеет stop_reason равный tool_use, сигнализируя о намерении Claude.
3. Выполните инструмент и верните результаты

   • Извлеките имя инструмента и входные данные из запроса Claude
   • Выполните код инструмента в вашей системе
   • Верните результаты в новом сообщении user, содержащем блок контента tool_result
4. Claude использует результат инструмента для формулирования ответа

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

Примечание: Шаги 3 и 4 необязательны. Для некоторых рабочих процессов запрос Claude на использование инструмента (шаг 2) может быть всем, что вам нужно, без отправки результатов обратно Claude.

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

Серверные инструменты следуют другому рабочему процессу:

1. Предоставьте Claude инструменты и пользовательский запрос

   • Серверные инструменты, такие как веб-поиск и веб-извлечение, имеют свои собственные параметры.
   • Включите пользовательский запрос, который может потребовать эти инструменты, например, “Найдите последние новости об ИИ” или “Проанализируйте содержимое по этому URL.”
2. Claude выполняет серверный инструмент

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

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

---

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

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

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

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "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"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The unit of temperature, either \"celsius\" or \"fahrenheit\""
                }
            },
            "required": ["location"]
        }
    }],
    "messages": [{"role": "user", "content": "What is the weather like in San Francisco?"}]
}'

Claude вернет ответ, похожий на:

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "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"}
    }
  ]
}

Затем вам нужно будет выполнить функцию get_weather с предоставленными входными данными и вернуть результат в новом сообщении user:

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "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"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature, either \"celsius\" or \"fahrenheit\""
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What is the weather like in San Francisco?"
        },
        {
            "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"
                    }
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
                    "content": "15 degrees"
                }
            ]
        }
    ]
}'

Это вывед окончательный ответ Claude, включающий данные о погоде:

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-4-1-20250805",
  "stop_reason": "stop_sequence",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "The current weather in San Francisco is 15 degrees Celsius (59 degrees Fahrenheit). It's a cool day in the city by the bay!"
    }
  ]
}

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

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

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

Для исчерпывающих примеров, тестовых скриптов и лучших практик реализации параллельных вызовов инструментов см. раздел параллельного использования инструментов в нашем руководстве по реализации.

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

Вы можете предоставить Claude несколько инструментов на выбор в одном запросе. Вот пример с инструментами get_weather и get_time, а также пользовательским запросом, который запрашивает оба.

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "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"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
                }
            },
            "required": ["location"]
        }
    },
    {
        "name": "get_time",
        "description": "Get the current time in a given time zone",
        "input_schema": {
            "type": "object",
            "properties": {
                "timezone": {
                    "type": "string",
                    "description": "The IANA time zone name, e.g. America/Los_Angeles"
                }
            },
            "required": ["timezone"]
        }
    }],
    "messages": [{
        "role": "user",
        "content": "What is the weather like right now in New York? Also what time is it there?"
    }]
}'

В этом случае Claude может либо:

• Использовать инструменты последовательно (по одному за раз) — сначала вызвать get_weather, затем get_time после получения результата погоды
• Использовать параллельные вызовы инструментов — выводить несколько блоков tool_use в одном ответе, когда операции независимы

Когда Claude делает параллельные вызовы инструментов, вы должны вернуть все результаты инструментов в одном сообщении user, с каждым результатом в своем собственном блоке tool_result.

Недостающая информация

Если запрос пользователя не включает достаточно информации для заполнения всех обязательных параметров инструмента, Claude Opus гораздо более вероятно распознает, что параметр отсутствует, и попросит его. Claude Sonnet может спросить, особенно когда его просят подумать перед выводом запроса инструмента. Но он также может сделать все возможное, чтобы вывести разумное значение.

Например, используя инструмент get_weather выше, если вы спросите Claude “Какая погода?” без указания местоположения, Claude, особенно Claude Sonnet, может сделать предположение о входных данных инструментов:

JSON

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": {"location": "New York, NY", "unit": "fahrenheit"}
}

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

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

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

Вот пример использования инструмента get_location для получения местоположения пользователя, затем передачи этого местоположения инструменту get_weather:

Shell

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_location",
            "description": "Get the current user location based on their IP address. This tool has no parameters or arguments.",
            "input_schema": {
                "type": "object",
                "properties": {}
            }
        },
        {
            "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"]
            }
        }
    ],
    "messages": [{
        "role": "user",
        "content": "What is the weather like where I am?"
    }]
}'

В этом случае Claude сначала вызовет инструмент get_location, чтобы получить местоположение пользователя. После того, как вы вернете местоположение в tool_result, Claude затем вызовет get_weather с этим местоположением, чтобы получить окончательный ответ.

Полный разговор может выглядеть так:

Роль	Содержание
Пользователь	Какая погода там, где я нахожусь?
Ассистент	Сначала я найду ваше текущее местоположение, а затем проверю там погоду. [Использование инструмента для get_location]
Пользователь	[Результат инструмента для get_location с соответствующим id и результатом San Francisco, CA]
Ассистент	[Использование инструмента для get_weather со следующими входными данными]{ “location”: “San Francisco, CA”, “unit”: “fahrenheit” }
Пользователь	[Результат инструмента для get_weather с соответствующим id и результатом “59°F (15°C), в основном облачно”]
Ассистент	Основываясь на вашем текущем местоположении в Сан-Франциско, Калифорния, погода сейчас 59°F (15°C) и в основном облачно. Это довольно прохладный и пасмурный день в городе. Возможно, вы захотите взять легкую куртку, если собираетесь выходить на улицу.

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

1. Claude сначала понимает, что ему нужно местоположение пользователя, чтобы ответить на вопрос о погоде, поэтому он вызывает инструмент get_location.
2. Пользователь (т.е. клиентский код) выполняет фактическую функцию get_location и возвращает результат “San Francisco, CA” в блоке tool_result.
3. Теперь, зная местоположение, Claude переходит к вызову инструмента get_weather, передавая “San Francisco, CA” как параметр location (а также угаданный параметр unit, поскольку unit не является обязательным параметром).
4. Пользователь снова выполняет фактическую функцию get_weather с предоставленными аргументами и возвращает данные о погоде в другом блоке tool_result.
5. Наконец, Claude включает данные о погоде в естественный языковой ответ на исходный вопрос.

Цепочка рассуждений при использовании инструментов

По умолчанию Claude Opus получает запрос подумать, прежде чем отвечать на запрос использования инструмента, чтобы лучше определить, необходим ли инструмент, какой инструмент использовать и подходящие параметры. Claude Sonnet и Claude Haiku получают запрос попытаться использовать инструменты как можно больше и более вероятно вызовут ненужный инструмент или выведут недостающие параметры. Чтобы побудить Sonnet или Haiku лучше оценить пользовательский запрос перед вызовом инструментов, можно использовать следующий запрос:

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

Ответьте на запрос пользователя, используя соответствующие инструменты (если они доступны). Перед вызовом инструмента проведите анализ. Сначала подумайте, какой из предоставленных инструментов является соответствующим инструментом для ответа на запрос пользователя. Во-вторых, пройдите через каждый из обязательных параметров соответствующего инструмента и определите, предоставил ли пользователь напрямую или дал достаточно информации для вывода значения. При принятии решения о том, можно ли вывести параметр, внимательно рассмотрите весь контекст, чтобы увидеть, поддерживает ли он конкретное значение. Если все обязательные параметры присутствуют или могут быть разумно выведены, продолжайте с вызовом инструмента. НО, если одно из значений для обязательного параметра отсутствует, НЕ вызывайте функцию (даже не с заполнителями для отсутствующих параметров) и вместо этого попросите пользователя предоставить отсутствующие параметры. НЕ просите больше информации о необязательных параметрах, если она не предоставлена.

Режим JSON

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

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

• Обычно вы хотите предоставить один инструмент
• Вы должны установить tool_choice (см. Принуждение к использованию инструмента), чтобы проинструктировать модель явно использовать этот инструмент
• Помните, что модель передаст input инструменту, поэтому имя инструмента и описание должны быть с точки зрения модели.

Следующий пример использует инструмент record_summary для описания изображения в определенном формате.

Shell

#!/bin/bash
IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.anthropic.com/v1/messages \
     --header "content-type: application/json" \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --data \
'{
    "model": "claude-opus-4-1-20250805",
    "max_tokens": 1024,
    "tools": [{
        "name": "record_summary",
        "description": "Record summary of an image using well-structured JSON.",
        "input_schema": {
            "type": "object",
            "properties": {
                "key_colors": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
"r": { "type": "number", "description": "red value [0.0, 1.0]" },
"g": { "type": "number", "description": "green value [0.0, 1.0]" },
"b": { "type": "number", "description": "blue value [0.0, 1.0]" },
"name": { "type": "string", "description": "Human-readable color name in snake_case, e.g. \"olive_green\" or \"turquoise\"" }
                        },
                        "required": [ "r", "g", "b", "name" ]
                    },
                    "description": "Key colors in the image. Limit to less than four."
                },
                "description": {
                    "type": "string",
                    "description": "Image description. One to two sentences max."
                },
                "estimated_year": {
                    "type": "integer",
                    "description": "Estimated year that the image was taken, if it is a photo. Only set this if the image appears to be non-fictional. Rough estimates are okay!"
                }
            },
            "required": [ "key_colors", "description" ]
        }
    }],
    "tool_choice": {"type": "tool", "name": "record_summary"},
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "Describe this image."}
        ]}
    ]
}'

---

Ценообразование

Tool use requests are priced based on:

1. The total number of input tokens sent to the model (including in the tools parameter)
2. The number of output tokens generated
3. For server-side tools, additional usage-based pricing (e.g., web search charges per search performed)

Client-side tools are priced the same as any other Claude API request, while server-side tools may incur additional charges based on their specific usage.

The additional tokens from tool use come from:

• The tools parameter in API requests (tool names, descriptions, and schemas)
• tool_use content blocks in API requests and responses
• tool_result content blocks in API requests

When you use tools, we also automatically include a special system prompt for the model which enables tool use. The number of tool use tokens required for each model are listed below (excluding the additional tokens listed above). Note that the table assumes at least 1 tool is provided. If no tools are provided, then a tool choice of none uses 0 additional system prompt tokens.

Model	Tool choice	Tool use system prompt token count
Claude Opus 4.1	auto, none any, tool	346 tokens 313 tokens
Claude Opus 4	auto, none any, tool	346 tokens 313 tokens
Claude Sonnet 4	auto, none any, tool	346 tokens 313 tokens
Claude Sonnet 3.7	auto, none any, tool	346 tokens 313 tokens
Claude Sonnet 3.5 (Oct) (deprecated)	auto, none any, tool	346 tokens 313 tokens
Claude Sonnet 3.5 (June) (deprecated)	auto, none any, tool	294 tokens 261 tokens
Claude Haiku 3.5	auto, none any, tool	264 tokens 340 tokens
Claude Opus 3 (deprecated)	auto, none any, tool	530 tokens 281 tokens
Claude Sonnet 3	auto, none any, tool	159 tokens 235 tokens
Claude Haiku 3	auto, none any, tool	264 tokens 340 tokens

These token counts are added to your normal input and output tokens to calculate the total cost of a request.

Обратитесь к нашей таблице обзора моделей для текущих цен по моделям.

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

---

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

Изучите наш репозиторий готовых к реализации примеров кода использования инструментов в наших кулинарных книгах:

Инструмент калькулятора

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

Агент службы поддержки клиентов

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

Экстрактор JSON

Посмотрите, как Claude и использование инструментов могут извлекать структурированные данные из неструктурированного текста.