APIカタログでエージェントにサイト検索を発見させる

この記事は Dries Buytaert 氏の公式ブログ「dri.es」の翻訳記事です。Driesブログの記事一覧よりすべての翻訳記事をご覧いただけます。

同じちょっとした不満に何度もぶつかっていました。私のサイトには独自の検索機能があるのに、あるトピックについて過去に書いたことがあるかとAIエージェントに聞くと、サイトの検索を直接使わずにGoogleで検索してしまうのです。その結果、Googleがインデックスしていない関連記事を見逃すことがよくありました。

同時に、ウェブには新しいオーディエンスが増えています。ページを訪れる人間に加えて、AIエージェントがサイトの知識やツールに直接アクセスするケースが増えています。

この2つが重なり、私のサイトに /.well-known/api-catalog のサポートを追加しました。https://dri.es/.well-known/api-catalog へのリクエストは現在、次のレスポンスを返します：

{
  "linkset": [
    {
      "anchor": "https://dri.es/search/json",
      "service-desc": [
        {
          "href": "https://dri.es/openapi.json",
          "type": "application/openapi+json"
        }
      ]
    }
  ]
}

IETFの提案標準であるRFC 9727は、/.well-known/api-catalog をサイトの公開APIを発見するための予測可能な場所として定義しています。

カタログはLinksetフォーマットで書かれた小さなJSONドキュメントです。私の検索エンドポイントを公示し、さらにソフトウェアがその使い方を知るためのOpenAPIドキュメントへのリンクを持っています。

/search/json のJSONエンドポイントはカタログよりも前から存在しており、私のサイトの検索を動かしています。しかしドキュメント化されておらず、ソフトウェアが発見しやすいものでもありませんでした。カタログによって、それが明示的になりました。

https://dri.es/openapi.json のOpenAPIドキュメントは、エンドポイントの呼び出し方と結果の解釈の仕方をAIエージェントに正確に伝えます。推測を排除し、エージェントがAPIの使い方を把握するために費やすはずだった時間とトークンを削減します。

つまり、APIカタログは検索APIの存在を知らせ、OpenAPIドキュメントはその使い方を説明します。エージェントはドメイン名さえあれば、/.well-known/api-catalog を確認し、OpenAPIドキュメントへのリンクをたどり、dri.esを直接検索する方法を学べます。

この機能は数ヶ月前から稼働していますが、記事にするのは今が初めてです。その間、/.well-known/api-catalog と /openapi.json へのすべてのリクエストをログに記録してきました。結果はというと、AIエージェントの利用はゼロでした。

llms.txt の利用状況を分析したときも同じ問題に気づきました。想定していたAIクローラーがまったく使わないため、実装を見送ったほどです。

llms.txt と違うのは、APIカタログは自分自身の問題を解決するものであり、業界全体での採用を待つ必要がないことです。私は最近Agent Skill（SKILL.md ファイル）を作成し、自分のエージェントがdri.esの情報を必要とするときはカタログを確認してサイトの検索APIを使うよう指示しました。

私のエージェントは今、dri.esを直接検索してGoogleが見逃す記事も見つけてくれます。そしてAIエージェントがAPIカタログの探索に対応したとき、私のサイトはすでに準備できています。

By Dries Buytaert

この記事は 「Helping agents discover my site search with an API Catalog」（投稿日：2026-07-22）の翻訳記事です。