> ## 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 エージェントの実装

ブランドが Sponsored Intelligence エージェントを実装するためのガイドです。実装が完了すると、Addy や ChatGPT などの SI ホスト、その他の AI アシスタントからエージェントを呼び出せるようになります。

## Quick Start

SI エージェントは、以下 4 つのタスクを実装する MCP または A2A サーバーです。

1. `si_get_offering` - Respond to offering lookups (details, availability, products)
2. `si_initiate_session` - Start a conversation
3. `si_send_message` - Exchange messages
4. `si_terminate_session` - End the conversation

## Capability Discovery

SI エージェントは、標準の AdCP タスク `get_adcp_capabilities` を通じて機能を公開します。ホストがこのタスクを呼び出すと、エージェントは SI の設定を返します。

```json theme={null}
{
  "adcp": { "major_versions": [2] },
  "supported_protocols": ["sponsored_intelligence"],
  "sponsored_intelligence": {
    "endpoint": {
      "transports": [
        { "type": "mcp", "url": "https://yourbrand.example/si-agent" }
      ]
    },
    "capabilities": {
      "modalities": {
        "conversational": true,
        "voice": false,
        "video": false,
        "avatar": false
      },
      "components": {
        "standard": ["text", "link", "image", "product_card", "carousel", "action_button"],
        "extensions": {}
      },
      "commerce": {
        "acp_checkout": false
      }
    },
    "brand_manifest_url": "https://yourbrand.example/.well-known/brand-manifest.json"
  }
}
```

この統一されたディスカバリー手段により、ホストは他の AdCP プロトコルと同様に SI の機能を把握できます。

## Reference Implementation

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

  * 4 つすべての SI タスクを MCP ツールとして実装
  * タイムアウトを含むセッション管理
  * アイデンティティと同意の取り扱い
  * UI 要素の生成
  * ACP へのチェックアウト引き継ぎ
</Note>

### Task Structure

各 SI タスクは MCP ツールのパターンに従います。

```typescript theme={null}
server.tool(
  "si_initiate_session",
  "Start a conversational session with this brand agent",
  {
    context: { type: "string", description: "Natural language user intent" },
    identity: { type: "object", description: "User identity with consent" },
    media_buy_id: { type: "string", description: "AdCP media buy ID (optional)" },
    offering_id: { type: "string", description: "Brand-specific offering reference (optional)" },
  },
  async ({ context, identity, media_buy_id, offering_id }) => {
    // Your implementation here
    return {
      content: [{
        type: "text",
        text: JSON.stringify({
          session_id: "sess_abc123",
          response: { message: "Hello! How can I help?" },
          negotiated_capabilities: { /* ... */ }
        })
      }]
    };
  }
);
```

## 実装で押さえるポイント

### 1. 会話のハンドオフ

`si_initiate_session` の `context` フィールドはホストからの引き継ぎメッセージで、ユーザーの意図についてホスト AI がブランドエージェントに伝える内容です。これは会話の流れの一部としてユーザーにも見えます。

たとえば ChatGPT でユーザーが「来週ボストンに飛びたい」と言い、ホストが Delta の SI エージェントに接続すると決めた場合、ハンドオフは次のようになります。

> 「ボストン行きの便を探すために Delta につなぎます。空き状況や提供内容を確認してくれます。」

ブランドエージェントはこのコンテキストを受け取り、会話をそのまま続けるように自然に回答する必要があります。

```typescript theme={null}
// あなたのエージェントは会話で応答する AI です
// context がユーザーの要求を教えてくれるので、素直に手助けしてください

// 望ましい回答:
"こんにちは！ ボストン行きの便探しをお手伝いします。
来週のいつ頃をご希望ですか？時間帯の希望はありますか？"

// NG 例: 解析結果を機械的に返さない
"判定結果: category=flight, destination=Boston, timeframe=next_week"
```

重要なのは、SI が API 呼び出しではなく会話だという点です。ブランドエージェントはフォーム入力のような機械的な応答ではなく、親切な人と話しているように感じられるべきです。

### 2. アイデンティティの扱い

`consent_granted` が true の場合、実際の PII が渡されます。

```typescript theme={null}
async function handleIdentity(identity: Identity) {
  if (!identity.consent_granted) {
    // Anonymous session - can still help, just can't personalize
    return null;
  }

  // Look up existing customer by email
  const customer = await lookupCustomer(identity.user.email);

  if (customer) {
    // Personalize based on history
    return {
      name: customer.preferred_name || identity.user.name,
      loyalty_status: customer.loyalty_tier,
      preferences: customer.preferences,
    };
  }

  // New customer - use provided identity
  return {
    name: identity.user.name,
    email: identity.user.email,
  };
}
```

### 3. UI 要素

ホストが描画できる構造化データを返します。

```typescript theme={null}
const uiElements = [
  // Product card for a specific item
  {
    type: "product_card",
    data: {
      title: "Premium Widget",
      subtitle: "Best seller",
      price: "$99",
      image_url: "https://...",
      cta: { label: "Add to Cart", action: "add_to_cart", payload: { sku: "WIDGET-001" } },
    },
  },

  // Carousel for browsing options
  {
    type: "carousel",
    data: {
      title: "You might also like",
      items: [
        { title: "Option A", price: "$49" },
        { title: "Option B", price: "$79" },
      ],
    },
  },

  // Action button for explicit CTA
  {
    type: "action_button",
    data: {
      label: "Complete Purchase",
      action: "checkout",
      payload: { items: ["WIDGET-001"] },
    },
  },
];
```

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

セッションにはタイムアウトとクリーンアップを設定します。

```typescript theme={null}
const SESSION_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes

function cleanupExpiredSessions() {
  const now = Date.now();
  for (const [id, session] of sessions) {
    if (now - session.last_activity.getTime() > SESSION_TIMEOUT_MS) {
      sessions.delete(id);
    }
  }
}

// Run cleanup periodically
setInterval(cleanupExpiredSessions, 60 * 1000);
```

### 5. ACP へのハンドオフ

ユーザーが購入準備できたら、ハンドオフを知らせます。

```typescript theme={null}
if (userWantsToPurchase) {
  return {
    session_status: "pending_handoff",
    handoff: {
      type: "transaction",
      intent: {
        action: "purchase",
        product: selectedProduct,
        price: { amount: 99, currency: "USD" },
      },
      context_for_checkout: {
        conversation_summary: "User selected Premium Widget after discussing features",
        applied_offers: appliedOffers,
      },
    },
  };
}
```

## エンドポイントのテスト

### ローカルテスト

MCP Inspector を使ってエンドポイントをテストします。

```bash theme={null}
npx @anthropic-ai/mcp-inspector your-si-agent
```

### Addy との統合テスト

エンドポイントを登録したら、次の手順で確認します。

1. AgenticAdvertising.org の Slack ワークスペースに参加します
2. Addy との会話を開始します
3. 「connect me with \[Your Brand]」と伝える
4. Addy が SI エンドポイントを呼び出します

## SI エージェントの登録

Addy やその他のホストで SI エージェントを利用可能にするには次を実施します。

1. 5 つの SI タスク（`get_adcp_capabilities` + 4 つの SI タスク）を実装します
2. `get_adcp_capabilities` が SI エンドポイントと機能を返すことを確認します
3. AgenticAdvertising.org チームに連絡し、エンドポイントを登録します
4. ステージング環境で統合をテストします

## 次のステップ

* 詳細なスキーマ仕様は [タスクリファレンス](./tasks/) を参照してください
* コンセプトの理解には [SI プロトコル概要](./overview) を確認してください
* 実装に関する議論は [ワーキンググループ](https://join.slack.com/t/agenticads/shared_invite/zt-3c5sxvdjk-x0rVmLB3OFHVUp~WutVWZg) に参加してください