@adcp/sdk 14.0.0 → 14.2.0

package/skills/adcp-si.previous/SKILL.md

@@ -1,206 +0,0 @@
----
-name: adcp-si
-description: Execute AdCP Sponsored Intelligence (SI) Protocol operations with brand agents - start conversational sessions, send messages, preview offerings, and manage session lifecycle. Use when users want to have conversations with brand agents, explore product offerings, or manage sponsored interactions.
----
-
-# 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:**
-```json
-{
-  "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"
-}
-```
-
-**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:**
-```json
-{
-  "session_id": "sess_abc123",
-  "message": "Do you have this in size medium?"
-}
-```
-
-**Action response (button click, form submit):**
-```json
-{
-  "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:**
-```json
-{
-  "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:**
-```json
-{
-  "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

package/skills/adcp-signals.previous/SKILL.md

@@ -1,204 +0,0 @@
----
-name: adcp-signals
-description: Execute AdCP Signals Protocol operations with signal agents - discover audience signals using natural language and activate them on DSPs or sales agents. Use when users want to find targeting data, activate audience segments, or work with signal providers.
----
-
-# AdCP Signals Protocol
-
-This skill enables you to execute the AdCP Signals Protocol with signal agents. Use the standard MCP tools (`get_signals`, `activate_signal`) exposed by the connected agent.
-
-> **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 Signals Protocol provides 2 standardized tasks for discovering and activating targeting data:
-
-| Task | Purpose | Response Time |
-|------|---------|---------------|
-| `get_signals` | Discover signals using natural language | ~60s |
-| `activate_signal` | Activate a signal on a platform/agent | Minutes-Hours |
-
-## Typical Workflow
-
-1. **Discover signals**: `get_signals` with a natural language description of targeting needs
-2. **Review options**: Evaluate signals by coverage, pricing, and deployment status
-3. **Activate if needed**: `activate_signal` for signals not yet live on your platform
-4. **Use in campaigns**: Reference the activation key in your media buy targeting
-
----
-
-## Task Reference
-
-### get_signals
-
-Discover signals based on natural language description, with deployment status across platforms.
-
-**Request:**
-```json
-{
-  "signal_spec": "High-income households interested in luxury goods",
-  "destinations": [
-    {
-      "type": "platform",
-      "platform": "the-trade-desk",
-      "account": "agency-123"
-    }
-  ],
-  "countries": ["US"],
-  "filters": {
-    "max_cpm": 5.0,
-    "catalog_types": ["marketplace"]
-  },
-  "max_results": 5
-}
-```
-
-**Key fields:**
-- `signal_spec` (string, conditional): Natural language description of desired signals. Required unless `signal_ids` is provided.
-- `destinations` (array, optional): Filter signals to those activatable on specific agents/platforms. When omitted, returns all signals available on the current agent. Each item: `type`, `platform`/`agent_url`, optional `account`.
-- `countries` (array, optional): ISO 3166-1 alpha-2 country codes where signals will be used
-- `filters` (object, optional): Filter by `catalog_types`, `data_providers`, `max_cpm`, `min_coverage_percentage`
-- `max_results` (number, optional): Limit number of results
-
-**Deployment types:**
-```json
-// DSP platform
-{ "type": "platform", "platform": "the-trade-desk", "account": "agency-123" }
-
-// Sales agent
-{ "type": "agent", "agent_url": "https://salesagent.example.com" }
-```
-
-**Response contains:**
-- `signals`: Array of matching signals with:
-  - `signal_agent_segment_id`: Use this in `activate_signal`
-  - `name`, `description`: Human-readable signal info
-  - `data_provider`: Source of the signal data
-  - `coverage_percentage`: Reach relative to agent's population
-  - `deployments`: Status per platform with `is_live`, `activation_key`, `estimated_activation_duration_minutes`
-  - `pricing`: CPM and currency
-
----
-
-### activate_signal
-
-Activate a signal for use on a specific platform or agent.
-
-**Request:**
-```json
-{
-  "signal_agent_segment_id": "luxury_auto_intenders",
-  "deployments": [
-    {
-      "type": "platform",
-      "platform": "the-trade-desk",
-      "account": "agency-123-ttd"
-    }
-  ]
-}
-```
-
-**Key fields:**
-- `signal_agent_segment_id` (string, required): From `get_signals` response
-- `deployments` (array, required): Target deployment(s) with `type`, `platform`/`agent_url`, and optional `account`
-
-**Response contains:**
-- `deployments`: Array with activation results per target
-  - `activation_key`: The key to use for targeting (segment ID or key-value pair)
-  - `deployed_at`: ISO timestamp when activation completed
-  - `estimated_activation_duration_minutes`: Time remaining if async
-- `errors`: Any warnings or errors encountered
-
----
-
-## Key Concepts
-
-### Deployment Targets
-
-Signals can be activated on two types of targets:
-
-**DSP Platforms:**
-```json
-{
-  "type": "platform",
-  "platform": "the-trade-desk",
-  "account": "agency-123"
-}
-```
-
-**Sales Agents:**
-```json
-{
-  "type": "agent",
-  "agent_url": "https://wonderstruck.salesagents.com"
-}
-```
-
-### Activation Keys
-
-When signals are live, the response includes an activation key for targeting:
-
-**Segment ID format (typical for DSPs):**
-```json
-{
-  "type": "segment_id",
-  "segment_id": "ttd_segment_12345"
-}
-```
-
-**Key-Value format (typical for sales agents):**
-```json
-{
-  "type": "key_value",
-  "key": "audience_segment",
-  "value": "luxury_auto_intenders"
-}
-```
-
-### Signal Types
-
-- **marketplace**: Licensed from data providers (CPM pricing)
-- **custom**: Built for specific principal accounts
-- **owned**: Private signals from your own data (no cost)
-
-### Coverage Percentage
-
-Indicates signal reach relative to the agent's population:
-- 99%: Very broad signal (matches most identifiers)
-- 50%: Medium signal
-- 1%: Very niche signal
-
-### Asynchronous Operations
-
-Signal activation may take time. Check the response:
-- `is_live: true` + `activation_key`: Ready to use immediately
-- `is_live: false` + `estimated_activation_duration_minutes`: Activation in progress
-
-Poll or use webhooks to check completion status.
-
----
-
-## Error Handling
-
-Common error codes:
-
-- `SIGNAL_AGENT_SEGMENT_NOT_FOUND`: Invalid signal_agent_segment_id
-- `ACTIVATION_FAILED`: Could not activate signal
-- `ALREADY_ACTIVATED`: Signal already active on target
-- `DEPLOYMENT_UNAUTHORIZED`: Not authorized for platform/account
-- `AGENT_NOT_FOUND`: Private agent not visible to this principal
-- `AGENT_ACCESS_DENIED`: Not authorized for this signal agent
-
-Error responses include:
-```json
-{
-  "errors": [
-    {
-      "code": "DEPLOYMENT_UNAUTHORIZED",
-      "message": "Account not authorized for this data provider",
-      "field": "deployment.account",
-      "suggestion": "Contact your account manager to enable access"
-    }
-  ]
-}
-```