adagents.json 技術仕様 - AdCP

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/v2/adagents.json",
  "contact": {
    "name": "Example Publisher Ad Operations",
    "email": "[email protected]",
    "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 (任意): このファイルで扱うプロパティの配列（正規定義） 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 (必須): ベンダー/エージェント名（例: “Scope3”, “TAG”, “OneTrust”）
features (必須): 提供する Feature ID の配列（例: ["carbon_score", "gdpr_compliant"]）
publisher_id (任意): そのエージェント側でのパブリッシャー識別子

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

URL 参照パターン

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

URL 参照を使う場合

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

URL 参照の構造

{
  "$schema": "https://adcontextprotocol.org/schemas/v2/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 段階まで

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

A publisher with multiple domains can maintain one authoritative file: On each domain (https://domain1.com/.well-known/adagents.json, https://domain2.com/.well-known/adagents.json, etc.):

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

Authoritative file (https://cdn.publisher.com/adagents/v2/adagents.json):

{
  "$schema": "https://adcontextprotocol.org/schemas/v2/adagents.json",
  "contact": {
    "name": "Publisher Ad Operations",
    "email": "[email protected]"
  },
  "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 種の認可パターンをサポートし、用途に最適化されています:

Pattern 1: Property IDs (Direct References)

Best for: Specific, enumerable property lists. Direct and unambiguous. Structure:

{
  "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"]
    }
  ]
}

How it works: Agent is authorized for specific properties listed in property_ids array. The properties must be defined in the top-level properties array.

Pattern 2: Property Tags (Efficient Grouping)

Best for: Large networks where one tag can reference hundreds/thousands of properties. Provides grouping efficiency without listing every property ID. Key Insight: Tags are not just “human-readable metadata” - they’re a performance optimization. A publisher with 500 properties can use one tag to authorize all of them, rather than listing 500 property IDs. Structure:

{
  "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"]
    }
  ]
}

How it works: Agent is authorized for all properties that have ANY of the listed tags. Properties are matched against the tags array in each property definition.

Pattern 3: Inline Properties

Best for: Small, specific property sets without top-level property declarations. Structure:

{
  "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"}
          ]
        }
      ]
    }
  ]
}

How it works: Properties are defined directly within the agent authorization entry instead of the top-level properties array. Useful when each agent has unique property definitions.

Pattern 4: Publisher Property References

Best for: Third-party agents representing multiple publishers. Single source of truth for property definitions. Structure:

{
  "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"]
        }
      ]
    }
  ]
}

How it works: Agent references properties from OTHER publishers’ adagents.json files. The publisher_domain points to the publisher, and selection_type determines how to resolve properties (by_id or by_tag).

Domain Matching Rules

For website properties with domain identifiers, AdCP follows web conventions:

Base Domain (`example.com`)

Matches domain plus standard web subdomains:

✅ example.com
✅ www.example.com (standard web)
✅ m.example.com (standard mobile)
❌ subdomain.example.com (requires explicit authorization)

Specific Subdomain (`subdomain.example.com`)

Matches only that exact subdomain:

✅ subdomain.example.com
❌ All other domains/subdomains

Wildcard (`*.example.com`)

Matches ALL subdomains but NOT base:

✅ Any subdomain
❌ example.com (base domain requires separate authorization)

Real-World Examples

Example 1: Meta Network (Tag-Based)

Large network using tags for grouping efficiency:

{
  "contact": {
    "name": "Meta Advertising Operations",
    "email": "[email protected]",
    "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": "[email protected]",
    "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 compliance, sustainability, and quality data.

{
  "$schema": "https://adcontextprotocol.org/schemas/v2/adagents.json",
  "contact": {
    "name": "Premium News Publisher",
    "email": "[email protected]",
    "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-safe 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.scope3.com",
      "name": "Scope3",
      "features": ["carbon_score", "sustainability_grade"],
      "publisher_id": "pub_news_12345"
    },
    {
      "url": "https://api.tagtoday.net",
      "name": "TAG",
      "features": ["tag_certified_against_fraud", "tag_brand_safety_certified"]
    },
    {
      "url": "https://api.onetrust.com",
      "name": "OneTrust",
      "features": ["gdpr_compliant", "tcf_registered", "ccpa_compliant"],
      "publisher_id": "ot_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 Scope3	✅ Yes
Publisher is TAG certified	✅ Yes
Publisher tracks consent via OneTrust	✅ Yes
Publisher self-reports brand safety	❌ 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 参照の構造

​要件

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

​検証時の挙動

​キャッシュ推奨

​認可パターン

​Pattern 1: Property IDs (Direct References)

​Pattern 2: Property Tags (Efficient Grouping)

​Pattern 3: Inline Properties

​Pattern 4: Publisher Property References

​Domain Matching Rules

​Base Domain (example.com)

​Specific Subdomain (subdomain.example.com)

​Wildcard (*.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 参照の構造

要件

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

検証時の挙動

キャッシュ推奨

認可パターン

Pattern 1: Property IDs (Direct References)

Pattern 2: Property Tags (Efficient Grouping)

Pattern 3: Inline Properties

Pattern 4: Publisher Property References

Domain Matching Rules

Base Domain (`example.com`)

Specific Subdomain (`subdomain.example.com`)

Wildcard (`*.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