Skip to content

feat: add V3 protocol support (Governance, Content Standards, SI, CLI) #117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
bokelley wants to merge 10 commits into
base: main
Choose a base branch
from
Open

feat: add V3 protocol support (Governance, Content Standards, SI, CLI) #117

bokelley wants to merge 10 commits into from
+16,049 −3,914

Conversation

@bokelley
Copy link
Contributor

@bokelley bokelley commented Jan 25, 2026

Summary

This PR adds comprehensive ADCP V3 protocol support to the Python SDK:

  • Governance (Property Lists): Full support for property list management with GovernanceHandler
  • Content Standards: Content calibration and validation with ContentStandardsHandler
  • Sponsored Intelligence: Conversational AI sponsorship with SponsoredIntelligenceHandler
  • Protocol Discovery: get_adcp_capabilities for runtime capability detection
  • CLI Support: All 17 V3 operations available from command line

Server Framework

New handler base classes for implementing ADCP agents:

  • GovernanceHandler - 5 abstract methods for property list CRUD
  • ContentStandardsHandler - 7 abstract methods for content standards operations
  • SponsoredIntelligenceHandler - 4 abstract methods for SI sessions
  • All handlers stub cross-domain operations with clear "not supported" messages

Client

  • Typed client methods for all V3 operations
  • Proper activity logging for observability
  • Full type exports from adcp.types

CLI

All V3 operations added to adcp command:

# Protocol Discovery
adcp myagent get_adcp_capabilities

# Content Standards  
adcp cs-agent calibrate_content '{"content_standards_id":"cs-123"}'

# Sponsored Intelligence
adcp si-agent si_get_offering

# Governance
adcp gov-agent list_property_lists

Protocol Adapters

Governance methods added to both MCP and A2A adapters.

Test plan

  • All 502 tests pass
  • Server framework tests for all handler types
  • CLI dispatch tests for V3 operations
  • Code review by subagent
  • Protocol expert review by subagent

🤖 Generated with Claude Code

bokelley and others added 10 commits January 25, 2026 18:49
@bokelley @claude
feat: add V3 protocol support (Governance, Content Standards, SI, CLI)
a550aa6 
Add comprehensive V3 ADCP protocol support including:

Server Framework:
- Add GovernanceHandler for property list management
- Add ContentStandardsHandler for content calibration
- Add SponsoredIntelligenceHandler for conversational AI sponsorship
- Add governance method stubs to all protocol handlers
- Add MCP tool definitions for all V3 operations

Client:
- Add typed client methods for all V3 operations
- Export all V3 types from adcp.types

Protocol Adapters:
- Add governance methods to protocol base class
- Add governance implementations to MCP and A2A adapters

CLI:
- Add all V3 operations to command-line client:
  - Protocol Discovery: get_adcp_capabilities
  - Content Standards: 7 operations
  - Sponsored Intelligence: 4 operations
  - Governance: 5 operations

Types:
- Sync schemas with ADCP 2.6+ spec
- Generate types for V3 domains

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bokelley @claude
fix: resolve ruff linting errors
0e86feb 
- Fix import block sorting (I001) across multiple files
- Remove unused import ContentStandards from content_standards.py
- Update Callable import to collections.abc in mcp_tools.py
- Fix line length (E501) in server/base.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bokelley @claude
feat: sync with ADCP 2.6 schema changes
f19d9af 
- Sync schemas from upstream adcontextprotocol.org
- Consolidate pricing options (CpmAuction/CpmFixed -> CpmPricingOption, VcpmAuction/VcpmFixed -> VcpmPricingOption)
- Consolidate PreviewRender (UrlPreviewRender/HtmlPreviewRender/BothPreviewRender -> unified PreviewRender)
- Update type exports and aliases for backwards compatibility
- Fix preview_cache.py to work with unified PreviewRender (no longer RootModel)
- Update tests to reflect schema changes

BREAKING CHANGE: CpmAuctionPricingOption, CpmFixedRatePricingOption, VcpmAuctionPricingOption, VcpmFixedRatePricingOption have been consolidated into CpmPricingOption and VcpmPricingOption respectively.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bokelley @claude
fix: resolve ruff import sorting error in _ergonomic.py
2afad34 
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bokelley @claude
feat: sync schemas with upstream and fix type generation
263665f 
- Fix generate_types.py to convert absolute /schemas/latest/ $ref paths
  to relative paths for proper schema resolution
- Sync all schemas from upstream (ADCP package 2.6)
- PreviewRender is now a discriminated union by output_format:
  - PreviewRender1 (output_format='url') with preview_url
  - PreviewRender2 (output_format='html') with preview_html
  - PreviewRender3 (output_format='both') with both
- Update aliases: UrlPreviewRender, HtmlPreviewRender, BothPreviewRender
  now point to their respective variant types
- Fix preview_cache.py to access RootModel.root for PreviewRender
- Update tests for discriminated union types

This fixes the "Validate schemas are up-to-date" CI failure.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bokelley @claude
feat: support authoritative_location redirects in fetch_adagents
349ef38 
- Implements authoritative_location redirect following per AdCP spec
- When adagents.json contains authoritative_location instead of
  authorized_agents, fetches the referenced URL for actual data
- Includes loop detection and max depth limit (5) for security
- Validates HTTPS requirement for authoritative_location URLs
- Tests for happy path, HTTPS validation, loop detection, max depth

Cherry-picked from PR #118 (bokelley/issue-114)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bokelley @claude
fix: address PR review feedback for V3 migration
86160e9 
Handler Method Signatures:
- Refactored GovernanceHandler, ContentStandardsHandler, and
  SponsoredIntelligenceHandler to fix Liskov Substitution Principle violation
- Public methods now accept params: dict[str, Any] matching base class
- Added Pydantic validation with proper error responses
- Abstract handle_* methods accept typed requests for type safety

CLI Dispatch Table:
- Replaced mutable global TOOL_DISPATCH with cached _get_dispatch_table()
- Fails fast with clear error message if types can't be imported
- Eliminates late import error surprises

Version Interop Tests:
- Added test_version_interop.py to verify V3/V2 compatibility
- Tests V3-only tools are in dispatch table
- Tests V2 core tools remain available
- Tests base handler returns 'not supported' for unimplemented V3 methods

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bokelley @claude
fix: rename summary() to model_summary() to avoid field collision
d24bf06 
The generated POC types have `summary` fields that conflicted with
the AdCPBaseModel.summary() method, causing mypy errors. Renamed
to model_summary() to follow Pydantic's naming convention
(model_dump, model_dump_json, etc.) and avoid the collision.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bokelley @claude
docs: add tests documenting version negotiation design
7195fda 
Version negotiation is intentionally delegated to consumers. The SDK
provides primitives (get_adcp_capabilities, TaskResult wrapping), not
policy. Added TestVersionNegotiationDesign class with tests that serve
as executable documentation for:

- TaskResult error wrapping pattern
- Capabilities response structure
- Recommended version detection pattern
- Recommended feature detection pattern

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@bokelley @claude
docs: update pricing option examples to current schema format
2bfb1f7 
Updated test fixtures and documentation examples from deprecated format:
  {"model": "cpm_fixed_rate", "is_fixed": true, "cpm": 5.50}

To current unified CpmPricingOption schema format:
  {
    "pricing_model": "cpm",
    "pricing_option_id": "po-1",
    "currency": "USD",
    "fixed_price": 5.50
  }

The old format used separate types with is_fixed discriminator.
The new schema uses optional fixed_price/floor_price fields to
distinguish fixed vs auction pricing.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@bokelley