Урок 1. Зачем модели инструменты и как это устроено

Модель хорошо работает с текстом — и плохо со всем остальным. Она не считает надёжно, не знает сегодняшний курс доллара, не видит вашу базу данных и не может отправить письмо. Tool use (он же function calling, «вызов функций») — механизм, который закрывает ровно эту дыру: мы даём Claude набор инструментов, которые он может попросить нас вызвать.

Что такое tool use

Tool use — это способность расширить возможности Claude, описав ему внешние инструменты (функции), которые он может вызвать в любой момент. Мы пишем код, который умеет делать что-то конкретное: сходить в API, посчитать, достать строку из базы. А Claude решает, когда этот код нужен, и просит его выполнить.

Самое важное, что стоит понять сразу: Claude сам код не выполняет. Он не запускает ваши функции, не ходит в интернет и не имеет никаких «встроенных серверных инструментов». Все инструменты вы явно передаёте в каждом запросе к API — с именами, описаниями и схемой входных данных. И вы же их выполняете у себя и возвращаете результат. Это неудобно на первый взгляд, но даёт полный контроль: ничего не произойдёт без вашего кода.

Зачем это нужно

• Расширить возможности модели. Всё, чего Claude не умеет сам, можно вынести в инструмент — и он начнёт это уметь.
• Подключиться к своим системам. Инструмент может дёрнуть ваш бэкенд, достать данные из базы, вызвать внутренний API. Claude работает поверх вашей существующей инфраструктуры, а не вместо неё.
• Автоматизировать сложные задачи. Многошаговые процессы упаковываются в инструменты, и модель вызывает нужный в нужный момент — исходя из запроса пользователя.
• Улучшить опыт пользователя. Человек пишет на обычном языке, а получает точный ответ на живых данных или сразу выполненное действие.
• Масштабировать и настраивать. Требования меняются — вы добавляете новый инструмент или правите старый, не переделывая продукт целиком.

Где применяют

Общие сценарии, которые встречаются чаще всего:

• Получение информации — погода, котировки, новости, данные из вашей базы или стороннего API.
• Вычисления — финансовые расчёты, научные и статистические операции, всё, где нужна точность, а не правдоподобие.
• Работа с данными — форматирование, извлечение, конвертация из формата в формат.
• Взаимодействие с внешними системами — отправить письмо, послать уведомление, управлять устройством.
• Генерация контента — картинки, графики, документы по шаблону.

Более конкретные примеры из практики: интеграция с CRM, ERP и ITSM; финансовая аналитика и отчётность; работа с электронными медкартами и медицинскими базами знаний; персональное обучение и генерация учебных материалов; анализ юридических документов; автоматизация поддержки поверх базы знаний и тикет-системы; продажи и маркетинг; помощь разработчику в связке с IDE и системой контроля версий; исследования и патентный анализ; создание и оптимизация контента для сайтов и соцсетей.

Как устроен цикл

Цикл всегда один и тот же, четыре шага:

1. Вы даёте Claude инструменты и промпт пользователя (запрос к API). Описываете набор инструментов: имя, описание, схема входных данных. И передаёте вопрос, для ответа на который эти инструменты могут понадобиться — например: «Сколько акций General Motors я куплю на $500?»
2. Claude просит вызвать инструмент (ответ API). Модель оценивает вопрос и решает, поможет ли какой-то из инструментов. Если да — выбирает, какой именно и с какими аргументами, и возвращает корректно оформленный запрос на вызов. У такого ответа stop_reason равен tool_use: это сигнал «я хочу воспользоваться внешним инструментом».
3. Вы достаёте аргументы, запускаете код и возвращаете результат (запрос к API). На своей стороне вытаскиваете имя инструмента и входные данные, выполняете настоящую функцию, а результат отдаёте обратно — новым сообщением с ролью user, внутри которого лежит блок tool_result.
4. Claude формулирует ответ по результату (ответ API). Получив данные, модель собирает финальный ответ на исходный вопрос пользователя.

Шаги 3 и 4 необязательны. Иногда сам факт вызова — уже всё, что вам нужно от модели: она разобрала запрос на структурированные аргументы, а дальше вы работаете без неё. К этому вернёмся в одном из следующих уроков.

Обратите внимание на деталь, на которой все спотыкаются: результат инструмента возвращается ролью user, а не assistant. Формально это «реплика пользователя», хотя написал её ваш код.

Разбор сценария: цена акции

Представим, что мы строим чат про фондовый рынок: пользователь спрашивает Claude про акции и хочет видеть актуальные цены. Модель, конечно, не знает, что происходит на бирже прямо сейчас, — значит, нужен инструмент get_stock_price, который достаёт текущую цену по названию компании.

Шаг 0. Сначала пишем сам инструмент

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

def get_stock_price(company):
    # Запрашиваем у биржевого API текущую цену акции компании
    # Возвращаем словарь с информацией о текущей цене

Если функцию дописать и вызвать как get_stock_price("General Motors"), она вернёт что-то вроде:

{
  "symbol": "GM",
  "price": 43.09
}

Шаг 1. Описываем инструмент и делаем запрос

Модель не видит ваш код — она видит только описание. Нужно задать три вещи: имя, описание (по нему Claude поймёт, когда инструмент уместен) и схему входных данных.

tool_definition = {
    "name": "get_stock_price",
    "description": "Возвращает текущую цену акции указанной компании",
    "input_schema": {
        "type": "object",
        "properties": {
            "company": {
                "type": "string",
                "description": "Название компании, по которой нужны биржевые данные"
            }
        },
        "required": ["company"]
    }
}

Теперь передаём это описание в запрос вместе с вопросом пользователя — через параметр tools:

response = client.messages.create(
    model="claude-sonnet-5",
    messages=[{"role": "user",
               "content": "Сколько акций General Motors я куплю на $500?"}],
    max_tokens=500,
    tools=[tool_definition]          # список доступных инструментов
)

Шаг 2. Claude просит вызвать инструмент

Claude читает вопрос и решает, что get_stock_price здесь поможет. В ответ приходит не текст, а запрос на вызов — упрощённо он выглядит так:

{
  "stop_reason": "tool_use",
  "tool_use": {
    "name": "get_stock_price",
    "input": {
      "company": "General Motors"
    }
  }
}

Ключевое поле — stop_reason со значением "tool_use". Именно по нему ваш код понимает: модель остановилась не потому, что договорила, а потому что ждёт данных. Точную структуру ответа разберём в следующем уроке.

Шаг 3. Выполняем и возвращаем результат

Вытаскиваем из ответа имя инструмента (get_stock_price) и аргумент (General Motors), вызываем настоящую функцию, получаем живые данные:

{
  "symbol": "GM",
  "price": 43.09
}

И продолжаем разговор: добавляем новое сообщение с ролью user, внутри которого лежит блок tool_result с этим результатом.

Шаг 4. Claude отвечает пользователю

Получив цену, модель встраивает её в ответ на исходный вопрос:

Заметьте: цену посчитал ваш код, а деление на 500 и человеческую формулировку сделала модель. Разделение труда ровно такое.

Упражнения

Упражнение 1.1 — Что вынести в инструмент

Вы делаете бота поддержки интернет-магазина. Он должен: (1) вежливо отвечать на вопрос «где мой заказ №12345», (2) объяснять условия возврата из текста политики, (3) сообщать актуальный остаток товара на складе. Что здесь требует инструмента, а что модель сделает сама?

Упражнение 1.2 — Опишите инструмент словами

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

tool_definition = {
    "name": "get_weather",
    "description": "Возвращает текущую погоду в указанном городе",
    "input_schema": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "Город, для которого нужна погода"
            },
            "units": {
                "type": "string",
                "description": "Единицы измерения температуры: celsius или fahrenheit"
            }
        },
        "required": ["city"]
    }
}

Что запомнить

• Tool use = вы описываете Claude внешние функции, он просит их вызвать. Модель код не выполняет никогда.
• Встроенных инструментов у Claude нет: всё, что ему доступно, вы передаёте сами в каждом запросе.
• Цикл: инструменты + промпт → ответ со stop_reason: "tool_use" → вы выполняете код → возвращаете tool_result ролью user → модель отвечает.
• Инструмент нужен там, где требуются свежие данные, точный расчёт или действие во внешней системе. Чисто языковые задачи модель решает и так.
• Шаги 3 и 4 необязательны — иногда достаточно самого запроса на вызов.