adcp 1.4.1__py3-none-any.whl → 1.6.0__py3-none-any.whl

adcp/__init__.py

@@ -7,8 +7,21 @@ Official Python client for the Ad Context Protocol (AdCP).
 Supports both A2A and MCP protocols with full type safety.
 """
 
+from adcp.adagents import (
+    domain_matches,
+    fetch_adagents,
+    get_all_properties,
+    get_all_tags,
+    get_properties_by_agent,
+    identifiers_match,
+    verify_agent_authorization,
+    verify_agent_for_property,
+)
 from adcp.client import ADCPClient, ADCPMultiAgentClient
 from adcp.exceptions import (
+    AdagentsNotFoundError,
+    AdagentsTimeoutError,
+    AdagentsValidationError,
     ADCPAuthenticationError,
     ADCPConnectionError,
     ADCPError,
@@ -150,7 +163,7 @@ from adcp.types.generated import (
     TaskStatus as GeneratedTaskStatus,
 )
 
-__version__ = "1.4.1"
+__version__ = "1.6.0"
 
 __all__ = [
     # Client classes
@@ -162,6 +175,15 @@ __all__ = [
     "TaskResult",
     "TaskStatus",
     "WebhookMetadata",
+    # Adagents validation
+    "fetch_adagents",
+    "verify_agent_authorization",
+    "verify_agent_for_property",
+    "domain_matches",
+    "identifiers_match",
+    "get_all_properties",
+    "get_all_tags",
+    "get_properties_by_agent",
     # Test helpers
     "test_agent",
     "test_agent_a2a",
@@ -185,6 +207,9 @@ __all__ = [
     "ADCPToolNotFoundError",
     "ADCPWebhookError",
     "ADCPWebhookSignatureError",
+    "AdagentsValidationError",
+    "AdagentsNotFoundError",
+    "AdagentsTimeoutError",
     # Request/Response types
     "ActivateSignalRequest",
     "ActivateSignalResponse",

adcp/adagents.py

@@ -0,0 +1,521 @@
+from __future__ import annotations
+
+"""
+Utilities for fetching, parsing, and validating adagents.json files per the AdCP specification.
+
+Publishers declare authorized sales agents via adagents.json files hosted at
+https://{publisher_domain}/.well-known/adagents.json. This module provides utilities
+for sales agents to verify they are authorized for specific properties.
+"""
+
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from adcp.exceptions import AdagentsNotFoundError, AdagentsTimeoutError, AdagentsValidationError
+
+
+def _normalize_domain(domain: str) -> str:
+    """Normalize domain for comparison - strip, lowercase, remove trailing dots/slashes.
+
+    Args:
+        domain: Domain to normalize
+
+    Returns:
+        Normalized domain string
+
+    Raises:
+        AdagentsValidationError: If domain contains invalid patterns
+    """
+    domain = domain.strip().lower()
+    # Remove both trailing slashes and dots iteratively
+    while domain.endswith("/") or domain.endswith("."):
+        domain = domain.rstrip("/").rstrip(".")
+
+    # Check for invalid patterns
+    if not domain or ".." in domain:
+        raise AdagentsValidationError(f"Invalid domain format: {domain!r}")
+
+    return domain
+
+
+def _validate_publisher_domain(domain: str) -> str:
+    """Validate and sanitize publisher domain for security.
+
+    Args:
+        domain: Publisher domain to validate
+
+    Returns:
+        Validated and normalized domain
+
+    Raises:
+        AdagentsValidationError: If domain is invalid or contains suspicious characters
+    """
+    # Check for suspicious characters BEFORE stripping (to catch injection attempts)
+    suspicious_chars = ["\\", "@", "\n", "\r", "\t"]
+    for char in suspicious_chars:
+        if char in domain:
+            raise AdagentsValidationError(
+                f"Invalid character in publisher domain: {char!r}"
+            )
+
+    domain = domain.strip()
+
+    # Check basic constraints
+    if not domain:
+        raise AdagentsValidationError("Publisher domain cannot be empty")
+    if len(domain) > 253:  # DNS maximum length
+        raise AdagentsValidationError(f"Publisher domain too long: {len(domain)} chars (max 253)")
+
+    # Check for spaces after stripping leading/trailing whitespace
+    if " " in domain:
+        raise AdagentsValidationError(
+            "Invalid character in publisher domain: ' '"
+        )
+
+    # Remove protocol if present (common user error) - do this BEFORE checking for slashes
+    if "://" in domain:
+        domain = domain.split("://", 1)[1]
+
+    # Remove path if present (should only be domain) - do this BEFORE checking for slashes
+    if "/" in domain:
+        domain = domain.split("/", 1)[0]
+
+    # Normalize
+    domain = _normalize_domain(domain)
+
+    # Final validation - must look like a domain
+    if "." not in domain:
+        raise AdagentsValidationError(
+            f"Publisher domain must contain at least one dot: {domain!r}"
+        )
+
+    return domain
+
+
+def normalize_url(url: str) -> str:
+    """Normalize URL by removing protocol and trailing slash.
+
+    Args:
+        url: URL to normalize
+
+    Returns:
+        Normalized URL (domain/path without protocol or trailing slash)
+    """
+    parsed = urlparse(url)
+    normalized = parsed.netloc + parsed.path
+    return normalized.rstrip("/")
+
+
+def domain_matches(property_domain: str, agent_domain_pattern: str) -> bool:
+    """Check if domains match per AdCP rules.
+
+    Rules:
+    - Exact match always succeeds
+    - 'example.com' matches www.example.com, m.example.com (common subdomains)
+    - 'subdomain.example.com' matches that specific subdomain only
+    - '*.example.com' matches all subdomains
+
+    Args:
+        property_domain: Domain from property
+        agent_domain_pattern: Domain pattern from adagents.json
+
+    Returns:
+        True if domains match per AdCP rules
+    """
+    # Normalize both domains for comparison
+    try:
+        property_domain = _normalize_domain(property_domain)
+        agent_domain_pattern = _normalize_domain(agent_domain_pattern)
+    except AdagentsValidationError:
+        # Invalid domain format - no match
+        return False
+
+    # Exact match
+    if property_domain == agent_domain_pattern:
+        return True
+
+    # Wildcard pattern (*.example.com)
+    if agent_domain_pattern.startswith("*."):
+        base_domain = agent_domain_pattern[2:]
+        return property_domain.endswith(f".{base_domain}")
+
+    # Bare domain matches common subdomains (www, m)
+    # If agent pattern is a bare domain (no subdomain), match www/m subdomains
+    if "." in agent_domain_pattern and not agent_domain_pattern.startswith("www."):
+        # Check if this looks like a bare domain (e.g., example.com)
+        parts = agent_domain_pattern.split(".")
+        if len(parts) == 2:  # Looks like bare domain
+            common_subdomains = ["www", "m"]
+            for subdomain in common_subdomains:
+                if property_domain == f"{subdomain}.{agent_domain_pattern}":
+                    return True
+
+    return False
+
+
+def identifiers_match(
+    property_identifiers: list[dict[str, str]],
+    agent_identifiers: list[dict[str, str]],
+) -> bool:
+    """Check if any property identifier matches agent's authorized identifiers.
+
+    Args:
+        property_identifiers: Identifiers from property
+            (e.g., [{"type": "domain", "value": "cnn.com"}])
+        agent_identifiers: Identifiers from adagents.json
+
+    Returns:
+        True if any identifier matches
+
+    Notes:
+        - Domain identifiers use AdCP domain matching rules
+        - Other identifiers (bundle_id, roku_store_id, etc.) require exact match
+    """
+    for prop_id in property_identifiers:
+        prop_type = prop_id.get("type", "")
+        prop_value = prop_id.get("value", "")
+
+        for agent_id in agent_identifiers:
+            agent_type = agent_id.get("type", "")
+            agent_value = agent_id.get("value", "")
+
+            # Type must match
+            if prop_type != agent_type:
+                continue
+
+            # Domain identifiers use special matching rules
+            if prop_type == "domain":
+                if domain_matches(prop_value, agent_value):
+                    return True
+            else:
+                # Other identifier types require exact match
+                if prop_value == agent_value:
+                    return True
+
+    return False
+
+
+def verify_agent_authorization(
+    adagents_data: dict[str, Any],
+    agent_url: str,
+    property_type: str | None = None,
+    property_identifiers: list[dict[str, str]] | None = None,
+) -> bool:
+    """Check if agent is authorized for a property.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+        agent_url: URL of the sales agent to verify
+        property_type: Type of property (website, app, etc.) - optional
+        property_identifiers: List of identifiers to match - optional
+
+    Returns:
+        True if agent is authorized, False otherwise
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+
+    Notes:
+        - If property_type/identifiers are None, checks if agent is authorized
+          for ANY property on this domain
+        - Implements AdCP domain matching rules
+        - Agent URLs are matched ignoring protocol and trailing slash
+    """
+    # Validate structure
+    if not isinstance(adagents_data, dict):
+        raise AdagentsValidationError("adagents_data must be a dictionary")
+
+    authorized_agents = adagents_data.get("authorized_agents")
+    if not isinstance(authorized_agents, list):
+        raise AdagentsValidationError("adagents.json must have 'authorized_agents' array")
+
+    # Normalize the agent URL for comparison
+    normalized_agent_url = normalize_url(agent_url)
+
+    # Check each authorized agent
+    for agent in authorized_agents:
+        if not isinstance(agent, dict):
+            continue
+
+        agent_url_from_json = agent.get("url", "")
+        if not agent_url_from_json:
+            continue
+
+        # Match agent URL (protocol-agnostic)
+        if normalize_url(agent_url_from_json) != normalized_agent_url:
+            continue
+
+        # Found matching agent - now check properties
+        properties = agent.get("properties")
+
+        # If properties field is missing or empty, agent is authorized for all properties
+        if properties is None or (isinstance(properties, list) and len(properties) == 0):
+            return True
+
+        # If no property filters specified, we found the agent - authorized
+        if property_type is None and property_identifiers is None:
+            return True
+
+        # Check specific property authorization
+        if isinstance(properties, list):
+            for prop in properties:
+                if not isinstance(prop, dict):
+                    continue
+
+                # Check property type if specified
+                if property_type is not None:
+                    prop_type = prop.get("property_type", "")
+                    if prop_type != property_type:
+                        continue
+
+                # Check identifiers if specified
+                if property_identifiers is not None:
+                    prop_identifiers = prop.get("identifiers", [])
+                    if not isinstance(prop_identifiers, list):
+                        continue
+
+                    if identifiers_match(property_identifiers, prop_identifiers):
+                        return True
+                else:
+                    # Property type matched and no identifier check needed
+                    return True
+
+    return False
+
+
+async def fetch_adagents(
+    publisher_domain: str,
+    timeout: float = 10.0,
+    user_agent: str = "AdCP-Client/1.0",
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """Fetch and parse adagents.json from publisher domain.
+
+    Args:
+        publisher_domain: Domain hosting the adagents.json file
+        timeout: Request timeout in seconds
+        user_agent: User-Agent header for HTTP request
+        client: Optional httpx.AsyncClient for connection pooling.
+            If provided, caller is responsible for client lifecycle.
+            If None, a new client is created for this request.
+
+    Returns:
+        Parsed adagents.json data
+
+    Raises:
+        AdagentsNotFoundError: If adagents.json not found (404)
+        AdagentsValidationError: If JSON is invalid or malformed
+        AdagentsTimeoutError: If request times out
+
+    Notes:
+        For production use with multiple requests, pass a shared httpx.AsyncClient
+        to enable connection pooling and improve performance.
+    """
+    # Validate and normalize domain for security
+    publisher_domain = _validate_publisher_domain(publisher_domain)
+
+    # Construct URL
+    url = f"https://{publisher_domain}/.well-known/adagents.json"
+
+    try:
+        # Use provided client or create a new one
+        if client is not None:
+            # Reuse provided client (connection pooling)
+            response = await client.get(
+                url,
+                headers={"User-Agent": user_agent},
+                timeout=timeout,
+                follow_redirects=True,
+            )
+        else:
+            # Create new client for single request
+            async with httpx.AsyncClient() as new_client:
+                response = await new_client.get(
+                    url,
+                    headers={"User-Agent": user_agent},
+                    timeout=timeout,
+                    follow_redirects=True,
+                )
+
+        # Process response (same for both paths)
+        if response.status_code == 404:
+            raise AdagentsNotFoundError(publisher_domain)
+
+        if response.status_code != 200:
+            raise AdagentsValidationError(
+                f"Failed to fetch adagents.json: HTTP {response.status_code}"
+            )
+
+        # Parse JSON
+        try:
+            data = response.json()
+        except Exception as e:
+            raise AdagentsValidationError(f"Invalid JSON in adagents.json: {e}") from e
+
+        # Validate basic structure
+        if not isinstance(data, dict):
+            raise AdagentsValidationError("adagents.json must be a JSON object")
+
+        if "authorized_agents" not in data:
+            raise AdagentsValidationError(
+                "adagents.json must have 'authorized_agents' field"
+            )
+
+        if not isinstance(data["authorized_agents"], list):
+            raise AdagentsValidationError("'authorized_agents' must be an array")
+
+        return data
+
+    except httpx.TimeoutException as e:
+        raise AdagentsTimeoutError(publisher_domain, timeout) from e
+    except httpx.RequestError as e:
+        raise AdagentsValidationError(f"Failed to fetch adagents.json: {e}") from e
+
+
+async def verify_agent_for_property(
+    publisher_domain: str,
+    agent_url: str,
+    property_identifiers: list[dict[str, str]],
+    property_type: str | None = None,
+    timeout: float = 10.0,
+    client: httpx.AsyncClient | None = None,
+) -> bool:
+    """Convenience wrapper to fetch adagents.json and verify authorization in one call.
+
+    Args:
+        publisher_domain: Domain hosting the adagents.json file
+        agent_url: URL of the sales agent to verify
+        property_identifiers: List of identifiers to match
+        property_type: Type of property (website, app, etc.) - optional
+        timeout: Request timeout in seconds
+        client: Optional httpx.AsyncClient for connection pooling
+
+    Returns:
+        True if agent is authorized, False otherwise
+
+    Raises:
+        AdagentsNotFoundError: If adagents.json not found (404)
+        AdagentsValidationError: If JSON is invalid or malformed
+        AdagentsTimeoutError: If request times out
+    """
+    adagents_data = await fetch_adagents(publisher_domain, timeout=timeout, client=client)
+    return verify_agent_authorization(
+        adagents_data=adagents_data,
+        agent_url=agent_url,
+        property_type=property_type,
+        property_identifiers=property_identifiers,
+    )
+
+
+def get_all_properties(adagents_data: dict[str, Any]) -> list[dict[str, Any]]:
+    """Extract all properties from adagents.json data.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+
+    Returns:
+        List of all properties across all authorized agents, with agent_url added
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+    """
+    if not isinstance(adagents_data, dict):
+        raise AdagentsValidationError("adagents_data must be a dictionary")
+
+    authorized_agents = adagents_data.get("authorized_agents")
+    if not isinstance(authorized_agents, list):
+        raise AdagentsValidationError("adagents.json must have 'authorized_agents' array")
+
+    properties = []
+    for agent in authorized_agents:
+        if not isinstance(agent, dict):
+            continue
+
+        agent_url = agent.get("url", "")
+        if not agent_url:
+            continue
+
+        agent_properties = agent.get("properties", [])
+        if not isinstance(agent_properties, list):
+            continue
+
+        # Add each property with the agent URL for reference
+        for prop in agent_properties:
+            if isinstance(prop, dict):
+                # Create a copy and add agent_url
+                prop_with_agent = {**prop, "agent_url": agent_url}
+                properties.append(prop_with_agent)
+
+    return properties
+
+
+def get_all_tags(adagents_data: dict[str, Any]) -> set[str]:
+    """Extract all unique tags from properties in adagents.json data.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+
+    Returns:
+        Set of all unique tags across all properties
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+    """
+    properties = get_all_properties(adagents_data)
+    tags = set()
+
+    for prop in properties:
+        prop_tags = prop.get("tags", [])
+        if isinstance(prop_tags, list):
+            for tag in prop_tags:
+                if isinstance(tag, str):
+                    tags.add(tag)
+
+    return tags
+
+
+def get_properties_by_agent(adagents_data: dict[str, Any], agent_url: str) -> list[dict[str, Any]]:
+    """Get all properties authorized for a specific agent.
+
+    Args:
+        adagents_data: Parsed adagents.json data
+        agent_url: URL of the agent to filter by
+
+    Returns:
+        List of properties for the specified agent (empty if agent not found or no properties)
+
+    Raises:
+        AdagentsValidationError: If adagents_data is malformed
+    """
+    if not isinstance(adagents_data, dict):
+        raise AdagentsValidationError("adagents_data must be a dictionary")
+
+    authorized_agents = adagents_data.get("authorized_agents")
+    if not isinstance(authorized_agents, list):
+        raise AdagentsValidationError("adagents.json must have 'authorized_agents' array")
+
+    # Normalize the agent URL for comparison
+    normalized_agent_url = normalize_url(agent_url)
+
+    for agent in authorized_agents:
+        if not isinstance(agent, dict):
+            continue
+
+        agent_url_from_json = agent.get("url", "")
+        if not agent_url_from_json:
+            continue
+
+        # Match agent URL (protocol-agnostic)
+        if normalize_url(agent_url_from_json) != normalized_agent_url:
+            continue
+
+        # Found the agent - return their properties
+        properties = agent.get("properties", [])
+        if not isinstance(properties, list):
+            return []
+
+        return [p for p in properties if isinstance(p, dict)]
+
+    return []

adcp/exceptions.py

@@ -153,3 +153,33 @@ class ADCPSimpleAPIError(ADCPError):
             f"         # Handle error with full TaskResult context"
         )
         super().__init__(message, agent_id, None, suggestion)
+
+
+class AdagentsValidationError(ADCPError):
+    """Base error for adagents.json validation issues."""
+
+
+class AdagentsNotFoundError(AdagentsValidationError):
+    """adagents.json file not found (404)."""
+
+    def __init__(self, publisher_domain: str):
+        """Initialize not found error."""
+        message = f"adagents.json not found for domain: {publisher_domain}"
+        suggestion = (
+            "Verify that the publisher has deployed adagents.json to:\n"
+            f"     https://{publisher_domain}/.well-known/adagents.json"
+        )
+        super().__init__(message, None, None, suggestion)
+
+
+class AdagentsTimeoutError(AdagentsValidationError):
+    """Request for adagents.json timed out."""
+
+    def __init__(self, publisher_domain: str, timeout: float):
+        """Initialize timeout error."""
+        message = f"Request to fetch adagents.json timed out after {timeout}s"
+        suggestion = (
+            "The publisher's server may be slow or unresponsive.\n"
+            "     Try increasing the timeout value or check the domain is correct."
+        )
+        super().__init__(message, None, None, suggestion)

adcp/types/__init__.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 """Type definitions for AdCP client."""
 
+from adcp.types.base import AdCPBaseModel
 from adcp.types.core import (
     Activity,
     ActivityType,
@@ -14,6 +15,7 @@ from adcp.types.core import (
 )
 
 __all__ = [
+    "AdCPBaseModel",
     "AgentConfig",
     "Protocol",
     "TaskResult",

adcp/types/base.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+"""Base model for AdCP types with spec-compliant serialization."""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class AdCPBaseModel(BaseModel):
+    """Base model for AdCP types with spec-compliant serialization.
+
+    AdCP JSON schemas use additionalProperties: false and do not allow null
+    for optional fields. Therefore, optional fields must be omitted entirely
+    when not present (not sent as null).
+    """
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        if "exclude_none" not in kwargs:
+            kwargs["exclude_none"] = True
+        return super().model_dump(**kwargs)
+
+    def model_dump_json(self, **kwargs: Any) -> str:
+        if "exclude_none" not in kwargs:
+            kwargs["exclude_none"] = True
+        return super().model_dump_json(**kwargs)

adcp/types/generated.py

@@ -14,7 +14,9 @@ from __future__ import annotations
 import re
 from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import ConfigDict, Field, field_validator
+
+from adcp.types.base import AdCPBaseModel as BaseModel
 
 
 
@@ -158,6 +160,8 @@ class Targeting(BaseModel):
     geo_region_any_of: list[str] | None = Field(None, description="Restrict delivery to specific regions/states. Use for regulatory compliance or RCT testing.")
     geo_metro_any_of: list[str] | None = Field(None, description="Restrict delivery to specific metro areas (DMA codes). Use for regulatory compliance or RCT testing.")
     geo_postal_code_any_of: list[str] | None = Field(None, description="Restrict delivery to specific postal/ZIP codes. Use for regulatory compliance or RCT testing.")
+    axe_include_segment: str | None = Field(None, description="AXE segment ID to include for targeting")
+    axe_exclude_segment: str | None = Field(None, description="AXE segment ID to exclude from targeting")
     frequency_cap: FrequencyCap | None = None
 
 
@@ -635,6 +639,7 @@ class ActivateSignalRequest(BaseModel):
 
     signal_agent_segment_id: str = Field(description="The universal identifier for the signal to activate")
     destinations: list[Destination] = Field(description="Target destination(s) for activation. If the authenticated caller matches one of these destinations, activation keys will be included in the response.")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agents must echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class BuildCreativeRequest(BaseModel):
@@ -643,6 +648,7 @@ class BuildCreativeRequest(BaseModel):
     message: str | None = Field(None, description="Natural language instructions for the transformation or generation. For pure generation, this is the creative brief. For transformation, this provides guidance on how to adapt the creative.")
     creative_manifest: CreativeManifest | None = Field(None, description="Creative manifest to transform or generate from. For pure generation, this should include the target format_id and any required input assets (e.g., promoted_offerings for generative formats). For transformation (e.g., resizing, reformatting), this is the complete creative to adapt.")
     target_format_id: FormatId = Field(description="Format ID to generate. The format definition specifies required input assets and output structure.")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class CreateMediaBuyRequest(BaseModel):
@@ -655,6 +661,7 @@ class CreateMediaBuyRequest(BaseModel):
     start_time: StartTiming
     end_time: str = Field(description="Campaign end date/time in ISO 8601 format")
     reporting_webhook: Any | None = None
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class GetMediaBuyDeliveryRequest(BaseModel):
@@ -665,6 +672,7 @@ class GetMediaBuyDeliveryRequest(BaseModel):
     status_filter: Any | None = Field(None, description="Filter by status. Can be a single status or array of statuses")
     start_date: str | None = Field(None, description="Start date for reporting period (YYYY-MM-DD)")
     end_date: str | None = Field(None, description="End date for reporting period (YYYY-MM-DD)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class GetProductsRequest(BaseModel):
@@ -673,6 +681,7 @@ class GetProductsRequest(BaseModel):
     brief: str | None = Field(None, description="Natural language description of campaign requirements")
     brand_manifest: BrandManifestRef | None = Field(None, description="Brand information manifest providing brand context, assets, and product catalog. Can be provided inline or as a URL reference to a hosted manifest.")
     filters: dict[str, Any] | None = Field(None, description="Structured filters for product discovery")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class GetSignalsRequest(BaseModel):
@@ -682,12 +691,14 @@ class GetSignalsRequest(BaseModel):
     deliver_to: dict[str, Any] = Field(description="Destination platforms where signals need to be activated")
     filters: dict[str, Any] | None = Field(None, description="Filters to refine results")
     max_results: int | None = Field(None, description="Maximum number of results to return")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agents must echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class ListAuthorizedPropertiesRequest(BaseModel):
     """Request parameters for discovering which publishers this agent is authorized to represent"""
 
     publisher_domains: list[str] | None = Field(None, description="Filter to specific publisher domains (optional). If omitted, returns all publishers this agent represents.")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class ListCreativeFormatsRequest(BaseModel):
@@ -702,6 +713,7 @@ class ListCreativeFormatsRequest(BaseModel):
     min_height: int | None = Field(None, description="Minimum height in pixels (inclusive). Returns formats with height >= this value.")
     is_responsive: bool | None = Field(None, description="Filter for responsive formats that adapt to container size. When true, returns formats without fixed dimensions.")
     name_search: str | None = Field(None, description="Search for formats by name (case-insensitive partial match)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class ListCreativesRequest(BaseModel):
@@ -714,6 +726,7 @@ class ListCreativesRequest(BaseModel):
     include_performance: bool | None = Field(None, description="Include aggregated performance metrics in response")
     include_sub_assets: bool | None = Field(None, description="Include sub-assets (for carousel/native formats) in response")
     fields: list[Literal["creative_id", "name", "format", "status", "created_date", "updated_date", "tags", "assignments", "performance", "sub_assets"]] | None = Field(None, description="Specific fields to include in response (omit for all fields)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class PackageRequest(BaseModel):
@@ -741,6 +754,7 @@ class ProvidePerformanceFeedbackRequest(BaseModel):
     creative_id: str | None = Field(None, description="Specific creative asset (if feedback is creative-specific)")
     metric_type: Literal["overall_performance", "conversion_rate", "brand_lift", "click_through_rate", "completion_rate", "viewability", "brand_safety", "cost_efficiency"] | None = Field(None, description="The business metric being measured")
     feedback_source: Literal["buyer_attribution", "third_party_measurement", "platform_analytics", "verification_partner"] | None = Field(None, description="Source of the performance data")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agentsmust echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class SyncCreativesRequest(BaseModel):
@@ -753,6 +767,7 @@ class SyncCreativesRequest(BaseModel):
     dry_run: bool | None = Field(None, description="When true, preview changes without applying them. Returns what would be created/updated/deleted.")
     validation_mode: Literal["strict", "lenient"] | None = Field(None, description="Validation strictness. 'strict' fails entire sync on any validation error. 'lenient' processes valid creatives and reports errors.")
     push_notification_config: PushNotificationConfig | None = Field(None, description="Optional webhook configuration for async sync notifications. Publisher will send webhook when sync completes if operation takes longer than immediate response time (typically for large bulk operations or manual approval/HITL).")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agents must echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class TasksGetRequest(BaseModel):
@@ -760,6 +775,7 @@ class TasksGetRequest(BaseModel):
 
     task_id: str = Field(description="Unique identifier of the task to retrieve")
     include_history: bool | None = Field(None, description="Include full conversation history for this task (may increase response size)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agents must echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class TasksListRequest(BaseModel):
@@ -769,6 +785,7 @@ class TasksListRequest(BaseModel):
     sort: dict[str, Any] | None = Field(None, description="Sorting parameters")
     pagination: dict[str, Any] | None = Field(None, description="Pagination parameters")
     include_history: bool | None = Field(None, description="Include full conversation history for each task (may significantly increase response size)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agents must echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 class UpdateMediaBuyRequest(BaseModel):
@@ -781,6 +798,7 @@ class UpdateMediaBuyRequest(BaseModel):
     end_time: str | None = Field(None, description="New end date/time in ISO 8601 format")
     packages: list[dict[str, Any]] | None = Field(None, description="Package-specific updates")
     push_notification_config: PushNotificationConfig | None = Field(None, description="Optional webhook configuration for async update notifications. Publisher will send webhook when update completes if operation takes longer than immediate response time.")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context included in the request payload. Agents must echo this value back unchanged in responses and webhooks. Use for UI/session hints, correlation tokens, or tracking metadata.")
 
 
 # Response containing the transformed or generated creative manifest, ready for use with preview_creative or sync_creatives. Returns either the complete creative manifest OR error information, never both.
@@ -791,6 +809,7 @@ class BuildCreativeResponseVariant1(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     creative_manifest: CreativeManifest = Field(description="The generated or transformed creative manifest")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class BuildCreativeResponseVariant2(BaseModel):
@@ -799,6 +818,7 @@ class BuildCreativeResponseVariant2(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     errors: list[Error] = Field(description="Array of errors explaining why creative generation failed")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 # Union type for Build Creative Response
@@ -818,6 +838,7 @@ class GetMediaBuyDeliveryResponse(BaseModel):
     aggregated_totals: dict[str, Any] | None = Field(None, description="Combined metrics across all returned media buys. Only included in API responses (get_media_buy_delivery), not in webhook notifications.")
     media_buy_deliveries: list[dict[str, Any]] = Field(description="Array of delivery data for media buys. When used in webhook notifications, may contain multiple media buys aggregated by publisher. When used in get_media_buy_delivery API responses, typically contains requested media buys.")
     errors: list[Error] | None = Field(None, description="Task-specific errors and warnings (e.g., missing delivery data, reporting platform issues)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class GetProductsResponse(BaseModel):
@@ -825,6 +846,7 @@ class GetProductsResponse(BaseModel):
 
     products: list[Product] = Field(description="Array of matching products")
     errors: list[Error] | None = Field(None, description="Task-specific errors and warnings (e.g., product filtering issues)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class GetSignalsResponse(BaseModel):
@@ -832,6 +854,7 @@ class GetSignalsResponse(BaseModel):
 
     signals: list[dict[str, Any]] = Field(description="Array of matching signals")
     errors: list[Error] | None = Field(None, description="Task-specific errors and warnings (e.g., signal discovery or pricing issues)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class ListAuthorizedPropertiesResponse(BaseModel):
@@ -844,6 +867,7 @@ class ListAuthorizedPropertiesResponse(BaseModel):
     advertising_policies: str | None = Field(None, description="Publisher's advertising content policies, restrictions, and guidelines in natural language. May include prohibited categories, blocked advertisers, restricted tactics, brand safety requirements, or links to full policy documentation.")
     last_updated: str | None = Field(None, description="ISO 8601 timestamp of when the agent's publisher authorization list was last updated. Buyers can use this to determine if their cached publisher adagents.json files might be stale.")
     errors: list[Error] | None = Field(None, description="Task-specific errors and warnings (e.g., property availability issues)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class ListCreativeFormatsResponse(BaseModel):
@@ -852,6 +876,7 @@ class ListCreativeFormatsResponse(BaseModel):
     formats: list[Format] = Field(description="Full format definitions for all formats this agent supports. Each format's authoritative source is indicated by its agent_url field.")
     creative_agents: list[dict[str, Any]] | None = Field(None, description="Optional: Creative agents that provide additional formats. Buyers can recursively query these agents to discover more formats. No authentication required for list_creative_formats.")
     errors: list[Error] | None = Field(None, description="Task-specific errors and warnings")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class ListCreativesResponse(BaseModel):
@@ -862,6 +887,7 @@ class ListCreativesResponse(BaseModel):
     creatives: list[dict[str, Any]] = Field(description="Array of creative assets matching the query")
     format_summary: dict[str, Any] | None = Field(None, description="Breakdown of creatives by format type")
     status_summary: dict[str, Any] | None = Field(None, description="Breakdown of creatives by status")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 # Response payload for provide_performance_feedback task. Returns either success confirmation OR error information, never both.
@@ -872,6 +898,7 @@ class ProvidePerformanceFeedbackResponseVariant1(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     success: Literal[True] = Field(description="Whether the performance feedback was successfully received")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class ProvidePerformanceFeedbackResponseVariant2(BaseModel):
@@ -880,6 +907,7 @@ class ProvidePerformanceFeedbackResponseVariant2(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     errors: list[Error] = Field(description="Array of errors explaining why feedback was rejected (e.g., invalid measurement period, missing campaign data)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 # Union type for Provide Performance Feedback Response
@@ -900,6 +928,7 @@ class TasksGetResponse(BaseModel):
     progress: dict[str, Any] | None = Field(None, description="Progress information for long-running tasks")
     error: dict[str, Any] | None = Field(None, description="Error details for failed tasks")
     history: list[dict[str, Any]] | None = Field(None, description="Complete conversation history for this task (only included if include_history was true in request)")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 class TasksListResponse(BaseModel):
@@ -908,6 +937,7 @@ class TasksListResponse(BaseModel):
     query_summary: dict[str, Any] = Field(description="Summary of the query that was executed")
     tasks: list[dict[str, Any]] = Field(description="Array of tasks matching the query criteria")
     pagination: dict[str, Any] = Field(description="Pagination information")
+    context: dict[str, Any] | None = Field(None, description="Initiator-provided context echoed inside the task payload. Opaque metadata such as UI/session hints, correlation tokens, or tracking identifiers.")
 
 
 
@@ -917,6 +947,7 @@ class TasksListResponse(BaseModel):
 # The simple code generator produces type aliases (e.g., PreviewCreativeRequest = Any)
 # for complex schemas that use oneOf. We override them here with proper Pydantic classes
 # to maintain type safety and enable batch API support.
+# Note: All classes inherit from BaseModel (which is aliased to AdCPBaseModel for exclude_none).
 
 
 class FormatId(BaseModel):

{adcp-1.4.1.dist-info → adcp-1.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: adcp
-Version: 1.4.1
+Version: 1.6.0
 Summary: Official Python client for the Ad Context Protocol (AdCP)
 Author-email: AdCP Community <maintainers@adcontextprotocol.org>
 License: Apache-2.0
@@ -461,6 +461,50 @@ auth = index.get_agent_authorizations("https://agent-x.com")
 premium = index.find_agents_by_property_tags(["premium", "ctv"])
 ```
 
+## Publisher Authorization Validation
+
+Verify sales agents are authorized to sell publisher properties via adagents.json:
+
+```python
+from adcp import (
+    fetch_adagents,
+    verify_agent_authorization,
+    verify_agent_for_property,
+)
+
+# Fetch and parse adagents.json from publisher
+adagents_data = await fetch_adagents("publisher.com")
+
+# Verify agent authorization for a property
+is_authorized = verify_agent_authorization(
+    adagents_data=adagents_data,
+    agent_url="https://sales-agent.example.com",
+    property_type="website",
+    property_identifiers=[{"type": "domain", "value": "publisher.com"}]
+)
+
+# Or use convenience wrapper (fetch + verify in one call)
+is_authorized = await verify_agent_for_property(
+    publisher_domain="publisher.com",
+    agent_url="https://sales-agent.example.com",
+    property_identifiers=[{"type": "domain", "value": "publisher.com"}],
+    property_type="website"
+)
+```
+
+**Domain Matching Rules:**
+- Exact match: `example.com` matches `example.com`
+- Common subdomains: `www.example.com` matches `example.com`
+- Wildcards: `api.example.com` matches `*.example.com`
+- Protocol-agnostic: `http://agent.com` matches `https://agent.com`
+
+**Use Cases:**
+- Sales agents verify authorization before accepting media buys
+- Publishers test their adagents.json files
+- Developer tools build authorization validators
+
+See `examples/adagents_validation.py` for complete examples.
+
 ## CLI Tool
 
 The `adcp` command-line tool provides easy interaction with AdCP agents without writing code.

{adcp-1.4.1.dist-info → adcp-1.6.0.dist-info}/RECORD

@@ -1,8 +1,9 @@
-adcp/__init__.py,sha256=zV1J1z4uR1C7rGIccifeDGjN8pnZI1o280FioRvwRLM,6976
+adcp/__init__.py,sha256=AssQu9RgVTit-LqDxtQ-pgKuxjoDQr67HhiIxKMmSFA,7612
 adcp/__main__.py,sha256=Avy_C71rruh2lOuojvuXDj09tkFOaek74nJ-dbx25Sw,12838
+adcp/adagents.py,sha256=thq6qZScRHLWrRR4DjGlZzHpC1ZssQqhc5l0pbKSa-Q,17483
 adcp/client.py,sha256=4qoFNDT5swzi4w5bnWJ5nVTG5JIL0xnLJOJMGeMyci4,28412
 adcp/config.py,sha256=Vsy7ZPOI8G3fB_i5Nk-CHbC7wdasCUWuKlos0fwA0kY,2017
-adcp/exceptions.py,sha256=9L7a3TKrMhmbEqDM0Qjdu3dQAFeKCSW4nc1IcLGSj4Y,5597
+adcp/exceptions.py,sha256=1aZEWpaM92OxD2jl9yKsqJp5ReSWaj0S0DFhxChhLlA,6732
 adcp/simple.py,sha256=FgPYWT32BNXkQz07r2x2gXgOmOikWLi88SzN5UIVSiU,10440
 adcp/protocols/__init__.py,sha256=6UFwACQ0QadBUzy17wUROHqsJDp8ztPW2jzyl53Zh_g,262
 adcp/protocols/a2a.py,sha256=FHgc6G_eU2qD0vH7_RyS1eZvUFSb2j3-EsceoHPi384,12467
@@ -10,17 +11,18 @@ adcp/protocols/base.py,sha256=vBHD23Fzl_CCk_Gy9nvSbBYopcJlYkYyzoz-rhI8wHg,5214
 adcp/protocols/mcp.py,sha256=d9uSpGd0BKvQ0JxztkfDvHwoDrDYhuiw5oivpYOAbmM,16647
 adcp/testing/__init__.py,sha256=ZWp_floWjVZfy8RBG5v_FUXQ8YbN7xjXvVcX-_zl_HU,1416
 adcp/testing/test_helpers.py,sha256=4n8fZYy1cVpjZpFW2SxBzpC8fmY-MBFrzY4tIPqe4rQ,10028
-adcp/types/__init__.py,sha256=3E_TJUXqQQFcjmSZZSPLwqBP3s_ijsH2LDeuOU-MP30,402
+adcp/types/__init__.py,sha256=FXm4210pkzOIQQEgpe-EeLLd7mxofzEgKLGl1r8fj4o,465
+adcp/types/base.py,sha256=QoEuVfI4yzefup0dc2KN11AcJTbcGxRep7xOw5hXfs8,837
 adcp/types/core.py,sha256=RXkKCWCXS9BVJTNpe3Opm5O1I_LaQPMUuVwa-ipvS1Q,4839
-adcp/types/generated.py,sha256=Ig4ucbJzKRuHlwYzsqvMF9M3w2KghhQQqsXuOnBqVMM,74993
+adcp/types/generated.py,sha256=NY6A6eBw8wscSqJlLhW4OFvhTaZegcNR1hQ5VU51IFM,81526
 adcp/types/tasks.py,sha256=Ae9TSwG2F7oWXTcl4TvLhAzinbQkHNGF1Pc0q8RMNNM,23424
 adcp/utils/__init__.py,sha256=uetvSJB19CjQbtwEYZiTnumJG11GsafQmXm5eR3hL7E,153
 adcp/utils/operation_id.py,sha256=wQX9Bb5epXzRq23xoeYPTqzu5yLuhshg7lKJZihcM2k,294
 adcp/utils/preview_cache.py,sha256=8_2qs5CgrHv1_WOnD4bs43VWueu-rcZRu5PZMQ_lyuE,17573
 adcp/utils/response_parser.py,sha256=uPk2vIH-RYZmq7y3i8lC4HTMQ3FfKdlgXKTjgJ1955M,6253
-adcp-1.4.1.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
-adcp-1.4.1.dist-info/METADATA,sha256=Y2iI6jHEWqkxqXSHHv5m2NX2OHet5KyEIPktdlNfOJo,19931
-adcp-1.4.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-adcp-1.4.1.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
-adcp-1.4.1.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
-adcp-1.4.1.dist-info/RECORD,,
+adcp-1.6.0.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
+adcp-1.6.0.dist-info/METADATA,sha256=9p6HjEycLX_f45n5H1l_gsDlLU67EpDJM3jBWZhLcqk,21345
+adcp-1.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+adcp-1.6.0.dist-info/entry_points.txt,sha256=DQKpcGsJX8DtVI_SGApQ7tNvqUB4zkTLaTAEpFgmi3U,44
+adcp-1.6.0.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
+adcp-1.6.0.dist-info/RECORD,,