Разработка с Claude API

Функции-инструменты (Tool Functions): Расширяем возможности Claude

При создании интеллектуальных приложений на базе больших языковых моделей (LLM), таких как Claude, часто возникает необходимость предоставить ИИ доступ к актуальной информации в реальном времени или возможность выполнять определенные действия во внешних системах. Сама по себе LLM обладает знаниями, полученными в процессе обучения, но не может, например, узнать текущую погоду, отправить электронное письмо или забронировать билет. Именно здесь на помощь приходят функции-инструменты (Tool Functions) – мощный механизм, позволяющий Claude взаимодействовать с внешним миром.

Функции-инструменты — это обычные функции на языке Python (или любом другом языке, который вы используете для своего бэкенда), которые Claude может "вызывать", когда ему требуется дополнительная информация для помощи пользователю или когда необходимо выполнить какое-либо действие. Представьте, что Claude — это мозг, а функции-инструменты — это его руки и глаза, позволяющие ему видеть мир и действовать в нем.

Что такое функции-инструменты и как они работают?

По своей сути, функция-инструмент — это обычная функция, которую вы пишете в своем коде. Например, если пользователь спрашивает: "Какое сейчас время в Нью-Йорке?", Claude понимает, что для ответа ему нужна актуальная информация, которой у него нет. Вместо того чтобы пытаться угадать, Claude генерирует "запрос на использование инструмента" (tool use request), который описывает, какую функцию он хотел бы вызвать (например, get_current_datetime) и с какими параметрами (например, location="New York").

Ваше приложение, выступающее в роли оркестратора, перехватывает этот запрос от Claude, выполняет соответствующую Python-функцию (например, get_current_datetime("America/New_York")), получает результат (например, "15:30:25") и передает его обратно Claude. Получив эту информацию, Claude может сформулировать точный и полезный ответ для пользователя: "Сейчас в Нью-Йорке 15:30:25".

Этот механизм позволяет Claude:

• Получать данные в реальном времени (текущая дата/время, погода, курсы валют, новости).
• Выполнять действия (отправлять сообщения, создавать напоминания, управлять календарем, взаимодействовать с базами данных).
• Доступ к специализированным знаниям, которые не были включены в его обучающие данные (например, внутренняя документация компании, специфические API).

Лучшие практики при разработке функций-инструментов

Чтобы функции-инструменты были максимально эффективными и надежными, следуйте этим рекомендациям:

• Используйте описательные имена: Названия ваших функций и их параметров должны четко указывать на их назначение. Например, get_current_datetime лучше, чем просто get_time, а date_format лучше, чем fmt. Это помогает Claude лучше понять, когда и как использовать инструмент.
• Валидируйте входные данные: Всегда проверяйте, что обязательные параметры не пусты и имеют допустимые значения. Если входные данные некорректны, генерируйте ошибки. Это критически важно, потому что Claude учится на ошибках. Если вы выдадите четкую ошибку, например, "Параметр 'location' не может быть пустым", Claude может попытаться вызвать функцию снова с правильным значением location.
• Предоставляйте осмысленные сообщения об ошибках: Claude может "видеть" сообщения об ошибках. Чем яснее сообщение, тем выше вероятность, что Claude сможет исправить свой запрос или объяснить проблему пользователю. Например, вместо "Ошибка" лучше "Не удалось получить погоду для указанного города: город не найден".
• Обеспечьте идемпотентность (по возможности): Если функция выполняет действие (например, отправляет сообщение), подумайте, что произойдет, если она будет вызвана несколько раз. Идемпотентные функции дают один и тот же результат при многократном вызове с одними и теми же параметрами, что повышает надежность системы.

Создание вашей первой функции-инструмента: Получение текущей даты и времени

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

import datetime

def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    """
    Возвращает текущую дату и время в указанном формате.

    Параметры:
    date_format (str): Строка формата для даты и времени (по умолчанию "%Y-%m-%d %H:%M:%S").
                       Примеры: "%H:%M", "%A, %d %B %Y".
    """
    if not date_format:
        raise ValueError("Параметр 'date_format' не может быть пустым.")
    
    return datetime.datetime.now().strftime(date_format)

Эта функция использует встроенный модуль Python datetime для получения текущего времени и форматирования его в соответствии с предоставленной строкой формата. Формат по умолчанию "%Y-%m-%d %H:%M:%S" дает нам год-месяц-день час:минута:секунда.

Вы можете увидеть, как она работает с разными форматами:

• Вызов без параметров: get_current_datetime() вернет что-то вроде "2024-07-20 10:30:25".
• Вызов с конкретным форматом: get_current_datetime("%H:%M") вернет только часы и минуты, например "10:30".
• Вызов с другим форматом: get_current_datetime("%A, %d %B %Y") вернет день недели, число, месяц и год, например "Saturday, 20 July 2024".

Проверка if not date_format: raise ValueError(...) гарантирует, что Claude не сможет передать пустую строку для формата даты. Хотя такая специфическая ошибка маловероятна, она демонстрирует шаблон валидации входных данных и предоставления полезных сообщений об ошибках, из которых Claude может извлекать уроки.

Интеграция функций-инструментов с Claude

Создание самой функции — это только первый шаг. Чтобы Claude мог "знать" о существовании вашей функции и правильно ее вызывать, вам необходимо описать ее в формате JSON schema. Эта схема содержит информацию о названии функции, ее описании, а также о параметрах, которые она принимает (их типы, описания, обязательность). Затем вы передаете эту JSON schema вместе с запросом к Claude через его API.

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

1. Получить ответ от Claude.
2. Обнаружить блок tool_use.
3. Извлечь название функции и параметры.
4. Выполнить соответствующую Python-функцию в вашем коде.
4. Получить результат выполнения функции.
5. Отправить этот результат обратно Claude (в виде блока tool_result).
6. Claude использует этот результат для генерации окончательного ответа пользователю.

Такой подход к функциям-инструментам предоставляет Claude мощные возможности, сохраняя при этом ваш код организованным, модульным и легко поддерживаемым. Это открывает двери для создания по-настоящему динамичных и полезных AI-приложений.