Repository navigation
Description
Two related pieces of SDK work coming out of adcp#4825 and adcp#4823.
Part 1 — Inline-resolution path for publisher_properties selectors
adcp#4825 (spec PR adcp#4827) endorses parent-file inline resolution: when a parent file's top-level properties[] entries carry a publisher_domain matching one in the selector's publisher_domains[], the consumer MAY satisfy the selector from those inline properties without per-child adagents.json fetches.
This SDK has two related bugs at adcp/adagents.py:953-957:
-
Returns raw selector dicts instead of resolved properties.
get_properties_by_agent(cafemedia_data, "https://interchange.io")returns 1 selector dict instead of the 6,843 inline properties. -
No
publisher_domains[]fan-out._resolve_agent_propertiesdoesn't expand the compact-formpublisher_domains[]array into per-domain resolution. This is the bug adcp#4825's triage identified as orthogonal to the spec change.
Both need fixing. The fix:
if authorization_type == "publisher_properties":
selectors = agent.get("publisher_properties", [])
if not isinstance(selectors, list):
return []
resolved: list[Property] = []
parent_properties = adagents_data.get("properties", []) or []
for selector in selectors:
if not isinstance(selector, dict):
continue
domains = _selector_domains(selector) # publisher_domain | publisher_domains
for domain in domains:
inline = _resolve_inline(selector, parent_properties, domain)
if inline is not None:
resolved.extend(inline)
continue # inline succeeded; skip federated fetch
resolved.extend(_resolve_federated(selector, domain))
return resolved_resolve_inline returns None (not []) when no matched property carries the expected publisher_domain, so federated fallback fires. Empty inline match with at least one inline candidate counts as a real empty resolution.
Divergence rule (from spec): if both paths resolve to the same (publisher_domain, property_id) and disagree, federated wins; SDK SHOULD log the divergence.
Revocation: inline path MUST honor revoked_publisher_domains[] on the parent file.
Part 2 — Directory inverse-lookup wrapper
adcp#4823 (spec PR adcp#4828) defines GET /v1/agents/{agent_url}/publishers. SDK needs a wrapper:
def fetch_agent_authorizations_from_directory(
agent_url: str,
directory_url: str = "https://agenticadvertising.org",
*,
since: datetime | None = None,
status: list[str] = ["authorized"],
cursor: str | None = None,
limit: int = 200,
timeout: float = 30.0,
) -> AgentDirectoryLookup:
"""Inverse of fetch_agent_authorizations — returns the publishers
that authorize this agent, sourced from the AAO directory's index.
Mirrors the existing AdAgentsValidationResult provenance fields
(discovery_method, manager_domain) so consumers can route directory-
sourced and per-domain results through the same code path.
"""Return type mirrors the response envelope schema. Iterator support for paginated responses is a plus.
Acceptance
Part 1:
-
get_properties_by_agent(cafemedia_data, "https://interchange.io")returns the 6,843 inline properties matchingtags ∋ "raptive_managed"andpublisher_domain ∈ publisher_domains[...], not the selector dicts. -
publisher_domains[]compact form is fanned into per-domain resolution. - When inline and federated diverge, SDK logs the divergence and uses the federated result.
- Parent-file
revoked_publisher_domains[]revokes inline matches for that domain.
Part 2:
-
fetch_agent_authorizations_from_directoryreturns spec-conformantAgentDirectoryLookupwithdiscovery_method,manager_domain,properties_authorized,properties_total,signing_keys_pinned,status,last_verified_atper publisher. - Cursor pagination handled transparently or exposed as iterator.
- Reuses
AdAgentsValidationResultprovenance fields where the vocabulary overlaps.
References
- Spec PR for the resolution rule: adcp#4827
- Spec PR for the directory endpoint: adcp#4828
- Downstream consumer hitting Part 1: prebid/salesagent#511
- Existing SDK gap:
adcp/adagents.py:909-959
Activity
fix(adagents): dedup resolved properties, fix by_id str filter, updat…
bokelley commentedon May 20, 2026
Triage
Classification: Bug (Part 1) + Feature request (Part 2)
Bucket(s): client (no
clientlabel exists in this repo — gap noted)Status: drafting-pr (Part 1 shipped as #750) / clarify (Part 2 pending 3 questions below)
What the experts said:
by_idbranch missingisinstance(str)filter (fixed); no dedup across multi-selector fan-out (fixed); missingby_idunit test (added). Part 2 — mutable defaultstatus=["authorized"]is a footgun; function must beasync defto match the rest of the module.publisher_domains[]compact form is not in the 3.0 schema cache (needs regeneration after adcp#4827 merges). Part 2 — endpoint/v1/agents/{url}/publishersdoesn't match the live/api/registry/base already in the SDK;AgentDirectoryLookupreturn type is undefined;agent_urlmust be%-encoded in the path.My take: Part 1 is a clear bug fix with spec backing — draft PR #750 ships today. Part 2 has three unresolved protocol questions; implementing it now would produce a 404-ing endpoint wrapper with an undefined return type.
Part 2 — 3 questions before I can proceed:
Endpoint path: Is it
/v1/agents/{encoded_url}/publishersor/api/registry/agents/{encoded_url}/publishers? The SDK's existingRegistryClientuses the/api/registry/base — if/v1/is a new tree onagenticadvertising.org, please link the changelog or confirm the route.Return type: Should
AgentDirectoryLookupbe a new Pydantic type (needs a schema file +_generated.py+stable.pyexport pipeline) or an extension/alias of the existingFederatedAgentWithDetails? The latter already carriespublisher_domains: list[str] | None.Divergence rule: Is there a normative quote from adcp#4827 confirming "federated wins on disagreement"? The current PR defers divergence logging pending that confirmation — happy to add it once I can verify the trust-ordering direction.
Part 1 shipped: #750
Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}
Generated by Claude Code
bokelley commentedon May 20, 2026
Refinements after merging adcp#4827 + adcp#4828 + adcp#4838 + adcp#4840
Two additions to the work already scoped above:
1. Canonical fixture: cafemedia.com / interchange.io
After PR adcp#4840 deploys (the crawler write-path that fans
publisher_properties[].publisher_domains[]into per-child rows), production has real data backing the inline-resolution path:https://cafemedia.com/.well-known/adagents.json— 2.6 MB, 6,843 inlineproperties[], 6,800 unique child publisher_domains, all taggedraptive_managed. One authorized agent:https://interchange.io.GET https://agenticadvertising.org/api/v1/agents/https%3A%2F%2Finterchange.io/publishersreturns ~6,800 rows withdiscovery_method='adagents_authoritative'andmanager_domain='cafemedia.com'.Use this as the canonical fixture for the SDK's
_resolve_agent_propertiestest suite — it's the production reference for the managed-network shape, sized large enough to catch O(N²) accidents and provenance edge cases.2. Part 3 — Divergence detector
When the inline resolution path (Part 1) and federated resolution (per-child fetch) produce different
(publisher_domain, property_id)sets, the spec says federated wins and the SDK SHOULD log a divergence warning (adagents.mdx Resolution paths). Today no consumer ever sees that signal because no one runs both paths.Add a verifier helper:
sample_sizeis required for managed networks — running this against cafemedia's 6,800 children means 6,800 sequential HTTP fetches. Default to None (full sweep) but document the cost.Output should be machine-readable so a sales agent operator can hook it into their existing monitoring rather than reading SDK logs.
This is Part 3 of the ticket — same SDK release as Parts 1 and 2.
Updated acceptance
Part 1 (inline resolution):
get_properties_by_agent(cafemedia_data, "https://interchange.io")Part 2 (directory wrapper):
Part 3 (divergence detector):
detect_publisher_properties_divergencereturns expected drift on a synthetic test fixture where parent and child disagreesample_sizeparameter caps itperf(adagents): index parent properties by domain to fix O(N×M) at ca…
test(adagents): tighten cafemedia fixture domain assertion to equality
fix(adagents): address expert-review blockers on divergence detector …
fix(adagents): address code-reviewer findings on Parts 2+3
bokelley commentedon May 20, 2026
Triage update — re-engaged on @bokelley's refinements comment
New scope in the comment: cafemedia/interchange.io canonical fixture (Part 1), divergence detector (Part 3), and partial unblock of Part 2.
What shipped:
Part 1 additions → PR #750 (existing draft, new commits):
_resolve_agent_properties: pre-builds adomain→propertiesindex before the selector loop so each per-domain lookup is O(1) instead of O(N). At cafemedia scale (6,843 × 6,800 = 46 M comparisons without the index), the old code would have timed out in tests.raptive_managedchild domains,publisher_domains[]compact form). Sized to catch O(N×M) regressions.Parts 2+3 → draft PR #752 (new):
fetch_agent_authorizations_from_directory— async wrapper forGET /api/v1/agents/{encoded_url}/publishers. Returns pagedAgentDirectoryLookup+AgentPublisherEntryper publisher. Endpoint path confirmed by your comment;statususes repeated query params.detect_publisher_properties_divergence— compares directory'sproperties_authorizedcount against per-child federated fetch. ReturnsDivergenceReport(list ofPublisherDivergence).sample_sizecaps sweeps on large networks.missing_in_inline/missing_in_federatedarelist[str] | NonewhereNonesignals count-only mode. Count-equality ≠ set-equality (same-count property replacement is undetectable at this level). Will upgrade to full(publisher_domain, property_id)set-diff once?include=propertiesis deployed.adcp.__init__.Part 2 questions (from prior triage), now resolved:
/api/v1/agents/{encoded_url}/publishers✓ confirmed by your commentAgentDirectoryLookup/AgentPublisherEntrydataclasses matching the schema fields from the issue acceptance criteriaWhat remains open:
(publisher_domain, property_id)set-diff in Part 3 (requires?include=propertiesdirectory support)revoked_publisher_domains[]revocation (deferred, pending schema definition)Triaged by Claude Code. Session: https://claude.ai/code/session_01RDYrywLhVbd4crrAHkTnsH
Generated by Claude Code
feat(adagents): inline-resolution path for publisher_properties selec…
feat(adagents): full set-diff divergence detection via ?include=prope…
feat(adagents): directory inverse-lookup + divergence detector (Parts…
feat(adagents): divergence detector + ?include=properties for directo…
feat(adagents): inline-resolution path for publisher_properties selec…
feat(adagents): inline-resolution path for publisher_properties selec…
feat(adagents): divergence detector + ?include=properties for directo…
feat(adagents): divergence detector + ?include=properties for directo…
feat(adagents): divergence detector + ?include=properties for directo…