Генератор ai-plugin.json

Предоставление доступа к вашему API для AI-агентов

Манифест `ai-plugin.json` служит базовым контрактом между вашим API и растущей экосистемой AI-помощников. Размещенный по предсказуемому пути `/.well-known/ai-plugin.json`, этот JSON-файл — не просто метаданные; это критически важный шлюз. Наш генератор гарантирует, что ваш манифест строго соответствует ссылкам на спецификацию OpenAPI (OAS), позволяя моделям, таким как GPT-4 и Google Gemini, точно понимать и вызывать ваши функции. Правильная генерация имеет первостепенное значение для бесшовной интеграции, предотвращая ошибки `invalid_manifest` и обеспечивая надежные вызовы инструментов.

Критически важное создание `description_for_model`

Поле `description_for_model` в `ai-plugin.json`, пожалуй, является наиболее значимым для использования инструментов, управляемых AI. Эта краткая строка (обычно до 200 символов) предоставляет контекст, спроектированный с помощью промптов, для LLM, чтобы решить, когда и как вызвать ваш API. Наш генератор помогает вам создавать точные, ориентированные на действия описания, например, «Используйте этот плагин для получения котировок акций в реальном времени по заданному тикеру», а не расплывчатые обобщения. Эта специфичность напрямую влияет на склонность LLM вызывать ваш инструмент.

Настройка аутентификации и URL OpenAPI

Безопасное предоставление вашего API для AI-агентов требует тщательной настройки аутентификации. `ai-plugin.json` поддерживает различные типы `auth`, включая `none` (без аутентификации), `oauth` (OAuth 2.0 Client Credentials Grant) и `service_http` (токен Bearer или базовая аутентификация). Наш генератор облегчает выбор и настройку этих параметров, гарантируя защиту ваших конечных точек при их доступности для авторизованных агентов. Одновременно он проверяет запись `api.url`, подтверждая, что она указывает на действующую, обнаруживаемую спецификацию OpenAPI/Swagger (например, `https://api.example.com/openapi.yaml`), что важно для понимания моделью.

Почему путь `/.well-known/` так важен

Размещение `ai-plugin.json` по пути `/.well-known/` не случайно; это стандарт, определенный RFC 8615 для обнаружения хост-метаданных. Это предсказуемое расположение позволяет краулерам AI-агентов (таким как `ChatGPT-User` или `Google-Extended`) эффективно обнаруживать и получать ваш манифест без явной настройки. Этот стандартизированный механизм обнаружения минимизирует задержки и накладные расходы для агентов, делая ваш API немедленно доступным для любой AI-системы, разработанной для поиска инструментов по этому указанному и широко используемому URI.

Типичные ошибки при генерации ai-plugin.json

Ключевые аспекты для вашего ai-plugin.json

• Убедитесь, что `name_for_model` является кратким, уникальным идентификатором (например, `stock_price_api`).
• Проверьте, что `description_for_model` является ясным, лаконичным и ориентированным на действия для интерпретации LLM.
• Подтвердите, что ваш `api.url` указывает на публично доступную, валидную спецификацию OpenAPI 3.0 или 3.1.
• Реализуйте соответствующую конфигурацию `auth` (например, `service_http` для токенов Bearer).
• Размещайте файл `ai-plugin.json` исключительно по пути `/.well-known/ai-plugin.json`.
• Проверьте `legal_info_url` и `contact_email` на соответствие требованиям и поддержку.
• Регулярно проверяйте сгенерированный манифест с помощью инструментов на соответствие схеме.
• Протестируйте вызовы API с реальным AI-агентом (например, ChatGPT Plugins) перед полным развертыванием.

Шаги для развертывания вашего манифеста AI-плагина

1. 1
   Определите основную функциональность API

   Четко сформулируйте конкретные действия, которые позволяет выполнять ваш API. Определите ключевые конечные точки, параметры и ожидаемые ответы. Эта ясность напрямую повлияет на `description_for_model` и спецификацию OpenAPI. Сосредоточьтесь на том, что AI-агенты могут *делать* с вашим API, а не только на том, что он *есть*.

2. 2
   Сгенерируйте спецификацию OpenAPI

   Создайте полную спецификацию OpenAPI (OAS 3.0/3.1) для вашего API. Эта спецификация подробно описывает все конечные точки, методы, параметры и модели данных. Убедитесь, что она точна и актуальна, поскольку AI-агенты будут анализировать этот документ, чтобы понять возможности вашего API и способы построения запросов.

3. 3
   Настройте детали манифеста

   Используйте генератор для ввода `name_for_model`, `description_for_model`, типа `auth` (например, `service_http` для ключей API), `logo_url`, `legal_info_url` и `contact_email`. Уделите особое внимание созданию `description_for_model` для оптимального понимания LLM и вызова вашего плагина.

4. 4
   Проверьте сгенерированный JSON

   Перед развертыванием тщательно проверьте выходной `ai-plugin.json` на соответствие официальной схеме. Проверьте на синтаксические ошибки, отсутствующие поля и правильные форматы URL. Убедитесь, что `api.url` точно указывает на размещенную спецификацию OpenAPI, чтобы предотвратить проблемы с обнаружением AI-агентами, такими как `ChatGPT-User`.

5. 5
   Разверните манифест в `/.well-known/`

   Разместите сгенерированный файл `ai-plugin.json` по точному URI `YOUR_DOMAIN/.well-known/ai-plugin.json`. Этот стандартный путь критически важен для автоматического обнаружения вашего плагина краулерами AI-агентов без предварительных знаний. Неправильное размещение сделает ваш плагин необнаруживаемым большинством AI-систем.

6. 6
   Мониторинг и итерации

   После развертывания отслеживайте использование вашего API и логи взаимодействия агентов. Обращайте внимание на то, как часто вызывается ваш плагин и есть ли какие-либо ошибки парсинга. Используйте эту обратную связь для уточнения `description_for_model` и спецификации OpenAPI, обеспечивая оптимальную производительность и надежную интеграцию AI-агентов со временем.