AgentOffer Protocol

Query alternatives when there is no match

The v1.0 response extension keeps offers: [] and its empty_reason. An optional alternative_offerslist can contain 1–3 complete Generic Offers selected for regional_popularity, rather than a direct match to the query. Each entry contains basis, a request-specific selection_reason, and offer. The selection reason remains present with thinking_mode=false; an alternative Offer never carries match_reason.

Alternatives are permitted only for below_relevance_thresholdor no_material, after the existing main selection path is empty. Eligibility, explicit constraints, privacy, scene and frequency gates still apply. Without suitable candidates the field is omitted. Read the normative Query rules and the complete synthetic example. The example wrapper contains request and response objects; only its response object is the protocol response body. It does not prove live inventory or popularity.

Service, SDK and Agent support for this extension is pending separate integration. Protocol publication does not enable it on a deployment. Old strict readers may reject the new field and permissive readers may discard it: upgrade consumers before a producer enables alternatives. Requests and the exact 1.0 selector are unchanged. force_offer remains supported under its existing contract; any later retirement follows consumer migration.

Choose an implementation surface

Start with Quick Start to choose REST API, SDK, or provisioned MCP. Return here when you need the source behind a field, schema, version rule, or example.

Use canonical sources for exact behavior

AON Docs summarizes implementation context. Specifications, schemas, and examples remain authoritative and should not be redefined in a second guide.

For protocol publication context, visit the Protocol website. Future proposals remain in the RFC repository and are not part of the current contract.

Keep classification, lookup, and targeting distinct

Query v1.0 accepts explicit category constraints but no viewer-location field. Location Search resolves and normalizes registry ids; it does not add a Query filter. Partner Offer-side geographic eligibility is defined separately in the Location and Age Targeting source below.

High-signal source files

Open these files when you need exact field names, enums, required fields, and lifecycle semantics.

Contract and runtime boundaries

New integrations use the HTTP selector above and validate responses against this contract's canonical schema and field semantics. A published contract does not certify a particular deployment, credential, SDK release, or Hosted MCP account for live use.