build-seller-agent

name	build-seller-agent
description	Use when building an AdCP seller agent in Go — a publisher, SSP, or retail media network that sells advertising inventory to buyer agents.

Build a Seller Agent (Go)

Overview

A seller agent receives briefs from buyers, returns products with pricing, accepts media buys, manages creatives, and reports delivery.

When to Use

• User wants to build an agent that sells ad inventory in Go
• User mentions publisher, SSP, retail media, or media network in the context of AdCP

Not this skill: buyer/DSP agents, audience signals (skills/build-signals-agent/), creative rendering (skills/build-creative-agent/)

Before Writing Code

Ask the user — don't guess.

1. What kind of seller? Premium publisher (guaranteed, fixed pricing) / SSP (non-guaranteed, auction) / Retail media (both)
2. Guaranteed or non-guaranteed? delivery_type: "guaranteed" vs "non_guaranteed". Many sellers support both.
3. Products and pricing. Each product needs: product_id, name, description, publisher_properties, channels (array of channel enums), delivery_type, pricing_options, format_ids, and reporting_capabilities. Use PublisherPropertySelector entries pointing at publisher_domain values.
4. Approval workflow. Instant create returns a media buy such as status: "active" or status: "pending_creatives". Async create returns the submitted task envelope (status: "submitted", task_id, optional message) and later exposes the confirmed buy via get_media_buys or signed webhooks to push_notification_config.url — see skills/build-webhook-publisher/ for the emission pattern.
5. Creative management. Standard (list_creative_formats + sync_creatives) or none.

Complete Skeleton

adcp.Register wires handler functions to the server. Set only the handlers you support — capabilities are auto-detected. Account resolution and error formatting are automatic.

package main

import (
    "context"
    "fmt"
    "log"
    "sync"
    "sync/atomic"
    "time"

    "github.com/adcontextprotocol/adcp-go/adcp"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

const agentURL = "http://localhost:3001/mcp"

// --- Your backend (replace with your real DB / ad server client) ---

type backend struct {
    mu        sync.RWMutex
    accounts  map[string]*adcp.AccountResult
    mediaBuys map[string]*adcp.MediaBuyData
    creatives map[string]string
    delivery  map[string]*struct{ Impressions, Clicks int; Spend float64 }
    buySeq    atomic.Int64
}

// --- Products and formats (your catalog) ---

var products = []adcp.Product{
    {
        ProductID: "premium-display", Name: "Premium Display",
        Description: "High-impact display placements.",
        Channels: []string{"display"}, DeliveryType: "guaranteed",
        PublisherProperties: []adcp.PublisherPropertySelector{
            {PublisherDomain: "example.com", SelectionType: "all"},
        },
        PricingOptions: []adcp.PricingOption{
            {PricingOptionID: "pd-cpm", PricingModel: "cpm", FixedPrice: adcp.Ptr(15.00), Currency: "USD"},
        },
        FormatIDs: []adcp.FormatRef{{AgentURL: agentURL, ID: }},
        ReportingCapabilities: adcp.ReportingCapabilities{
            AvailableMetrics: []{, , },
            AvailableReportingFrequencies: []{},
            ExpectedDelayMinutes: ,
            Timezone: ,
            SupportsWebhooks: ,
            DateRangeSupport: ,
        },
    },
}

 formats = []adcp.CreativeFormat{
    {
        FormatID: adcp.FormatRef{AgentURL: agentURL, ID: },
        Name:     ,
        Renders:  []adcp.Render{{Width: , Height: }},
        Assets: []adcp.AssetSlot{
            {ItemType: , AssetID: , AssetType: , Required: ,
                AcceptedMediaTypes: []{, }},
        },
    },
}

 {
    b := &backend{
        accounts:  ([]*adcp.AccountResult),
        mediaBuys: ([]*adcp.MediaBuyData),
        creatives: ([]),
        delivery:  ([]*{ Impressions, Clicks ; Spend  }),
    }

    log.Fatal(adcp.Serve( *mcp.Server {
        server := mcp.NewServer(&mcp.Implementation{Name: , Version: }, )

        adcp.Register(server, adcp.Config{
            Sandbox:              ,
            IdempotencyReplayTTL:  * time.Hour, 

            
            Capabilities: &adcp.CapabilitiesData{
                Account: &adcp.AccountCapabilities{SupportedBilling: []{}},
                MediaBuy: &adcp.MediaBuyCapabilities{
                    SupportedPricingModels: []{},
                    Portfolio:              &adcp.PortfolioCaps{PublisherDomains: []{}},
                },
            },

            ResolveAccount:  (any, ) {
                b.mu.RLock()
                 b.mu.RUnlock()
                domain := 
                 ref.Brand !=  { domain = ref.Brand.Domain }
                id := fmt.Sprintf(, domain, ref.Operator)
                 acct, ok := b.accounts[id]; ok {  acct,  }
                 , 
            },

            SyncAccounts:  ([]adcp.AccountResult, ) {
                b.mu.Lock()
                 b.mu.Unlock()
                results := ([]adcp.AccountResult, , (req.Accounts))
                 _, acct :=  req.Accounts {
                    domain := 
                     acct.Brand !=  { domain = acct.Brand.Domain }
                    id := fmt.Sprintf(, domain, acct.Operator)
                    result := adcp.AccountResult{AccountID: id, Brand: acct.Brand, Operator: acct.Operator, Action: , Status: }
                     existing, ok := b.accounts[id]; ok { result.Action = ; result.Status = existing.Status }
                    b.accounts[id] = &result
                    results = (results, result)
                }
                 results, 
            },

            SyncGovernance:  ([]adcp.GovernanceResult, ) {
                results := ([]adcp.GovernanceResult, , (req.Accounts))
                 _, acct :=  req.Accounts {
                    govAcct := acct.Account
                     govAcct ==  { govAcct = &adcp.GovernanceAccount{Brand: acct.Brand, Operator: acct.Operator} }
                    results = (results, adcp.GovernanceResult{Account: govAcct, Status: , GovernanceAgents: acct.GovernanceAgents})
                }
                 results, 
            },

            GetProducts:  (*adcp.ProductsData, ) {
                
                 &adcp.ProductsData{Products: products}, 
            },

            CreateMediaBuy:  (adcp.CreateMediaBuyResult, ) {
                b.mu.Lock()
                 b.mu.Unlock()
                
                n := b.buySeq.Add()
                id := fmt.Sprintf(, n)
                pkgs := ([]adcp.PackageStatus, , (req.Packages))
                createPkgs := ([]adcp.Package, , (req.Packages))
                hasCreatives := 
                 i, p :=  req.Packages {
                     (p.CreativeAssignments) >  { hasCreatives =  }
                    pkg := adcp.Package{
                        PackageID: fmt.Sprintf(, id, i+), ProductID: p.ProductID,
                        PricingOptionID: p.PricingOptionID, Budget: p.Budget,
                        StartTime: p.StartTime, EndTime: p.EndTime,
                        AgencyEstimateNumber: p.AgencyEstimateNumber,
                        MeasurementTerms: p.MeasurementTerms, PerformanceStandards: p.PerformanceStandards,
                        CreativeAssignments: p.CreativeAssignments,
                    }
                    pkgs = (pkgs, adcp.PackageStatus{Package: pkg})
                    createPkgs = (createPkgs, pkg)
                }
                 totalBudget 
                 _, p :=  req.Packages { totalBudget += p.Budget }
                status := 
                 !hasCreatives { status =  }
                validActions := []{, , , }
                 status ==  { validActions = []{, , } }
                buy := &adcp.MediaBuyData{
                    MediaBuyID: id, Status: status, TotalBudget: totalBudget, Packages: pkgs,
                    Currency: , ValidActions: validActions,
                }
                b.mediaBuys[id] = buy
                 _, pkg :=  pkgs { b.delivery[pkg.PackageID] = &{ Impressions, Clicks ; Spend  }{} }
                 &adcp.CreateMediaBuySuccess{
                    MediaBuyID: id, Status: status, Packages: createPkgs,
                    ValidActions: buy.ValidActions, Sandbox: adcp.Bool(),
                }, 
            },

            
            

            GetMediaBuys:  (*adcp.GetMediaBuysResponse, ) {
                b.mu.RLock()
                 b.mu.RUnlock()
                buys := ([]adcp.MediaBuyData, )
                 (req.MediaBuyIDs) >  {
                     _, id :=  req.MediaBuyIDs {
                         buy, ok := b.mediaBuys[id]; ok { buys = (buys, *buy) }
                    }
                }  {
                     _, buy :=  b.mediaBuys { buys = (buys, *buy) }
                }
                 &adcp.GetMediaBuysResponse{MediaBuys: buys}, 
            },

            ListCreativeFormats:  ([]adcp.CreativeFormat, ) {
                 formats, 
            },

            SyncCreatives:  ([]adcp.CreativeResult, ) {
                b.mu.Lock()
                 b.mu.Unlock()
                
                results := ([]adcp.CreativeResult, , (req.Creatives))
                 _, c :=  req.Creatives {
                    action := 
                     _, exists := b.creatives[c.CreativeID]; exists { action =  }
                    b.creatives[c.CreativeID] = 
                    results = (results, adcp.CreativeResult{CreativeID: c.CreativeID, Action: action, Status: })
                }
                 _, assign :=  req.Assignments {
                     _, buy :=  b.mediaBuys {
                         i :=  buy.Packages {
                             buy.Packages[i].PackageID == assign.PackageID {
                                buy.Packages[i].CreativeAssignments = (buy.Packages[i].CreativeAssignments, adcp.CreativeAssignment{
                                    CreativeID: assign.CreativeID, Weight: assign.Weight, PlacementIDs: assign.PlacementIDs,
                                })
                                buy.Status = 
                                buy.ValidActions = []{, , , }
                            }
                        }
                    }
                }
                 results, 
            },

            GetDelivery:  (*adcp.DeliveryData, ) {
                b.mu.RLock()
                 b.mu.RUnlock()
                
                now := time.Now().UTC()
                ids := req.MediaBuyIDs
                 (ids) ==  {  id :=  b.mediaBuys { ids = (ids, id) } }
                deliveries := ([]adcp.MediaBuyDelivery, )
                 _, mbID :=  ids {
                    buy, ok := b.mediaBuys[mbID]
                     !ok {  }
                    pkgDel := ([]adcp.PackageDelivery, )
                     _, pkg :=  buy.Packages {
                        pkgDel = (pkgDel, adcp.PackageDelivery{PackageID: pkg.PackageID, Spend: , PricingModel: , Rate: , Currency: })
                    }
                    deliveries = (deliveries, adcp.MediaBuyDelivery{MediaBuyID: mbID, Status: buy.Status, Totals: adcp.MediaBuyDeliveryTotals{}, ByPackage: pkgDel})
                }
                 &adcp.DeliveryData{
                    ReportingPeriod: adcp.ReportingPeriod{Start: now.Add( * time.Hour).Format(time.RFC3339), End: now.Format(time.RFC3339)},
                    MediaBuyDeliveries: deliveries,
                }, 
            },
        })

        
        adcp.RegisterTestController(server, &adcp.TestControllerStore{
            ForceAccountStatus:  (*adcp.StateTransition, ) {
                b.mu.Lock();  b.mu.Unlock()
                acct, ok := b.accounts[accountID]
                 !ok {  , fmt.Errorf() }
                prev := acct.Status; acct.Status = status
                 &adcp.StateTransition{Success: , PreviousState: prev, CurrentState: status}, 
            },
            ForceMediaBuyStatus:  (*adcp.StateTransition, ) {
                b.mu.Lock();  b.mu.Unlock()
                buy, ok := b.mediaBuys[mediaBuyID]
                 !ok {  , fmt.Errorf() }
                prev := buy.Status
                 prev ==  || prev ==  || prev ==  {  , fmt.Errorf() }
                buy.Status = status
                 &adcp.StateTransition{Success: , PreviousState: prev, CurrentState: status}, 
            },
            ForceCreativeStatus:  (*adcp.StateTransition, ) {
                b.mu.Lock();  b.mu.Unlock()
                prev, ok := b.creatives[creativeID]
                 !ok {  , fmt.Errorf() }
                b.creatives[creativeID] = status
                 &adcp.StateTransition{Success: , PreviousState: prev, CurrentState: status}, 
            },
            SimulateDelivery:  (*adcp.SimulationResult, ) {
                b.mu.Lock();  b.mu.Unlock()
                buy, ok := b.mediaBuys[mediaBuyID]
                 !ok {  , fmt.Errorf() }
                 spend 
                 p.ReportedSpend !=  { spend = p.ReportedSpend.Amount }
                 _, pkg :=  buy.Packages {
                    ds := b.delivery[pkg.PackageID]
                     ds ==  { ds = &{ Impressions, Clicks ; Spend  }{}; b.delivery[pkg.PackageID] = ds }
                    ds.Impressions += p.Impressions; ds.Clicks += p.Clicks; ds.Spend += spend
                }
                 &adcp.SimulationResult{Success: , Simulated: []any{: p.Impressions, : p.Clicks, : spend}}, 
            },
            SimulateBudgetSpend:  (*adcp.SimulationResult, ) {
                b.mu.Lock();  b.mu.Unlock()
                buy, ok := b.mediaBuys[p.MediaBuyID]
                 !ok {  , fmt.Errorf() }
                 total 
                 _, pkg :=  buy.Packages { total += pkg.Budget }
                spend := total * p.SpendPercentage
                 _, pkg :=  buy.Packages {
                     total ==  {  }
                    ds := b.delivery[pkg.PackageID]
                     ds ==  { ds = &{ Impressions, Clicks ; Spend  }{}; b.delivery[pkg.PackageID] = ds }
                    ds.Spend += spend * (pkg.Budget / total)
                }
                 &adcp.SimulationResult{Success: , Simulated: []any{: spend, : p.SpendPercentage}}, 
            },
        })

         server
    }))
}

go.mod

module your-seller-agent

go 1.25

require (
    github.com/adcontextprotocol/adcp-go/adcp v0.0.0
    github.com/modelcontextprotocol/go-sdk v1.5.0
)

Then go mod tidy.

Validation

go run main.go &
npx @adcp/client storyboard run http://localhost:3001/mcp media_buy_seller --json

Fix failures, repeat until all 9 steps pass.

Returning Typed Errors

Handlers can return adcp.NewError for domain-specific errors instead of generic INTERNAL_ERROR:

return nil, adcp.NewError("BUDGET_TOO_LOW", adcp.ErrorOptions{
    Message: "Budget $500 is below the $1,000 minimum for video",
    Field:   "budget",
})

Error codes with auto-recovery: RATE_LIMITED (retry), BUDGET_TOO_LOW / INVALID_REQUEST (revise), ACCOUNT_NOT_FOUND (terminal).

Product Definitions

Each product needs: ProductID, Name, Description, Channels, DeliveryType, PricingOptions, FormatIDs. PublisherProperties is optional — a slice of adcp.PublisherPropertySelector pointing at publisher domains.

Use lowercase pricing models: "cpm", "cpc", "cpcv", not "CPM".

Broadcast/CTV products include business terms:

{
    ProductID: "primetime-30s", Name: "Primetime :30 — M-F 8-11pm",
    Description: "Primetime 30-second broadcast spots.",
    Channels: []string{"broadcast"}, DeliveryType: "guaranteed",
    PricingOptions: []adcp.PricingOption{
        {PricingOptionID: "unit-30s", PricingModel: "unit", FixedPrice: adcp.Ptr(5000.0), Currency: "USD"},
    },
    FormatIDs: []adcp.FormatRef{{AgentURL: agentURL, ID: "broadcast-30s"}},
    CancellationPolicy: &adcp.CancellationPolicy{
        NoticePeriod:    adcp.Duration{Interval: 14, Unit: "days"},
        CancellationFee: adcp.CancellationFee{Type: "percent_remaining", Rate: 0.25},
    },
    MeasurementTerms: &adcp.MeasurementTerms{
        BillingMeasurement: &adcp.BillingMeasurement{
            Vendor: &adcp.BrandReference{Domain: "nielsen.com"}, MeasurementWindow: "c7",
        },
        MakegoodPolicy: &adcp.MakegoodPolicy{AvailableRemedies: []string{"additional_delivery", "credit"}},
    },
    PerformanceStandards: []adcp.PerformanceStandard{
        {Metric: "viewability", Threshold: 0.70, Standard: "mrc", Vendor: &adcp.BrandReference{Domain: "doubleverify.com"}},
    },
}

Storyboards

Storyboard	Use case
media_buy_seller	Full lifecycle — pass this first
media_buy_non_guaranteed	Auction flow with bid adjustment
media_buy_guaranteed_approval	IO approval workflow
media_buy_broadcast_seller	Broadcast/CTV with measurement windows, Ad-ID, delayed delivery
deterministic_testing	Test controller state machines

Common Mistakes

Mistake	Fix
Missing IdempotencyReplayTTL on adcp.Config	Required — set to 24*time.Hour. Panics at startup if unset or outside 1h–7d.
Missing Description on products	Required by schema validation
Missing publisher_properties, format_ids, or reporting_capabilities on products	Required fields. Use at least one publisher selector, supported format, and reporting capability block.
sync_governance response key results	Must be accounts
sync_creatives status "accepted"	Use "approved" — valid: processing, pending_review, approved, rejected, archived
Empty slices serialize as null	Use make([]T, 0) not var x []T
Uppercase pricing model	Use "cpm", "cpc" not "CPM"
Ignoring buyer's measurement_terms on packages	Echo accepted terms back on confirmed package

SDK Reference

import (
    "github.com/adcontextprotocol/adcp-go/adcp"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

Function	Usage
adcp.Register(server, adcp.Config{...})	Wire handlers — only set the tools you support. Auto-detects capabilities.
adcp.Config.IdempotencyReplayTTL	Required. How long you retain idempotency_key responses. Must be 1h–7d; 24h is standard.
adcp.Config.Capabilities	Optional typed CapabilitiesData — declare account / media_buy / audience_targeting blocks. Filled in automatically if nil.
adcp.Config.ResolveAccount	Automatic account resolution. Returns ACCOUNT_NOT_FOUND if nil.
adcp.NewError(code, opts)	Typed error from handlers (BUDGET_TOO_LOW, TERMS_REJECTED, etc.)
adcp.Serve(createAgent)	HTTP server on :3001/mcp
adcp.RegisterTestController(server, store)	Add comply_test_controller for storyboard testing
adcp.AddTool(server, name, desc, handler)	Register custom tools not covered by Config

The skill contains everything you need. Do not read additional docs before writing code.