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

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

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

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

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 поддерживает два типа инструментов:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Claude выполняет серверный инструмент

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

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

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

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

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

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

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:

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 несколько инструментов на выбор в одном запросе. Вот пример с инструментами get_weather и get_time, а также пользовательским запросом, который запрашивает оба.

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:

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

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

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

Режим JSON

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

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

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

#!/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:

The total number of input tokens sent to the model (including in the tools parameter)
The number of output tokens generated
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 и использование инструментов могут извлекать структурированные данные из неструктурированного текста.

Первые шаги

Модели и цены

Узнать о Claude

Возможности

Инструменты

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Экстрактор JSON

Первые шаги

Модели и цены

Узнать о Claude

Возможности

Инструменты

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Экстрактор JSON

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

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

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

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

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

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