adcp-go

adcp-go

Go SDK for the Ad Context Protocol (AdCP). Build advertising agents that sell inventory, serve audience data, manage creatives, and pass storyboard compliance validation.

Building an Agent

go get github.com/adcontextprotocol/adcp-go/adcp

package main

import (
    "context"
    "log"
    "time"

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

func main() {
    server := mcp.NewServer(&mcp.Implementation{Name: "my-agent", Version: "1.0.0"}, nil)

    adcp.Register(server, adcp.Config{
        IdempotencyReplayTTL: 24 * time.Hour,
        Capabilities: &adcp.CapabilitiesData{
            SupportedProtocols: []string{"media_buy"},
            MediaBuy: &adcp.MediaBuyCapabilities{
                SupportedPricingModels: []string{"cpm"},
            },
        },
        GetProducts: func(ctx context.Context, acct any, req *adcp.GetProductsRequest) (*adcp.ProductsData, error) {
            return &adcp.ProductsData{Products: []adcp.Product{}}, nil
        },
    })

    log.Fatal(adcp.Serve(func() *mcp.Server { return server }))
}

Validate with the storyboard runner:

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

Skills

Use skill files to build complete agents with coding assistants (Claude, Codex). Each skill is self-contained — a coding agent reads one file and produces a passing agent.

SDK Reference

Tool registration

adcp.AddTool(server, "get_products", "Available advertising products",
    func(ctx context.Context, req *mcp.CallToolRequest, input adcp.GetProductsRequest) (*mcp.CallToolResult, any, error) {
        return adcp.ProductsResponse(&adcp.ProductsData{Products: []adcp.Product{}})
    })

AddTool generates a JSON schema from the Go input struct while allowing additional protocol fields. Use it instead of mcp.AddTool (which rejects extra fields).

Prefer adcp.Register for seller agents when possible. It wires common tools, fills required idempotency and capability fields, and handles AdCP 3.0/3.1 capability negotiation. See docs/adcp-version-compatibility.md for the version compatibility contract.

Response builders

Other

Types

• adcp/types.go — Hand-written SDK types (Product, MediaBuyData, Signal, etc.)
• adcp/inputs.go — Typed input structs for all tool handlers
• adcp/types_gen.go — types generated from AdCP schemas 3.1.0
• adcp/governance_types.go — hand-written Plan and related governance types (inline in sync_plans)
• adcp/plan_validate.go — client-side enforcement of the budget oneOf and Annex III if/then invariants

Media-buy seller helpers use the schema variants directly: *CreateMediaBuySuccess, *CreateMediaBuyError, or *CreateMediaBuySubmitted for create_media_buy, and MediaBuyData for items returned by get_media_buys. MediaBuyData.Packages is []PackageStatus; create success packages remain []Package. Use adcp.Bool(true) for optional boolean updates and adcp.Float64(0) when a creative assignment weight of zero is intentional. CreativeAssignment.Extra preserves seller-specific assignment fields allowed by the schema.

Generated enum aliases decode unknown wire values for forward compatibility. When handler logic needs strict current-schema validation, use the generated helpers: KnownMediaBuyStatusValues(), IsKnownMediaBuyStatus(status), and ParseMediaBuyStatus(raw).

For typed structs whose schema-required fields cannot be represented by Go's zero values, use the SDK validators before request submission or handler-side acceptance. Validation is opt-in and intentionally narrower than full JSON Schema validation: it catches required fields and schema invariants the Go type cannot express, but keeps unknown enum and oneOf variant values forward-compatible unless adcp.WithStrictEnums() is supplied. Flattened oneOf types are validated by active branch: event-only fields such as attribution_window are checked on event goals and ignored on metric goals. For value-based event targets such as per_ad_spend and maximize_value, the validator also requires at least one event source value_field; that is an SDK invariant derived from the schema descriptions, not a general-purpose JSON Schema validation pass.

goal := adcp.OptimizationGoal{
    Kind:   "event",
    Target: adcp.OptimizationGoalCostPerTarget{Value: 10},
    EventSources: []adcp.OptimizationGoalEventSource{{
        EventSourceID: "pixel-1",
        EventType:     "purchase",
    }},
}

if issues := goal.Validate(); len(issues) > 0 {
    // Map issue.Code and issue.Field to your request error handling.
}

Request signing (AdCP 3.0 optional, 4.0 required)

adcp/signing implements the AdCP RFC 9421 request-signing profile — optional in 3.0, required for spend-committing operations in 4.0. The package is self-validating against the spec's conformance vectors: all 8 positive + 20 negative vectors pass, and signed Ed25519 signatures match the committed positive-vector bytes.

As an agent that signs requests:

import "github.com/adcontextprotocol/adcp-go/adcp/signing"

pemBytes, _ := os.ReadFile("signing.pem")
priv, _, _ := signing.LoadPrivateKey(pemBytes)
signer, _ := signing.NewSigner(signing.SignerOptions{
    KeyID:      "buyer-ed25519-2026",
    PrivateKey: priv,
})
client := &http.Client{Transport: signer.RoundTripper(nil, true /* cover content-digest */)}
resp, err := client.Post("https://seller.example.com/adcp/create_media_buy", "application/json", body)

As a verifier (seller):

mw := signing.Middleware(signing.MiddlewareOptions{
    Resolver:            signing.NewHTTPJWKSResolver(agents), // SSRF-safe fetcher
    Replay:              signing.NewMemoryReplayStore(0),
    Revocation:          signing.NewStaticRevocationList(nil),
    OperationResolver:   signing.DefaultOperationResolver,    // /adcp/<op>
    RequiredFor:         []string{"create_media_buy"},
    ContentDigestPolicy: signing.DigestRequired,
})
http.ListenAndServe(":8080", mw(yourHandler))

Generate a signing keypair:

go run github.com/adcontextprotocol/adcp-go/adcp/cmd/adcp-signing-keygen -alg ed25519 -kid my-agent-2026 -out signing.pem

Emits a PEM-encoded private key plus the public JWK (with adcp_use: "request-signing") ready to paste into your agent's JWKS document at jwks_uri.

Packages

TMP Performance

Benchmarked on Apple M4 Pro:

TMP is 1.8x faster than OpenRTB with 37% smaller payloads.

Documentation

Contributing

Contributions welcome! All contributors must agree to the AgenticAdvertising.Org IPR Policy — the bot prompts new contributors on their first PR and a single signature covers all AAO repositories.

License

Apache 2.0