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

# 仕様

<Warning>
  **ドラフト仕様** — このプロトコルは開発中です。最終リリースまでに API やスキーマが変更される可能性があります。
</Warning>

本ドキュメントでは Sponsored Intelligence (SI) プロトコルの仕様を定義します。本文中の "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "OPTIONAL" の語は [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) に従って解釈します。

## Protocol Overview

SI プロトコルは、AI アシスタント（ホスト）がブランドエージェントのエンドポイントを呼び出し、会話型のブランド体験を提供する方法を定義します。プロトコルは次で構成されます。

1. **ディスカバリー** - ホストがブランドエージェントとその機能を発見する方法
2. **提供内容の照会** - セッション引き継ぎ前の匿名チェック
3. **セッション管理** - 開始、メッセージ交換、終了
4. **機能ネゴシエーション** - 利用できる機能の決定
5. **UI コンポーネント** - 描画用の標準的なビジュアル要素

## Transport Requirements

### サポートするトランスポート

ブランドエージェントは、以下のうち少なくとも 1 つのトランスポートをサポートしなければなりません。

| Transport | Protocol               | Description             |
| --------- | ---------------------- | ----------------------- |
| MCP       | Model Context Protocol | JSON-RPC によるツールベースのやり取り |
| A2A       | Agent-to-Agent         | メッセージベースのやり取り           |

推奨トランスポートとして MCP をサポートすることが望まれます。

### トランスポートの宣言

ブランドエージェントは `get_adcp_capabilities` でサポートするトランスポートを宣言します。

```json theme={null}
{
  "adcp": { "major_versions": [2] },
  "supported_protocols": ["sponsored_intelligence"],
  "sponsored_intelligence": {
    "endpoint": {
      "transports": [
        { "type": "mcp", "url": "https://brand.example/mcp" }
      ],
      "preferred": "mcp"
    },
    "capabilities": { ... },
    "brand_manifest_url": "https://brand.example/.well-known/brand-manifest.json"
  }
}
```

複数のトランスポートを宣言する場合、レスポンスには `preferred` フィールドを含めることが望まれます。

## Discovery

### 機能ディスカバリー

ブランドエージェントは SI 対応を宣言するために `get_adcp_capabilities` タスクを実装しなければなりません。ホストがこのタスクを呼び出したとき、レスポンスには次を必ず含めます。

* `supported_protocols` 配列内の `sponsored_intelligence`
* 次を含む `sponsored_intelligence` オブジェクト:
  * `endpoint` - トランスポートの設定（必須）
  * `capabilities` - サポートするモダリティとコンポーネント（必須）

レスポンスには以下を含めることが望まれます。

* `brand_manifest_url` - ブランドアイデンティティの参照

## Get Offering

### Purpose

`si_get_offering` タスクはセッション引き継ぎ前に提供内容と提供可否を取得します。ホストはブランドとのエンゲージメントに同意を求める前に、価格や在庫などの情報をユーザーへ提示できます。

### Requirements

ホストはセッション開始前に `si_get_offering` を呼び出してもかまいません。

`si_get_offering` を呼び出す場合:

1. リクエストにユーザーの PII を含めてはいけません
2. リクエストには `offering_id` を含める必要があります
3. パーソナライズ結果のために `context` を含めてもかまいません（例: "mens size 14 near Cincinnati"）
4. 一致する商品を得るために `include_products: true` を設定してもかまいません
5. ブランドエージェントは可能であれば `offering_token` を返さなければなりません
6. ブランドエージェントは有効期限を示す `ttl_seconds` を返すことが望まれます

### Offering Token Flow

ホストが `offering_token` を受け取った場合:

1. 後続の `si_initiate_session` リクエストにこのトークンを含めることが望まれます
2. ブランドエージェントはトークンを使って照会とセッションを関連付けることができます
3. ホストはトークンを不透明な値として扱わなければなりません

```json theme={null}
{
  "offering_token": "offering_abc123xyz"
}
```

### Matching Products

`include_products` が true で `context` が与えられている場合、レスポンスに一致する商品を含めてもかまいません。

```json theme={null}
{
  "available": true,
  "offering_token": "offering_abc123xyz",
  "offering": {
    "title": "Nike Summer Sale",
    "summary": "Up to 50% off summer collection",
    "price_hint": "from $89"
  },
  "matching_products": [
    {
      "product_id": "nike-air-max-90",
      "name": "Nike Air Max 90",
      "price": "$129",
      "availability_summary": "Size 14 in stock"
    }
  ],
  "total_matching": 12
}
```

これにより、セッション開始前にリッチなプレビューを提示できます。

### Sponsored Context Accountability

Offering レスポンスとセッションレスポンスは、返された offering、マッチする商品、message、または UI 要素がホスト境界に入るスポンサードコンテキストである場合、`sponsored_context` を含めてもかまいません（MAY）。宣言は 3 つの事実を分離します。

| Field                   | Purpose                                                                       |
| ----------------------- | ----------------------------------------------------------------------------- |
| `paying_principal`      | 経済的説明責任: コンテキストに資金提供またはスポンサーしたブランド。任意のセラーアカウント/オペレーターコンテキスト付き                 |
| `context_use`           | 宣言されたホスト側の使用モード: `presentation_only`、`comparison_set`、または `reasoning_context` |
| `disclosure_obligation` | ホストがコンテキストを使う前に受け入れて満たすか拒否するかしなければならない開示                                      |

スポンサードコンテキストの説明責任には 4 つのハンドオフポイントがあります。

| Handoff point | Accountability fact                                                                                                    |
| ------------- | ---------------------------------------------------------------------------------------------------------------------- |
| プロバイダー宣言      | ブランド/セラーが、コンテキストがホストサーフェスに入る前に、`paying_principal`、`context_use`、`disclosure_obligation` を含む `sponsored_context` を宣言する。 |
| ホストレシート       | ホストが、スポンサードコンテキストを受け入れたか拒否したか、受け入れたコンテキストについては受け入れた宣言使用モードと開示コミットメントを記録する。                                             |
| ユーザー向け開示      | `disclosure_obligation.required` が true のとき、ホストは、スポンサードコンテキストの前または横で、ユーザー向けサーフェスに適切な開示をレンダリングする説明責任を負う。                |
| 監査証拠          | 当事者は、支払いプリンシパル、宣言された使用モード、開示義務、ホストレシート、およびホストが記録する任意のレンダリングされた開示証拠をリンクする証拠証跡を保持できる。                                    |

このモデルは**提示開示**を**推論影響**から分離します。提示開示は、必要なときにホストがレンダリングするユーザーに見えるラベル、カード処理、通知、または同等の開示です。推論影響は、スポンサードコンテキストが比較セット、ランキング、生成された回答、プラン、またはモデル/オーケストレーションコンテキストを形成してよいかどうかです。`context_use` は許可される影響境界を宣言し、`disclosure_obligation` はユーザー向けの開示義務を宣言します。

| `context_use`       | Applies when                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `presentation_only` | コンテキストが、スポンサードカード、回答ブロック、ブランドエージェントハンドオフなどの別個のラベル付きユニットとしてレンダリングまたは提供される。                                           |
| `comparison_set`    | コンテキストが比較、ランキング、または選択のためのスポンサード候補セットを形成する。これは `matching_products` に自然に適用される: 返された商品は、すべてのアイテムがレンダリングされなくても比較を形成しうる。 |
| `reasoning_context` | コンテキストが、回答生成、プランニング、ランキング、またはその他の推論のためにホストモデルまたはオーケストレーション層に利用可能であることを意図する。                                         |

宣言は、将来の拡張が個々のアイテムに狭めない限り、返された offering と `matching_products` パッケージ全体に適用されます。

ホストは、スポンサードコンテキストを受け入れる、または明示的に拒否するとき、`paying_principal`、宣言された `context_use`、`disclosure_obligation`、ホストレシートをリンクする監査記録を保持すべきです（SHOULD）。ホストが後続で `si_initiate_session` または `si_send_message` を呼び出すとき、その決定をブランド/セラーに見えるようにするために `sponsored_context_receipt` を含めてもかまいません（MAY）。レシートは受信サーフェスの説明責任事実を記録します: ホストがコンテキストを受け入れたか、受け入れたレシートについてはどの使用モードと開示コミットメントを行ったか。

受け入れられたレシートについて:

* `accepted_context_use` は宣言の `context_use` に一致しなければなりません（MUST）
* `disclosure_obligation.required` が true のとき `disclosure_commitment.status` は `accepted` でなければなりません（MUST）
* `disclosure_obligation.required` が false のときのみ `disclosure_commitment.status` は `not_required` であってもかまいません（MAY）

宣言された使用モードを尊重できない、または必要な開示義務を満たせないホストは、受け入れられたレシートを送る代わりにスポンサードコンテキストを拒否しなければなりません（MUST）。

拒否されたレシートについては、`accepted_context_use` と `disclosure_commitment` は存在してはなりません（MUST）。拒否されたレシートは、ホストがスポンサードコンテキストを受け入れなかったまたは使わなかったことを、理由を説明する任意の `rejection_reason` とともに記録します。

これは境界コントラクトです。AdCP は隠されたモデルの推論を検査せず、思考の連鎖を標準化せず、ホストモデルがレシート後に内部でコンテキストをどう使うかを保証しません。宣言された使用モードまたは開示義務を尊重できない準拠ホストは、黙ってダウンスコープしたり開示なしに使ったりするのではなく、スポンサードコンテキストを拒否しなければなりません（MUST）。

## Session Lifecycle

### Session States

SI セッションには次の状態があります。

| State             | Description            |
| ----------------- | ---------------------- |
| `active`          | セッションが進行中              |
| `pending_handoff` | ブランドがコマースフローへのハンドオフを要求 |
| `complete`        | セッションが正常終了             |

### Session State Transitions

```
si_initiate_session ──▶ active
                         │
                         ├── si_send_message ──▶ pending_handoff
                         │                           │
                         │                           └── si_terminate_session ──▶ complete (terminal)
                         │                               (handoff_transaction
                         │                                or handoff_complete)
                         │
                         ├── si_send_message ──▶ complete (terminal)
                         │   (conversation concluded)
                         │
                         └── si_terminate_session ──▶ terminated (terminal)
                             (user_exit, session_timeout,
                              or host_terminated)

Any non-terminal ── si_terminate_session(user_exit/timeout/host) ──▶ terminated
```

**ルール:**

* ブランドエージェントは、成功時に `si_initiate_session` から `session_status: "active"` を返さなければなりません（MUST）
* ブランドエージェントは、すべての `si_send_message` レスポンスで `session_status` を返さなければなりません（MUST）
* `session_status` が `pending_handoff` のとき、レスポンスは `handoff` オブジェクトを含まなければなりません（MUST）
* ブランドエージェントは、会話がコマースまたはチェックアウトの意図に達したとき、任意の `si_send_message` レスポンスで `active` から `pending_handoff` に遷移してもかまいません（MAY）
* ブランドエージェントは、会話が結論に達したとき（例: 質問に回答済み、追加のアクション不要）、`si_send_message` レスポンスで `active` から直接 `complete` に遷移してもかまいません（MAY）
* ホストは、セッションを終了するために `si_terminate_session` を呼び出さなければなりません（MUST）。ブランドエージェントは、任意の非終端状態からの終了を受け入れなければなりません（MUST）。
* ブランドエージェントは、未知または期限切れのセッションに送られたメッセージについて `SESSION_NOT_FOUND` を返さなければなりません（MUST）
* ブランドエージェントは、`complete` または `terminated` 状態のセッションに送られたメッセージについて `SESSION_TERMINATED` を返さなければなりません（MUST）。情報開示の最小化を優先するブランドエージェントは、終了したセッションについても `SESSION_NOT_FOUND` を返してもかまいません（MAY）— 回復パスは両方のケースで同一です。
* 終端状態は不可逆です — セッションが `complete` または `terminated` になると、新しいセッションを開始しなければなりません

### Session Timeout

セッションは最大非アクティブタイムアウトを持つべきです（SHOULD）。ブランドエージェントは、アイドルセッションを `terminated` に遷移させることでタイムアウトを強制してもかまいません（MAY）。

* ブランドエージェントは、一定期間の非アクティブ後にセッションを期限切れとして扱うべきです（SHOULD。推奨: 会話セッションで 5 分）
* ブランドエージェントは、期限切れセッションに送られたメッセージについて、黙って新しいセッションを作成するのではなく `SESSION_NOT_FOUND` を返すべきです（SHOULD）
* ホストは `last_active_at` を追跡し、可能な場合はセッションタイムアウト前にユーザーに警告すべきです（SHOULD）
* ブランドエージェントは、タイムアウト期間をホストに伝えるために `si_initiate_session` レスポンスに `session_ttl_seconds` を含めてもかまいません（MAY）

### Initiate Session

`si_initiate_session` タスクは新しい SI セッションを確立します。

#### Request Requirements

ホストは次を必ず含めなければなりません。

* `context` - ユーザー意図の自然言語説明
* `identity` - 同意状態を含むユーザーのアイデンティティ

ホストは次を含めることが望まれます。

* `supported_capabilities` - ネゴシエーション用のホスト側機能セット
* `offering_token` - `si_get_offering` を実行した場合のトークン

ホストは次を含めてもかまいません。

* `media_buy_id` - 広告起点の場合の AdCP メディアバイ ID
* `offering_id` - 適用するブランド固有のオファー
* `placement` - セッションがトリガーされた場所

#### Response Requirements

ブランドエージェントは次を必ず返さなければなりません。

* `session_id` - セッションの一意識別子

ブランドエージェントは次を返すことが望まれます。

* `response.message` - 最初の会話メッセージ
* `negotiated_capabilities` - ブランドとホストの機能の交差集合

### Send Message

`si_send_message` タスクはアクティブなセッション内でメッセージをやり取りします。

#### Request Requirements

ホストは次を必ず含めなければなりません。

* `session_id` - アクティブなセッション ID

さらに次のいずれかを必ず含めます。

* `message` - ユーザーのテキストメッセージ
* `action_response` - UI アクションへの応答

#### Response Requirements

ブランドエージェントは次を必ず返さなければなりません。

* `session_id` - セッション ID
* `session_status` - 現在のセッション状態（`active`、`pending_handoff`、`complete`）

ブランドエージェントは次を返すことが望まれます。

* `response.message` - 会話の応答

`session_status` が `pending_handoff` の場合、レスポンスには必ず次を含めます。

* `handoff` - コマースフローへのハンドオフ設定

### Terminate Session

`si_terminate_session` タスクは SI セッションを終了します。

#### Request Requirements

ホストは次を必ず含めなければなりません。

* `session_id` - 終了するセッション ID
* `reason` - 終了理由

#### Termination Reasons

| Reason                | Description       |
| --------------------- | ----------------- |
| `handoff_transaction` | ユーザーが購入に進む        |
| `handoff_complete`    | 会話が正常に完了した        |
| `user_exit`           | ユーザーがセッションを終了した   |
| `session_timeout`     | 非アクティブによるタイムアウト   |
| `host_terminated`     | ホストがポリシー/エラーで終了した |

#### Handoff Data

`reason` が `handoff_transaction` のとき、ブランドエージェントは終了レスポンスで `acp_handoff` オブジェクトを返すべきです（SHOULD）。

| Field            | Type     | Description                                                                                      |
| ---------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `checkout_url`   | uri      | ブランドの ACP チェックアウトエンドポイント。ホストは開く前にこれが HTTPS であることを検証しなければなりません（MUST。Security Considerations を参照）。 |
| `checkout_token` | string   | チェックアウトエンドポイントに渡す不透明トークン。SI セッションをトランザクションと相関させる。                                                |
| `payload`        | object   | リッチなチェックアウトコンテキスト（商品詳細、適用オファー、価格）。構造化データが必要な統合のための `checkout_token` の代替。                         |
| `expires_at`     | datetime | このハンドオフデータが期限切れになる時刻。ホストはこの時刻の前にチェックアウトを開始すべきです（SHOULD）。                                         |

ブランドエージェントは、ホストがセッションコンテキストをチェックアウトエンドポイントに渡せるよう、`checkout_token` または `payload`（または両方）を含めるべきです（SHOULD）。

ブランドエージェントは、セッション後のコンテキスト（例: 議論した内容のサマリー、次のステップ）を持つ `follow_up` オブジェクトを返してもかまいません（MAY）。

## Capability Negotiation

### Negotiation Process

1. ブランドが SI マニフェストで機能を宣言します
2. ホストがセッション開始時にサポート機能を送る
3. ブランドがレスポンスでネゴシエート済み（交差）の機能を返す
4. セッションは交差した機能のみを使用します

### Capability Categories

#### Modalities

モダリティはインタラクションのモードを定義します。

| Modality         | Description    | Required Support |
| ---------------- | -------------- | ---------------- |
| `conversational` | テキストでのやり取り     | すべての実装で必須        |
| `voice`          | 音声によるインタラクション  | 任意               |
| `video`          | 動画コンテンツの再生     | 任意               |
| `avatar`         | アバターによる動画プレゼンス | 任意               |

すべての SI 実装は `conversational` モダリティをサポートしなければなりません。

#### Standard Components

準拠するすべてのホストは次のコンポーネントを描画できなければなりません。

| Component       | Purpose           |
| --------------- | ----------------- |
| `text`          | 会話メッセージ           |
| `link`          | ラベル付き URL         |
| `image`         | 単一画像              |
| `product_card`  | CTA を含む商品表示       |
| `carousel`      | カード/画像の配列         |
| `action_button` | コールバックをトリガーする CTA |

#### Extension Components

ホストは追加コンポーネントをサポートしてもかまいません。

| Component             | Purpose              |
| --------------------- | -------------------- |
| `app_handoff`         | プラットフォーム固有アプリへのハンドオフ |
| `integration_actions` | MCP/A2A 追加のプロンプト     |

ブランドエージェントはコア機能を拡張コンポーネントに依存してはいけません。

## UI Element Requirements

### Standard Component Data

各スタンダードコンポーネントは `si-ui-element.json` で定義された必須フィールドを含めなければなりません。

**text**: `message`（必須）

**link**: `url`, `label`（必須）; `preview`（任意）

**image**: `url`, `alt`（必須）; `caption`（任意）

**product\_card**: `title`, `price`（必須）; `subtitle`, `image_url`, `description`, `badge`, `cta`（任意）

**carousel**: `items`（必須）; `title`（任意）

**action\_button**: `label`, `action`（必須）; `payload`（任意）

### Action Handling

ユーザーが `action_button` を操作した場合:

1. ホストは `si_send_message` を介して `action_response` を送信しなければなりません
2. `action_response` には `action` 識別子を含めなければなりません
3. `payload` が提供されている場合、`action_response` に含めることが望まれます

### Integration Actions

`integration_actions` コンポーネントは、ブランドエージェントが恒久的な接続を提案するためのものです。

```json theme={null}
{
  "type": "integration_actions",
  "data": {
    "actions": [
      { "type": "mcp", "label": "Add as MCP Tool", "highlighted": true },
      { "type": "a2a", "label": "Connect via A2A" }
    ]
  }
}
```

ホストは、その統合タイプをサポートしている場合に限り integration actions を描画してもかまいません。

## Identity and Privacy

### Consent Requirements

ホストはブランドエージェントとアイデンティティを共有する前に、ユーザーの明示的な同意を得なければなりません。

同意フローでは次を必ず行います。

1. 共有するデータを明示します
2. ブランドのプライバシーポリシーを参照させる
3. ユーザーに拒否する選択肢を提供します

### Identity Object

同意が得られた場合、`identity` オブジェクトには次を必ず含めます。

* `consent_granted: true`
* `consent_timestamp` - 同意を取得した時刻
* `consent_scope` - 同意したデータ種別の配列
* `privacy_policy_acknowledged.brand_policy_url`

`user` オブジェクトには次を含めてもかまいません。

* `email`
* `name`
* `locale`
* `shipping_address`

### Anonymous Sessions

同意が得られない場合:

* `identity.consent_granted` は必ず `false`
* `identity.anonymous_session_id` を提供することが望まれます
* PII を送信してはなりません

## Commerce Integration

### ACP Handoff

`session_status` が `pending_handoff` で `handoff.type: "transaction"` の場合:

1. ホストは ACP のチェックアウトフローを開始することが望まれます
2. `handoff.intent` には購入意図を記述しなければなりません
3. `handoff.context_for_checkout` には会話コンテキストを含めてもかまいません

### Commerce Actions

`action_button` コンポーネントにはコマースアクションを含めてもかまいません。

| Action         | Description    |
| -------------- | -------------- |
| `acp_checkout` | ACP チェックアウトを開始 |
| `add_to_cart`  | 永続カートに追加       |

## Error Handling

### Error Response

ブランドエージェントは標準のエラースキーマを使い、`errors` 配列でエラーを返さなければなりません。

```json theme={null}
{
  "errors": [
    {
      "code": "session_not_found",
      "message": "セッションが期限切れ、または存在しません"
    }
  ]
}
```

### Error Codes

| Code                     | Description         |
| ------------------------ | ------------------- |
| `session_not_found`      | セッション ID が無効または期限切れ |
| `offer_unavailable`      | 参照されたオファーが利用不可      |
| `capability_unsupported` | 必要な機能が利用不可          |
| `rate_limited`           | リクエストが多すぎる          |

## Security Considerations

### Transport Security

すべての SI 通信は TLS 1.2 以上の HTTPS を使用しなければなりません。

### Token Security

* Availability トークンは不透明かつ予測不能でなければなりません
* セッション ID は一意で予測不能でなければなりません
* トークンは妥当な期間内に期限切れにすることが望まれます

### Handoff URL Validation

ホストは、ユーザーに提示する前に `acp_handoff` データの `checkout_url` を検証しなければなりません（MUST）。ホストは `https` スキームに制限すべきで（SHOULD）、ドメインがブランドエージェントの登録ドメインに一致することを検証してもかまいません（MAY）。ホストは、ハンドオフデータから `javascript:`、`data:`、その他の非 HTTPS URI を開いてはなりません（MUST NOT）。

### Data Minimization

* 同意なしにホストは PII を送信してはなりません
* ブランドエージェントはデータ収集を最小限にすることが望まれます
* セッション終了後はセッションデータを削除することが望まれます

## Conformance

### Host Conformance

準拠する SI ホストは次を満たさなければなりません。

1. MCP トランスポートをサポートします
2. すべてのスタンダードコンポーネントを描画します
3. セッションライフサイクル（開始、送信、終了）を実装します
4. アイデンティティ共有前に同意を取得します
5. 機能ネゴシエーションをサポートします

### Brand Agent Conformance

準拠する SI ブランドエージェントは次を満たさなければなりません。

1. SI マニフェストを公開します
2. 指定されたトランスポートの少なくとも 1 つをサポートします
3. 会話モダリティをサポートします
4. 有効なセッション ID を返す
5. すべての終了理由を処理します

## Version History

| Version | Date    | Changes |
| ------- | ------- | ------- |
| 1.0.0   | 2025-01 | 初版      |