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.

Local development

This repo is a multi-module Go workspace. To work on multiple modules at once with unpublished changes visible across them, copy go.work.example to go.work:

cp go.work.example go.work
go build ./...

go.work is intentionally gitignored so CI and downstream consumers resolve real tagged versions of each sub-module, while local development uses your working tree directly.

Modules & versioning

This repository is a Go multi-module workspace. The top-level module (github.com/adcontextprotocol/adcp-go) is internal glue — test helpers, workspace scaffolding, and cross-module examples — and is not intended for external import. The published API surface is delivered through the sub-modules below, each with its own tag prefix and SemVer cadence.

The adcp/vN major version tracks the AdCP protocol spec's major version 1:1. adcp/v3 speaks AdCP 3.x; a hypothetical future adcp/v4 will ship when the protocol spec bumps to 4.0. Other sub-modules stay on independent SemVer. Until AdCP 3.3 is ratified, main publishes adcp/v3 as pre-releases (adcp/v3.3.0-beta.N); see RELEASING.md.

Upgrading from adcp v2 or an earlier root-module pseudo-version? See MIGRATING.md for the full recipe — import path map, sample go.mod diffs, rollback steps, and the tag-naming history behind the v2 module.

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))

Response size is capped by default:

client, _ := signing.NewSignedHTTPClient(signing.SignedHTTPClientOptions{
    KeyID:      "buyer-ed25519-2026",
    PrivateKey: priv,
    // MaxResponseBytes defaults to signing.DefaultMaxResponseBytes (4 MiB).
    // Raise it for an agent with a genuinely large catalog; set
    // signing.UnlimitedResponseBytes to turn the cap off.
})

Agent responses are untrusted input, so NewSignedHTTPClient rejects any response over 4 MiB with a typed *signing.ResponseTooLargeError instead of buffering it. The cap is enforced while the body streams (declared Content-Length is pre-rejected), counts decompressed bytes, and covers SSE both per event and cumulatively per call. Override it per client with MaxResponseBytes / MaxSSEEventBytes or per call with signing.WithResponseLimits. See adcp/v3/signing/README.md.

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.

For unanswered maintainer questions on otherwise merge-ready PRs, see the five-day SDK review consensus guidance.

License

Apache 2.0