AdCP — adagents.json 技術仕様

adagents.json は、パブリッシャーがプロパティを宣言し、セールスエージェントを認可するための標準的な手段を提供します。Property Governance の土台であり、何が存在し誰が販売できるかを定義します。

AdAgents.json Builder - 既存ファイルの検証やガイド付きでの新規作成に利用できます

配置場所

パブリッシャーは adagents.json を次の場所に配置する必要があります:

https://example.com/.well-known/adagents.json

RFC 8615 の well-known URI に従うことで、一貫した発見性を確保します。

基本構造

ファイルは UTF-8 の有効な JSON で、HTTP 200 を返す必要があります。

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/adagents.json",
  "contact": {
    "name": "Example Publisher Ad Operations",
    "email": "adops@example.com",
    "domain": "example.com",
    "seller_id": "pub-example-12345",
    "tag_id": "67890"
  },
  "properties": [
    {
      "property_id": "example_site",
      "property_type": "website",
      "name": "Example Site",
      "identifiers": [
        {"type": "domain", "value": "example.com"}
      ]
    }
  ],
  "authorized_agents": [
    {
      "url": "https://agent.example.com",
      "authorized_for": "Official sales agent",
      "authorization_type": "property_ids",
      "property_ids": ["example_site"]
    }
  ],
  "last_updated": "2025-01-10T12:00:00Z"
}

スキーマフィールド

$schema (任意): 検証用の JSON Schema 参照 contact (任意): ファイル管理主体の連絡先

name (必須): 管理主体名（パブリッシャーまたは第三者）
email (任意): 問い合わせ先メール
domain (任意): 管理主体のドメイン
seller_id (任意): IAB Tech Lab sellers.json の Seller ID
tag_id (任意): TAG Certified Against Fraud ID
privacy_policy_url (任意): 消費者同意フロー用のプライバシーポリシー URL

properties (任意): このファイルで扱うプロパティの配列（正規定義）

supported_channels (任意): このプロパティがサポートする広告チャネルの配列（例: ["display", "olv", "social"]）。Media Channel Taxonomy を参照。

tags (任意): 人が読みやすく、グルーピングに使えるタグメタデータ authorized_agents (必須): 認可されたセールスエージェントの配列

url (必須): エージェントの API エンドポイント
authorized_for (必須): 認可内容の説明
authorization_type (任意): property_ids, property_tags, inline_properties, publisher_properties のいずれか
追加フィールド: authorization_type に依存（後述のパターン参照）

last_updated (任意): 最終更新日時（ISO 8601） property_features (任意): このファイル内プロパティに関するデータを提供するガバナンスエージェントの配列

url (必須): ガバナンスエージェントの API エンドポイント
name (必須): ベンダー/エージェント名（人が読める名前）
features (必須): 提供する Feature ID の配列（例: ["carbon_score", "mfa_score"]）
publisher_id (任意): そのエージェント側でのパブリッシャー識別子

このフィールドにより ガバナンスエージェントの発見 が可能になり、バイヤーは全エージェントを総当たりせずに、どのエージェントがコンプライアンス/サステナビリティ/品質データを持つかを把握できます。

URL 参照パターン

複雑なインフラや CDN 配信を行うパブリッシャーは、全文を埋め込む代わりに信頼できる URL への参照を記載できます。

URL 参照を使う場合

CDN 配信: 認可データをグローバル CDN から配信
集中管理: 複数ドメインを単一のソースで管理
大規模ファイル: インライン埋め込みには大きすぎる場合
動的更新: ドメイン上のファイルを触らず頻繁に更新したい場合

URL 参照の構造

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/adagents.json",
  "authoritative_location": "https://cdn.example.com/adagents/v2/adagents.json",
  "last_updated": "2025-01-15T10:00:00Z"
}

要件

HTTPS 必須: authoritative_location は HTTPS を使用
入れ子禁止: 参照先がさらに URL 参照であってはなりません（無限ループ防止）
同一スキーマ: 参照先は有効なインライン adagents.json 構造であること
1 ホップのみ: URL 間接参照は 1 段階まで

ユースケース: 複数ドメインを持つパブリッシャー

複数ドメインを持つパブリッシャーは 1 つの権威ファイルを維持できる: 各ドメイン上 (https://domain1.com/.well-known/adagents.json, https://domain2.com/.well-known/adagents.json など):

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/adagents.json",
  "authoritative_location": "https://cdn.publisher.com/adagents/v2/adagents.json",
  "last_updated": "2025-01-15T10:00:00Z"
}

権威ファイル (https://cdn.publisher.com/adagents/v2/adagents.json):

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/adagents.json",
  "contact": {
    "name": "Publisher Ad Operations",
    "email": "adops@publisher.com"
  },
  "properties": [
    {
      "property_id": "domain1_site",
      "property_type": "website",
      "name": "Domain 1",
      "identifiers": [{"type": "domain", "value": "domain1.com"}],
      "publisher_domain": "domain1.com"
    },
    {
      "property_id": "domain2_site",
      "property_type": "website",
      "name": "Domain 2",
      "identifiers": [{"type": "domain", "value": "domain2.com"}],
      "publisher_domain": "domain2.com"
    }
  ],
  "authorized_agents": [
    {
      "url": "https://sales-agent.publisher.com",
      "authorized_for": "All publisher properties",
      "authorization_type": "property_ids",
      "property_ids": ["domain1_site", "domain2_site"]
    }
  ],
  "last_updated": "2025-01-15T09:00:00Z"
}

検証時の挙動

AdCP の検証で URL 参照が見つかった場合:

参照取得: /.well-known/adagents.json を取得
参照検出: authoritative_location を確認
URL 検証: authoritative_location が HTTPS かつ有効か確認
参照先取得: authoritative_location の内容を取得
ループ防止: 参照先がさらに参照でないことを確認
構造検証: 参照先を通常のインライン構造として検証

キャッシュ推奨

参照ファイルは最低 24 時間キャッシュ
権威ファイルは別途 TTL を設定してキャッシュ
last_updated でキャッシュ無効化を判断
取得失敗時は指数バックオフを実装

認可パターン

AdCP は 4 種の認可パターンをサポートし、用途に最適化されています:

パターン 1: Property IDs（直接参照）

最適な用途: 具体的で列挙可能なプロパティリスト。明確で曖昧さがない。構造:

{
  "properties": [
    {
      "property_id": "cnn_ctv_app",
      "property_type": "ctv_app",
      "name": "CNN CTV App",
      "identifiers": [
        {"type": "roku_store_id", "value": "12345"}
      ]
    }
  ],
  "authorized_agents": [
    {
      "url": "https://cnn-ctv-agent.com",
      "authorized_for": "CNN CTV properties",
      "authorization_type": "property_ids",
      "property_ids": ["cnn_ctv_app"]
    }
  ]
}

仕組み: エージェントは property_ids 配列に列挙された特定プロパティのみを認可されます。プロパティはトップレベルの properties 配列で定義されていなければなりません。

パターン 2: Property Tags（効率的なグルーピング）

最適な用途: 1 つのタグで数百〜数千のプロパティを参照できる大規模ネットワーク。全 property_id を列挙せずにグルーピング効率を実現します。 重要な観点: タグは単なる「人が読めるメタデータ」ではなく、パフォーマンス最適化です。500 プロパティを持つパブリッシャーは 1 つのタグで全プロパティを認可でき、500 個の property_id を列挙する必要がない。構造:

{
  "properties": [
    {
      "property_id": "instagram",
      "property_type": "mobile_app",
      "name": "Instagram",
      "identifiers": [
        {"type": "ios_bundle", "value": "com.burbn.instagram"}
      ],
      "tags": ["meta_network", "social_media"]
    },
    {
      "property_id": "facebook",
      "property_type": "mobile_app",
      "name": "Facebook",
      "identifiers": [
        {"type": "ios_bundle", "value": "com.facebook.Facebook"}
      ],
      "tags": ["meta_network", "social_media"]
    }
  ],
  "tags": {
    "meta_network": {
      "name": "Meta Network",
      "description": "All Meta-owned properties - enables one tag to authorize entire network"
    }
  },
  "authorized_agents": [
    {
      "url": "https://meta-ads.com",
      "authorized_for": "All Meta properties",
      "authorization_type": "property_tags",
      "property_tags": ["meta_network"]
    }
  ]
}

仕組み: エージェントはリストされたタグのいずれかを持つすべてのプロパティを認可されます。プロパティは各プロパティ定義の tags 配列と照合されます。

パターン 3: Inline Properties

最適な用途: トップレベルのプロパティ宣言なしに小規模・特定のプロパティ集合を扱う場合。構造:

{
  "authorized_agents": [
    {
      "url": "https://agent.com",
      "authorized_for": "Specific inventory",
      "authorization_type": "inline_properties",
      "properties": [
        {
          "property_type": "website",
          "name": "Example Site",
          "identifiers": [
            {"type": "domain", "value": "example.com"}
          ]
        }
      ]
    }
  ]
}

仕組み: プロパティはトップレベルの properties 配列ではなく、エージェント認可エントリ内で直接定義されます。各エージェントが固有のプロパティ定義を持つ場合に便利。

パターン 4: Publisher Property References

最適な用途: 複数のパブリッシャーを代表するサードパーティエージェント。プロパティ定義の単一のソース・オブ・トゥルース。構造:

{
  "contact": {
    "name": "Third-Party CTV Network"
  },
  "authorized_agents": [
    {
      "url": "https://ctv-network.com/api",
      "authorized_for": "CTV inventory from multiple publishers",
      "authorization_type": "publisher_properties",
      "publisher_properties": [
        {
          "publisher_domain": "cnn.com",
          "selection_type": "by_tag",
          "property_tags": ["ctv"]
        },
        {
          "publisher_domain": "espn.com",
          "selection_type": "by_tag",
          "property_tags": ["ctv"]
        }
      ]
    }
  ]
}

仕組み: エージェントは他のパブリッシャーの adagents.json ファイルからプロパティを参照します。publisher_domain でパブリッシャーを指定し、selection_type でプロパティの解決方法（by_id または by_tag）を決定します。

ドメインマッチングルール

ドメイン識別子を持つウェブサイトプロパティについて、AdCP はウェブの慣例に従います。

ベースドメイン（`example.com`）

ドメイン本体と標準的なウェブサブドメインにマッチします。

✅ example.com
✅ www.example.com（標準ウェブ）
✅ m.example.com（標準モバイル）
❌ subdomain.example.com（明示的な認可が必要）

特定サブドメイン（`subdomain.example.com`）

その特定サブドメインのみにマッチします。

✅ subdomain.example.com
❌ その他のすべてのドメイン/サブドメイン

ワイルドカード（`*.example.com`）

すべてのサブドメインにマッチしますが、ベースドメインはマッチしません。

✅ 任意のサブドメイン
❌ example.com（ベースドメインは別途認可が必要）

Real-World Examples

Example 1: Meta Network (Tag-Based)

Large network using tags for grouping efficiency:

{
  "contact": {
    "name": "Meta Advertising Operations",
    "email": "adops@meta.com",
    "domain": "meta.com",
    "seller_id": "pub-meta-12345",
    "tag_id": "12345",
    "privacy_policy_url": "https://www.meta.com/privacy/policy"
  },
  "properties": [
    {
      "property_type": "mobile_app",
      "name": "Instagram",
      "identifiers": [
        {"type": "ios_bundle", "value": "com.burbn.instagram"},
        {"type": "android_package", "value": "com.instagram.android"}
      ],
      "tags": ["meta_network"],
      "publisher_domain": "instagram.com"
    },
    {
      "property_type": "mobile_app",
      "name": "Facebook",
      "identifiers": [
        {"type": "ios_bundle", "value": "com.facebook.Facebook"},
        {"type": "android_package", "value": "com.facebook.katana"}
      ],
      "tags": ["meta_network"],
      "publisher_domain": "facebook.com"
    },
    {
      "property_type": "mobile_app",
      "name": "WhatsApp",
      "identifiers": [
        {"type": "ios_bundle", "value": "net.whatsapp.WhatsApp"},
        {"type": "android_package", "value": "com.whatsapp"}
      ],
      "tags": ["meta_network"],
      "publisher_domain": "whatsapp.com"
    }
  ],
  "tags": {
    "meta_network": {
      "name": "Meta Network",
      "description": "All Meta-owned properties - one tag authorizes entire network efficiently"
    }
  },
  "authorized_agents": [
    {
      "url": "https://meta-ads.com",
      "authorized_for": "All Meta properties",
      "authorization_type": "property_tags",
      "property_tags": ["meta_network"]
    }
  ]
}

Why this works: One tag (meta_network) authorizes all properties without listing individual property IDs. As Meta adds properties, they just tag them - no need to update agent authorization.

Example 2: CNN (Channel Segmentation)

Different agents for different channels:

{
  "contact": {
    "name": "CNN Advertising Operations",
    "email": "adops@cnn.com",
    "domain": "cnn.com"
  },
  "properties": [
    {
      "property_id": "cnn_ctv_app",
      "property_type": "ctv_app",
      "name": "CNN CTV App",
      "identifiers": [
        {"type": "roku_store_id", "value": "12345"}
      ],
      "tags": ["ctv"]
    },
    {
      "property_id": "cnn_web_us",
      "property_type": "website",
      "name": "CNN.com US",
      "identifiers": [
        {"type": "domain", "value": "cnn.com"}
      ],
      "tags": ["web"]
    }
  ],
  "authorized_agents": [
    {
      "url": "https://cnn-ctv-agent.com",
      "authorized_for": "CNN CTV properties",
      "authorization_type": "property_ids",
      "property_ids": ["cnn_ctv_app"]
    },
    {
      "url": "https://cnn-web-agent.com",
      "authorized_for": "CNN web properties",
      "authorization_type": "property_ids",
      "property_ids": ["cnn_web_us"]
    }
  ]
}

Example 3: Publisher with Governance Agent References

Publishers can declare which governance agents have data about their properties using property_features. This enables buyers to discover where to get sustainability, quality, and suitability data.

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/adagents.json",
  "contact": {
    "name": "Premium News Publisher",
    "email": "adops@news.example.com",
    "domain": "news.example.com"
  },
  "properties": [
    {
      "property_id": "news_main",
      "property_type": "website",
      "name": "News Example",
      "identifiers": [
        {"type": "domain", "value": "news.example.com"}
      ],
      "tags": ["premium", "news"],
      "publisher_domain": "news.example.com"
    }
  ],
  "tags": {
    "premium": {
      "name": "Premium Properties",
      "description": "High-quality, brand-suitable properties"
    },
    "news": {
      "name": "News Properties",
      "description": "News and journalism content"
    }
  },
  "authorized_agents": [
    {
      "url": "https://sales.news.example.com",
      "authorized_for": "All news properties",
      "authorization_type": "property_tags",
      "property_tags": ["news"]
    }
  ],
  "property_features": [
    {
      "url": "https://api.sustainability-vendor.example",
      "name": "Sustainability Vendor",
      "features": ["carbon_score", "green_media_certified"],
      "publisher_id": "pub_news_12345"
    },
    {
      "url": "https://api.quality-vendor.example",
      "name": "Quality Vendor",
      "features": ["mfa_score", "ad_density", "page_speed"]
    },
    {
      "url": "https://api.suitability-vendor.example",
      "name": "Suitability Vendor",
      "features": ["content_category", "brand_risk_score", "sentiment"],
      "publisher_id": "suit_news_67890"
    }
  ],
  "last_updated": "2025-01-10T18:00:00Z"
}

Why this works:

Publishers declare relationships with governance agents upfront
Buyers discover governance agents by reading adagents.json (no need to query every possible agent)
The publisher_id field helps agents look up the publisher’s data efficiently
Feature IDs tell buyers what data types are available without querying

Governance Agent Discovery

The property_features field solves a key discovery problem: how does a buyer know which governance agents have data about a given property?

When to Use property_features

Scenario	Use property_features?
Publisher has carbon scoring from a sustainability vendor	✅ Yes
Publisher has MFA score measured by a quality vendor	✅ Yes
Publisher has content classification from a suitability vendor	✅ Yes
Publisher self-reports brand suitability	❌ No - use property tags
Sales agent provides quality data	❌ No - that’s agent capability

Vendor Extensions

Governance agents can include vendor-specific data in feature definitions via an ext block. See get_adcp_capabilities for details.

Fetching and Validating

Using the AdAgents.json Builder

The easiest way to validate or create an adagents.json file is using the AdAgents.json Builder web tool. It provides:

Domain validation (fetches and checks /.well-known/adagents.json)
Structure validation against the JSON schema
Agent card endpoint verification (checks if agent URLs respond correctly)
Guided file creation with proper formatting

Programmatic Validation

For programmatic validation, use the validation API:

// Validate a domain's adagents.json file
const response = await fetch('https://adcontextprotocol.org/api/adagents/validate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ domain: 'example.com' })
});

const { success, data } = await response.json();

if (success && data.found) {
  console.log(`Valid: ${data.validation.valid}`);
  console.log(`Agents: ${data.validation.raw_data?.authorized_agents?.length || 0}`);

  // Check for any validation errors
  if (data.validation.errors?.length > 0) {
    console.log('Errors:', data.validation.errors.map(e => e.message));
  }
} else {
  console.log('No adagents.json found at this domain');
}

The validation API fetches https://{domain}/.well-known/adagents.json, validates its structure, follows URL references if present, and optionally checks agent card endpoints.

Using AdCP Client Libraries

The AdCP client libraries provide built-in validation and authorization checking:

import asyncio
from adcp import fetch_adagents, verify_agent_authorization

async def validate_authorization():
    # Fetch and validate adagents.json from a publisher domain
    adagents_data = await fetch_adagents('example-publisher.com')

    # Check if a specific agent is authorized
    is_authorized = verify_agent_authorization(
        adagents_data=adagents_data,
        agent_url='https://our-sales-agent.com',
        property_type='website',
        property_identifiers=[{'type': 'domain', 'value': 'example-publisher.com'}]
    )

    print(f"Agent authorized: {is_authorized}")
    print(f"Total agents: {len(adagents_data.get('authorized_agents', []))}")

asyncio.run(validate_authorization())

The Python library handles validation automatically when fetching - if the adagents.json file is malformed or missing required fields, it raises AdagentsValidationError.

Best Practices

1. Use Appropriate Authorization Pattern

Property IDs: Small, enumerable lists (< 20 properties)
Property Tags: Large networks (100+ properties)
Inline Properties: Simple cases without top-level properties
Publisher Properties: Third-party agents representing multiple publishers

2. Cache Files Appropriately

Cache for 24 hours minimum
Use last_updated timestamp to detect staleness
Handle 404 as “no file” (not an error - proceed without validation)
Implement retry logic with exponential backoff for network errors

3. Validate Structure

Validate against JSON schema before processing
Check required fields exist (authorized_agents array)
Verify authorization scope matches product claims
Cross-reference with seller.json if available

4. Handle Missing Files Gracefully

404 status = No file present (not an authorization failure)
Absence of file does not mean agent is unauthorized
Use adagents.json as verification, not requirement

Next Steps

After implementing adagents.json validation:

Integrate with Product Discovery: Use get_products to discover inventory
Validate at Purchase: Check authorization before calling create_media_buy
Cache Property Mappings: Store resolved properties for efficient validation
Monitor Authorization: Track validation success rates and unauthorized attempts

Learn More

AdCP Basics: Authorized Properties - Accessible introduction to AdCP authorization
get_adcp_capabilities - Discover agent capabilities and portfolio
Property Schema - Property definition structure
AdAgents.json Builder - Web-based validator and creator

Getting Started

Building with AdCP

Governance Protocol

Signals Protocol

Curation Protocol

Sponsored Intelligence Protocol

Media Buy Protocol

Creative

Reference

Community

​配置場所

​基本構造

​スキーマフィールド

​URL 参照パターン

​URL 参照を使う場合

​URL 参照の構造

​要件

​ユースケース: 複数ドメインを持つパブリッシャー

​検証時の挙動

​キャッシュ推奨

​認可パターン

​パターン 1: Property IDs（直接参照）

​パターン 2: Property Tags（効率的なグルーピング）

​パターン 3: Inline Properties

​パターン 4: Publisher Property References

​ドメインマッチングルール

​ベースドメイン（example.com）

​特定サブドメイン（subdomain.example.com）

​ワイルドカード（*.example.com）

​Real-World Examples

​Example 1: Meta Network (Tag-Based)

​Example 2: CNN (Channel Segmentation)

​Example 3: Publisher with Governance Agent References

​Governance Agent Discovery

​When to Use property_features

​Vendor Extensions

​Fetching and Validating

​Using the AdAgents.json Builder

​Programmatic Validation

​Using AdCP Client Libraries

​Best Practices

​1. Use Appropriate Authorization Pattern

​2. Cache Files Appropriately

​3. Validate Structure

​4. Handle Missing Files Gracefully

​Next Steps

​Learn More

配置場所

基本構造

スキーマフィールド

URL 参照パターン

URL 参照を使う場合

URL 参照の構造

要件

ユースケース: 複数ドメインを持つパブリッシャー

検証時の挙動

キャッシュ推奨

認可パターン

パターン 1: Property IDs（直接参照）

パターン 2: Property Tags（効率的なグルーピング）

パターン 3: Inline Properties

パターン 4: Publisher Property References

ドメインマッチングルール

ベースドメイン（`example.com`）

特定サブドメイン（`subdomain.example.com`）

ワイルドカード（`*.example.com`）

Real-World Examples

Example 1: Meta Network (Tag-Based)

Example 2: CNN (Channel Segmentation)

Example 3: Publisher with Governance Agent References

Governance Agent Discovery

When to Use property_features

Vendor Extensions

Fetching and Validating

Using the AdAgents.json Builder

Programmatic Validation

Using AdCP Client Libraries

Best Practices

1. Use Appropriate Authorization Pattern

2. Cache Files Appropriately

3. Validate Structure

4. Handle Missing Files Gracefully

Next Steps

Learn More