Add fetch_agent_authorizations() helper to adcp.adagents

[bokelley]

Summary

Add a convenience function to discover what publishers have authorized a specific sales agent.

Motivation

Sales agents need to:

1. Check authorization across many publishers (100+)
2. Discover which property IDs and tags they're authorized for
3. Handle errors gracefully (404, timeout, validation)

Currently requires manual combination of:

• fetch_adagents() for each domain
• verify_agent_authorization() to check if listed
• get_properties_by_agent() to extract properties
• Custom error handling and parallelization

Proposed API

from adcp.adagents import fetch_agent_authorizations

# Discover what publishers have authorized your agent
contexts = await fetch_agent_authorizations(
    "https://our-sales-agent.com",
    ["nytimes.com", "wsj.com", "cnn.com"]
)

for domain, ctx in contexts.items():
    print(f"{domain}:")
    if ctx.is_authorized:
        print(f"  Property IDs: {ctx.property_ids}")
        print(f"  Tags: {ctx.property_tags}")

Features

• ✅ Parallel fetches with rate limiting
• ✅ Structured results via AgentAuthorizationContext dataclass
• ✅ Error handling (404, timeout, validation failures)
• ✅ Property extraction - IDs and tags in one call
• ✅ Scalable - handles 100+ publishers efficiently

Implementation

See reference implementation: https://github.com/adcontextprotocol/salesagent/blob/main/docs/specs/fetch_agent_authorizations.py

Use Case

Sales agent startup flow:

# Load publisher partners from database
publishers = ["nytimes.com", "espn.com", ...]  # 100+ domains

# Discover authorizations in parallel (~1 second for 100 domains)
contexts = await fetch_agent_authorizations(OUR_AGENT_URL, publishers)

# Store verification results
for domain, ctx in contexts.items():
    update_publisher_status(domain, ctx.is_authorized, ctx.error)
    
    if ctx.is_authorized:
        cache_authorized_properties(domain, ctx.property_ids, ctx.property_tags)

Related

• RFC: AdCP Registry API for cached adagents.json lookup adcp#201 - AdCP Registry API (long-term solution)
• This function provides immediate value while registry is being built