> ## Documentation Index > Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # AAO ディレクトリ API — エージェント ↔ パブリッシャー逆引き > セールスエージェントオペレーターがどのパブリッシャーが自身のエージェントを認可するかを発見する HTTP API。AAO ディレクトリのパブリッシャー adagents.json ファイルのインデックスから取得。プロベナンス、パブリッシャーごとのプロパティ数、ライフサイクルステータスを返す。 # AAO ディレクトリ API `agenticadvertising.org` の AAO ディレクトリは、オープンウェブ全体でパブリッシャー `adagents.json` ファイルをインデックスします。この API は、すべてのセールスエージェントオペレーターが同期時に必要とする **逆マップ** を表示します: > 「どのパブリッシャーが私のエージェントを認可したか?」 このエンドポイントなしでは、オペレーターはパブリッシャードメインリストを手動で保守し `fetch_agent_authorizations` をそれに対して呼ぶか、オープンウェブを自分でクロールしなければなりません。両方ともマネージドネットワークスケールでは実行不可能です（[cafemedia](https://cafemedia.com/.well-known/adagents.json) だけで単一のマネージャーファイルの下に約 6,800 のパブリッシャードメインを委譲）。 このエンドポイントは **ディスカバリー** であり、**認可** ではありません。パブリッシャー自身の `adagents.json` がトラストルートのままです。ディレクトリは、どのパブリッシャーを SDK のドメインごとプリミティブ（`verify_agent_authorization`、`fetch_agent_authorizations`）経由で直接検証すべきかを伝えます。 ## エンドポイント ``` GET https://{aao_directory}/v1/agents/{agent_url}/publishers ``` `{agent_url}` はパーセントエンコードされなければなりません（MUST）。ディレクトリは、SDK が `verify_agent_authorization` で適用するのと同じ規約を使って、ルックアップキーを正準化します（小文字ホスト、デフォルトポート除去、パスコンポーネントの末尾スラッシュ正規化）。 ### クエリパラメーター | Parameter | Type | Default | Semantics | | --------- | ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `since` | ISO 8601 | 未設定 | `last_verified_at` ≥ `since` のパブリッシャーのみを返す。増分同期を可能にする。 | | `cursor` | 不透明文字列 | 未設定 | 先のレスポンスが返したページネーションカーソル。カーソルの寿命の間、ディレクトリのリフレッシュサイクル全体で安定。 | | `status` | string、繰り返し | `authorized` | ライフサイクルステータスでフィルター。v1: `authorized`、`revoked`。値ごとにキーを 1 回繰り返す（OpenAPI `style: form, explode: true`）。カンマ区切り単一値形式（`status=authorized,revoked`）は受け入れられ **ない**。ディレクトリは繰り返しキー形式を指す説明とともに `400` を返さなければならない（MUST）。 | | `limit` | int（1–1000） | 200 | ページあたり最大パブリッシャー数。 | | `include` | string、繰り返し | 未設定 | 拡張されたロウごとフィールドにオプトイン。v1: `properties` — 各 `PublisherEntry` がそのパブリッシャーの下の正準 `property_ids[]` リストを運ぶ（消費者が数比較だけでなくフェデレーテッドフェッチに対して完全な集合差分を実行できる）。繰り返しキー形式、`status` と同じエンコードルール。未知の値は `400` を返す。 | #### 実例: 複数のステータス値でフィルター ``` GET /v1/agents/https%3A%2F%2Fsales-agent.example.com%2F/publishers?status=authorized&status=revoked&limit=500 ``` TypeScript での同等物: ```ts theme={null} const url = new URL(`${directory}/v1/agents/${encodeURIComponent(agentUrl)}/publishers`); url.searchParams.append("status", "authorized"); url.searchParams.append("status", "revoked"); url.searchParams.set("limit", "500"); ``` Python（`requests`）での同等物: ```python theme={null} requests.get( f"{directory}/v1/agents/{quote(agent_url, safe='')}/publishers", params=[("status", "authorized"), ("status", "revoked"), ("limit", "500")], ) ``` `status` パラメーターの OpenAPI フラグメント: ```yaml theme={null} - in: query name: status schema: type: array items: type: string enum: [authorized, revoked] style: form explode: true required: false ``` 繰り返しキーが選ばれたのは、(a) それが `URLSearchParams.append()` と OpenAPI のデフォルト `explode: true` が生成するもので、(b) カンマを含みうる将来の値ときれいに合成し、(c) ディレクトリでパーサーの曖昧性を残さないからです。 #### 実例: 完全な集合差分のため `?include=properties` を要求 ``` GET /v1/agents/https%3A%2F%2Fsales-agent.example.com%2F/publishers?include=properties ``` デフォルトレスポンスは `properties_authorized` を数としてのみ運びます。数の等価は集合の等価では **ありません**: 3 つのプロパティをローテートするパブリッシャーは数を変えないまま集合を完全に異なるものにし、数ベースの分岐検出器はそれを見られません。`?include=properties` は `PublisherEntry` ごとに `property_ids: list[string]` フィールドを追加します — そのパブリッシャーの下でエージェントのセレクターが解決する正準 ID — 消費者がフェデレーテッド `fetch_agent_authorizations` 結果に対して集合として完全な集合差分を実行し、大きさの差分だけでなくローテーションを検出できるように。 フラグはデフォルトページペイロードを小さく保つためオプトインです。インライン ID はパブリッシャーごとのプロパティ数 × 約 16 バイト/ID を追加します。マネージドネットワーク親ファイル（約 6,800 パブリッシャー × 平均 1 プロパティ ≈ 追加 7 KB の ID）では、オーバーヘッドは小さいが非ゼロです。ページネーションセマンティクスは変わりません。 ### レスポンス ```json theme={null} { "agent_url": "https://sales-agent.example.com", "directory_indexed_at": "2026-05-19T12:00:00Z", "publishers": [ { "publisher_domain": "recipeswithessentialoils.com", "discovery_method": "ads_txt_managerdomain", "manager_domain": "cafemedia.com", "properties_authorized": 1, "properties_total": 1, "signing_keys_pinned": false, "status": "authorized", "last_verified_at": "2026-05-19T08:00:00Z" }, { "publisher_domain": "wsj.com", "discovery_method": "direct", "manager_domain": null, "properties_authorized": 47, "properties_total": 200, "signing_keys_pinned": true, "status": "authorized", "last_verified_at": "2026-05-19T10:00:00Z" }, { "publisher_domain": "former-partner.example", "discovery_method": "authoritative_location", "manager_domain": "cafemedia.com", "properties_authorized": 0, "properties_total": 0, "signing_keys_pinned": false, "status": "revoked", "last_verified_at": "2026-05-19T11:00:00Z" } ], "next_cursor": "eyJv..." } ``` `?include=properties` では、各 `PublisherEntry` が追加で `property_ids` を運びます: ```json theme={null} { "publisher_domain": "recipeswithessentialoils.com", "discovery_method": "ads_txt_managerdomain", "manager_domain": "cafemedia.com", "properties_authorized": 3, "properties_total": 3, "property_ids": ["p-001", "p-002", "p-003"], "signing_keys_pinned": false, "status": "authorized", "last_verified_at": "2026-05-19T08:00:00Z" } ``` ## フィールドリファレンス ### エンベロープ | Field | Required | Notes | | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `agent_url` | yes | ルックアップキーの正準化エコー。 | | `directory_indexed_at` | yes | 結果セット内の最新のパブリッシャーごとリフレッシュ。消費者自身のキャッシュのプロベナンス。**空のページでは NULL** — レポートするアンカーがない。消費者は null 値からキャッシュ鮮度を進めるべきでない（SHOULD NOT）。 | | `publishers` | yes | 配列。空配列は有効なレスポンス — ディレクトリはこのエージェントをインデックスしたが現在の認可が解決しない。 | | `next_cursor` | optional | 不透明ページネーションカーソル。終端ページでは不在または null。 | ### `PublisherEntry` | Field | Required | Notes | | ----------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `publisher_domain` | yes | `adagents.json` がエージェントを認可するパブリッシャー。 | | `discovery_method` | yes | `direct`、`authoritative_location`、`adagents_authoritative`、または `ads_txt_managerdomain`。下記参照。 | | `manager_domain` | conditional | `discovery_method` ≠ `direct` のとき必須。それ以外は null。 | | `properties_authorized` | yes | エージェントのセレクターが解決する **この publisher\_domain のみ** の下のプロパティ数。決してネットワーク全体の数ではない。 | | `properties_total` | yes | パブリッシャーのファイル（またはそのドメインの親ファイルのインラインサブセット）内の **この publisher\_domain のみ** の下のプロパティ数。決してネットワーク全体の数ではない。 | | `property_ids` | conditional | リクエストが `?include=properties` を含んだとき、かつそのときのみ存在。エージェントのセレクターがこのパブリッシャーの下で解決する `property_id` の正準リスト — `properties_authorized` が数える同じ集団を、消費者がフェデレーテッドフェッチに対して完全な集合差分（数比較だけでなく）を実行できるよう ID として表示。パブリッシャーごとスコープ。決してネットワーク全体でない。集合として扱う。順序は未指定。 | | `signing_keys_pinned` | optional | パブリッシャーがこのエージェントに `signing_keys[]` をピン留めするか。`true` のとき、エージェントの署名付きレスポンスはエージェント自身の JWKS にかかわらずピン留めされた集合に対して検証されなければならない（MUST）。 | | `status` | yes | `authorized` または `revoked`。下記参照。 | | `last_verified_at` | yes | ディレクトリがこのパブリッシャーの `adagents.json` を最後にフェッチし検証したとき。 | ### `discovery_method` 値 | Value | Meaning | Trust profile | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `direct` | パブリッシャー自身の `/.well-known/adagents.json` にエージェントがリストされている。 | 最強 — 委譲ホップなし。 | | `authoritative_location` | パブリッシャーの `/.well-known/adagents.json` が、エージェントをリストするマネージャーファイルを指す `authoritative_location` を宣言。 | 強 — パブリッシャーが積極的に委譲。 | | `adagents_authoritative` | マネージャーファイル自身の `properties[]` がパブリッシャーのドメインを運ぶことで発見（[adcp#4825 インライン解決ルール](https://github.com/adcontextprotocol/adcp/issues/4825) に従い）。 | 中 — パブリッシャーはマネージャーファイルで名指されたが委譲を自身でホストしなかった。 | | `ads_txt_managerdomain` | マネージャーファイルを指すパブリッシャーの `ads.txt` `MANAGERDOMAIN=` ディレクティブ経由で発見。 | 最弱 — [`managerdomain` フォールバック安全ルール](/docs/governance/property/adagents#safety-rules-for-this-fallback) が唯一の肯定的クロスチェック。 | ディレクトリは `discovery_method: ads_txt_managerdomain` のロウを返す前に `managerdomain` 安全ルールを検証します — これがオペレーターごとの `ads.txt` クロールに対するディレクトリの主な付加価値です。 ### `status` 値 | Value | Meaning | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `authorized` | セレクターがこの publisher\_domain の下で 1 つ以上のプロパティに解決する。通常のケース。 | | `revoked` | パブリッシャーが以前エージェントを認可し、今や権威ファイルの `revoked_publisher_domains[]` にこの `publisher_domain` をリストする。失効が着地した後の最初の同期でトゥームストーンとして発行され、その後ドロップ。オペレーターが各パブリッシャーのキャッシュ TTL をポーリングせずに失効を伝播できる。 | `unbound`、`pending`、`unreachable`、`no_properties` は **意図的に v1 の一部でありません**。ディレクトリは `adagents.json` が正常にフェッチされエージェントを参照するパブリッシャーのみをインデックスします。パブリッシャーが消えた場合、ディレクトリはトゥームストーンを返すのではなく結果からそれをドロップします（消費者は先のページに対する集合差分でメンバーシップを追跡）。 ## HTTP セマンティクス | Status | Meaning | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- | | `200 OK` | ルックアップ成功。ボディは空の `publishers[]` を持ってもよい（MAY）。 | | `400 Bad Request` | 不正な形式の `agent_url`、無効なカーソル、未知の `status` 値、または繰り返しキーではなくカンマ区切りリストとして供給された `status`。 | | `404 Not Found` | ディレクトリはこの `agent_url` を参照するパブリッシャーを決してインデックスしていない。**`200` + 空とは区別される**（それはディレクトリがこのエージェントをインデックスしたが現在の認可が解決しないことを意味する）。 | | `429 Too Many Requests` | レート制限。`Retry-After` ヘッダーが設定される。バケットキー: `agent_url`（匿名）プラス IP（多層防御）。 | | `5xx` | ディレクトリエラー。消費者はバックオフでリトライすべき（SHOULD）。 | エンドポイントは `Cache-Control` と `ETag` を設定します。条件付き `GET`（`If-None-Match`）がワイヤーレベルのキャッシュメカニズムです。ボディの `directory_indexed_at` が消費者ロジックの鮮度アンカーです。 ## 認証 V1 は未認証です。パブリッシャー `adagents.json` ファイルは公開です。逆マップは公開です。レート制限が IP ベースからアイデンティティベースに卒業する場合、パスはエージェントの公開 JWKS をキーとする [RFC 9421](https://datatracker.ietf.org/doc/html/rfc9421) リクエスト署名を重ねる別の RFC です — エージェントはリクエストに署名することで `agent_url` を制御することを証明します。この RFC の範囲外。 ## ページネーション カーソルは不透明です。置換可能な文字列として扱い、そのまま返してください。ディレクトリは通知なしにカーソル形式を変更してもよい（MAY）。消費者はカーソル内容を解析してはなりません（MUST NOT）。 カーソルは少なくとも 1 つのディレクトリリフレッシュサイクルの間有効なままです。それを過ぎると、ディレクトリは `cursor_expired` を伴う `400` または最初からの再走査を伴う `200` を返してもよい（MAY） — 両方とも適合。消費者は先のリクエストの実時間を記録し、24 時間より古いカーソルの使用を拒否すべきです（SHOULD）。 ## 他のプリミティブとの関係 AAO ディレクトリは既存の SDK プリミティブを補完します: | Question | Primitive | Direction | | ------------------------------------------------------ | ---------------------------------------------------------- | ---------------------- | | *この* エージェントは *この* パブリッシャーの `adagents.json` にリストされているか? | `verify_agent_authorization(adagents_data, agent_url)` | プッシュ（パブリッシャー → エージェント） | | パブリッシャーのリストが与えられたとき、どれが私のエージェントを認可するか? | `fetch_agent_authorizations(agent_url, publisher_domains)` | プル、呼び出し元供給リスト | | **どのパブリッシャーが私のエージェントを認可するか?** | **`GET /v1/agents/{agent_url}/publishers`** | **プル、ディレクトリ供給リスト** | 最初の 2 つは、オペレーターが既にパブリッシャー集合を知っている質問に答えます。ディレクトリエンドポイントはオペレーターの実際の同期時の質問に答えます: 「私のパブリッシャー集合は何か?」 推奨ワークフロー: 1. `GET /v1/agents/{agent_url}/publishers` を呼んでパブリッシャー集合を発見。 2. レスポンスの各 `publisher_domain` について、オペレーターはトラストルートに対して再確認するためパブリッシャー自身の `adagents.json` に対して `verify_agent_authorization` を呼んでもよい（MAY）。ディレクトリの `last_verified_at` はクリティカルパスでのドメインごと検証の必要性を減らすが排除しない。 3. レスポンスの `properties_authorized` / `properties_total` をオペレーター向けスコープサマリーに、`signing_keys_pinned` フラグをどのエージェントがパブリッシャーのピンに一致する JWKS を公開しなければならないかを表示するために使う。 4. 分岐検出器（ディレクトリとパブリッシャーのライブ `adagents.json` が不一致のケースを捕捉）を実行するオペレーターは、`?include=properties` を要求し、ディレクトリの `property_ids[]` をフェデレーテッドフェッチに対して数ではなく集合として比較すべき（SHOULD）。N プロパティをローテートするパブリッシャーは両側で等しい数を生成する。集合比較のみがそれを捕捉する。 ## `publisher_properties` インライン解決との関係 マネージドネットワーク型親ファイル（[adcp#4825 インライン解決ルール](/docs/governance/property/adagents#resolution-paths) に従い）では、ディレクトリは `publisher_domain` でフィルターされた親ファイルのインライン `properties[]` から `properties_total` を計算します。このスケールでの厳格なフェデレーションは、ディレクトリリフレッシュごとパブリッシャーごとに N HTTP フェッチを要求します — オペレーターが持つのと同じスケール問題が 1 レイヤー上に移動しただけ。ディレクトリは仕様が承認するインライン解決ルールを使います。 ## 範囲外（v1） * **認証。** 公開エンドポイント、匿名レート制限。アイデンティティバウンドの制限は必要なら別の RFC で到達。 * **クロスディレクトリフェデレーション。** 単一ディレクトリ。エンドポイント形状は、複数の AAO 互換ディレクトリがそれを実装できるよう定義されている。どのディレクトリをクエリするかのディスカバリーは今日は構成。 * **新しい認可のプッシュ通知。** ポーリングベースの v1。 * **完全なプロパティオブジェクトのインライン。** `?include=properties` は解決された `property_ids[]` のみを返す — プロパティオブジェクト自体ではない。ID を持つ消費者は既存のドメインごとプリミティブ経由で詳細をフェッチできる。 ## 関連項目 * [adagents.json 技術仕様](/docs/governance/property/adagents) — トラストルート。 * [マネージドネットワークデプロイ](/docs/governance/property/managed-networks) — このエンドポイントがインデックスする正準マルチパブリッシャーパターン。 * [adcp#4825](https://github.com/adcontextprotocol/adcp/issues/4825) — ディレクトリの数フィールドが依存する `publisher_properties` インライン解決ルール。