Skip to content

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

Closed

Description

@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

Activity

  1. added
    bugSomething isn't working
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 22, 2026
  2. added a commit that references this issue on May 22, 2026
    ef3c34f
  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 22, 2026
  4. bokelley commented on May 22, 2026

    @bokelley
    ContributorAuthor

    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

  5. bokelley commented on May 23, 2026

    @bokelley
    ContributorAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions