adcp-si

用途

AdCP Sponsored Intelligence (SI) 协议技能用于与品牌智能体（brand agents）执行对话式商务会话。SI 支持用户直接与品牌智能体进行购物、咨询和交易等对话式交互。

该技能仅覆盖各任务的语义；买方侧的基础能力（幂等重放、oneOf 变体、异步 status:'submitted' 轮询、从 adcp_error.issues[] 恢复错误）位于 skills/call-adcp-agent/SKILL.md。

主要能力

SI 协议提供 4 个标准化任务用于管理对话会话：

任务	用途	响应时间
si_initiate_session	启动品牌会话	约 2-5 秒
si_send_message	在活跃会话中发送消息	约 1-5 秒
si_get_offering	在开始前预览商品	约 1-3 秒
si_terminate_session	结束会话	约 1 秒

典型工作流：

1. 预览（可选）：使用 si_get_offering 在征得同意前查看品牌提供的商品
2. 启动会话：使用 si_initiate_session 传入用户意图与同意信息
3. 对话：使用 si_send_message 转发用户消息与操作响应
4. 结束：完成后使用 si_terminate_session

使用方式

si_initiate_session

启动与品牌智能体的对话会话。

请求示例：

{
  "intent": "I'm interested in your winter jacket collection",
  "identity": {
    "consent_granted": true,
    "consent_timestamp": "2025-01-15T10:30:00Z",
    "consent_scope": ["email", "name"],
    "user": {
      "email": "user@example.com",
      "name": "Jane Smith",
      "locale": "en-US"
    }
  },
  "placement": "chatgpt_search"
}

关键字段：

• intent（字符串，必填）：用户意图的自然语言描述，即从宿主到品牌智能体的会话交接
• identity（对象，必填）：带同意状态的用户身份
  • consent_granted（布尔，必填）：用户是否同意共享身份
  • consent_timestamp（字符串，可选）：同意的 ISO 8601 时间戳
  • consent_scope（数组，可选）：用户同意共享的字段
  • user（对象，可选）：PII（仅当 consent_granted 为 true 时）——email、name、locale
  • anonymous_session_id（字符串，可选）：无同意时的会话 ID
• media_buy_id（字符串，可选）：若由广告触发，则为 AdCP 媒体购买 ID
• placement（字符串，可选）：会话触发位置
• offering_id（字符串，可选）：品牌特定的商品引用
• offering_token（字符串，可选）：来自 si_get_offering 的令牌，用于会话连续性
• supported_capabilities（对象，可选）：宿主平台能力（模态、组件、商务）
• context（对象，可选）：不透明关联数据（如 {"trace_id": "abc-123"}），在响应中原样回传——品牌智能体从不解析

响应包含：

• session_id：用于后续 si_send_message 和 si_terminate_session 调用
• greeting：品牌智能体的初始消息
• suggested_actions：可选 UI 元素（按钮、快捷回复）

si_send_message

在活跃的 SI 会话中发送消息。

文本消息：

{
  "session_id": "sess_abc123",
  "message": "Do you have this in size medium?"
}

操作响应（按钮点击、表单提交）：

{
  "session_id": "sess_abc123",
  "action_response": {
    "action": "add_to_cart",
    "element_id": "btn_add_cart_sku789",
    "payload": {
      "size": "M",
      "color": "navy"
    }
  }
}

关键字段：

• session_id（字符串，必填）：来自 si_initiate_session 的会话 ID
• message（字符串，条件必填）：用户文本消息。除非提供 action_response，否则必填。
• action_response（对象，条件必填）：对 UI 操作的响应——action、element_id、payload。除非提供 message，否则必填。

响应包含：

• message：品牌智能体的响应文本
• suggested_actions：用于下一次交互的可选 UI 元素
• components：可选富 UI 组件（产品卡片、轮播、表单）

si_get_offering

在启动会话前获取商品详情与可用性。允许在请求用户同意前展示丰富预览。

请求示例：

{
  "offering_id": "winter-collection-2025",
  "intent": "Looking for warm jackets under $200",
  "include_products": true,
  "product_limit": 5
}

关键字段：

• offering_id（字符串，必填）：来自目录的商品标识符
• intent（字符串，可选）：用于个性化结果的用户意图自然语言描述（无 PII）
• include_products（布尔，可选）：是否包含匹配产品
• product_limit（数字，可选）：返回的最大产品数（默认 5，最大 50）
• context（对象，可选）：不透明关联数据，在响应中原样回传——品牌智能体从不解析

响应包含：

• offering：商品详情（名称、描述、可用性）
• products：若 include_products 为 true，则为匹配产品
• offering_token：传给 si_initiate_session 以保持会话连续性

si_terminate_session

结束 SI 会话。

请求示例：

{
  "session_id": "sess_abc123",
  "reason": "user_exit"
}

关键字段：

• session_id（字符串，必填）：要终止的会话 ID
• reason（字符串，必填）：会话结束原因——handoff_transaction、handoff_complete、user_exit、session_timeout、host_terminated
• termination_context（对象，可选）：会话摘要、交易意图及终止原因
• context（对象，可选）：不透明关联数据，在响应中原样回传——品牌智能体从不解析

reason 取值：

• handoff_transaction：用户被重定向以完成交易
• handoff_complete：交易在会话内完成
• user_exit：用户选择离开
• session_timeout：会话超时
• host_terminated：宿主平台结束会话

关键概念

同意模型

SI 会话在共享 PII 前需要用户明确同意：

• consent_granted: false + anonymous_session_id：匿名会话
• consent_granted: true + user 对象：带身份的个性化会话

会话生命周期

si_get_offering（可选）→ si_initiate_session → si_send_message（重复）→ si_terminate_session

会话是有状态的。品牌智能体在会话内跨消息维护上下文。

位置（Placements）

SI 会话的触发位置：

• chatgpt_search：在 ChatGPT 搜索结果中
• publisher_article：在发布者文章页上
• social_feed：在社交媒体信息流中
• ctv_overlay：在 CTV 流媒体叠加层上

错误处理

常见错误码：

• SESSION_NOT_FOUND：无效或过期的 session_id
• SESSION_EXPIRED：会话超时
• CONSENT_REQUIRED：未获同意即尝试共享 PII
• OFFERING_NOT_FOUND：无效的 offering_id
• RATE_LIMITED：短时间内消息过多

适用场景与限制

适用场景：对话式商务，包括购物咨询、品牌互动与交易；可在 ChatGPT 搜索、发布者文章页、社交媒体信息流、CTV 叠加层等位置触发。

限制：共享 PII 前必须获得用户明确同意；会话有状态且可能超时；存在速率限制；具体收费、价格、平台支持范围等资料暂未提供。