Skip to content

fix: make server dispatch automatically adapt responses by requested AdCP version #868

Closed

Description

@bokelley

Summary

After #855, the Python SDK exposes resolve_requested_adcp_version(), which is useful, but seller applications still have to wire the versioning contract manually inside tool handlers.

That leaves generic protocol behavior in every adopter:

  • Resolve the buyer's requested AdCP release from request payload fields.
  • Default omitted/legacy buyers to the correct 3.0 compatibility behavior.
  • Convert unsupported versions into a protocol error.
  • Project media-buy responses into the requested release shape.
  • Keep MCP and A2A behavior consistent.

This should be automatic in the SDK/server dispatch layer. Seller handlers should be able to return the canonical current response model, and the server should serialize the correct wire shape for the buyer.

Current adopter-side code

Prebid Sales Agent currently has to carry local code equivalent to:

SUPPORTED_ADCP_VERSIONS = ("3.0", "3.1-beta.3")

requested_adcp_version = resolve_requested_adcp_version(
    request_payload,
    supported=SUPPORTED_ADCP_VERSIONS,
)

if requested_adcp_version == "3.0" and response.status == "completed":
    response.status = response.media_buy_status
    del response.media_buy_status

The real code is more defensive, but the important point is that it is protocol negotiation and response projection, not seller business logic.

Expected

The SDK/server layer should own version negotiation and response serialization:

  • Resolve the requested version once during dispatch.
  • Reject unsupported versions before invoking the platform handler, or expose a standard exception mapping.
  • Expose the resolved version on RequestContext for legitimate business-logic cases.
  • Normalize versioned response shapes after the handler returns, for both MCP and A2A.
  • Keep this behavior aligned with advertised supported_versions.

Then a seller can implement create_media_buy/update_media_buy once and return the current canonical model:

{
  "status": "completed",
  "media_buy_status": "pending_creatives"
}

The SDK would emit legacy 3.0 wire shape for 3.0 buyers:

{
  "status": "pending_creatives"
}

and 3.1 shape for explicit 3.1 buyers:

{
  "status": "completed",
  "media_buy_status": "pending_creatives"
}

Why this matters

If this stays in seller code, every adopter has to rediscover the same edge cases and keep MCP/A2A behavior aligned by hand. That is exactly the kind of SDK workaround that will fragment implementations.

Related follow-ups from the same integration pass:

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 26, 2026
  2. bokelley commented on May 26, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Feature request
    Bucket(s): handlers, middleware (neither label exists in repo — flagged in run summary)
    Status: ready-to-implement

    What the experts said:

    • dx-expert: real boilerplate reduction; resolved_adcp_version: str | None = None on ToolContext is the right attachment point; non-breaking additive field; cautions that sellers doing manual version projection today must remove their projection code after migration or it will be applied twice
    • ad-tech-protocol-expert: MCP dispatch already centralizes normalization correctly; A2A gap is confirmed — a2a_server.py never calls _normalize_response_envelope at all; spec places projection on the transport layer, not the handler; critical: None must mean "assume latest" in A2A, not collapse to the DEFAULT_UNNEGOTIATED_ADCP_VERSION = "3.0" pin that unnegotiated MCP traffic uses

    My take: The dispatch already resolves wire version and normalizes MCP responses internally — the two missing pieces are (1) threading the resolved version onto ToolContext so handlers can observe it, and (2) extending the same normalization to the A2A path, which currently has none. Both are additive and the normalization is idempotent with what the MCP path already does.

    Implementation scope:

    • src/adcp/server/base.py — add resolved_adcp_version: str | None = None to ToolContext
    • src/adcp/server/mcp_tools.py — set ctx.resolved_adcp_version = wire_version in call_tool after the version is resolved (~line 2307)
    • src/adcp/server/a2a_server.py — add detect_wire_version call and post-handler _normalize_response_envelope (currently absent); preserve None = assume latest, not None = 3.0
    • Tests: ToolContext.resolved_adcp_version is populated in both MCP and A2A dispatch; A2A path normalizes 3.0 shapes correctly
    • Required checks: pytest tests/, mypy src/adcp/server/, ruff check src/
    • Non-breaking: new None-default field on ToolContext; MCP normalization already runs today; A2A addition is strictly additive

    Related: #866 (MCP outputSchema validation, parallel work, not a blocker).


    Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}


    Generated by Claude Code

  3. added
    enhancementNew feature or request
    and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 26, 2026
  4. bokelley commented on May 26, 2026

    @bokelley
    ContributorAuthor

    Resolved on main by the server dispatch/version negotiation work. Dispatch now resolves the requested ADCP version, threads , and applies response adaptation; A2A uses the same tool-caller path with explicit major-version projection coverage in .

  5. bokelley commented on May 26, 2026

    @bokelley
    ContributorAuthor

    Correction to the close note above: resolved on main by the server dispatch/version negotiation work. Dispatch now resolves the requested ADCP version, threads ToolContext.resolved_adcp_version, and applies response adaptation; A2A uses the same tool-caller path with explicit major-version projection coverage in tests/test_a2a_server.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

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions