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

# SI ホストの実装

このガイドは、AI プラットフォームが Sponsored Intelligence ホスト機能を実装する際の手助けをします。実装後は、AI アシスタントがブランドエージェントを呼び出し、充実した会話型コマース体験を提供できます。

## クイックスタート

SI ホストが行うべきこと:

1. SI マニフェストを通じてブランドエージェントを **探索** します
2. ハンドオフ前にオファー詳細を **取得** する（任意だが推奨）
3. ブランドエージェントと **ケイパビリティを交渉** します
4. セッションを **管理** する（開始、メッセージ送受信、終了）
5. 標準 UI コンポーネントを **描画** します
6. コマースハンドオフを **処理** します

## アーキテクチャ概要

```mermaid theme={null}
flowchart TB
    subgraph Platform["Your AI Platform"]
        CE[Conversation Engine]
        SM[SI Session Manager]
        UI[UI Renderer]
        MCP[MCP Client]

        CE --> SM
        SM --> UI
        CE --> MCP
        SM --> MCP
        UI --> MCP
    end

    subgraph Brand["Brand Agent (MCP Server)"]
        T1[si_get_offering]
        T2[si_initiate_session]
        T3[si_send_message]
        T4[si_terminate_session]
    end

    MCP --> Brand
```

## リファレンス実装

<Note>
  リファレンス実装は近日公開予定です。公開され次第、次を示します:

  * ブランドエージェントへの MCP クライアント接続
  * タイムアウト処理を含むセッション管理
  * 同意フローの実装
  * UI コンポーネントのレンダリング
  * ACP へのコマースハンドオフ
</Note>

## 実装時の重要な考慮点

### 1. 同意フロー

ブランドエージェントとユーザーのアイデンティティを共有する前に、明示的な同意を取得する必要があります:

1. ブランドと要求データを示す明確な同意ダイアログを提示します
2. ブランドのプライバシーポリシーへのリンクを表示します
3. 共有するフィールド（氏名、メール、配送先など）をユーザーが選べるようにします
4. アイデンティティオブジェクトに同意のタイムスタンプと範囲を記録します

同意が拒否された場合は、`consent_granted: false` の匿名セッションを作成します。

### 2. UI コンポーネントのレンダリング

ホストは SI プロトコルで定義されたすべての標準 UI コンポーネントをレンダリングする必要があります:

| Component       | Purpose         | Required Fields   |
| --------------- | --------------- | ----------------- |
| `text`          | 会話メッセージ         | `message`         |
| `link`          | ラベル付き URL       | `url`, `label`    |
| `image`         | 単一画像            | `url`, `alt`      |
| `product_card`  | CTA 付きの商品表示     | `title`, `price`  |
| `carousel`      | カード/画像の配列       | `items`           |
| `action_button` | コールバックを起動する CTA | `label`, `action` |

ユーザーが `action_button` をクリックしたら、アクション識別子とペイロードを添えて `si_send_message` で `action_response` を送信します。

### 3. オファー参照フロー

スポンサード結果に推奨されるフロー:

1. **オファー詳細を取得**（匿名） - オファー情報とマッチする商品を取得
2. **オファーをユーザーに提示** - オファー詳細や商品を表示し、接続するかを尋ねる
3. **同意取得** - 接続する場合は同意ダイアログを提示
4. **セッション開始** - 手順 1 のオファートークンを含めます

### 4. コマースハンドオフ

セッションが `session_status: "pending_handoff"` を返した場合:

* `handoff.type: "transaction"` の場合 - 提供された intent で ACP チェックアウトを開始
* 理由を `handoff_transaction` として SI セッションを終了

### 5. セッション管理

* セッションタイムアウトを実装する（推奨: 5 分間の非アクティブ）
* セッション状態をローカルで追跡し、終了時にクリーンアップします
* 次のエラーコードを処理します: `session_not_found`, `offering_unavailable`, `rate_limited`

## 実装のテスト

### ブランドシミュレーターでのローカルテスト

```bash theme={null}
# Run the SI brand simulator
npx @adcontextprotocol/si-simulator

# Connect your host to localhost:3001
```

### 統合チェックリスト

* [ ] SI マニフェスト経由でブランドエージェントを探索できます
* [ ] オファー詳細を取得できる（匿名、PII なし）
* [ ] アイデンティティ有無にかかわらずセッションを開始できます
* [ ] メッセージ送受信ができます
* [ ] すべての終了理由を処理できます
* [ ] すべての標準コンポーネントを正しく描画できます
* [ ] アクションボタンとコールバックを処理できます
* [ ] 適切な同意フローを実装しています
* [ ] コマースハンドオフを処理できます
* [ ] セッションタイムアウトを実装しています

## 次のステップ

* 規定要件については [SI Specification](./specification) を確認します
* ブランド側の実装は [Implementing SI Agents](./implementing-si-agents) を参照します
* 詳細なスキーマ仕様は [Task Reference](./tasks/) を確認します
* 実装サポートには [Community](https://join.slack.com/t/agenticads/shared_invite/zt-3c5sxvdjk-x0rVmLB3OFHVUp~WutVWZg) に参加します