@adcp/sdk 5.23.0

package/skills/adcp-media-buy.previous/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: adcp-media-buy
+description: Execute AdCP Media Buy Protocol operations with sales agents - discover advertising products, create and manage campaigns, sync creatives, and track delivery. Use when users want to buy advertising, create media buys, interact with ad sales agents, or test advertising APIs.
+---
+
+# AdCP Media Buy Protocol
+
+This skill enables you to execute the AdCP Media Buy Protocol with sales agents. Use the standard MCP tools (`get_products`, `create_media_buy`, `sync_creatives`, etc.) 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 Media Buy Protocol provides 11 standardized tasks for managing advertising campaigns:
+
+| Task | Purpose | Response Time |
+|------|---------|---------------|
+| `get_products` | Discover inventory using natural language | ~60s |
+| `list_authorized_properties` | See publisher properties | ~1s |
+| `list_creative_formats` | View creative specifications | ~1s |
+| `create_media_buy` | Create campaigns | Minutes-Days |
+| `update_media_buy` | Modify campaigns | Minutes-Days |
+| `get_media_buys` | Retrieve campaign state and status | ~1-5s |
+| `sync_creatives` | Upload creative assets | Minutes-Days |
+| `sync_catalogs` | Sync product feeds and catalogs | Minutes-Days |
+| `list_creatives` | Query creative library | ~1s |
+| `get_media_buy_delivery` | Get performance data | ~60s |
+| `provide_performance_feedback` | Share outcomes with publishers | ~1-5s |
+
+## Typical Workflow
+
+1. **Discover products**: `get_products` with a natural language brief
+2. **Review formats**: `list_creative_formats` to understand creative requirements
+3. **Create campaign**: `create_media_buy` with selected products and budget
+4. **Upload creatives**: `sync_creatives` to add creative assets
+5. **Monitor delivery**: `get_media_buy_delivery` to track performance
+
+---
+
+## Task Reference
+
+### get_products
+
+Discover advertising products using natural language briefs.
+
+**Request:**
+```json
+{
+  "buying_mode": "brief",
+  "brief": "Looking for premium video inventory for a tech brand targeting developers",
+  "brand": {
+    "domain": "example.com"
+  },
+  "filters": {
+    "channels": ["video", "ctv"],
+    "budget_range": { "min": 5000, "max": 50000 }
+  }
+}
+```
+
+**Key fields:**
+- `buying_mode` (string): Required discriminator - `"brief"` or `"wholesale"`
+- `brief` (string): Natural language description of campaign requirements
+- `brand` (object): Brand identity - `{ "domain": "acmecorp.com" }`
+- `filters` (object, optional): Filter by channels, budget, delivery_type
+
+**Response contains:**
+- `products`: Array of matching products with `product_id`, `name`, `description`, `pricing_options`
+- Each product includes `format_ids` (supported creative formats) and `targeting` (available targeting)
+
+---
+
+### list_authorized_properties
+
+Get the list of publisher properties this agent can sell.
+
+**Request:**
+```json
+{}
+```
+
+No parameters required.
+
+**Response contains:**
+- `publisher_domains`: Array of domain strings the agent is authorized to sell
+
+---
+
+### list_creative_formats
+
+View supported creative specifications.
+
+**Request:**
+```json
+{
+  "asset_types": ["video", "image"]
+}
+```
+
+**Key fields:**
+- `asset_types` (array, optional): Filter by asset types (image, video, audio, text, html, vast, etc.)
+- `name_search` (string, optional): Case-insensitive partial match on name or description
+
+**Response contains:**
+- `formats`: Array of format specifications with dimensions, requirements, and asset schemas
+
+---
+
+### create_media_buy
+
+Create an advertising campaign from selected products.
+
+**Request:**
+```json
+{
+  "brand": {
+    "domain": "acme.com"
+  },
+  "packages": [
+    {
+      "product_id": "premium_video_30s",
+      "pricing_option_id": "cpm-standard",
+      "budget": 10000
+    }
+  ],
+  "start_time": {
+    "type": "asap"
+  },
+  "end_time": "2024-03-31T23:59:59Z"
+}
+```
+
+**Key fields:**
+- `brand` (object, required): Brand identity - `{ "domain": "acmecorp.com" }`
+- `packages` (array, required): Products to purchase, each with:
+  - `product_id`: From `get_products` response
+  - `pricing_option_id`: From product's `pricing_options`
+  - `budget`: Amount in dollars
+  - `bid_price`: Required for auction pricing
+  - `targeting_overlay`: Additional targeting constraints
+  - `creative_ids` or `creatives`: Creative assignments
+- `start_time` (object, required): `{ "type": "asap" }` or `{ "type": "scheduled", "datetime": "..." }`
+- `end_time` (string, required): ISO 8601 datetime
+
+**Response contains:**
+- `media_buy_id`: The created campaign identifier
+- `status`: Current lifecycle state — `pending_creatives` (no creatives assigned yet), `pending_start` (waiting for flight date), or `active` (serving immediately)
+- `packages`: Created packages with their IDs
+
+---
+
+### update_media_buy
+
+Modify an existing campaign.
+
+**Request:**
+```json
+{
+  "media_buy_id": "mb_abc123",
+  "updates": {
+    "budget_change": 5000,
+    "end_time": "2024-04-30T23:59:59Z",
+    "status": "paused"
+  }
+}
+```
+
+**Key fields:**
+- `media_buy_id` (string, required): The campaign to update
+- `updates` (object): Changes to apply - budget_change, end_time, status, targeting, etc.
+
+---
+
+### sync_catalogs
+
+Sync product catalogs, store locations, job postings, and other structured feeds to a seller account. Supports inline items or external feed URLs. When called without catalogs, returns existing catalogs (discovery mode).
+
+**Request:**
+```json
+{
+  "account": {
+    "account_id": "acct_123"
+  },
+  "catalogs": [
+    {
+      "catalog_id": "winter-collection",
+      "name": "Winter 2025 Collection",
+      "type": "product",
+      "items": [
+        { "id": "sku-001", "name": "Wool Coat", "price": 299.99, "currency": "USD" }
+      ]
+    }
+  ]
+}
+```
+
+**Key fields:**
+- `account` (object, required): Account that owns the catalogs — `{ account_id }`
+- `catalogs` (array, optional): Catalog objects to sync. Omit for discovery mode.
+  - `type` (string, required): `offering`, `product`, `inventory`, `store`, `promotion`, `hotel`, `flight`, `job`, `vehicle`, `real_estate`, `education`, `destination`, `app`
+  - `items` (array): Inline catalog data (mutually exclusive with `url`)
+  - `url` (string): External feed URL (mutually exclusive with `items`)
+  - `feed_format` (string): `google_merchant_center`, `facebook_catalog`, `shopify`, `linkedin_jobs`, `custom`
+- `delete_missing` (boolean, optional): Remove catalogs not in this sync (use with caution)
+- `dry_run` (boolean, optional): Preview changes without applying
+
+---
+
+### sync_creatives
+
+Upload and manage creative assets.
+
+**Request:**
+```json
+{
+  "creatives": [
+    {
+      "creative_id": "hero_video_30s",
+      "name": "Brand Hero Video",
+      "format_id": {
+        "agent_url": "https://creative.adcontextprotocol.org",
+        "id": "video_standard_30s"
+      },
+      "assets": {
+        "video": {
+          "url": "https://cdn.example.com/hero.mp4",
+          "width": 1920,
+          "height": 1080,
+          "duration_ms": 30000
+        }
+      }
+    }
+  ],
+  "assignments": {
+    "hero_video_30s": ["pkg_001", "pkg_002"]
+  }
+}
+```
+
+**Key fields:**
+- `creatives` (array, required): Creative assets to sync
+  - `creative_id`: Your unique identifier
+  - `format_id`: Object with `agent_url` and `id` from format specifications
+  - `assets`: Asset content (video, image, html, etc.)
+- `assignments` (object, optional): Map creative_id to package IDs
+- `dry_run` (boolean): Preview changes without applying
+- `delete_missing` (boolean): Archive creatives not in this sync
+
+---
+
+### list_creatives
+
+Query the creative library with filtering.
+
+**Request:**
+```json
+{
+  "filters": {
+    "status": ["active"]
+  },
+  "limit": 20
+}
+```
+
+---
+
+### get_media_buys
+
+Retrieve media buy state: status, valid_actions, creative approvals, pending formats, and optional delivery snapshots or revision history.
+
+**Request:**
+```json
+{
+  "media_buy_ids": ["mb_abc123"],
+  "include_snapshot": true,
+  "include_history": 5
+}
+```
+
+**Key fields:**
+- `media_buy_ids` (array, optional): Specific media buy IDs to retrieve
+- `account` (object, optional): Filter to a specific account
+- `status_filter` (string or array, optional): Filter by status — `pending_creatives`, `pending_start`, `active`, `paused`, `completed`, `rejected`, `canceled`. Defaults to `["active"]` when no IDs provided.
+- `include_snapshot` (boolean, optional): Include near-real-time delivery snapshots per package
+- `include_history` (integer, optional): Include the last N revision history entries per media buy
+
+**Response contains:**
+- `media_buys`: Array with `media_buy_id`, `status`, `valid_actions`, `packages`, creative approval state
+- Optional `snapshot` per package (impressions, spend, pacing)
+- Optional `history` entries (revision, timestamp, actor, action, summary)
+
+---
+
+### provide_performance_feedback
+
+Share performance outcomes with publishers to enable data-driven optimization.
+
+**Request:**
+```json
+{
+  "media_buy_id": "mb_abc123",
+  "measurement_period": {
+    "start": "2025-01-01T00:00:00Z",
+    "end": "2025-01-31T23:59:59Z"
+  },
+  "performance_index": 1.2,
+  "metric_type": "conversion_rate",
+  "feedback_source": "buyer_attribution"
+}
+```
+
+**Key fields:**
+- `media_buy_id` (string, required): Publisher's media buy identifier
+- `measurement_period` (object, required): Time period with `start` and `end` (ISO 8601)
+- `performance_index` (number, required): Normalized score — 0.0 = no value, 1.0 = expected, >1.0 = above expected
+- `package_id` (string, optional): Specific package for package-level feedback
+- `creative_id` (string, optional): Specific creative for creative-level feedback
+- `metric_type` (string, optional): `overall_performance`, `conversion_rate`, `brand_lift`, `click_through_rate`, `completion_rate`, `viewability`, `brand_safety`, `cost_efficiency`
+- `feedback_source` (string, optional): `buyer_attribution`, `third_party_measurement`, `platform_analytics`, `verification_partner`
+
+---
+
+### get_media_buy_delivery
+
+Retrieve performance metrics for a campaign.
+
+**Request:**
+```json
+{
+  "media_buy_id": "mb_abc123",
+  "granularity": "daily",
+  "date_range": {
+    "start": "2024-01-01",
+    "end": "2024-01-31"
+  }
+}
+```
+
+**Response contains:**
+- `delivery`: Aggregated metrics (impressions, spend, clicks, etc.)
+- `by_package`: Breakdown by package
+- `timeseries`: Data points over time if granularity specified
+
+---
+
+## Key Concepts
+
+### Brand identity
+
+Brand context is provided by domain reference:
+
+```json
+{
+  "brand": {
+    "domain": "acmecorp.com"
+  }
+}
+```
+
+The agent resolves the domain to retrieve the brand's identity (name, colors, guidelines, etc.) from its `brand.json` file.
+
+### Format IDs
+
+Creative format identifiers are structured objects:
+```json
+{
+  "format_id": {
+    "agent_url": "https://creative.adcontextprotocol.org",
+    "id": "display_300x250"
+  }
+}
+```
+
+The `agent_url` specifies which creative agent defines the format. Use `https://creative.adcontextprotocol.org` for standard IAB formats.
+
+### Pricing Options
+
+Products include `pricing_options` array. Each option has:
+- `pricing_option_id`: Use this in `create_media_buy`
+- `pricing_model`: "cpm", "cpm-auction", "flat-fee", etc.
+- `price`: Base price (for fixed pricing)
+- `floor`: Minimum bid (for auction)
+
+For auction pricing, include `bid_price` in your package.
+
+### Asynchronous Operations
+
+Operations like `create_media_buy` and `sync_creatives` may require human approval. The response includes:
+- `status: "pending"` - Operation awaiting approval
+- `task_id` - For tracking async progress
+
+Poll or use webhooks to check completion status.
+
+---
+
+## Error Handling
+
+Common error patterns:
+
+- **400 Bad Request**: Invalid parameters - check required fields
+- **401 Unauthorized**: Invalid or missing authentication token
+- **404 Not Found**: Invalid product_id, media_buy_id, or creative_id
+- **422 Validation Error**: Schema validation failure - check field types
+
+Error responses include:
+```json
+{
+  "errors": [
+    {
+      "code": "VALIDATION_ERROR",
+      "message": "budget must be greater than 0",
+      "field": "packages[0].budget"
+    }
+  ]
+}
+```
+
+---
+
+## Testing Mode
+
+Use **sandbox mode** for testing without real transactions. Sandbox is account-level — once a request references a sandbox account, the entire request is treated as sandbox with no real platform calls or spend.
+
+Check whether the agent supports sandbox via `get_adcp_capabilities`:
+```json
+{
+  "account": {
+    "sandbox": true
+  }
+}
+```
+
+To enter sandbox mode, set `sandbox: true` on the account reference:
+```json
+{
+  "account": {
+    "brand": { "domain": "acme-corp.com" },
+    "operator": "acme-corp.com",
+    "sandbox": true
+  }
+}
+```
+
+Some sync tasks (`sync_creatives`, `sync_catalogs`) also support a `dry_run` parameter that previews changes without applying them. This is orthogonal to sandbox — you can use `dry_run` in both sandbox and production accounts.
+
+See [Sandbox mode](https://docs.adcontextprotocol.org/docs/media-buy/advanced-topics/sandbox) for full details.

package/skills/adcp-si/SKILL.md

@@ -0,0 +1,206 @@
+---
+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