私は英語で API を探索できる AI エージェントを構築しました

私の現在の製品には数百のAPIがあります。APIの仕様を参照する必要があるたびに、Swaggerリンクに移動し、延々とスクロールするか、ブラウザの検索機能を使って必要なものを見つけ、そして手動でフィルタリングする必要があります。これはイライラするし、痛いほど遅いです。さらに悪いことに、APIと連携する必要がある全ての開発者が同じ経験をしなければなりません。

この不満から、AIがどのようにプロセスを改善できるかを探ることになりました。この投稿は、その旅と、それがどのようにシンプルで堅牢、そして効果的なものへと進化したかについての詳細な考察です。

準備

充実したAPIドキュメント

最初のステップとして、API全体のドキュメントを見直し、swaggerドキュメントに明確な概要と説明の詳細があることを確認しました。これは後の段階での発見性を高めるための重要なステップです。また、各APIの概要と説明が一意であることも確認しました。

paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

APIの分類

数百のAPIが利用可能な状態では、関連するものを特定するのが難しい場合があります。APIを分類することで管理がより効率的になり、後で自然言語入力に基づいて適切なAPIを選択することが簡単になります。この分類はOpenAPI仕様で定義されているタグ付けの概念を使用して実装されました。

\

"paths": {     "/users/accounts/{account-id}": {       "put": {         "tags": [           "Account API"         ],         "summary": "Update Test suite by test-suite-id",         "externalDocs": {           "description": "Robust get account details description",           "url": "https://mydocs.com/description"         },

\

自然言語検索の構築

ユーザー入力

ユーザーはAPIに関連する自然言語の質問を入力します。

例：アカウントの詳細を取得するにはどうすればよいですか？

カテゴリの分類

この段階では、質問と利用可能なすべてのカテゴリがLLMに送信されます。LLMは質問が該当する高レベルのカテゴリを返すよう指示されます。このステップの出力はカテゴリの一つです。

特定のAPIの分類

LLMが特定したカテゴリに基づいて、システムは同じ質問を別のリクエストとしてモデルに送信します — ただし今回は、前のステップで検出された特定のカテゴリ内のすべてのAPI詳細を含めます。

ここで以前の準備が活きてきます：APIドキュメントが詳細で構造化されているほど、結果は良くなります。明確な説明はLLMがユーザーが情報を求めているAPIを正確に判断するのに役立ちます。

このステップの出力は単一の特定のAPIです。

APIレスポンス詳細の充実

APIのOpenAPI仕様はLLMに提供され、元の質問と共にAPIの詳細でコンテキストが豊富な説明を生成します。

例えば、ユーザーが「アカウントIDを使用してアカウントの詳細を取得するにはどうすればよいですか？」と尋ねた場合、レスポンスにはアカウントAPIの関連する仕様の詳細が含まれます。

拡張

システムが適切なAPIを正確に検出する能力が向上したことで、ユーザーはさらに一歩進んで — 様々なAPIと直接対話するためのコードスニペットを生成することができるようになりました。

例えば：

• 「特定のIDに対してアカウント詳細の取得APIを呼び出すPythonコードを共有してください。」

• 「IDでアカウント詳細を取得するためのcURLコマンドを提供してください。」

• 「特定のIDのアカウント詳細を取得するためのGoクライアントを生成してください。」

\

学んだ教訓と洞察

• AIシステムを扱う際には、より高い精度のために充実したドキュメントが不可欠です。正確で明確、そして要点を押さえたドキュメントは堅牢性に不可欠です。ボーナス：各APIの概要と説明を生成するためにLLMも使用しました、これは非常に役立ちました。
• まず分類する
• なぜ： 数百のAPIがある場合、分類することで認知負荷を減らし、検索性を向上させます。
• 方法： 関連するAPIを明確なカテゴリの小さなセットにグループ化します。AIシステムはラベル空間が限定されている場合に性能が向上します。
• スケールのヒント： カタログが非常に大きい場合は、より細かいルーティングのためにサブカテゴリを追加します。
• 反復的に構築する
• 小さく始める： 仕様のサブセットを取り、正しいAPIを確実に選択できるルーターをトレーニング/検証します。
• 徐々に拡大する： 時間をかけてより多くのAPIを追加し、精度を測定し、誤分類のある領域を優先します。
• 焦点： 最初から幅広さよりも精度/リコールを最適化します。
• ユーザーとのループを閉じる
• フィードバックを収集する： システムが間違ったAPIを選んだケースをキャプチャします。
• シグナルに基づいて行動する： 誤認識されたAPIの説明、概要、タグを洗練させ、重複する範囲を明確にします。
• リピート： 各変更後に再評価して、精度が向上し、回帰が回避されることを確認します。

結論

利用可能なAPIの数が増え続けるにつれて、それらを探索し管理するには新しいアプローチが必要です。大規模言語モデル（LLM）を搭載したAIエージェントの台頭により、開発者はより直感的かつ効率的にAPIを発見し、対話する方法を手に入れました—以前は適切なエンドポイントを探すのに費やされていた無数の時間を節約します。

可能性はそこで止まりません。この概念は、実行時にOpenAPI仕様をシームレスに取り込み、自然言語インターフェースを通じて公開できるスタンドアロン製品へと進化する可能性があります—ユーザーにAPI探索のためのすぐに使えるソリューションを提供します。

この記事が、LLMを効果的に活用する方法と、構造化されたAPIドキュメントがより滑らかでインテリジェントな発見体験を生み出す方法を示すことができれば幸いです。

\n \n

\n \n