Add a minimal starter template — single-file sales agent for onboarding

[bokelley]

Summary

The adcp library provides spec-compliant types, but there's no example showing how to wire them into a working sales agent. The reference salesagent (prebid/salesagent) is ~15,000 lines across 50+ files with PostgreSQL, multi-tenancy, A2A, admin UI, multiple ad server adapters, and AI-powered ranking. There's no simple path from pip install adcp to a running server.

A minimal starter template shipped with this library would dramatically lower the barrier to entry.

What's Missing

When building a sales agent from scratch using this library, I had to:

1. Clone and reverse-engineer the full reference implementation to understand patterns
2. Manually introspect every type via model_fields (checking required vs optional)
3. Discover through trial and error which types go where (PricingOption RootModel doesn't proxy attribute access — breaks intuitive iteration #145, Package type proliferation — unclear which type to use in create_media_buy #146)
4. Work around the PricingOption RootModel opacity (PricingOption RootModel doesn't proxy attribute access — breaks intuitive iteration #145)

The docs site has a quickstart, but it focuses on the client side (calling agents), not the server side (building agents with this library).

Proposal

Add an examples/ directory with a single-file sales agent that:

• Defines 2-3 products in-memory (no database)
• Implements get_adcp_capabilities, get_products, and create_media_buy
• Uses fastmcp + this library's types (Product, FormatId, CpmFixedRatePricingOption, FlatRatePricingOption, CreateMediaBuySuccessResponse, etc.)
• Runs with python examples/minimal_agent.py (no Docker, no Postgres)
• Includes comments mapping to AdCP spec sections
• Is testable with npx @adcp/client http://localhost:8000/mcp

I built a working example (~250 lines) for a local news publisher with four products (newsletter sponsorship, website display, mobile display, event sponsorship). Happy to submit as a PR.

Why This Matters

This library is the primary building block for Python-based AdCP agents. The current onramp is:

pip install adcp → read 15K-line reference impl → extract patterns → build your own

The ideal onramp is:

pip install adcp → copy examples/minimal_agent.py → customize products → deploy

Scope

Intentionally minimal:

• Single file, no database, no auth, no adapters
• Just enough to demonstrate the AdCP:Buy flow end-to-end
• Clear enough that someone can read it top-to-bottom and understand how to use the library

[KonstantinMirin]

I am not following - what is the purpose of the deploy that doesn't talk to the ad server? To simulate simple replies for the buyer agent, to "get a feeling of it"? Then it does what it promises - a few products, a mock media buy.

From the actual agent development perspective this doesn't provide a foundation that I would suggest to a new developer.
If we want to give something very small, I would rather extract the same models etc from the salesagent, scoping to one tenant and updating the DB to in-memory like you suggest.

[bokelley]

I am not following - what is the purpose of the deploy that doesn't talk to the ad server? To simulate simple replies for the buyer agent, to "get a feeling of it"? Then it does what it promises - a few products, a mock media buy.

From the actual agent development perspective this doesn't provide a foundation that I would suggest to a new developer. If we want to give something very small, I would rather extract the same models etc from the salesagent, scoping to one tenant and updating the DB to in-memory like you suggest.

not all sales agents will be backed by an ad server - could be OMS, could be offline media. Thinking about this for training purposes - "stand up a local sales agent and test" for people who don't have GAM running. But that's fair feedback.