---
title: Определение инструментов
url: https://platform.claude.com/docs/ru/agents-and-tools/tool-use/define-tools
description: Задавайте схемы инструментов, пишите эффективные описания и управляйте тем, когда Claude вызывает ваши инструменты.
---
## Предварительные требования
* Знакомство с [обзором использования инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/overview)
* Ключ API Claude и рабочая настройка SDK или cURL
Если вы используете Claude с использованием инструментов и размышлениями, см. раздел [Размышления](https://platform.claude.com/docs/ru/build-with-claude/thinking) для получения дополнительной информации.
## Указание клиентских инструментов
Клиентские инструменты («client tools») указываются в параметре верхнего уровня `tools` запроса к API. Клиентские инструменты со схемой Anthropic, такие как инструменты bash и текстового редактора, объявляются с помощью `type` с версией по дате; поля, которые принимает каждый инструмент, см. на странице соответствующего инструмента, ссылки на которые приведены в [Справочнике по инструментам](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-reference). Инструменты использования компьютера и использования браузера являются [клиентскими наборами инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-reference#client-toolsets): это одна запись без `name`, которая объявляет фиксированный набор входящих в неё инструментов. Определение пользовательского инструмента включает:
| Параметр | Описание |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Имя инструмента. Должно соответствовать регулярному выражению `^[a-zA-Z0-9_-]{1,128}$`. |
| `description` | Подробное текстовое описание того, что делает инструмент, когда его следует использовать и как он себя ведёт. |
| `input_schema` | Объект [JSON Schema](https://json-schema.org/), определяющий ожидаемые параметры инструмента. |
| `input_examples` | (Необязательно) Массив примеров входных объектов, помогающих Claude понять, как использовать инструмент. См. [Предоставление примеров использования инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/define-tools#providing-tool-use-examples). |
Полный набор необязательных свойств, доступных для любого отдельного определения инструмента, включая `cache_control`, `strict`, `defer_loading` и `allowed_callers`, см. в [Справочнике по инструментам](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-reference#tool-definition-properties). Запись клиентского набора инструментов принимает `cache_control` и `allowed_callers` на уровне записи и задаёт `defer_loading` для каждого входящего инструмента; см. [Клиентские наборы инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-reference#client-toolsets).
```json 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".
### Системная подсказка для использования инструментов
Когда вы вызываете Claude API с параметром `tools`, API формирует специальную «system prompt» (системную подсказку) из определений инструментов, конфигурации инструментов и любой указанной пользователем системной подсказки. Сформированная подсказка предназначена для того, чтобы проинструктировать модель использовать указанные инструменты и предоставить необходимый контекст для правильной работы инструмента:
```text wrap
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 предложений, а если инструмент сложный — больше.
* **Отдавайте приоритет описаниям, но рассмотрите использование `input_examples` для сложных инструментов.** Чёткие описания важнее всего, но для инструментов со сложными входными данными, вложенными объектами или параметрами, чувствительными к формату, вы можете использовать поле `input_examples`, чтобы предоставить примеры, проверенные по схеме. Подробности см. в разделе [Предоставление примеров использования инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/define-tools#providing-tool-use-examples).
* **Объединяйте связанные операции в меньшее количество инструментов.** Вместо создания отдельного инструмента для каждого действия (`create_pr`, `review_pr`, `merge_pr`) сгруппируйте их в один инструмент с параметром `action`. Меньшее количество более функциональных инструментов снижает неоднозначность выбора и упрощает для Claude навигацию по вашему набору инструментов.
* **Используйте осмысленные пространства имён в именах инструментов.** Когда ваши инструменты охватывают несколько сервисов или ресурсов, добавляйте к именам префикс сервиса (например, `github_list_prs`, `slack_send_message`). Это делает выбор инструмента однозначным по мере роста вашей библиотеки и особенно важно при использовании [поиска инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-search-tool).
* **Проектируйте ответы инструментов так, чтобы они возвращали только высокоинформативные данные.** Возвращайте семантические, стабильные идентификаторы (например, слаги или UUID), а не непрозрачные внутренние ссылки, и включайте только те поля, которые нужны Claude для рассуждения о следующем шаге. Раздутые ответы расходуют контекст и затрудняют для Claude извлечение того, что важно.
* **Просите объяснение, а не рассуждение.** Если параметр спрашивает Claude, почему он выполняет вызов, просите краткое объяснение или подтверждающие данные. Параметр, запрашивающий размышления модели или пошаговое рассуждение, может привести к отказу `reasoning_extraction`. См. [Храните рассуждения в блоках размышлений](https://platform.claude.com/docs/ru/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).
```json 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 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 много открытых вопросов о поведении и использовании инструмента.
Более подробные рекомендации по проектированию инструментов (объединение, именование и формирование ответов) см. в статье [Writing tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents).
## Предоставление примеров использования инструментов
Вы можете предоставить конкретные примеры допустимых входных данных инструментов, чтобы помочь Claude понять, как использовать ваши инструменты более эффективно. Это особенно полезно для сложных инструментов с вложенными объектами, необязательными параметрами или входными данными, чувствительными к формату.
### Базовое использование
Добавьте необязательное поле `input_examples` в определение вашего инструмента с массивом примеров входных объектов. Каждый пример должен быть допустимым согласно `input_schema` инструмента:
```bash cURL
curl -sS 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-5-5",
"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"
}
},
"required": ["location"]
},
"input_examples": [
{"location": "San Francisco, CA", "unit": "fahrenheit"},
{"location": "Tokyo, Japan", "unit": "celsius"},
{"location": "New York, NY"}
]
}
],
"messages": [
{"role": "user", "content": "What is the weather like in San Francisco?"}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
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
required: [location]
input_examples:
- location: San Francisco, CA
unit: fahrenheit
- location: Tokyo, Japan
unit: celsius
- location: New York, NY # 'unit' is optional
messages:
- role: user
content: What's the weather like in San Francisco?
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
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",
},
},
"required": ["location"],
},
"input_examples": [
{"location": "San Francisco, CA", "unit": "fahrenheit"},
{"location": "Tokyo, Japan", "unit": "celsius"},
{
"location": "New York, NY" # 'unit' is optional
},
],
}
],
messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)
print(response)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
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"
}
},
required: ["location"]
},
input_examples: [
{
location: "San Francisco, CA",
unit: "fahrenheit"
},
{
location: "Tokyo, Japan",
unit: "celsius"
},
{
location: "New York, NY"
// Показывает, что 'unit' необязателен
}
]
}
],
messages: [{ role: "user", content: "What's the weather like in San Francisco?" }]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Tools = [
new ToolUnion(new Tool()
{
Name = "get_weather",
Description = "Get the current weather in a given location",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }),
["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" }, description = "The unit of temperature" }),
},
Required = ["location"],
},
InputExamples =
[
new Dictionary()
{
{ "location", JsonSerializer.SerializeToElement("San Francisco, CA") },
{ "unit", JsonSerializer.SerializeToElement("fahrenheit") },
},
new Dictionary()
{
{ "location", JsonSerializer.SerializeToElement("Tokyo, Japan") },
{ "unit", JsonSerializer.SerializeToElement("celsius") },
},
new Dictionary()
{
{ "location", JsonSerializer.SerializeToElement("New York, NY") },
},
],
}),
],
Messages = [
new() { Role = Role.User, Content = "What's the weather like in San Francisco?" }
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "get_weather",
Description: anthropic.String("Get the current weather in a given location"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"location": map[string]any{
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
},
"unit": map[string]any{
"type": "string",
"enum": []string{"celsius", "fahrenheit"},
"description": "The unit of temperature",
},
},
Required: []string{"location"},
},
InputExamples: []map[string]any{
{
"location": "San Francisco, CA",
"unit": "fahrenheit",
},
{
"location": "Tokyo, Japan",
"unit": "celsius",
},
{
"location": "New York, NY",
// Показывает, что 'unit' необязателен
},
},
}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather like in San Francisco?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.Tool.InputSchema;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024L)
.addTool(Tool.builder()
.name("get_weather")
.description("Get the current weather in a given location")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"location", Map.of(
"type", "string",
"description", "The city and state, e.g. San Francisco, CA"
),
"unit", Map.of(
"type", "string",
"enum", List.of("celsius", "fahrenheit"),
"description", "The unit of temperature"
)
)))
.required(List.of("location"))
.build())
.putAdditionalProperty("input_examples", JsonValue.from(List.of(
Map.of(
"location", "San Francisco, CA",
"unit", "fahrenheit"
),
Map.of(
"location", "Tokyo, Japan",
"unit", "celsius"
),
Map.of(
"location", "New York, NY"
)
)))
.build())
.addUserMessage("What's the weather like in San Francisco?")
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "What's the weather like in San Francisco?"]
],
model: 'claude-opus-5-5',
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'
]
],
'required' => ['location']
],
'input_examples' => [
[
'location' => 'San Francisco, CA',
'unit' => 'fahrenheit'
],
[
'location' => 'Tokyo, Japan',
'unit' => 'celsius'
],
[
'location' => 'New York, NY'
]
]
]
],
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5-5",
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"
}
},
required: ["location"]
},
input_examples: [
{
location: "San Francisco, CA",
unit: "fahrenheit"
},
{
location: "Tokyo, Japan",
unit: "celsius"
},
{
location: "New York, NY"
}
]
}
],
messages: [
{ role: "user", content: "What's the weather like in San Francisco?" }
]
)
puts message
```
Примеры включаются в подсказку вместе со схемой вашего инструмента, показывая Claude конкретные шаблоны правильно сформированных вызовов инструментов. Это помогает Claude понять, когда включать необязательные параметры, какие форматы использовать и как структурировать сложные входные данные.
### Требования и ограничения
* **Проверка по схеме** — каждый пример должен быть допустимым согласно `input_schema` инструмента. Недопустимые примеры возвращают ошибку 400
* **Не поддерживается для серверных инструментов и клиентских наборов инструментов** — примеры входных данных работают с пользовательскими инструментами и клиентскими инструментами со схемой Anthropic, кроме наборов инструментов [использования компьютера](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/computer-use-tool) и [использования браузера](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/browser-use-tool), но не с серверными инструментами, такими как веб-поиск или выполнение кода
* **Стоимость в токенах** — примеры увеличивают количество токенов подсказки: \~20–50 токенов для простых примеров, \~100–200 токенов для сложных вложенных объектов
## Управление выводом Claude
### Принудительное использование инструментов
В некоторых случаях вы можете захотеть, чтобы Claude использовал определённый инструмент для ответа на вопрос пользователя, даже если в противном случае Claude ответил бы напрямую, не вызывая инструмент. Вы можете сделать это, указав инструмент в поле `tool_choice` запроса.
Не каждая модель и настройка поддерживают принудительное использование инструментов. Там, где это не поддерживается, `tool_choice: {"type": "any"}` и `tool_choice: {"type": "tool", "name": "..."}` завершаются ошибкой, тогда как `tool_choice: {"type": "auto"}` (значение по умолчанию) и `tool_choice: {"type": "none"}` по-прежнему работают:
| Модель или настройка | Ограничение | Что использовать вместо этого |
| ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ручные [расширенные размышления](https://platform.claude.com/docs/ru/build-with-claude/extended-thinking) (`thinking: {type: "enabled"}`) | `any` и `tool` не поддерживаются и приводят к ошибке | `auto` или `none`. [Адаптивные размышления](https://platform.claude.com/docs/ru/build-with-claude/thinking) сами по себе не блокируют принудительное использование инструментов (модели с размышлениями, включёнными по умолчанию, такие как Claude Opus 5 и Claude Haiku 5.5, принимают его, но принудительный вызов пропускает размышления: ответ начинается с вызова инструмента и не содержит блока `thinking`); модели из следующей строки отклоняют принудительное использование инструментов независимо от настроек размышлений |
| Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 и [Claude Mythos 5.1](https://platform.claude.com/docs/ru/models/mythos-5-1/overview) | `any` и `tool` возвращают [ошибку 400](https://platform.claude.com/docs/ru/api/errors#forced-tool-use-not-supported) | `auto` со [строгим использованием инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/strict-tool-use), чтобы гарантировать соответствие входных данных инструментов схеме, или [структурированные выходные данные](https://platform.claude.com/docs/ru/build-with-claude/structured-outputs), когда вам нужен ответ в фиксированной форме JSON. Подсказки по-прежнему влияют на то, какой инструмент выбирает `auto`. `none` также поддерживается |
На моделях, которые это поддерживают, выделенные строки — единственное отличие от стандартного запроса с использованием инструментов:
```bash cURL
curl -sS 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-5",
"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"]
}
}
],
"tool_choice": {"type": "tool", "name": "get_weather"},
"messages": [
{"role": "user", "content": "What is the weather like in San Francisco?"}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5
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]
tool_choice:
type: tool
name: get_weather
messages:
- role: user
content: What's the weather like in San Francisco?
YAML
```
```python Python
client = anthropic.Anthropic()
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"],
},
}
]
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=tools,
tool_choice={"type": "tool", "name": "get_weather"},
messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)
print(response)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5",
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"]
}
}
],
tool_choice: { type: "tool", name: "get_weather" },
messages: [{ role: "user", content: "What's the weather like in San Francisco?" }]
});
console.log(response);
```
```csharp C#
AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Tools = [
new ToolUnion(new Tool()
{
Name = "get_weather",
Description = "Get the current weather in a given location",
InputSchema = new InputSchema()
{
Properties = new Dictionary
{
["location"] = JsonSerializer.SerializeToElement(new { type = "string", description = "The city and state, e.g. San Francisco, CA" }),
},
Required = ["location"],
},
}),
],
ToolChoice = new ToolChoiceTool { Name = "get_weather" },
Messages = [
new() { Role = Role.User, Content = "What's the weather like in San Francisco?" }
]
};
var message = await client.Messages.Create(parameters);
Console.WriteLine(message);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Tools: []anthropic.ToolUnionParam{
{OfTool: &anthropic.ToolParam{
Name: "get_weather",
Description: anthropic.String("Get the current weather in a given location"),
InputSchema: anthropic.ToolInputSchemaParam{
Properties: map[string]any{
"location": map[string]any{
"type": "string",
"description": "The city and state, e.g. San Francisco, CA",
},
},
Required: []string{"location"},
},
}},
},
ToolChoice: anthropic.ToolChoiceUnionParam{OfTool: &anthropic.ToolChoiceToolParam{Name: "get_weather"}},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather like in San Francisco?")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
import com.anthropic.models.messages.Tool;
import com.anthropic.models.messages.Tool.InputSchema;
import com.anthropic.models.messages.ToolChoice;
import com.anthropic.models.messages.ToolChoiceTool;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(1024L)
.addTool(Tool.builder()
.name("get_weather")
.description("Get the current weather in a given location")
.inputSchema(InputSchema.builder()
.properties(JsonValue.from(Map.of(
"location", Map.of(
"type", "string",
"description", "The city and state, e.g. San Francisco, CA"
)
)))
.required(List.of("location"))
.build())
.build())
.toolChoice(ToolChoice.ofTool(ToolChoiceTool.builder()
.name("get_weather")
.build()))
.addUserMessage("What's the weather like in San Francisco?")
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$message = $client->messages->create(
maxTokens: 1024,
messages: [
['role' => 'user', 'content' => "What's the weather like in San Francisco?"]
],
model: 'claude-opus-5',
toolChoice: ['type' => 'tool', 'name' => 'get_weather'],
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']
]
]
],
);
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-5",
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"]
}
}
],
tool_choice: { type: "tool", name: "get_weather" },
messages: [
{ role: "user", content: "What's the weather like in San Francisco?" }
]
)
puts message
```
При работе с параметром `tool_choice` есть четыре возможных варианта:
* `auto` позволяет Claude самостоятельно решать, вызывать ли какие-либо из предоставленных инструментов. Это значение по умолчанию, когда предоставлены `tools`.
* `any` сообщает Claude, что он должен использовать один из предоставленных инструментов, но не навязывает конкретный инструмент.
* `tool` заставляет Claude всегда использовать конкретный инструмент.
* `none` запрещает Claude использовать какие-либо инструменты. Это значение по умолчанию, когда `tools` не предоставлены.
При использовании [кэширования подсказок](https://platform.claude.com/docs/ru/build-with-claude/prompt-caching#what-invalidates-the-cache) изменения параметра `tool_choice` делают недействительными кэшированные блоки сообщений. Определения инструментов и системные подсказки остаются в кэше, но содержимое сообщений должно быть обработано заново.
Эта диаграмма иллюстрирует, как работает каждый вариант:
Обратите внимание, что когда `tool_choice` имеет значение `any` или `tool`, API предварительно заполняет сообщение ассистента, чтобы принудительно использовать инструмент. Это означает, что модели не будут выдавать ответ или объяснение на естественном языке перед блоками содержимого `tool_use`, даже если их явно об этом попросить.
Тестирование показало, что это не должно снижать производительность. Если вы хотите, чтобы модель предоставляла контекст или объяснения на естественном языке, при этом по-прежнему запрашивая использование моделью конкретного инструмента, вы можете использовать `{"type": "auto"}` для `tool_choice` (значение по умолчанию) и добавить явные инструкции в сообщение `user`. Например: `What's the weather like in London? Use the get_weather tool in your response.`
Принудительный вызов инструмента также пропускает размышления на каждой модели, которая принимает принудительное использование инструментов: ответ начинается с блока `tool_use` и не содержит блока `thinking`. Чтобы модель могла поразмышлять перед вызовом инструмента, используйте `auto` с инструкцией в подсказке таким же образом.
**Гарантированные вызовы инструментов со строгими инструментами**
На моделях, поддерживающих принудительное использование инструментов, сочетайте `tool_choice: {"type": "any"}` со [строгим использованием инструментов](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/strict-tool-use), чтобы гарантировать как вызов одного из ваших инструментов, так и строгое соответствие входных данных инструмента вашей схеме. Установите `strict: true` в определениях ваших инструментов, чтобы включить проверку по схеме.
### Ответы модели с инструментами
При использовании инструментов Claude часто комментирует то, что он делает, или естественным образом отвечает пользователю перед вызовом инструментов.
Например, на подсказку «What's the weather like in San Francisco right now, and what time is it there?» Claude может ответить так:
```json 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, и создаёт более диалоговое взаимодействие. Вы можете направлять стиль и содержание этих ответов с помощью ваших системных подсказок и предоставляя `` в ваших подсказках.
Важно отметить, что Claude может использовать различные формулировки и подходы при объяснении своих действий. Ваш код должен обрабатывать эти ответы как любой другой текст, сгенерированный ассистентом, и не полагаться на конкретные соглашения о форматировании.
## Следующие шаги
Разбирайте блоки tool\_use и форматируйте ответы tool\_result.
Позвольте SDK автоматически обрабатывать агентный цикл.
Каталог инструментов, предоставляемых Anthropic, и необязательных свойств.