> ## 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.

# 実装者向け FAQ

> AdCP 実装者のための質問と回答

AdCP の営業エージェントや統合を構築するチームから寄せられる一般的な質問に、仕様に基づいた回答をまとめました。

## プロダクト探索

### Q: `get_products` では予算、日付、目標などの特定パラメーターが必須ですか?

**A:** 現時点で `get_products` のパラメーターは `brief`（自然言語文字列）、`brand_manifest`、`filters`（構造化フィルター）の 3 つのみです。予算、日付、目標などのキャンペーン詳細は自然言語の `brief` に含めてください。

**将来:** 会話の往復を減らすため、予算・日付・目標・ターゲティングの構造化パラメーターを検討しています。最新情報はロードマップを確認してください。

**現在の回避策:** これらの詳細をブリーフに含めます:

```json theme={null}
{
  "brand_manifest": {
    "name": "Acme Corp",
    "url": "https://acmecorp.com"
  },
  "brief": "Tech startup needs display and video inventory to reach IT decision makers. Budget: $25K. Timeline: March 1-31. Objective: Lead generation with 2% conversion target."
}
```

### Q: `get_products` で特定のオーディエンスターゲティングを指定するには?

**A:** すべてのターゲティング指定は現在、自然言語の `brief` に記述します。まだ構造化されたターゲティングフィルターはありません。

**例:**

```json theme={null}
{
  "brand_manifest": {
    "name": "Energy Drink Co",
    "url": "https://energydrink.com"
  },
  "brief": "Target sports fans, ages 18-34, in major US cities for energy drink campaign"
}
```

パブリッシャーの AI がこれを解釈し、関連するプロダクトを返します。将来のバージョンで構造化ターゲティングフィルターが追加される可能性があります。

### Q: 「no brief = 標準カタログ」とは? 標準カタログがありません。

**A:** バイヤーが `brief` フィールドを省略すると、標準カタログの要求になります。これは、カスタムレコメンドなしで全広告主に提供するベースラインのプロダクトです。

**標準カタログを提供していない場合** はエラーを返します:

```json theme={null}
{
  "message": "We require a campaign brief to recommend products. Please provide details about your campaign goals, audience, and objectives.",
  "products": []
}
```

**標準カタログを提供している場合** は、指定されたフィルター（フォーマットタイプ、デリバリータイプなど）に合う標準プロダクトを返してください。

### Q: バイヤーは `get_products` の前後どちらで `list_creative_formats` を呼ぶべきですか?

**A:** **`get_products` の後** です。推奨フローは以下の通り:

1. キャンペーンブリーフ/フィルターとともに `get_products` を呼ぶ
2. 返されたプロダクトを確認する（`format_ids` 配列を含む）
3. 詳細が必要なフォーマット ID について `list_creative_formats` を呼ぶ
4. クリエイティブ要件が自社の能力と合致するか検証します
5. 選択したプロダクトで `create_media_buy` を呼ぶ

**理由:** どのフォーマット ID が必要かは、利用可能なプロダクトを確認するまで分かりません。すべてのフォーマットを最初に取得するのは非効率です。

## ポリシーコンプライアンス

### Q: パブリッシャーは広告ポリシーの問題（アルコール、アダルトなど）をどう把握しますか?

**A:** パブリッシャーは `brand_manifest` フィールドから広告主のアイデンティティを抽出します:

1. `brand_manifest.name`, `brand_manifest.url`, 任意の `brand_manifest.category` から **広告主情報を抽出**
2. `brief` テキストから **何がプロモートされているか確認**
3. 自社ポリシーに基づき **ポリシールールを適用**
4. **適切なレスポンスを返します:**
   * Allowed: プロダクトを通常返す
   * Blocked: ポリシー説明付きで products を空配列にします
   * Restricted: 手動承認が必要な旨を示します

**Example blocked response:**

```json theme={null}
{
  "message": "I'm unable to offer products for this campaign. Our publisher policy prohibits alcohol advertising without age verification capabilities.",
  "products": []
}
```

[Policy Compliance](/docs/media-buy/media-buys/policy-compliance) に完全な実装ガイドがあります。

### Q: 広告主名は常に共有されますか?

**A:** はい。`brand_manifest` フィールドは `get_products` と `create_media_buy` の両方で必須です。これは次のために必要な広告主の識別子を提供します:

* ポリシーコンプライアンスチェック
* ビジネス関係管理（KYC）
* 請求・レポート

Minimal manifests are simple:

```json theme={null}
{
  "brand_manifest": {
    "name": "Acme Corp",
    "url": "https://acmecorp.com"
  }
}
```

任意の `category` フィールド（例: `"athletic_apparel"`, `"alcohol"`, `"pharma"`）は自動ポリシーフィルタリングに役立ちます。

## スキーマとフィールド

### Q: `filters` パラメーターが「オブジェクト」と呼ばれるのはなぜですか?

**A:** 複数の任意フィールドを持つ入れ子の JSON オブジェクトだからです:

```json theme={null}
{
  "filters": {
    "delivery_type": "guaranteed",
    "format_types": ["video", "display"],
    "standard_formats_only": true,
    "is_fixed_price": true,
    "min_exposures": 10000
  }
}
```

単一のフィルターではなく、プロダクトカタログ検索のフィルター条件集合です。

### Q: なぜ `ad_units` ではなく `format_ids` なのですか?

**A:** AdCP はプロトコル非依存の用語を採用しています:

* **`format_ids`**: クリエイティブフォーマット仕様への構造化参照（例: `{agent_url: "...", id: "video_30s_hosted"}`）
* **Ad units**: 「300x250 バナー」のようなプラットフォーム固有の用語

フォーマットはすべての広告プラットフォームで機能する抽象的な仕様です。`_ids` サフィックスは参照であることを示し、完全なフォーマットオブジェクトは `list_creative_formats` で取得します。

### Q: 以前のドキュメントにあった `promoted_offering` フィールドはどこにありますか?

**A:** それは以前のバージョンのドキュメント誤りです。実際の API に **このフィールドは存在しません**。

正しい方法は次の通りです:

* **広告主の識別子** → `brand_manifest.name` と `brand_manifest.url`（必須）
* **プロモーション内容** → `brief` フィールドで記述（任意）

Example:

```json theme={null}
{
  "brand_manifest": {
    "name": "Nike",
    "url": "https://nike.com",
    "category": "athletic_apparel"
  },
  "brief": "Nike Air Max 2024 - latest innovation in cushioning technology targeting runners and fitness enthusiasts"
}
```

## ブリーフの扱い

### Q: バイヤーが不完全なブリーフを提供したらどうする?

**A:** 重要情報が欠けている場合、パブリッシャーは明確化を求めるべきです:

```json theme={null}
{
  "message": "I'd be happy to help find the right products for your campaign. To provide the best recommendations, could you share:\n\n• What's your campaign budget?\n• When do you want the campaign to run?\n• Which geographic markets are you targeting?",
  "products": []
}
```

これにより必要なコンテキストを集めつつ、会話的で親切な対応を維持できます。

### Q: 常に明確化を求めるべきですか、それともそのままプロダクトを返しますか?

**A:** パブリッシャーの戦略によります:

* **ハイタッチ型**: 不完全なブリーフには明確化を求め、会話的に対応します
* **セルフサービス型**: 利用可能な情報を基にベストなプロダクトを返す

どちらも有効です。ターゲットバイヤーのペルソナと自動化レベルに合わせて選択してください。

## ワークフローと統合

### Q: `brand_manifest` を必須とする場面と任意とする場面は?

**A:** 現行仕様では次の通りです:

* **`get_products` と `create_media_buy` の両方で必須**

ベストプラクティス: 常に必須にします。ポリシーチェックは購入時ではなく探索時に行うべきです。

### Q: バイヤーはプロダクトレスポンスをキャッシュできますか?

**A:** プロダクトは時間とともに変化する在庫状況を表します。推奨は次の通りです:

* **ブリーフベースの探索**: キャッシュしない — プロダクトはブリーフに基づいてコンテキストマッチされるため
* **標準カタログ**: カタログが安定していれば短時間（5〜15 分）キャッシュ可
* **プロダクト詳細**: `product_id` のマッピングはキャッシュ可能だが、購入前に在庫を再検証します

### Q: 1000 件以上の大規模プロダクトカタログはどう扱う?

**A:** 完全な `properties` 配列の代わりに `property_tags` を使用します:

```json theme={null}
{
  "product_id": "local_radio_midwest",
  "property_tags": ["local_radio", "midwest"],
  "format_ids": [...]
}
```

バイヤーは [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities) を通じてエージェントのポートフォリオ（パブリッシャードメインや主要チャネル）を把握できます。これによりレスポンスを軽量に保ちながら検証機能を維持できます。

## テストとバリデーション

### Q: ポリシーコンプライアンスをどうテストしますか?

**A:** Create test cases with known restricted categories:

```javascript theme={null}
// Test blocked category
const response = await get_products({
  brand_manifest: {
    name: "Test Alcohol Brand",
    url: "https://test-alcohol.example.com",
    category: "alcohol"
  },
  brief: "Promote our new craft beer"
});

assert(response.products.length === 0);
assert(response.message.includes("policy"));
```

### Q: 統合テストで何を検証すべきですか?

**A:** 次の主要シナリオをカバーしてください:

1. **ブリーフなし + フィルターあり** → 標準カタログ
2. **ブリーフあり** → `brief_relevance` 付きで AI マッチしたプロダクト
3. **ブロック対象広告主** → ポリシーエラー
4. **不完全なブリーフ** → 明確化リクエスト
5. **一致するプロダクトなし** → 有用な代替提案
6. **フォーマットフィルタリング** → 一致するフォーマットのみ返却

## よくある落とし穴

### Q: フォーマットフィルターが機能しないのはなぜ?

**A:** 文字列ではなく構造化された `format_ids` を使っているか確認してください:

**誤り:**

```json theme={null}
{
  "filters": {
    "format_ids": ["video_30s"]  // ❌ Strings don't work
  }
}
```

**正:**

```json theme={null}
{
  "filters": {
    "format_ids": [
      {
        "agent_url": "https://creative.adcontextprotocol.org",
        "id": "video_30s_hosted"
      }
    ]
  }
}
```

### Q: プロダクトに `brief_relevance` が含まれないのはなぜ?

**A:** `brief_relevance` は `brief` パラメーターが提供された場合にのみ含まれます。標準カタログ要求（ブリーフなし）ではコンテキストマッチがないためこのフィールドは含まれません。

### Q: `get_products` で認可を検証すべきですか?

**A:** **はい!** バイヤーエージェントは購入前に営業エージェントの認可を検証する必要があります:

1. プロダクトから properties を取得（または `property_tags` を解決）
2. 各 `publisher_domain` から `/.well-known/adagents.json` を取得
3. 営業エージェントの URL が `authorized_agents` に含まれることを確認
4. 認可されていないエージェントのプロダクトを拒否

完全な要件は [Authorization Validation](/docs/governance/property/adagents#buyer-agent-validation) を参照してください。

## 用語

### Q: 「product」と「package」の違いは?

**A:**

* **Product**: パブリッシャーの販売可能な在庫単位（`get_products` が返す）
* **Package**: 利用可能なプロダクトからバイヤーが選択したもの（`create_media_buy` で送信）

Product は入手可能なものを示し、Package は購入対象を示します。

### Q: 「delivery」と「distribution」の違いは?

**A:**

* **Delivery type**: `"guaranteed"` と `"non_guaranteed"`（インプレッション保証の有無）
* **Distribution**: クリエイティブが広告サーバーへ配信される方法（メディアバイではなくクリエイティブエージェントの領域）

### Q: ドキュメントにある "AXE" とは?

**A:** **Agentic eXecution Engine (AXE)** ― オーケストレーターとディシジョニングプラットフォームの間にあるリアルタイム実行レイヤーです。AXE は動的オーディエンスターゲティング（バイヤー持ち込みセグメント）、ブランドセーフティ適用、フリークエンシー管理、インプレッション時の 1st パーティデータ活用を処理します。詳細は [AXE documentation](/docs/media-buy/advanced-topics/agentic-execution-engine) を参照してください。

## さらにサポートが必要ですか?

ここで扱われていない場合:

1. 詳細な API ドキュメントは [Task Reference](/docs/media-buy/task-reference/) を確認
2. 探索ガイダンスは [Brief Expectations](/docs/media-buy/product-discovery/brief-expectations) を参照
3. プロダクトモデルの詳細は [Media Products](/docs/media-buy/product-discovery/media-products) を参照
4. 仕様の不明点は GitHub Issue を作成

この FAQ は実装者からのフィードバックに基づき定期的に更新されます。