ai-plugin.json ジェネレーター
有効なマニフェストを使ってAPIをAIエージェントに公開しましょう。
クイックアンサー
ai-plugin.jsonは、AIアシスタントがツールとしてAPIを呼び出すために使用するマニフェストファイルで、/.well-known/ai-plugin.jsonにホストされます。このジェネレーターは、API名、モデル向け説明、認証タイプ、OpenAPI URLを記述した有効なマニフェストを作成し、AIエージェントがエンドポイントを検出し呼び出せるようにします。
このインタラクティブジェネレーターは英語で動作しますが、その使用に必要なすべての情報は本ページで解説しています。
APIをAIエージェントに公開する
ai-plugin.jsonマニフェストは、あなたのAPIと成長するAIアシスタントのエコシステムとの間の基本的な契約として機能します。/.well-known/ai-plugin.jsonという予測可能なパスにホストされるこのJSONファイルは、単なるメタデータではありません。これは極めて重要なゲートウェイです。当社のジェネレーターは、マニフェストがOpenAPI Specification（OAS）の参照に厳密に従っていることを保証し、GPT-4やGoogleのGeminiのようなモデルがあなたの機能を正確に理解し、呼び出せるようにします。適切な生成はシームレスな統合に不可欠であり、invalid_manifestエラーを防ぎ、信頼性の高いツール呼び出しを保証します。
重要な`description_for_model`の作成
ai-plugin.json内のdescription_for_modelフィールドは、AI駆動型ツール利用において最も影響力のある要素と言えるでしょう。この簡潔な文字列（通常200文字以内）は、LLMがあなたのAPIをいつ、どのように呼び出すかを決定するためのプロンプトエンジニアリングされたコンテキストを提供します。当社のジェネレーターは、「与えられたティッカーシンボルのリアルタイム株価を取得するためにこのプラグインを使用する」といった、曖昧な一般論ではなく、正確で行動志向な説明を作成するのに役立ちます。この具体性が、LLMがあなたのツールを呼び出す傾向に直接影響します。
認証とOpenAPI URLの設定
AIエージェントにAPIを安全に公開するには、慎重な認証設定が必要です。ai-plugin.jsonは、none、oauth（OAuth 2.0 クライアントクレデンシャルグラント）、service_http（ベアラーNトークンまたは基本認証）など、様々な認証タイプをサポートしています。当社のジェネレーターは、これらの選択と設定を容易にし、エンドポイントが保護されつつ、許可されたエージェントからアクセス可能であることを保証します。同時に、api.urlエントリを検証し、それが稼働中の検出可能なOpenAPI/Swagger仕様（例：https://api.example.com/openapi.yaml）を指していることを確認します。これはモデルが理解するために不可欠です。
`/.well-known/`パスが不可欠な理由
ai-plugin.jsonが/.well-known/パスに配置されるのは恣意的なものではなく、RFC 8615で定義されたホストメタ検出のための標準です。この予測可能な場所により、AIエージェントクローラー（ChatGPT-UserやGoogle-Extendedなど）は、明示的な設定なしにあなたのマニフェストを効率的に発見し、取得できます。この標準化された検出メカニズムは、エージェントのレイテンシとオーバーヘッドを最小限に抑え、この指定され広く採用されているURIでツールを探すように設計されたあらゆるAIシステムに対して、あなたのAPIを即座に利用可能にします。
一般的なai-plugin.json生成時の落とし穴
| 問題 | 影響 | 緩和策 | クローラーの反応 |
|---|---|---|---|
| JSON形式が不正 | マニフェスト解析失敗、APIが発見されない | 厳密なJSON検証のためにリンターまたはジェネレーターを使用する | エージェントのログに`HTTP 400 Bad Request`または`Invalid JSON`エラー |
| OpenAPI URLが不正 | LLMにAPI機能が認識されない | `api.url`が稼働中の有効なOpenAPI仕様を指していることを確認する | `API spec not found`または`Unparseable OpenAPI`警告 |
| 曖昧な`description_for_model` | LLMによる利用が少ない | 簡潔で行動志向な説明（50-150文字）を作成する | LLMがツールを選択できない、または意図を誤解する |
| 必須フィールドの欠落 | マニフェストが拒否される | `name_for_model`、`name_for_human`、`description_for_model`、`api`、`auth`が存在することを確認する | `Missing required field`または`Manifest schema validation failed` |
| `/.well-known`パスがない | 標準クローラーによるマニフェストの発見不可 | `ai-plugin.json`を厳密に`/.well-known/ai-plugin.json`にデプロイする | クローラーがホストをスキップし、APIはエージェントに認識されないままになる |
ai-plugin.json作成の重要事項
- `name_for_model`が簡潔でユニークな識別子であることを確認する（例：`stock_price_api`）。
- `description_for_model`がLLMの解釈にとって明確で簡潔、かつ行動志向であることを確認する。
- `api.url`が公開されており、有効なOpenAPI 3.0または3.1仕様を指していることを確認する。
- 適切な`auth`設定（例：Bearerトークンの`service_http`）を実装する。
- `ai-plugin.json`ファイルを`/.well-known/ai-plugin.json`パスにのみデプロイする。
- コンプライアンスとサポートのために`legal_info_url`と`contact_email`を確認する。
- 生成されたマニフェストがスキーマに準拠しているか、ツールを使って定期的に検証する。
- 完全なデプロイ前に、実際のAIエージェント（例：ChatGPTプラグイン）でAPI呼び出しをテストする。
AIプラグインマニフェストのデプロイ手順
- 1コアAPI機能の定義
APIが提供する特定の機能を明確に表現します。主要なエンドポイント、パラメータ、および期待される応答を特定してください。この明確さが、`description_for_model`とOpenAPI仕様に直接反映されます。AIエージェントがAPIで「何ができるか」に焦点を当て、単に「何であるか」だけでなく記述します。
- 2OpenAPI仕様の生成
APIの包括的なOpenAPI（OAS 3.0/3.1）定義を作成します。この仕様は、すべてのエンドポイント、メソッド、パラメータ、およびデータモデルを詳細に記述します。AIエージェントがAPIの機能とリクエストの構築方法を理解するためにこのドキュメントを解析するため、正確で最新であることを確認してください。
- 3マニフェスト詳細の設定
ジェネレーターを使用して、`name_for_model`、`description_for_model`、`auth`タイプ（例：APIキーの`service_http`）、`logo_url`、`legal_info_url`、および`contact_email`を入力します。プラグインの最適なLLM理解と呼び出しのために、`description_for_model`の作成に細心の注意を払ってください。
- 4生成されたJSONの検証
デプロイする前に、生成された`ai-plugin.json`を公式スキーマに対して入念に検証します。構文エラー、欠落フィールド、および正しいURL形式を確認してください。`api.url`がホストされたOpenAPI仕様を正確に指していることを確認し、`ChatGPT-User`のようなAIエージェントによる発見の問題を防ぎます。
- 5`/.well-known/`へのマニフェストデプロイ
生成された`ai-plugin.json`ファイルを`YOUR_DOMAIN/.well-known/ai-plugin.json`という正確なURIにホストします。この標準パスは、AIエージェントクローラーが事前に知ることなくプラグインを自動的に発見するために不可欠です。誤った配置は、ほとんどのAIシステムによってプラグインが発見されなくなる原因となります。
- 6監視と改善
デプロイ後、APIの使用状況とエージェントのインタラクションログを監視します。プラグインが呼び出される頻度や解析エラーがないかに注意してください。このフィードバックを使用して、`description_for_model`とOpenAPI仕様を洗練させ、時間の経過とともに最適なパフォーマンスと信頼性の高いAIエージェント統合を確実にします。
よくある質問
- `ai-plugin.json`とは何ですか、また私のAPIにとってなぜ重要ですか？
- `ai-plugin.json`は、AIエージェント（ChatGPTやGeminiなどを動かすもの）があなたのAPIを発見し、理解するための青写真として機能する標準化されたマニフェストファイルです。これは、あなたのサービスをAIエコシステム内で呼び出し可能なツールにすることを可能にし、LLMがユーザーに代わってプログラム的にAPIと対話できるようにすることで、APIの到達範囲と有用性を大幅に拡大するため、極めて重要です。
- `ai-plugin.json`ファイルは具体的にどこにホストする必要がありますか？
- `ai-plugin.json`ファイルは、ドメインの相対パスとして`/.well-known/ai-plugin.json`に正確にホストする必要があります。たとえば、ドメインが`example.com`の場合、ファイルは`https://example.com/.well-known/ai-plugin.json`でアクセス可能である必要があります。この標準化された場所は、AIクローラーがプラグインマニフェストを確実に探し出してインデックスするために不可欠です。
- `description_for_model`と`description_for_human`の目的の違いは何ですか？
- `description_for_model`は、LLMがAPIをいつ、どのように呼び出すかを理解するために、簡潔で行動志向の要約を提供します（例：「場所の現在の天気データを取得する」）。`description_for_human`は、プラグインマーケットプレイスやディレクトリで人間ユーザーに表示される、ユーザーフレンドリーでより長い説明です。前者はAIによる呼び出しを駆動し、後者はユーザーの選択を促します。
- `ai-plugin.json`でサポートされている認証タイプは何ですか？
- `ai-plugin.json`標準は、いくつかの認証タイプをサポートしています：認証不要なAPIのための`none`、OAuth 2.0クライアントクレデンシャルフローのための`oauth`、そしてAPIキーベースの認証（`Authorization`ヘッダーのBearerトークンまたはHTTP基本認証のいずれか）のための`service_http`です。AIエージェントへの安全なAPI公開には、正しいタイプを選択することが不可欠です。
- APIにカスタムのOpenAPI仕様URLを使用できますか？
- はい、`ai-plugin.json`の`api.url`フィールドは、APIのOpenAPI仕様ドキュメントの直接URL（例：`https://api.example.com/openapi.yaml`または`https://api.example.com/openapi.json`）を指す必要があります。このURLは公開され、有効なOpenAPI 3.0または3.1仕様を提供している必要があり、AIエージェントがAPIのエンドポイントとスキーマを解析し理解するために必要です。
- `ai-plugin.json`はどのくらいの頻度で更新すべきですか？
- APIの機能、認証方法、または一般公開される説明に大きな変更があった場合は、`ai-plugin.json`を更新する必要があります。`description_for_model`のわずかな変更でもLLMの挙動に影響を与える可能性があります。APIの現在の状態と同期を保ち、AIエージェントが常に正確な情報を持つように努めてください。
- 私の`ai-plugin.json`が不正または無効な場合どうなりますか？
- もしあなたの`ai-plugin.json`が不正な形式である、構文エラーを含んでいる、または必須フィールドが欠落している場合、AIエージェントはそれを解析できない可能性が高いです。その結果、あなたのAPIはツールとして発見されず、エージェントは`invalid_manifest`エラーを報告します。当社のジェネレーターのような検証ツールや堅牢なジェネレーターを使用することで、これらの致命的な解析失敗を防ぎ、統合を成功させることができます。
- `ai-plugin.json`ファイルをクロールする特定のユーザーエージェントはありますか？
- はい、様々なAIエージェントプラットフォームは、`ai-plugin.json`ファイルを発見して解析するために特定のユーザーエージェントを使用します。注目すべき例としては、`ChatGPT-User`（OpenAIのプラットフォーム用）や`Google-Extended`（GoogleのAIサービス用）があります。`robots.txt`がこれらのユーザーエージェントに`/.well-known/`へのアクセスを許可していることを確認することは、プラグインの発見とインデックス作成を成功させるために不可欠です。