@adcp/client 4.23.0 → 4.24.0

package/skills/build-generative-seller-agent/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: build-generative-seller-agent
+description: Use when building an AdCP generative seller — an AI ad network, generative DSP, or platform that sells inventory AND generates creatives from briefs.
+---
+
+# Build a Generative Seller Agent
+
+## Overview
+
+A generative seller does everything a standard seller does (products, media buys, delivery) plus generates creatives from briefs. The buyer sends a creative brief instead of uploading pre-built assets. Your platform resolves the brand identity, generates the creative, and serves it.
+
+A generative seller that sells programmatic inventory MUST also accept standard IAB formats (display images, VAST tags, HTML banners). The generative capability is additive — buyers who already have creatives need to upload them directly.
+
+## When to Use
+
+- User wants to build a generative DSP or AI ad network
+- User's platform both sells inventory and creates/generates creatives
+- User mentions "creative from brief", "AI-generated ads", or "generative"
+
+**Not this skill:**
+- Standard seller (no creative generation) → `skills/build-seller-agent/`
+- Standalone creative agent (renders but doesn't sell) → creative agent
+- Signals/audience data → `skills/build-signals-agent/`
+
+## Before Writing Code
+
+Determine these things. Ask the user — don't guess.
+
+### 1. What kind of platform?
+
+- **AI ad network** — sells inventory across publishers, generates creatives from briefs
+- **Generative DSP** — programmatic buying + AI creative generation
+- **Retail media with creative** — retail inventory + dynamic ad generation from catalogs
+
+### 2. Products and pricing
+
+Same as standard seller. Each product needs: name, channel, delivery_type, pricing_options.
+
+### 3. Generative formats
+
+What creative formats does your platform generate?
+- **Display** — generated static images (300x250, 728x90, etc.)
+- **Video** — generated video ads (15s, 30s pre-roll)
+- **HTML** — generated interactive/rich media
+
+Each generative format needs a brief asset slot. Standard formats need traditional asset slots (image, video, VAST).
+
+### 4. What inputs does the brief accept?
+
+At minimum: `name`, `objective`, `tone`, `messaging` (headline, cta, key_messages).
+Optional: `audience`, `territory`, `compliance` (required_disclosures, prohibited_claims).
+
+### 5. Brand resolution
+
+The buyer's brand domain should be resolvable (via AgenticAdvertising.org or brand.json). If the brand domain is invalid, reject the creative — don't generate with unknown brand identity.
+
+## Tools and Required Response Shapes
+
+Everything from the standard seller skill applies. The delta is in `list_creative_formats` and `sync_creatives`.
+
+**`get_adcp_capabilities`** — register first, empty `{}` schema
+```
+capabilitiesResponse({
+  adcp: { major_versions: [3] },
+  supported_protocols: ['media_buy'],
+})
+```
+
+**`sync_accounts`** — `SyncAccountsRequestSchema.shape`
+```
+taskToolResponse({
+  accounts: [{
+    account_id: string,
+    brand: { domain: string },
+    operator: string,
+    action: 'created' | 'updated',
+    status: 'active' | 'pending_approval',
+  }]
+})
+```
+
+**`get_products`** — `GetProductsRequestSchema.shape`
+```
+productsResponse({
+  products: Product[],  // each needs product_id, delivery_type, pricing_options
+  sandbox: true,
+})
+```
+
+**`create_media_buy`** — `CreateMediaBuyRequestSchema.shape`
+```
+mediaBuyResponse({
+  media_buy_id: string,
+  packages: [{ package_id, product_id, pricing_option_id, budget }],
+})
+```
+
+**`list_creative_formats`** — `ListCreativeFormatsRequestSchema.shape`
+
+Return BOTH generative and standard formats:
+```
+taskToolResponse({
+  formats: [
+    // Generative format — accepts brief input
+    {
+      format_id: { agent_url: string, id: 'display_300x250_generative' },
+      name: 'Generated Display 300x250',
+      description: 'AI-generated display ad from creative brief',
+      renders: [{ width: 300, height: 250 }],
+      assets: [{
+        item_type: 'individual',
+        asset_id: 'brief',
+        asset_type: 'brief',
+        required: true,
+        description: 'Creative brief with messaging and brand guidelines',
+      }],
+    },
+    // Standard format — accepts pre-built assets
+    {
+      format_id: { agent_url: string, id: 'display_300x250' },
+      name: 'Display 300x250',
+      description: 'Standard IAB display banner',
+      renders: [{ width: 300, height: 250 }],
+      assets: [{
+        item_type: 'individual',
+        asset_id: 'image',
+        asset_type: 'image',
+        required: true,
+        accepted_media_types: ['image/jpeg', 'image/png'],
+      }],
+    },
+  ],
+})
+```
+
+**`sync_creatives`** — `SyncCreativesRequestSchema.shape`
+
+Handle both brief-based and standard creatives:
+```
+taskToolResponse({
+  creatives: [{
+    creative_id: string,              // echo from request
+    action: 'created' | 'updated',    // required
+    status: 'accepted' | 'pending_review',  // pending_review if generation is async
+  }],
+})
+```
+
+For invalid brand domains, return rejection:
+```
+taskToolResponse({
+  creatives: [{
+    creative_id: string,
+    action: 'created',
+    status: 'rejected',
+    errors: ['Brand domain not found: nonexistent-brand.example'],
+  }],
+})
+```
+
+**`get_media_buys`** — `GetMediaBuysRequestSchema.shape`
+```
+taskToolResponse({
+  media_buys: [{
+    media_buy_id: string,
+    status: 'active' | 'pending_start' | ...,
+    currency: 'USD',
+    packages: [{ package_id: string }],
+  }]
+})
+```
+
+**`get_media_buy_delivery`** — `GetMediaBuyDeliveryRequestSchema.shape`
+```
+deliveryResponse({
+  reporting_period: { start: string, end: string },
+  media_buy_deliveries: [{
+    media_buy_id: string,
+    status: 'active',
+    totals: { impressions: number, spend: number },
+    by_package: [],
+  }]
+})
+```
+
+## Compliance Testing (Optional)
+
+Add `registerTestController` so the comply framework can deterministically test your state machines. One function call — the SDK handles request parsing, status validation, and response formatting.
+
+```
+import { registerTestController, TestControllerError } from '@adcp/client';
+import type { TestControllerStore } from '@adcp/client';
+
+const store: TestControllerStore = {
+  async forceAccountStatus(accountId, status) {
+    const prev = accounts.get(accountId);
+    if (!prev) throw new TestControllerError('NOT_FOUND', `Account ${accountId} not found`);
+    accounts.set(accountId, status);
+    return { success: true, previous_state: prev, current_state: status };
+  },
+  async forceMediaBuyStatus(mediaBuyId, status) { /* same pattern */ },
+  async forceCreativeStatus(creativeId, status) { /* same pattern */ },
+  // simulateDelivery, simulateBudgetSpend — implement as needed
+};
+
+registerTestController(server, store);
+```
+
+Declare `compliance_testing` in `supported_protocols` in your `get_adcp_capabilities` response. Only implement the store methods for scenarios your agent supports — unimplemented methods are excluded from `list_scenarios` automatically.
+
+Validate with: `adcp storyboard run <agent> deterministic_testing --json`
+
+## SDK Quick Reference
+
+| SDK piece | Usage |
+|-----------|-------|
+| `serve(createAgent)` | Start HTTP server on `:3001/mcp` |
+| `createTaskCapableServer(name, version, { taskStore })` | Create MCP server with task support |
+| `server.tool(name, Schema.shape, handler)` | Register tool — `.shape` unwraps Zod |
+| `capabilitiesResponse(data)` | Build `get_adcp_capabilities` response |
+| `productsResponse(data)` | Build `get_products` response |
+| `mediaBuyResponse(data)` | Build `create_media_buy` response |
+| `deliveryResponse(data)` | Build `get_media_buy_delivery` response |
+| `taskToolResponse(data, summary)` | Build generic tool response |
+| `adcpError(code, { message })` | Structured error |
+| `registerTestController(server, store)` | Add `comply_test_controller` for deterministic testing |
+
+Import everything from `@adcp/client`. Types from `@adcp/client` with `import type`.
+
+## Implementation
+
+1. Single `.ts` file — all tools in one file
+2. Always register `get_adcp_capabilities` as the **first** tool with empty `{}` schema
+3. Use `Schema.shape` (not `Schema`) when registering tools
+4. Use response builders — never return raw JSON
+5. Set `sandbox: true` on all mock/demo responses
+6. Use `ServeContext` pattern: `function createAgent({ taskStore }: ServeContext)`
+
+The skill contains everything you need. Do not read additional docs before writing code.
+
+### Key implementation detail: sync_creatives handler
+
+The sync_creatives handler must check the format_id to decide how to process:
+- If the format is generative (e.g., id contains "generative"): read the `brief` asset from the creative's assets
+- If the format is standard: read the image/video/html asset
+- Validate the brand domain from the account — reject if invalid
+- Return `pending_review` for generative (async generation) or `accepted` for standard
+
+## Validation
+
+**After writing the agent, validate it. Fix failures. Repeat.**
+
+**Full validation** (if you can bind ports):
+```bash
+npx tsx agent.ts &
+npx @adcp/client storyboard run http://localhost:3001/mcp media_buy_generative_seller --json
+```
+
+**Sandbox validation** (if ports are blocked):
+```bash
+npx tsc --noEmit agent.ts
+```
+
+When storyboard output shows failures, fix each one:
+- `response_schema` → response doesn't match Zod schema
+- `field_present` → required field missing
+- MCP error → check tool registration (schema, name)
+
+**Keep iterating until all steps pass.**
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Only generative formats, no standard IAB | Programmatic sellers must accept pre-built assets too |
+| Ignore brand domain on brief sync | Validate brand, reject if unresolvable |
+| Same handler for brief and standard creatives | Check format_id to decide processing path |
+| Skip `get_adcp_capabilities` | Must be the first tool registered |
+| Pass `Schema` instead of `Schema.shape` | MCP SDK needs unwrapped Zod fields |
+| `sandbox: false` on mock data | Buyers may treat mock data as real |
+
+## Reference
+
+- `storyboards/media_buy_generative_seller.yaml` — full generative seller storyboard
+- `storyboards/media_buy_seller.yaml` — base seller storyboard (for standard seller parts)
+- `skills/build-seller-agent/SKILL.md` — standard seller skill (generative extends this)
+- `docs/guides/BUILD-AN-AGENT.md` — SDK patterns
+- `docs/llms.txt` — full protocol reference

package/skills/build-retail-media-agent/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: build-retail-media-agent
+description: Use when building an AdCP retail media network agent — a platform that sells on-site placements, supports product catalogs, tracks conversions, and reports performance.
+---
+
+# Build a Retail Media Agent
+
+## Overview
+
+A retail media agent sells advertising on a retailer's properties (sponsored products, homepage banners, search results). It extends the standard seller with catalog sync, event tracking, and performance feedback. Buyers sync product catalogs, the platform renders dynamic ads from the feed, and conversion data flows back for optimization.
+
+## When to Use
+
+- User wants to build a retail media network, commerce media platform, or sponsored products agent
+- User mentions catalogs, product feeds, conversion tracking, or performance feedback
+- User references `sync_catalogs`, `log_event`, or `provide_performance_feedback`
+
+**Not this skill:**
+- Standard seller without catalogs → `skills/build-seller-agent/`
+- Generative seller (AI creative from briefs) → `skills/build-generative-seller-agent/`
+- Signals/audience data → `skills/build-signals-agent/`
+
+## Before Writing Code
+
+Same domain decisions as the seller skill, plus:
+
+### 1. Products and pricing
+Same as seller. Get specific inventory: names, channels, pricing model, min spend.
+
+### 2. Catalog support
+What product catalogs does the platform accept?
+- Feed format: JSON, CSV, XML
+- What fields: product_id, title, price, image_url, category
+- How does the catalog connect to ad rendering?
+
+### 3. Event tracking
+What conversion events does the platform track?
+- Purchase, add_to_cart, page_view, search
+- How are events attributed to catalog items?
+
+### 4. Performance feedback
+Does the buyer send performance metrics back for optimization?
+
+## Tools and Required Response Shapes
+
+All standard seller tools apply (see `skills/build-seller-agent/SKILL.md`). The additional tools:
+
+**`get_adcp_capabilities`** — register first, empty `{}` schema
+```
+capabilitiesResponse({
+  adcp: { major_versions: [3] },
+  supported_protocols: ['media_buy'],
+})
+```
+
+**`sync_accounts`** — `SyncAccountsRequestSchema.shape`
+```
+taskToolResponse({
+  accounts: [{
+    account_id: string,
+    brand: { domain: string },
+    operator: string,
+    action: 'created' | 'updated',
+    status: 'active' | 'pending_approval',
+  }]
+})
+```
+
+**`get_products`** — `GetProductsRequestSchema.shape`
+```
+productsResponse({ products: Product[], sandbox: true })
+```
+
+**`create_media_buy`** — `CreateMediaBuyRequestSchema.shape`
+```
+mediaBuyResponse({
+  media_buy_id: string,
+  packages: [{ package_id, product_id, pricing_option_id, budget }],
+})
+```
+
+**`list_creative_formats`** — `ListCreativeFormatsRequestSchema.shape`
+```
+taskToolResponse({
+  formats: [{
+    format_id: { agent_url: string, id: string },
+    name: string,
+  }]
+})
+```
+
+**`sync_catalogs`** — `SyncCatalogsRequestSchema.shape`
+
+Accept product catalog feeds. Return per-catalog status with item counts.
+```
+taskToolResponse({
+  catalogs: [{
+    catalog_id: string,        // required — echo from request
+    action: 'created' | 'updated',  // required
+    item_count: number,        // total items in catalog
+    items_approved: number,    // items that passed validation
+  }],
+  sandbox: true,
+})
+```
+
+**`sync_event_sources`** — `SyncEventSourcesRequestSchema.shape`
+
+Register event tracking integrations.
+```
+taskToolResponse({
+  event_sources: [{
+    event_source_id: string,   // required — echo from request
+    action: 'created' | 'updated',  // required
+  }],
+  sandbox: true,
+})
+```
+
+**`log_event`** — `LogEventRequestSchema.shape`
+
+Accept conversion events.
+```
+taskToolResponse({
+  events_received: number,     // required — how many events in the request
+  events_processed: number,    // required — how many were successfully processed
+  sandbox: true,
+})
+```
+
+**`provide_performance_feedback`** — `ProvidePerformanceFeedbackRequestSchema.shape`
+
+Accept performance metrics from the buyer.
+```
+taskToolResponse({
+  success: true,
+  sandbox: true,
+})
+```
+
+**`get_media_buy_delivery`** — `GetMediaBuyDeliveryRequestSchema.shape`
+```
+deliveryResponse({
+  reporting_period: { start: string, end: string },
+  media_buy_deliveries: [{
+    media_buy_id: string,
+    status: 'active',
+    totals: { impressions: number, spend: number },
+    by_package: [],
+  }]
+})
+```
+
+## Compliance Testing (Optional)
+
+Add `registerTestController` so the comply framework can deterministically test your state machines. One function call — the SDK handles request parsing, status validation, and response formatting.
+
+```
+import { registerTestController, TestControllerError } from '@adcp/client';
+import type { TestControllerStore } from '@adcp/client';
+
+const store: TestControllerStore = {
+  async forceAccountStatus(accountId, status) {
+    const prev = accounts.get(accountId);
+    if (!prev) throw new TestControllerError('NOT_FOUND', `Account ${accountId} not found`);
+    accounts.set(accountId, status);
+    return { success: true, previous_state: prev, current_state: status };
+  },
+  async forceMediaBuyStatus(mediaBuyId, status) { /* same pattern */ },
+  async forceCreativeStatus(creativeId, status) { /* same pattern */ },
+  // simulateDelivery, simulateBudgetSpend — implement as needed
+};
+
+registerTestController(server, store);
+```
+
+Declare `compliance_testing` in `supported_protocols` in your `get_adcp_capabilities` response. Only implement the store methods for scenarios your agent supports — unimplemented methods are excluded from `list_scenarios` automatically.
+
+Validate with: `adcp storyboard run <agent> deterministic_testing --json`
+
+## SDK Quick Reference
+
+| SDK piece | Usage |
+|-----------|-------|
+| `serve(createAgent)` | Start HTTP server on `:3001/mcp` |
+| `createTaskCapableServer(name, version, { taskStore })` | Create MCP server with task support |
+| `server.tool(name, Schema.shape, handler)` | Register tool — `.shape` unwraps Zod |
+| `capabilitiesResponse(data)` | Build `get_adcp_capabilities` response |
+| `productsResponse(data)` | Build `get_products` response |
+| `mediaBuyResponse(data)` | Build `create_media_buy` response |
+| `deliveryResponse(data)` | Build `get_media_buy_delivery` response |
+| `taskToolResponse(data, summary)` | Build generic tool response |
+| `adcpError(code, { message })` | Structured error |
+| `registerTestController(server, store)` | Add `comply_test_controller` for deterministic testing |
+
+Schemas: `GetProductsRequestSchema`, `CreateMediaBuyRequestSchema`, `GetMediaBuyDeliveryRequestSchema`, `SyncAccountsRequestSchema`, `ListCreativeFormatsRequestSchema`, `SyncCatalogsRequestSchema`, `SyncEventSourcesRequestSchema`, `LogEventRequestSchema`, `ProvidePerformanceFeedbackRequestSchema`.
+
+Import everything from `@adcp/client`. Types from `@adcp/client` with `import type`.
+
+## Implementation
+
+1. Single `.ts` file — all tools in one file
+2. Always register `get_adcp_capabilities` as the **first** tool with empty `{}` schema
+3. Use `Schema.shape` (not `Schema`) when registering tools
+4. Use response builders — never return raw JSON
+5. Set `sandbox: true` on all mock/demo responses
+6. Use `ServeContext` pattern: `function createAgent({ taskStore }: ServeContext)`
+
+The skill contains everything you need. Do not read additional docs before writing code.
+
+## Validation
+
+**After writing the agent, validate it. Fix failures. Repeat.**
+
+```bash
+npx tsx agent.ts &
+npx @adcp/client storyboard run http://localhost:3001/mcp media_buy_catalog_creative --json
+```
+
+**Keep iterating until all steps pass.**
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Skip `get_adcp_capabilities` | Must be the first tool registered |
+| Pass `Schema` instead of `Schema.shape` | MCP SDK needs unwrapped Zod fields |
+| sync_catalogs missing `item_count` / `items_approved` | Required fields for catalog validation results |
+| log_event missing `events_received` / `events_processed` | Required counters |
+| `sandbox: false` on mock data | Buyers may treat mock data as real |
+
+## Reference
+
+- `skills/build-seller-agent/SKILL.md` — base seller skill (retail media extends this)
+- `storyboards/media_buy_catalog_creative.yaml` — full catalog creative storyboard
+- `docs/guides/BUILD-AN-AGENT.md` — SDK patterns
+- `docs/llms.txt` — full protocol reference