Claude в Google Vertex AI

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

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

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

Что Такое JSON Schema?

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

Используя JSON Schema, вы можете определить, какие поля должны присутствовать в JSON-объекте, их типы (строка, число, булево значение, массив, объект), форматы, минимальные/максимальные значения и многое другое. Для Claude это означает, что вы можете точно указать, какой тип данных ожидает ваша функция для каждого аргумента, что значительно снижает вероятность ошибок и улучшает надежность взаимодействия.

Анатомия Спецификации Инструмента

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

• Имя функции (name): Уникальное имя, которое Claude будет использовать для ссылки на ваш инструмент, например, "get_weather" или "send_email". Это имя должно быть кратким и описательным.
• Описание инструмента (description): Подробное текстовое описание того, что делает инструмент, в каких ситуациях его следует использовать и что он возвращает. Это критически важная часть, поскольку она помогает Claude принять решение о вы вызове инструмента.
• Схема входных аргументов (input_schema): Фактическая JSON Schema, описывающая параметры, которые ваша функция ожидает в качестве входных данных. Здесь вы указываете типы данных, описания и другие ограничения для каждого аргумента.

Создание Эффективных Описаний

Поле description является ключевым для помощи Claude в понимании вашего инструмента. Хорошее описание позволяет Claude точно определить, когда и как использовать инструмент, а также как интерпретировать его результаты. Следуйте этим рекомендациям для создания эффективных описаний:

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

Определение Входных Параметров с input_schema

Секция input_schema описывает параметры вашей функции, используя стандартный формат JSON Schema. Она является наиболее технической частью спецификации инструмента. Вот основные элементы, которые вы будете использовать:

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

• "type": "object": Это указывает, что входные параметры будут переданы в виде JSON-объекта, где каждый ключ является именем аргумента.
• "properties": Этот объект содержит определения для каждого ожидаемого аргумента вашей функции. Каждый ключ внутри properties соответствует имени аргумента функции.
  • "type": Определяет тип данных аргумента (например, "string", "number", "boolean", "array", "object").
  • "description": Подробное описание того, что представляет собой этот аргумент и для чего он используется. Это очень важно для Claude.
  • "default" (необязательно): Значение по умолчанию для аргумента, если оно не предоставлено.
  • Дополнительные поля: Вы также можете использовать другие ключевые слова JSON Schema, такие как "enum" (список допустимых значений), "minimum"/"maximum" для чисел, "minLength"/"maxLength" для строк и т.д.
• "required": Массив строк, содержащий имена всех обязательных аргументов. Если аргумент не указан в этом списке, Claude будет считать его необязательным.

Простой Способ: Позвольте Claude Написать Вашу Схему

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

Вот как это работает:

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

Пример запроса (prompt) к Claude может выглядеть так:

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

[Здесь вставьте код вашей функции]"

Этот подход значительно ускоряет разработку и снижает вероятность синтаксических ошибок в схеме.

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

Как только Claude сгенерирует вашу схему, скопируйте ее в файл с вашим кодом. Для поддержания порядка и ясности рекомендуется использовать согласованные шаблоны именования, например, добавлять суффикс _schema к имени переменной, хранящей схему.

Пример реализации в Python:

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

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

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

from anthropic.types import ToolParam

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

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

Заключение

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