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

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

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

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

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-20250514",
    "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 инструменты и запрос пользователя

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

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-20250514",
    "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-20250514",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>I need to call the get_weather function, and the user wants SF, which is likely San Francisco, CA.</thinking>"
    },
    {
      "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-20250514",
    "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": "<thinking>I need to use get_weather, and the user wants SF, which is likely San Francisco, CA.</thinking>"
                },
                {
                    "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-20250514",
  "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-20250514",
    "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 одновременно, особенно если они не зависят друг от друга. Вам нужно будет выполнить каждый инструмент и вернуть их результаты в отдельных блоках tool_result в рамках одного сообщения user.

Отсутствующая информация

Если запрос пользователя не содержит достаточно информации для заполнения всех обязательных параметров инструмента, 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-20250514",
    "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 с этим местоположением, чтобы получить окончательный ответ.

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

Роль	Содержание
Пользователь	Какая погода там, где я нахожусь?
Ассистент	<thinking>Чтобы ответить на этот вопрос, мне сначала нужно определить местоположение пользователя с помощью инструмента get_location. Затем я могу передать это местоположение инструменту get_weather, чтобы узнать текущую погоду там.</thinking>[Использование инструмента 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-20250514",
    "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	`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)	`auto`, `none` `any`, `tool`	346 tokens 313 tokens
Claude Sonnet 3.5 (June)	`auto`, `none` `any`, `tool`	294 tokens 261 tokens
Claude Haiku 3.5	`auto`, `none` `any`, `tool`	264 tokens 340 tokens
Claude Opus 3	`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 и использование инструментов могут извлекать структурированные данные из неструктурированного текста.

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

On this page

Как работает использование инструментов
Клиентские инструменты
Серверные инструменты
Примеры использования инструментов
Цены
Следующие шаги

Первые шаги

Изучить возможности

Модели и цены

Узнать о Claude

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

Компоненты агента

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

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

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

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

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

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

Цены

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

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

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

Экстрактор JSON

Первые шаги

Изучить возможности

Модели и цены

Узнать о Claude

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

Компоненты агента

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

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

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

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

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

​Цены

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

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

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

Экстрактор JSON

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

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

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

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

Цены

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