adcp-si

AdCP Sponsored Intelligence (SI) Protocol

This skill enables you to execute the AdCP SI Protocol with brand agents. SI enables conversational commerce sessions where users engage directly with brand agents for shopping, inquiries, and transactions.

Buyer-side basics — idempotency replay, oneOf variants, async status:'submitted' polling, error recovery from adcp_error.issues[] — live in skills/call-adcp-agent/SKILL.md. This skill covers per-task semantics only.

Overview

The SI Protocol provides 4 standardized tasks for managing conversational sessions:

Task	Purpose	Response Time
si_initiate_session	Start a brand conversation	~2-5s
si_send_message	Send a message in an active session	~1-5s
si_get_offering	Preview offerings before starting	~1-3s
si_terminate_session	End a session	~1s

Typical Workflow

1. Preview (optional): si_get_offering to see what the brand offers before consent
2. Start session: si_initiate_session with the user's intent and consent
3. Converse: si_send_message to relay user messages and action responses
4. End: si_terminate_session when done

---

Task Reference

si_initiate_session

Start a conversational session with a brand agent.

Request:

{
  "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": "[email protected]",
      "name": "Jane Smith",
      "locale": "en-US"
    }
  },
  "placement": "chatgpt_search"
}

Key fields:

• intent (string, required): Natural language description of user intent — the conversation handoff from host to brand agent
• identity (object, required): User identity with consent status
  • consent_granted (boolean, required): Whether user consented to share identity
  • consent_timestamp (string, optional): ISO 8601 timestamp of consent
  • consent_scope (array, optional): Fields user agreed to share
  • user (object, optional): PII (only if consent_granted is true) — email, name, locale
  • anonymous_session_id (string, optional): Session ID if no consent
• media_buy_id (string, optional): AdCP media buy ID if triggered by advertising
• placement (string, optional): Where the session was triggered
• offering_id (string, optional): Brand-specific offering reference
• offering_token (string, optional): Token from si_get_offering for session continuity
• supported_capabilities (object, optional): Host platform capabilities (modalities, components, commerce)
• context (object, optional): Opaque correlation data (e.g., {"trace_id": "abc-123"}) echoed unchanged in the response — never parsed by the brand agent

Response contains:

• session_id: Use in subsequent si_send_message and si_terminate_session calls
• greeting: Brand agent's initial message
• suggested_actions: Optional UI elements (buttons, quick replies)

---

si_send_message

Send a message within an active SI session.

Text message:

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

Action response (button click, form submit):

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

Key fields:

• session_id (string, required): Session ID from si_initiate_session
• message (string, conditional): User's text message. Required unless action_response is provided.
• action_response (object, conditional): Response to a UI action — action, element_id, payload. Required unless message is provided.

Response contains:

• message: Brand agent's response text
• suggested_actions: Optional UI elements for next interaction
• components: Optional rich UI components (product cards, carousels, forms)

---

si_get_offering

Get offering details and availability before initiating a session. Allows showing rich previews before asking for user consent.

Request:

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

Key fields:

• offering_id (string, required): Offering identifier from the catalog
• intent (string, optional): Natural language description of user intent for personalized results (no PII)
• include_products (boolean, optional): Include matching products
• product_limit (number, optional): Max products to return (default 5, max 50)
• context (object, optional): Opaque correlation data echoed unchanged in the response — never parsed by the brand agent

Response contains:

• offering: Offering details (name, description, availability)
• products: Matching products if include_products is true
• offering_token: Pass to si_initiate_session for session continuity

---

si_terminate_session

End an SI session.

Request:

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

Key fields:

• session_id (string, required): Session ID to terminate
• reason (string, required): Why the session is ending — handoff_transaction, handoff_complete, user_exit, session_timeout, host_terminated
• termination_context (object, optional): Conversation summary, transaction intent, and cause for the termination
• context (object, optional): Opaque correlation data echoed unchanged in the response — never parsed by the brand agent

Reason values:

• handoff_transaction: User is being redirected to complete a transaction
• handoff_complete: Transaction completed within the session
• user_exit: User chose to leave
• session_timeout: Session timed out
• host_terminated: Host platform ended the session

---

Key Concepts

Consent Model

SI sessions require explicit user consent before sharing PII:

• consent_granted: false + anonymous_session_id: Anonymous session
• consent_granted: true + user object: Personalized session with identity

Session Lifecycle

si_get_offering (optional) → si_initiate_session → si_send_message (repeat) → si_terminate_session

Sessions are stateful. The brand agent maintains context across messages within a session.

Placements

Where the SI session was triggered:

• chatgpt_search: Within ChatGPT search results
• publisher_article: On a publisher's article page
• social_feed: In a social media feed
• ctv_overlay: On a CTV streaming overlay

---

Error Handling

Common error codes:

• SESSION_NOT_FOUND: Invalid or expired session_id
• SESSION_EXPIRED: Session timed out
• CONSENT_REQUIRED: Attempting to share PII without consent
• OFFERING_NOT_FOUND: Invalid offering_id
• RATE_LIMITED: Too many messages in quick succession