bug(adagents): fetch_agent_authorizations_from_directory uses ?since= for cursor; spec says ?cursor=

[bokelley]

Symptom

fetch_agent_authorizations_from_directory (adcp/adagents.py) sends pagination cursors via ?since=<cursor>. The spec at docs/aao/directory-api.mdx defines two distinct query parameters:

param	type	purpose
since	ISO 8601	Return only publishers whose last_verified_at ≥ since. Incremental sync.
cursor	opaque string	Pagination cursor returned by a prior response.

The SDK's docstring conflates them:

since: Optional opaque cursor or RFC 3339 timestamp from a prior
    ``directory_indexed_at`` — passed through as ``?since=...``

Production server enforces the spec — ?since=<cursor> returns 400:

$ curl -s -o /dev/null -w "%{http_code}\n" \
    "https://agenticadvertising.org/api/v1/agents/https%3A%2F%2Finterchange.io/publishers?since=YWxsbnVyc2VzLmNvbQ"
400

$ curl -s -o /dev/null -w "%{http_code}\n" \
    "https://agenticadvertising.org/api/v1/agents/https%3A%2F%2Finterchange.io/publishers?cursor=YWxsbnVyc2VzLmNvbQ"
200

Impact

Pagination is broken end-to-end for the Python SDK. Caught against Raptive's ~6,800-publisher set:

result = await fetch_agent_authorizations_from_directory(
    "https://interchange.io",
    directory_url="https://agenticadvertising.org/api",
    since=cursor_from_previous_page,
)
# AdagentsValidationError: Agent-publishers directory returned HTTP 400

First page works (no cursor passed). Second page onward 400s. So today the SDK can fetch the first 200 publishers of a 6,800-publisher network and then fails.

Reproduction

import asyncio, urllib.parse, httpx

async def main():
    base = "https://agenticadvertising.org/api/v1/agents"
    agent = urllib.parse.quote("https://interchange.io", safe="")
    url = f"{base}/{agent}/publishers"

    async with httpx.AsyncClient(timeout=30) as c:
        page1 = (await c.get(url)).json()
        cursor = page1["next_cursor"]

        # SDK behavior — fails
        r = await c.get(url, params={"since": cursor})
        print(f"  since=cursor → HTTP {r.status_code}")  # 400

        # Spec behavior — works
        r = await c.get(url, params={"cursor": cursor})
        print(f"  cursor=cursor → HTTP {r.status_code}")  # 200

asyncio.run(main())

Fix

Add a distinct cursor: str | None = None keyword to fetch_agent_authorizations_from_directory, separate from since:

async def fetch_agent_authorizations_from_directory(
    agent_url: str,
    *,
    directory_url: str,
    since: str | None = None,          # ISO 8601 timestamp — incremental sync
    cursor: str | None = None,         # opaque pagination cursor
    include: list[str] | None = None,
    timeout: float = 10.0,
    client: httpx.AsyncClient | None = None,
) -> AgentAuthorizationsDirectoryResult:
    ...

Send since and cursor as separate query params. Update docstring to stop conflating them. Treat as a v5.7.0 follow-on bugfix.

Companion server bug

The same investigation found that production mounts the endpoint at /api/v1/... instead of the spec's /v1/.... Filed at adcontextprotocol/adcp#4924. Independent — fixing either does not fix the other.

References

• Spec: docs/aao/directory-api.mdx lines 29-30, 124, 153, 194, 207-209
• SDK call site: adcp/adagents.py:2094
• Triggering use case: prebid/salesagent#511

[bokelley]

Triage

Classification: Bug
Bucket(s): client
Status: drafting-pr
Milestone: v5.7.1 patch

What the experts said:

• code-reviewer: approved — fix is additive-only, no callers broken, test corpus correctly extended; nits on test consistency addressed pre-merge
• ad-tech-protocol-expert: approved — next_cursor → ?cursor= is unambiguously correct per spec; since for ISO 8601 timestamps is unchanged and independent; no protocol concern

My take: The bug is real and well-documented — production servers return HTTP 400 on ?since=<opaque-cursor>, breaking all multi-page directory fetches beyond the first 200 results. The fix adds a distinct cursor keyword argument and corrects the internal pagination loop in detect_publisher_properties_divergence, which was the primary broken call site. Draft PR at #813.

---

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

---

Generated by Claude Code

[bokelley]

Closing as completed on current main. The SDK now exposes a distinct cursor parameter, sends it as ?cursor=, keeps since as the timestamp filter, and detect_publisher_properties_divergence paginates with cursor=cursor. The corresponding regression tests are present in tests/test_adagents.py.