feat(adagents): fetch_agent_authorizations_from_directory — inverse lookup against AAO directory

[bokelley]

Background

fetch_agent_authorizations(agent_url, publisher_domains=[...]) at adcp/adagents.py:1306 requires the caller to supply the publisher list. That's fine when the list is known and small, but fails for managed-publisher cases like Raptive (~6,800 domains under CafeMedia) where the operator's whole problem is discovering the list.

The spec-side discussion lives at adcontextprotocol/adcp#4823 — proposing an AAO directory inverse-lookup endpoint (GET /v1/agents/{agent_url}/publishers). This SDK issue tracks the client-side function that wraps it.

Proposal

Add:

async def fetch_agent_authorizations_from_directory(
    agent_url: str,
    *,
    directory_url: str = \"https://agenticadvertising.org\",
    since: datetime | None = None,
    timeout: float = 30.0,
    client: httpx.AsyncClient | None = None,
) -> AgentAuthorizationsDirectoryResult:
    ...

Returns the directory's indexed view: list of publisher_domains authorizing this agent, with discovery_method (direct | authoritative_location | ads_txt_managerdomain), manager_domain where applicable, and property counts.

Mirrors the existing per-domain AdAgentsValidationResult field naming so callers can reuse downstream code paths.

since semantics

Optional incremental-sync cursor. Directory returns publishers whose last_verified_at > since. Operators use this for a daily cron that only re-syncs changed authorizations.

Configurability

directory_url is required-with-default rather than hardcoded so:

• Operators can point at staging / mirror directories during development
• Future federated-directory support doesn't require an SDK change
• Mirrors the existing AAO directory env-var convention (see salesagent's AAO_PUBLISHER_DIRECTORY_URL)

Error handling

Network errors → AdagentsTimeoutError / AdagentsValidationError (matches existing fetcher conventions). Directory returning 404 for the agent ("never indexed") → return empty publishers=[] rather than raise, so callers can treat "no authorizations yet" and "directory hasn't crawled yet" symmetrically.

Out of scope

• Caching layer (callers like salesagent have their own TTL policy)
• Reconciliation against locally-known publishers (caller's job)
• Push subscriptions (poll-based v1)

Blocked on

• feat(aao): inverse-lookup endpoint — given agent_url, return authorizing publishers adcp#4823 — endpoint shape needs to land first

References

• Triggering use case: prebid/salesagent#511
• Existing pull API: adcp/adagents.py:1306 fetch_agent_authorizations
• Existing single-domain discover-with-provenance: adcp/adagents.py:676 validate_adagents_domain

[bokelley]

Triage

Classification: Feature request
Bucket(s): cross-repo, client (neither label exists in this repo — flagged in run summary)
Status: deferred

What the experts said:
Expert consultation skipped — the issue author has already identified the precise blocker, and the implementation path is clear once the blocker resolves.

My take: This client-side wrapper (fetch_agent_authorizations_from_directory) cannot be meaningfully implemented until the AAO directory endpoint (GET /v1/agents/{agent_url}/publishers) is finalized in the spec, as pagination contract, error semantics (404 → empty list vs. raise), and field shape (discovery_method enum values) all flow from the spec definition. The proposal itself is well-scoped and non-breaking when it lands.

Blocked-on: adcontextprotocol/adcp#4823 — resurfaces on merge

---

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

---

Generated by Claude Code