Tool use — это мост между Claude и остальным вашим стеком. Сделаете схемы правильно — получите надёжного агента, который бронирует рейсы, ходит в базу и водит браузер. Сделаете плохо — и модель уверенно вызовет get_weather с location: "место, которое упомянул пользователь". В 2026 году, с Sonnet 4.5 и Opus 4.5, которые умеют параллельные вызовы, computer use и всё строже соблюдают JSON, разрыв между «демо» и «продакшеном» почти полностью определяется тем, насколько хорошо написаны определения инструментов.
Это практический гайд, который мы хотели бы иметь, когда сами начинали строить агентов на Claude.
Анатомия определения инструмента
У каждого инструмента, который вы даёте Claude, есть ровно три поля, которые имеют значение:
{
"name": "get_weather",
"description": "Получить текущую погоду и прогноз на 24 часа для конкретного города. Используй, когда пользователь спрашивает о температуре, дожде, снеге или погодных условиях. Не используй для исторической погоды (до сегодня) — для этого есть get_historical_weather.",
"input_schema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Название города на английском, например 'San Francisco', 'Tokyo'. Без страны."
},
"units": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Единицы температуры. По умолчанию celsius, кроме случаев когда пользователь в США."
}
},
"required": ["city"]
}
}
Три вещи в порядке приоритета:
description— самая важная переменная точности выбора инструмента. Это то, что Claude читает, чтобы решить, вызывать ли ваш инструмент вообще и подходит ли он под запрос. Думайте о нём как о docstring для джуниора, который никогда не видел этот код.input_schema— JSON Schema аргументов. Активно используйтеenum. Пишитеdescriptionдля каждого свойства. Честно отмечайтеrequired.name— нижний регистр, snake_case, начинается с глагола (get_,create_,search_).
Главная ошибка новичков — относиться к description как к подписи. Это не подпись. Это мини-промпт. Расскажите Claude, когда использовать инструмент, когда не использовать, какие у него побочные эффекты и что значат входные параметры.
Параллельные вызовы в Sonnet 4.5+
Старые версии Claude выдавали один блок tool_use за ход ассистента. Sonnet 4.5 и Opus 4.5 могут вернуть несколько блоков tool_use в одном ответе, если вызовы независимы. Это важно, потому что в UX агента доминирует задержка round-trip.
Если пользователь спрашивает «какая погода в Токио и Париже и что у меня в календаре на завтра», интеграция образца 2025 года сделает три последовательных хода. Интеграция 2026 года получит три блока tool_use в одном ответе, выполнит их параллельно у себя и вернёт три tool_result в следующем сообщении. Один round-trip вместо трёх.
Ничего специального включать не нужно — просто будьте готовы получить массив вызовов и диспатчить их конкурентно.
Рабочий пример: погода + база данных
Минимальный, но реалистичный цикл агента через шлюз Claudexia, который нативно говорит на Anthropic Messages API:
import anthropic
import json
client = anthropic.Anthropic(
base_url="https://api.claudexia.tech/v1",
api_key="cxa-..."
)
tools = [
{
"name": "get_weather",
"description": "Текущая погода для города. Используй для вопросов 'какая погода'.",
"input_schema": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "Название города на английском"},
"units": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["city"]
}
},
{
"name": "query_orders",
"description": "Поиск в базе заказов по email клиента или ID заказа. Возвращает до 20 последних заказов.",
"input_schema": {
"type": "object",
"properties": {
"email": {"type": "string", "format": "email"},
"order_id": {"type": "string", "description": "ID заказа вида 'ORD-12345'"}
}
}
}
]
def execute_tool(name, args):
if name == "get_weather":
return {"city": args["city"], "temp_c": 14, "condition": "cloudy"}
if name == "query_orders":
return {"orders": [{"id": "ORD-12345", "total": 89.50, "status": "shipped"}]}
return {"error": f"неизвестный инструмент: {name}"}
messages = [{"role": "user", "content": "Погода в Токио и найди заказы по jane@example.com"}]
while True:
response = client.messages.create(
model="claude-sonnet-4.5",
max_tokens=2048,
tools=tools,
messages=messages
)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
break
tool_results = []
for block in response.content:
if block.type == "tool_use":
result = execute_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(result)
})
messages.append({"role": "user", "content": tool_results})
print(response.content[-1].text)
Обратите внимание на цикл: пока ответ говорит stop_reason == "tool_use", выполняем все блоки инструментов, добавляем все результаты одним сообщением user и вызываем снова. Это и есть весь паттерн оркестрации.
Обработка ошибок: расскажите Claude, что пошло не так
Самый большой выигрыш в надёжности — относиться к ошибкам инструментов как к данным, а не как к исключениям. Когда инструмент падает (плохой ввод, API недоступен, rate limit), верните ошибку внутри tool_result и дайте Claude отреагировать:
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"is_error": True,
"content": "Таймаут БД через 5 секунд. Попробуй с более узким фильтром или меньшим числом полей."
})
Claude прочитает это, часто перепопробует с поправленными аргументами или эскалирует пользователю с понятным объяснением. Один этот паттерн заменяет огромное количество хрупких try/except, которые иначе пришлось бы оборачивать вокруг модели.
tool_choice: auto, any, tool, none
Параметр tool_choice управляет тем, насколько настойчиво Claude вызывает инструменты:
{"type": "auto"}— по умолчанию. Claude сам решает, вызвать инструмент или ответить текстом.{"type": "any"}— Claude обязан вызвать какой-то инструмент, но выбирает сам.{"type": "tool", "name": "get_weather"}— принудительный вызов конкретного инструмента. Полезно для структурированной экстракции: определите инструментrecord_user_intentс точной нужной схемой, форсируйте вызов и получите гарантированный JSON.{"type": "none"}— отключить вызовы инструментов для этого хода, даже если они определены.
Принудительный tool_choice — самый чистый способ получить надёжный структурированный вывод от Claude в 2026 году. Забудьте про танцы с JSON-mode: определили инструмент, форсировали, распарсили block.input.
Computer use: когда текстовых инструментов мало
Sonnet 4.5+ поддерживает computer use — модель может делать скриншоты, двигать мышь, печатать и кликать в виртуальном рабочем столе. Подключается через специальный инструмент computer_20250124 плюс bash и text_editor. Claude возвращает действия вида {"action": "screenshot"} или {"action": "click", "coordinate": [512, 384]}, ваш harness их выполняет и присылает новый скриншот.
Используйте computer use, когда:
- У системы, которой надо управлять, нет API (легаси админки, порталы вендоров).
- Задача действительно визуальная (проверка вёрстки, чтение графика в PDF).
- Нужно QA собственного продукта end-to-end.
Не используйте, когда есть нормальный API. Computer use медленнее, менее надёжен и дороже на задачу, чем function calling против правильного бэкенда.
Anthropic native против OpenAI-совместимой формы
Claudexia отдаёт оба эндпоинта. Формы отличаются заметно: у Anthropic — content-блоки tool_use/tool_result; у OpenAI — tool_calls с function.name и function.arguments в виде JSON-строки.
Если строите с нуля, берите форму Anthropic — она структурирована, эргономика параллельных вызовов лучше, и вы избегаете «строкотипизированных» аргументов. Если переносите готовую кодобазу на OpenAI-форме, совместимый эндпоинт https://api.claudexia.tech/v1/chat/completions позволяет сменить модель без переписывания слоя инструментов; на нативный шейп переедете позже.
Отладка вызовов инструментов
Когда агент сходит с рельсов, три вещи дают 90% сигнала:
- Логируйте каждый
tool_use_idвместе с input и result. Несовпадения ID — самая частая причина тихих сломов. - Логируйте
stop_reasonдля каждого хода. Если видитеend_turnтам, где ждалиtool_use— описание непонятное илиtool_choiceневерный. - Реплейте весь массив сообщений через API после сбоя. На низкой температуре Claude достаточно детерминирован, чтобы плохой вызов обычно воспроизводился.
Маленький дашборд, показывающий таймлайн сообщений, вызовы инструментов и результаты рядом — окупится за неделю.
Итог
Надёжные агенты на Claude в 2026 году получаются из двух привычек, повторяемых из раза в раз:
- Богатые описания у каждого инструмента и каждого параметра. Относитесь к полю description как к промпту, а не к подписи. Расскажите Claude, когда инструмент использовать не надо, что значат входы и что приходит в ответ.
- Маленькие, сфокусированные инструменты. Пять инструментов, каждый из которых делает одну вещь, всегда лучше одного мега-инструмента с двенадцатью опциональными параметрами. Claude лучше выбирает, схемы проще, ошибки понятнее.
Параллельные вызовы, computer use и принудительный tool_choice — мощные штуки, но они усиливают то, что уже заложено в дизайне инструментов. Потратьте час на описание. Это самый высоколеверажный час во всём стеке агента.
Про стоимость нагрузок с большим количеством инструментов — см. наш разбор цен Claude API.