SDK helper for community mirror adagents catalogs

[bokelley]

Summary

@adcp/sdk@8.1.0-beta.14 now exposes enough registry surface for basic AAO calls, and RegistryClient.createAdagents() accepts formats, placements, and placement_tags. That unblocks some adopter work, but there are still gaps for adopters who want to publish community mirror catalog files for platforms/properties that are not yet producing authorized seller agents.

Use case

Agentic Adapters wants to publish adagents.json-style catalog descriptors for social platforms and other publishers so buyers can discover:

• publisher properties
• canonical creative format options
• placements / placement tags
• no seller authorization claim when no authorized agent exists yet

For community mirror catalogs, v1_format_ref[].agent_url is being used as a format-shape namespace, not as a seller authorization claim. Beta.14 documents that distinction, which is good.

Remaining SDK asks

1. Add a high-level SDK helper for building community mirror catalog adagents.json files, separate from seller-authorized hosted publisher files.

   • It should make it difficult to accidentally imply platform adoption or seller authorization.
   • It should allow authorized_agents: [] while still carrying formats, placements, and placement_tags.

2. Strengthen the createAdagents input/return types.

   • Today the generated request allows formats?: unknown[] and placements?: unknown[].
   • Adopters need exported typed shapes for these objects so local code does not invent parallel schemas.

3. Clarify whether RegistryClient.createAdagents() is intended for runtime serving of .well-known/adagents.json, build-time generation, or both.

   • For public .well-known routes, adopters may not want a live AAO dependency on every request.
   • If the intended pattern is build/cache/write-through, an SDK helper should make that explicit.

4. If AAO will host/manage community mirror catalogs directly, expose that through the SDK rather than requiring adopters to hand-roll registry client calls.

Why this matters

The desired adopter pattern is: no custom registry client code in downstream repos. Registry fetching, validation, creation, and community mirror publication should all go through SDK APIs so semantics stay consistent across adopters.

Version checked

@adcp/sdk@8.1.0-beta.14

[bokelley]

Triage

Classification: Feature request (schema gap + SDK ergonomics)
Bucket(s): spec / protocol, schema
Status: ready-to-implement (spec-repo scope); cross-repo note below for SDK items
Milestone: 3.1.0 (#2)

What the experts said:

• ad-tech-protocol-expert: authorized_agents: minItems: 1 is correct for publisher-hosted files but categorically wrong for community mirror catalogs — a dummy entry would misrepresent the mirror operator as an authorized seller (supply-chain trust violation). Recommends Option A: remove authorized_agents from required in the inline variant. Non-breaking (relaxes a constraint; more documents accepted, none rejected). Not patch-eligible for 3.0.x because changing the required array is a schema-tier change; belongs in 3.1.x. No sellers.json precedent exists for "no sellers yet" — this is a novel AdCP capability.
• adtech-product-expert: Items 1–3 (SDK helper, typed shapes, runtime-vs-build clarification) are unambiguously adcp-client scope; nothing in this repo needs to change for them. Item 4 (AAO hosting): creative.adcontextprotocol.org already exists in server/src/creative-agent/index.ts but is hardcoded; per-platform community mirror files should be CDN/static artifacts behind aggressive caching, not dynamic Express routes. The catalog_etag/superseded_by design in the schema already assumes this pattern.

My take: The blocking spec issue in this repo is one schema change: make authorized_agents optional in the inline variant. Items 1–3 live in adcp-client; Item 4 is an infrastructure decision (CDN vs. server route), not a server code change.

Implementation scope (this repo only — Item 0, the schema fix):

• File: static/schemas/source/adagents.json
• Change: In the inline oneOf variant (second branch), remove "authorized_agents" from the required array. Keep the field defined and documented; add a note to its description that absence means "catalog-only / no authorization claims — valid for community mirror files."
• Do not remove minItems: 1 without also removing from required — the right semantic is "optional field; when present, must have at least one entry" (avoids the empty-array footgun).
• Changeset: minor (schema required change); base branch main.
• Non-breaking rationale: Relaxes a constraint — previously valid documents remain valid; the set of accepted documents grows. Buyer SDKs using additionalProperties: true already cannot assume field presence without a guard.
• Buyer SDK note: Add a sentence to the authorized_agents field description reminding buyer SDKs to check for absence before iterating (community mirror files will omit it).

Cross-repo (not this repo's PR):

• Sibling-repo-fix-needed: adcp-client — RegistryClient.createAdagents() types formats/placements as unknown[] (confirmed in server/src/routes/registry-api.ts Zod schema). Needs a separate community-mirror builder helper and typed ProductFormatDeclaration / placement exports. Items 1–3 from issue.
• Item 4 (AAO-hosted community mirror catalogs): static files on CDN, not an Express route. Separate infrastructure decision; file a follow-up when ready to implement the hosting.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01WJQgMna6YBQ8AcXf8BceFg

---

Generated by Claude Code