AdCP Basics: Creating a trusted advertising supply chain using adagents.json

How do I advertise on this property? How do I know that I'm actually buying what I think I'm buying?

The simplest way I can describe the Ad Context Protocol (AdCP) is that it attempts to make an agentic storefront for every publisher, platform, ad network, anybody who sells ads. It lets the agent discover ad products, place and manage a buy, get reporting, and even provide feedback on what’s working or not.

Over the course of a few posts, I’m going to walk through each step of this process. I will try to make it as interesting as possible and not completely technical. But I also feel like it’s important, as with any new protocol, to understand the details and get into the nitty-gritty.

And I’ll also say up front that this is all evolving and changing! So if you’re reading this in the future, please check out https://adcontextprotocol.org for the latest updates.

TL;DR

If you don’t feel like reading this whole thing, here’s what you need to know: AdCP requires publishers to register sales agents publicly using an adagents.json file. It is easy to set up. It’s easy for buyers and their agents to use. And it protects publishers and advertisers from the misrepresentation and shenanigans that have plagued programmatic advertising from the beginning.

Provenance and trust

For the entire 20 year lifetime of the programmatic ad industry, it’s been effectively impossible - even with initiatives like ads.txt and concerted effort from the ANA - to answer some simple questions:

• What platforms let me buy property x?

• If I see property x in an ad buy, is it legit?

Agentic advertising gives us the chance to start over. We can build supply provenance into the protocol.

There are two parts to this:

• Each publisher provides a list of the sales agents that they authorize to sell their inventory (see adagents.json)

• Each sales agent provides a list of publishers that they represent (see list_authorized_properties)

This provides clear provenance in both directions, answering both of the questions above. If you want to know if a sales agent represents a property, see if it’s mentioned in the adagents.json file. If you want to know which properties a sales agent represents, ask it… then verify by looking at the adsagents.json file for each publisher.

Will publishers comply? Yes, for the same reason that Louis Vuitton has a team of lawyers looking for fake handbags and Hollywood has a team of lawyers looking for unauthorized use of their films. It’s in their interest to prevent anyone else selling their content. It creates scarcity, it provides control, and it drives increased yield.

adagents.json validation tool

adagents.json

Let’s say our ad buying agent wants to advertise on a property, say CNN. How do we know where we can find their agentic storefront (aka, their sales agent)?

We look for an adagents.json file on a standard URL: [publisher-domain]/.well-known/adagents.json

This file tells us which sales agents offer CNN inventory. Since CNN controls their domain, we can be confident that this list of sales agents are authorized to sell CNN.

What is in the adagents.json file? Let’s look at the tech spec.

{
  “contact”: {...},           // Who manages this file
  “properties”: [...],        // What properties are managed
  “tags”: {...},              // Groups of properties  
  “authorized_agents”: [...]  // Which agents can sell them
}

Let’s start with contact. This tells us who is responsible for this adagents.json file, generally the publisher but potentially a third-party or sales house.

{
  “contact”: {
    “name”: “CNN Advertising Operations”,
    “email”: “adops@cnn.com”,
    “seller_id”: “pub-cnn-12345”,  // From sellers.json
    “tag_id”: “67890”               // TAG Certified Against Fraud ID
  }
}

Next, what properties are managed by this file? CNN has CTV apps and websites. Note that www.cnn.com and m.cnn.com are automatically included in the root domain, but any other subdomain must be explicitly included. This prevents CNN from, for instance, putting up z.cnn.com, routing it to a third party, and having buyers accidentally buy that inventory as if it’s part of the main CNN site.

If we want, we can also group properties using tags like mobile_sites or ctv_apps which would be useful for a very large publisher that has hundreds or thousands of properties.

{
  “properties”: [
    {
      "property_id": "cnn_ctv_app",
      “property_type”: “ctv_app”,
       “name”: “CNN CTV App”,
       “identifiers”: [
         {”type”: “roku_store_id”, “value”: “12345”},
         {”type”: “fire_tv_asin”, “value”: “B00ABC123”},
         {”type”: “apple_tv_bundle”, “value”: “com.cnn.tv”}
       ]
    }.
    {
      "property_id": "cnn_us",
      “property_type”: “website”,
      “name”: “CNN.com US”,
      “identifiers”: [
        {”type”: “domain”, “value”: “cnn.com”}
      ]
    },
    {
      "property_id": "cnn_international",
      “property_type”: “website”,
      “name”: “CNN International”,
      “identifiers”: [
        {”type”: “domain”, “value”: “edition.cnn.com”}
      ]
    }
  ]
}

Finally, the most important part: what agents are authorized to sell this inventory? Note the free text “authorized_for” field. This is useful in cases where an ad network controls a particular placement - think Taboola or Outbrain at the bottom of the page.

“authorized_agents”: [
    {
      “url”: “https://cnn-ctv-agent.cnn.com”,
      “authorized_for”: “All CTV formats in the US”,
      “property_ids”: [”cnn_ctv_app”]
    }
  ]

This may seem like a lot to do to answer the simple question: how do I buy ads from CNN? But it’s worth it. We can be confident that we’re buying from an authorized storefront that has CNN’s permission and blessing to sell their ads.

list_authorized_properties

So we know which sales agents represent CNN. How do we go the other direction, and find out what publishers a sales agent represents?

The list_authorized_properties tool (or skill in A2A terminology) lets a sales agent share the properties it represents, as well as general information about the countries and channels it does business in. This helps buying agents know 1) does this sales agent have the inventory I want and 2) does this sales agent operate where I want to buy ads.

Request

The buying agent makes a simple call to the sales agent:

{
  “tool”: “list_authorized_properties”,
  “arguments”: {}
}

Response

The sales agent responds with a list of publishers where it is authorized to sell inventory. This list is not authoritative! The buyer needs to go check these publisher domains to find out what this sales agent is authorized to sell.

The sales agent also responds with its primary channels and countries to help buyers decide whether to it makes sense to include it in future requests:

{
  “publisher_domains”: [”cnn.com”, “espn.com"],
  “primary_channels”: [”ctv”],
  “primary_countries”: [”US”],
  “portfolio_description”: “CTV specialist for news and sports publishers”
}

I won’t go into ad products yet - that’s for next time - but when a buyer queries a sales agent, each ad product will list its included properties. These properties must be checked against the adagents.json file to ensure that this sales agent is authorized to sell them. In the future, I’d love to see signed delivery as a core feature of the ad delivery process to close the loop all the way to the edge - but again, that’s for a future discussion.

Implementation

So what does this mean practically?

As a buyer agent, I need to:

• Before I buy an ad product from a sales agent, check the adagents.json for the underlying publishers and make sure the sales agent is authorized (try this npm library)

As a publisher, I need to:

• Publish and maintain an adagents.json file (try this adagents.json generator)

As a sales agent, I need to:

• Make sure my publishers have adagents.json properly configured before I include them in my ad products (built into the open source sales agent that many publishers are using)

The community will continue to evolve more tools, like a registry to automate the discovery and validation of authorized agents.

Final thoughts

Like the rest of AdCP, this is a work in progress. Much thought has gone into making this as flexible and powerful as possible, and especially to build in the context of a post-web world where domains aren’t the primary entry point to digital content. However, we definitely haven’t thought of everything, or anything close to it. If you’re curious about the protocol, have thoughts, ideas, feedback, criticisms, whatever… please get involved. There’s an active slack group where we’re working on how to develop the protocol and tooling around it, build training and education for the industry at large, and explore the new things that AI is enabling us to do.

Building a safe and sustainable media and advertising ecosystem starts with this community of collaboration and innovation. Thank you for taking the time to get into the weeds, and I’m excited to learn together as we build the future of advertising.