@adcp/client 4.22.1 → 4.24.0

package/skills/build-creative-agent/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: build-creative-agent
+description: Use when building an AdCP creative agent — an ad server, creative management platform, or any system that accepts, stores, transforms, and serves ad creatives.
+---
+
+# Build a Creative Agent
+
+## Overview
+
+A creative agent manages the creative lifecycle: accepts assets from buyers, stores them in a library, builds serving tags, and renders previews. Unlike a generative seller (which also sells inventory), a creative agent is a standalone creative platform — it manages creatives but doesn't sell media.
+
+## When to Use
+
+- User wants to build an ad server, creative management platform, or creative rendering service
+- User mentions `build_creative`, `preview_creative`, `sync_creatives`, or `list_creatives`
+- User references creative formats, VAST tags, serving tags, or creative libraries
+
+**Not this skill:**
+- Selling inventory + generating creatives → `skills/build-generative-seller-agent/`
+- Selling inventory (no creative management) → `skills/build-seller-agent/`
+- Serving audience segments → `skills/build-signals-agent/`
+
+## Before Writing Code
+
+Determine these things. Ask the user — don't guess.
+
+### 1. What kind of creative platform?
+
+- **Ad server** (Innovid, Flashtalking, CM360) — stateful library, builds serving tags (VAST, display tags), tracks delivery
+- **Creative management platform** (Celtra) — format transformation, template rendering, asset management
+- **Publisher creative service** — accepts buyer assets, validates against publisher specs, renders previews
+
+### 2. What formats?
+
+Get specific formats the platform supports. Common ones:
+- **Display**: `display_300x250`, `display_728x90`, `display_160x600`
+- **Video**: `video_30s`, `vast_30s`, `video_15s`
+- **Native**: `native_content` (image + headline + description)
+- **Rich media**: `html5_300x250` (interactive HTML)
+
+Each format needs: dimensions, accepted asset types (image, video, html, text), mime types.
+
+### 3. What operations?
+
+- **Sync** — accept and store creatives from buyers (always needed)
+- **List** — query the creative library with filtering (recommended)
+- **Preview** — render a visual preview of a creative (recommended)
+- **Build** — produce serving tags (VAST, display tags, etc.) from stored creatives (recommended)
+
+### 4. Review pipeline?
+
+What happens when a creative is synced:
+- **Instant accept** — creative passes validation, immediately available
+- **Pending review** — human or automated review before going live
+- **Rejection** — creative fails validation (wrong dimensions, prohibited content)
+
+## Tools and Required Response Shapes
+
+**`get_adcp_capabilities`** — register first, empty `{}` schema
+```
+capabilitiesResponse({
+  adcp: { major_versions: [3] },
+  supported_protocols: ['creative'],
+})
+```
+
+**`list_creative_formats`** — `ListCreativeFormatsRequestSchema.shape`
+```
+taskToolResponse({
+  formats: [{
+    format_id: { agent_url: string, id: string },  // required
+    name: string,                                    // required
+    description: string,
+    renders: [{ width: number, height: number }],    // output dimensions
+    assets: [{                                       // what the format accepts
+      item_type: 'individual',
+      asset_id: string,
+      asset_type: 'image' | 'video' | 'html' | 'text',
+      required: boolean,
+      accepted_media_types: string[],                // e.g., ['image/png', 'image/jpeg']
+    }],
+  }],
+})
+```
+
+**`sync_creatives`** — `SyncCreativesRequestSchema.shape`
+
+Store creatives in the library. Echo back creative_id and action.
+```
+taskToolResponse({
+  creatives: [{
+    creative_id: string,              // required — echo from request
+    action: 'created' | 'updated',    // required
+    status: 'accepted' | 'pending_review' | 'rejected',
+  }],
+})
+```
+
+**`list_creatives`** — `ListCreativesRequestSchema.shape`
+
+Return creatives from the library. Support filtering by format_id.
+```
+taskToolResponse({
+  creatives: [{
+    creative_id: string,
+    name: string,
+    format_id: { agent_url: string, id: string },
+    status: 'accepted' | 'pending_review' | 'rejected',
+  }],
+})
+```
+
+The handler should check `args.filters?.format_ids` — if present, return only creatives matching those formats.
+
+**`preview_creative`** — `PreviewCreativeRequestSchema.shape`
+
+Render a preview of a stored creative. Each preview has a `renders` array with output_format discriminator.
+```
+taskToolResponse({
+  response_type: 'single',
+  previews: [{
+    preview_id: string,
+    input: { format_id: { agent_url: string, id: string }, name: string, assets: {} },
+    renders: [{
+      render_id: string,
+      output_format: 'url',         // discriminator: 'url' or 'html'
+      preview_url: string,          // URL to rendered preview (for output_format: 'url')
+      role: 'primary',
+      dimensions: { width: number, height: number },
+    }],
+  }],
+  expires_at: string,              // ISO timestamp
+})
+```
+
+**`build_creative`** — `BuildCreativeRequestSchema.shape`
+
+Produce a serving tag from a stored creative.
+```
+taskToolResponse({
+  creative_manifest: {
+    format_id: { agent_url: string, id: string },
+    name: string,
+    assets: {},              // built output assets
+  },
+  sandbox: true,
+})
+```
+
+## 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 |
+| `taskToolResponse(data, summary)` | Build generic tool response |
+| `adcpError(code, { message })` | Structured error |
+
+Schemas: `ListCreativeFormatsRequestSchema`, `SyncCreativesRequestSchema`, `ListCreativesRequestSchema`, `PreviewCreativeRequestSchema`, `BuildCreativeRequestSchema`.
+
+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 an in-memory Map to store synced creatives (the creative library)
+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: creative library
+
+Use a `Map<string, Creative>` to store synced creatives. The `sync_creatives` handler adds/updates entries. The `list_creatives` handler queries the map. The `preview_creative` and `build_creative` handlers look up by `creative_id`.
+
+## 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 creative_lifecycle --json
+```
+
+**Sandbox validation** (if ports are blocked):
+```bash
+npx tsc --noEmit agent.ts
+```
+
+**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 |
+| `list_creatives` ignores format filter | Check `args.filters?.format_ids` and filter results |
+| `preview_creative` returns wrong response_type | Must be `'single'` for single creative previews |
+| `build_creative` missing creative_manifest | Required field — contains the built output |
+| No in-memory store for synced creatives | `list_creatives` and `preview_creative` need to find previously synced creatives |
+
+## Storyboards
+
+| Storyboard | Tests |
+|-----------|-------|
+| `creative_lifecycle` | Full lifecycle: format discovery → sync → list → preview → build |
+| `creative_template` | Stateless template rendering (build + preview only) |
+| `creative_sales_agent` | Sales agent that accepts pushed assets |
+| `creative_ad_server` | Ad server with pre-loaded library |
+
+## Reference
+
+- `storyboards/creative_lifecycle.yaml` — full creative lifecycle storyboard
+- `docs/guides/BUILD-AN-AGENT.md` — SDK patterns
+- `docs/llms.txt` — full protocol reference

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