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

Схемы Инструментов: Как Научить Claude Использовать Ваши Функции

В мире больших языковых моделей (LLM), таких как Claude, способность не просто генерировать текст, но и взаимодействовать с внешним миром — это мощный шаг вперед. Эта способность называется "использованием инструментов" (tool use). Представьте, что Claude может не только ответить на вопрос "Какая сейчас погода в Париже?", но и фактически вызвать функцию, которая получит актуальные данные о погоде из внешнего API. Чтобы Claude мог это сделать, ему нужно точно знать, какие инструменты доступны, что они делают и как их использовать. Именно здесь на сцену выходят схемы инструментов (tool schemas).

Схема инструмента — это, по сути, подробная инструкция или "руководство пользователя" для Claude, описывающее вашу функцию. Она сообщает модели, какие аргументы ожидает ваша функция, каково ее назначение и когда ее следует вызывать. Без такой схемы Claude не сможет понять, как правильно взаимодействовать с вашим кодом, что делает ее неотъемлемой частью разработки с использованием возможностей tool use.

Что Такое JSON Schema?

Прежде чем углубляться в схемы инструментов, важно понять основу, на которой они строятся: JSON Schema. Это не специфическая для AI технология, а широко используемая спецификация для описания структуры и валидации данных в формате JSON. Она существует уже много лет и применяется в самых разных областях для обеспечения целостности и предсказуемости данных, позволяя разработчикам определять, как должны выглядеть JSON-данные.

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

Основные Компоненты Спецификации Инструмента

Полная спецификация инструмента, которую Claude использует для понимания и вызова вашей функции, состоит из трех ключевых частей:

• Четкое, описательное имя для вашего инструмента: Это уникальный идентификатор, который Claude будет использовать для ссылки на вашу функцию. Например, "get_weather" или "get_current_datetime". Имя должно быть лаконичным, написано в стиле snake_case и точно отражать назначение инструмента.
• Подробное описание того, что делает инструмент, когда его следует использовать и что он возвращает: Это текстовое описание, которое Claude читает, чтобы принять решение о вызове инструмента. Оно должно быть максимально информативным и понятным, объясняя цель, условия применения и ожидаемый результат.
• Фактическая JSON Schema, описывающая аргументы функции: Это техническое описание входных параметров вашей функции, включая их типы, описания и любые ограничения. Именно эта часть позволяет Claude понять, какие данные нужно предоставить функции и в каком формате.

Написание Эффективных Описаний

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

• Цель инструмента: Сформулируйте в 3-4 предложениях, что именно делает инструмент. Будьте конкретны и избегайте двусмысленности. Например, вместо "получает данные", напишите "получает текущую температуру и влажность для указанного города из внешнего погодного API".
• Условия использования: Четко опишите, в каких сценариях Claude должен использовать этот инструмент. Например, "использовать, когда пользователь явно спрашивает о текущей погоде, температуре или влажности в конкретном населенном пункте".
• Возвращаемые данные: Объясните, какой тип данных и в каком формате возвращает инструмент. Например, "возвращает объект JSON с полями 'температура' (число в градусах Цельсия) и 'единицы_измерения' (строка, например, 'C' или 'F')".
• Детальные описания для каждого аргумента: Внутри JSON Schema для каждого параметра функции предоставьте подробное описание. Это поможет Claude понять, что означают различные входные данные и как их правильно формировать. Например, для аргумента "city" можно написать: "Название города, для которого нужно получить данные о погоде. Должно быть строкой, например, 'Париж' или 'Нью-Йорк'".

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

Простой Способ Генерации Схем: Используйте Claude!

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

1. Скопируйте код вашей функции: Возьмите Python-код функции, для которой вы хотите создать схему. Убедитесь, что функция хорошо документирована с помощью docstrings, так как Claude может использовать их для создания описаний.
2. Обратитесь к Claude: Вставьте код функции в диалог с Claude и попросите его написать JSON Schema для вызова инструмента.
3. Предоставьте контекст: Очень важно включить в ваш запрос документацию Anthropic по использованию инструментов в качестве дополнительного контекста. Это гарантирует, что Claude сгенерирует схему, соответствующую лучшим практикам и требованиям API Anthropic. Вы можете просто сказать: "Следуй лучшим практикам, описанным в документации Anthropic по использованию инструментов."
4. Позвольте Claude сгенерировать схему: Claude создаст правильно отформатированную схему, следуя предоставленным инструкциям и лучшим практикам.

Пример запроса может выглядеть так: "Напиши валидную спецификацию JSON Schema для вызова инструмента для следующей функции. Следуй лучшим практикам, описанным в приложенной документации Anthropic по использованию инструментов." Затем вы вставляете код вашей функции.

Реализация Схемы в Коде

После того как Claude сгенерирует вашу схему, вам нужно скопировать ее в файл с вашим кодом. Рекомендуется следовать определенному шаблону именования, чтобы поддерживать порядок и легко сопоставлять схемы с соответствующими функциями. Обычно это имя_функции_schema.

Рассмотрим пример функции, которая возвращает текущую дату и время, и соответствующую ей схему:

import datetime

def get_current_datetime(date_format="%Y-%m-%d %H:%M:%S"):
    """
    Возвращает текущую дату и время, отформатированные согласно указанному формату.
    """
    if not date_format:
        raise ValueError("date_format cannot be empty")
    return datetime.datetime.now().strftime(date_format)

get_current_datetime_schema = {
    "name": "get_current_datetime",
    "description": "Возвращает текущую дату и время, отформатированные согласно указанному формату. Используется, когда пользователь запрашивает текущую дату или время.",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "Строка, указывающая формат возвращаемой даты и времени. Использует коды форматирования Python strftime.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
}

В этом примере get_current_datetime_schema — это словарь Python, который содержит всю необходимую информацию для Claude. Обратите внимание на поля "name", "description" и "input_schema", которое содержит саму JSON Schema для аргументов функции. Поле "required": [] указывает, что все параметры являются необязательными, так как date_format имеет значение по умолчанию.

Добавление Типовой Безопасности (Type Safety)

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

from anthropic.types import ToolParam
import datetime

# ... (определение функции get_current_datetime) ...

get_current_datetime_schema: ToolParam = ToolParam({
    "name": "get_current_datetime",
    "description": "Возвращает текущую дату и время, отформатированные согласно указанному формату. Используется, когда пользователь запрашивает текущую дату или время.",
    "input_schema": {
        "type": "object",
        "properties": {
            "date_format": {
                "type": "string",
                "description": "Строка, указывающая формат возвращаемой даты и времени. Использует коды форматирования Python strftime.",
                "default": "%Y-%m-%d %H:%M:%S"
            }
        },
        "required": []
    }
})

Использование ToolParam явно указывает, что этот словарь предназначен для описания инструмента, что позволяет инструментам статического анализа кода и IDE лучше проверять ваш код на соответствие типам, делая его более предсказуемым и легким для отладки. Это особенно полезно в больших проектах, где ошибки типов могут быть труднообнаруживаемыми.

Заключение

Схемы инструментов являются краеугольным камнем для эффективного использования функций внешнего мира моделями LLM, такими как Claude. Они служат мостом между вашей бизнес-логикой и интеллектуальными возможностями модели. Тщательное описание инструментов, использование стандартизированных JSON Schema и применение лучших практик, включая генерацию схем с помощью самого Claude и использование ToolParam для типовой безопасности, позволит вам создавать мощные и надежные приложения, расширяющие возможности AI за пределы простого текстового взаимодействия. Освоив создание и управление схемами инструментов, вы значительно расширите потенциал Claude в своих проектах.