AdCP 3.1.13 · Media Buy

get_products

get_products request fields

The required column reflects the top-level required array only. One of the 20 request fields carries a top-level required flag: buying_mode. A top-level if, anyOf, oneOf or dependencies block can make an unmarked field mandatory in the mode being called, and a flat table cannot render a rule that fires in one mode only. Those branches are visible in the request schema itself.

get_products reads. 30 of the 64 registered operations are flagged x-mutates-state and its request schema is not one of them, so repeating the call is side-effect free. AdCP's release notes describe x-mutates-state as a non-normative tooling hint that agents do not validate, so it is the registry's classification of the operation rather than a contract, and it is the only machine-readable answer in the registry to whether an operation is safe to retry.

get_products response fields

The first 13 rows are the shared protocol envelope from core/version-envelope.json and core/protocol-envelope.json. Only 16 of the 29 rows below belong to get_products itself, beginning with products, extensions and proposals. One field in the whole response is marked required: status.

The shared protocol envelope

62 of AdCP's 64 registered operations carry every one of the 13 envelope fields. report_plan_outcome and check_governance compose core/version-envelope.json only, so they carry the version pair and none of the task fields.

status resolves to enums/task-status.json, which admits nine values: submitted, working, input-required, completed, canceled, failed, rejected, auth-required, unknown. The envelope marks it required on every response, and a synchronous call emits completed rather than omitting it. When it returns submitted or working instead, task_id is the polling handle and push_notification_config is the webhook the agent echoes back to confirm the callback. Webhooks are A2A and REST only: MCP sends progress notifications and defines no webhook.

payload appears in the response field table typed object. core/protocol-envelope.json describes it as a documentary construct and states that it is not a required wire field. Body fields are siblings of the envelope fields: on MCP at the root of the tool response, on A2A in task.artifacts[0].parts[].DataPart, on REST at the root of the JSON body. An accessor that reads response.payload finds nothing there.

Field lists are not published over the wire

AdCP's integration guide, docs/protocol/calling-an-agent.mdx, states that its MCP servers no longer publish per-tool parameter schemas: a tools/list call returns an empty properties object for every tool, and the guide directs clients not to infer shape from it. A client author reads the schema registry instead of the tool list.

Example get_products calls

The field tables above come from the 3.1.13 schema release and these blocks come from the documentation tree, which is versioned separately, so the two can disagree.

import { testAgent } from '@adcp/sdk/testing';
import { GetProductsResponseSchema } from '@adcp/sdk';

const result = await testAgent.getProducts({
  buying_mode: 'brief',
  brief: 'Premium athletic footwear with innovative cushioning',
  brand: {
    domain: 'acmecorp.com'
  }
});

if (!result.success) {
  throw new Error(`Request failed: ${result.error}`);
}

// Validate response against schema
const validated = GetProductsResponseSchema.parse(result.data);
if (validated.status === 'rejected') {
  console.log(`Seller declined the brief: ${validated.reason}`);
  for (const suggestion of validated.suggestions ?? []) {
    console.log(`- ${suggestion}`);
  }
} else {
  console.log(`Found ${validated.products.length} products`);

  // Access validated product fields
  for (const product of validated.products) {
    console.log(`- ${product.name} (${product.delivery_type})`);
    console.log(`  Formats: ${product.format_options.map(option => option.format_kind).join(', ')}`);
  }
}

import asyncio
from adcp.testing import test_agent

async def discover_products():
    result = await test_agent.simple.get_products(
        buying_mode='brief',
        brief='Premium athletic footwear with innovative cushioning',
        brand={
            'domain': 'acmecorp.com'
        }
    )
    if result.status == 'rejected':
        print(f"Seller declined the brief: {result.reason}")
        for suggestion in result.suggestions or []:
            print(f"- {suggestion}")
    else:
        print(f"Found {len(result.products)} products")

asyncio.run(discover_products())

uvx adcp \
  https://test-agent.adcontextprotocol.org/sales/mcp \
  get_products \
  '{"buying_mode":"brief","brief":"Premium athletic footwear with innovative cushioning","brand":{"domain":"acmecorp.com"}}' \
  --auth $ADCP_AUTH_TOKEN

Other operations in Media Buy

• create_media_buy
• get_media_buy_delivery
• get_media_buys
• list_creative_formats
• log_event
• provide_performance_feedback
• sync_audiences
• sync_catalogs
• sync_event_sources
• update_media_buy

Related

• The full Media Buy reference
• All 64 entries in the AdCP 3.1.13 registry
• Does AAMP have an equivalent operation?