adcp 0.1.2__py3-none-any.whl

adcp/__init__.py

@@ -0,0 +1,18 @@
+"""
+AdCP Python Client Library
+
+Official Python client for the Ad Context Protocol (AdCP).
+Supports both A2A and MCP protocols with full type safety.
+"""
+
+from adcp.client import ADCPClient, ADCPMultiAgentClient
+from adcp.types.core import AgentConfig, TaskResult, WebhookMetadata
+
+__version__ = "0.1.2"
+__all__ = [
+    "ADCPClient",
+    "ADCPMultiAgentClient",
+    "AgentConfig",
+    "TaskResult",
+    "WebhookMetadata",
+]

adcp/client.py

@@ -0,0 +1,493 @@
+"""Main client classes for AdCP."""
+
+import json
+import os
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any
+from uuid import uuid4
+
+from adcp.protocols.a2a import A2AAdapter
+from adcp.protocols.base import ProtocolAdapter
+from adcp.protocols.mcp import MCPAdapter
+from adcp.types.core import (
+    Activity,
+    ActivityType,
+    AgentConfig,
+    Protocol,
+    TaskResult,
+)
+
+
+def create_operation_id() -> str:
+    """Generate a unique operation ID."""
+    return f"op_{uuid4().hex[:12]}"
+
+
+class ADCPClient:
+    """Client for interacting with a single AdCP agent."""
+
+    def __init__(
+        self,
+        agent_config: AgentConfig,
+        webhook_url_template: str | None = None,
+        webhook_secret: str | None = None,
+        on_activity: Callable[[Activity], None] | None = None,
+    ):
+        """
+        Initialize ADCP client for a single agent.
+
+        Args:
+            agent_config: Agent configuration
+            webhook_url_template: Template for webhook URLs with {agent_id},
+                {task_type}, {operation_id}
+            webhook_secret: Secret for webhook signature verification
+            on_activity: Callback for activity events
+        """
+        self.agent_config = agent_config
+        self.webhook_url_template = webhook_url_template
+        self.webhook_secret = webhook_secret
+        self.on_activity = on_activity
+
+        # Initialize protocol adapter
+        self.adapter: ProtocolAdapter
+        if agent_config.protocol == Protocol.A2A:
+            self.adapter = A2AAdapter(agent_config)
+        elif agent_config.protocol == Protocol.MCP:
+            self.adapter = MCPAdapter(agent_config)
+        else:
+            raise ValueError(f"Unsupported protocol: {agent_config.protocol}")
+
+    def get_webhook_url(self, task_type: str, operation_id: str) -> str:
+        """Generate webhook URL for a task."""
+        if not self.webhook_url_template:
+            raise ValueError("webhook_url_template not configured")
+
+        return self.webhook_url_template.format(
+            agent_id=self.agent_config.id,
+            task_type=task_type,
+            operation_id=operation_id,
+        )
+
+    def _emit_activity(self, activity: Activity) -> None:
+        """Emit activity event."""
+        if self.on_activity:
+            self.on_activity(activity)
+
+    async def get_products(self, brief: str, **kwargs: Any) -> TaskResult[Any]:
+        """Get advertising products."""
+        operation_id = create_operation_id()
+        params = {"brief": brief, **kwargs}
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="get_products",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("get_products", params)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="get_products",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def list_creative_formats(self, **kwargs: Any) -> TaskResult[Any]:
+        """List supported creative formats."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="list_creative_formats",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("list_creative_formats", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="list_creative_formats",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def create_media_buy(self, **kwargs: Any) -> TaskResult[Any]:
+        """Create a new media buy."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="create_media_buy",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("create_media_buy", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="create_media_buy",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def update_media_buy(self, **kwargs: Any) -> TaskResult[Any]:
+        """Update an existing media buy."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="update_media_buy",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("update_media_buy", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="update_media_buy",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def sync_creatives(self, **kwargs: Any) -> TaskResult[Any]:
+        """Synchronize creatives with the agent."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="sync_creatives",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("sync_creatives", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="sync_creatives",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def list_creatives(self, **kwargs: Any) -> TaskResult[Any]:
+        """List creatives for a media buy."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="list_creatives",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("list_creatives", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="list_creatives",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def get_media_buy_delivery(self, **kwargs: Any) -> TaskResult[Any]:
+        """Get delivery metrics for a media buy."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="get_media_buy_delivery",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("get_media_buy_delivery", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="get_media_buy_delivery",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def list_authorized_properties(self, **kwargs: Any) -> TaskResult[Any]:
+        """List properties this agent is authorized to sell."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="list_authorized_properties",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("list_authorized_properties", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="list_authorized_properties",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def get_signals(self, **kwargs: Any) -> TaskResult[Any]:
+        """Get available signals for targeting."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="get_signals",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("get_signals", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="get_signals",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def activate_signal(self, **kwargs: Any) -> TaskResult[Any]:
+        """Activate a signal for use in campaigns."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="activate_signal",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("activate_signal", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="activate_signal",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def provide_performance_feedback(self, **kwargs: Any) -> TaskResult[Any]:
+        """Provide performance feedback for a campaign."""
+        operation_id = create_operation_id()
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_REQUEST,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="provide_performance_feedback",
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        result = await self.adapter.call_tool("provide_performance_feedback", kwargs)
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.PROTOCOL_RESPONSE,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type="provide_performance_feedback",
+                status=result.status,
+                timestamp=datetime.utcnow().isoformat(),
+            )
+        )
+
+        return result
+
+    async def handle_webhook(
+        self,
+        payload: dict[str, Any],
+        signature: str | None = None,
+    ) -> None:
+        """
+        Handle incoming webhook.
+
+        Args:
+            payload: Webhook payload
+            signature: Webhook signature for verification
+        """
+        # TODO: Implement signature verification
+        if self.webhook_secret and signature:
+            # Verify signature
+            pass
+
+        operation_id = payload.get("operation_id", "unknown")
+        task_type = payload.get("task_type", "unknown")
+
+        self._emit_activity(
+            Activity(
+                type=ActivityType.WEBHOOK_RECEIVED,
+                operation_id=operation_id,
+                agent_id=self.agent_config.id,
+                task_type=task_type,
+                timestamp=datetime.utcnow().isoformat(),
+                metadata={"payload": payload},
+            )
+        )
+
+
+class ADCPMultiAgentClient:
+    """Client for managing multiple AdCP agents."""
+
+    def __init__(
+        self,
+        agents: list[AgentConfig],
+        webhook_url_template: str | None = None,
+        webhook_secret: str | None = None,
+        on_activity: Callable[[Activity], None] | None = None,
+        handlers: dict[str, Callable[..., Any]] | None = None,
+    ):
+        """
+        Initialize multi-agent client.
+
+        Args:
+            agents: List of agent configurations
+            webhook_url_template: Template for webhook URLs
+            webhook_secret: Secret for webhook verification
+            on_activity: Callback for activity events
+            handlers: Task completion handlers
+        """
+        self.agents = {
+            agent.id: ADCPClient(
+                agent,
+                webhook_url_template=webhook_url_template,
+                webhook_secret=webhook_secret,
+                on_activity=on_activity,
+            )
+            for agent in agents
+        }
+        self.handlers = handlers or {}
+
+    def agent(self, agent_id: str) -> ADCPClient:
+        """Get client for specific agent."""
+        if agent_id not in self.agents:
+            raise ValueError(f"Agent not found: {agent_id}")
+        return self.agents[agent_id]
+
+    @property
+    def agent_ids(self) -> list[str]:
+        """Get list of agent IDs."""
+        return list(self.agents.keys())
+
+    async def get_products(self, brief: str, **kwargs: Any) -> list[TaskResult[Any]]:
+        """Execute get_products across all agents in parallel."""
+        import asyncio
+
+        tasks = [agent.get_products(brief, **kwargs) for agent in self.agents.values()]
+        return await asyncio.gather(*tasks)
+
+    @classmethod
+    def from_env(cls) -> "ADCPMultiAgentClient":
+        """Create client from environment variables."""
+        agents_json = os.getenv("ADCP_AGENTS")
+        if not agents_json:
+            raise ValueError("ADCP_AGENTS environment variable not set")
+
+        agents_data = json.loads(agents_json)
+        agents = [AgentConfig(**agent) for agent in agents_data]
+
+        return cls(
+            agents=agents,
+            webhook_url_template=os.getenv("WEBHOOK_URL_TEMPLATE"),
+            webhook_secret=os.getenv("WEBHOOK_SECRET"),
+        )

adcp/protocols/__init__.py

@@ -0,0 +1,7 @@
+"""Protocol adapters for AdCP."""
+
+from adcp.protocols.a2a import A2AAdapter
+from adcp.protocols.base import ProtocolAdapter
+from adcp.protocols.mcp import MCPAdapter
+
+__all__ = ["ProtocolAdapter", "A2AAdapter", "MCPAdapter"]

adcp/protocols/a2a.py

@@ -0,0 +1,159 @@
+"""A2A protocol adapter using HTTP client.
+
+The official a2a-sdk is primarily for building A2A servers. For client functionality,
+we implement the A2A protocol using HTTP requests as per the A2A specification.
+"""
+
+from typing import Any
+from uuid import uuid4
+
+import httpx
+
+from adcp.protocols.base import ProtocolAdapter
+from adcp.types.core import TaskResult, TaskStatus
+
+
+class A2AAdapter(ProtocolAdapter):
+    """Adapter for A2A protocol following the Agent2Agent specification."""
+
+    async def call_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
+        """
+        Call a tool using A2A protocol.
+
+        A2A uses a tasks/send endpoint to initiate tasks. The agent responds with
+        task status and may require multiple roundtrips for completion.
+        """
+        async with httpx.AsyncClient() as client:
+            headers = {"Content-Type": "application/json"}
+
+            if self.agent_config.auth_token:
+                headers["Authorization"] = f"Bearer {self.agent_config.auth_token}"
+
+            # Construct A2A message
+            message = {
+                "role": "user",
+                "parts": [
+                    {
+                        "type": "text",
+                        "text": self._format_tool_request(tool_name, params),
+                    }
+                ],
+            }
+
+            # A2A uses message/send endpoint
+            url = f"{self.agent_config.agent_uri}/message/send"
+
+            request_data = {
+                "message": message,
+                "context_id": str(uuid4()),
+            }
+
+            try:
+                response = await client.post(
+                    url,
+                    json=request_data,
+                    headers=headers,
+                    timeout=30.0,
+                )
+                response.raise_for_status()
+
+                data = response.json()
+
+                # Parse A2A response format
+                # A2A tasks have lifecycle: submitted, working, completed, failed, input-required
+                task_status = data.get("task", {}).get("status")
+
+                if task_status in ("completed", "working"):
+                    # Extract the result from the response message
+                    result_data = self._extract_result(data)
+
+                    return TaskResult[Any](
+                        status=TaskStatus.COMPLETED,
+                        data=result_data,
+                        success=True,
+                        metadata={"task_id": data.get("task", {}).get("id")},
+                    )
+                elif task_status == "failed":
+                    return TaskResult[Any](
+                        status=TaskStatus.FAILED,
+                        error=data.get("message", {})
+                        .get("parts", [{}])[0]
+                        .get("text", "Task failed"),
+                        success=False,
+                    )
+                else:
+                    # Handle other states (submitted, input-required)
+                    return TaskResult[Any](
+                        status=TaskStatus.SUBMITTED,
+                        data=data,
+                        success=True,
+                        metadata={"task_id": data.get("task", {}).get("id")},
+                    )
+
+            except httpx.HTTPError as e:
+                return TaskResult[Any](
+                    status=TaskStatus.FAILED,
+                    error=str(e),
+                    success=False,
+                )
+
+    def _format_tool_request(self, tool_name: str, params: dict[str, Any]) -> str:
+        """Format tool request as natural language for A2A."""
+        # For AdCP tools, we format as a structured request
+        import json
+
+        return f"Execute tool: {tool_name}\nParameters: {json.dumps(params, indent=2)}"
+
+    def _extract_result(self, response_data: dict[str, Any]) -> Any:
+        """Extract result data from A2A response."""
+        # Try to extract structured data from response
+        message = response_data.get("message", {})
+        parts = message.get("parts", [])
+
+        if not parts:
+            return response_data
+
+        # Return the first part's content
+        first_part = parts[0]
+        if first_part.get("type") == "text":
+            # Try to parse as JSON if it looks like structured data
+            text = first_part.get("text", "")
+            try:
+                import json
+
+                return json.loads(text)
+            except (json.JSONDecodeError, ValueError):
+                return text
+
+        return first_part
+
+    async def list_tools(self) -> list[str]:
+        """
+        List available tools from A2A agent.
+
+        Note: A2A doesn't have a standard tools/list endpoint. Agents expose
+        their capabilities through the agent card. For AdCP, we rely on the
+        standard AdCP tool set.
+        """
+        async with httpx.AsyncClient() as client:
+            headers = {"Content-Type": "application/json"}
+
+            if self.agent_config.auth_token:
+                headers["Authorization"] = f"Bearer {self.agent_config.auth_token}"
+
+            # Try to fetch agent card (OpenAPI spec)
+            url = f"{self.agent_config.agent_uri}/agent-card"
+
+            try:
+                response = await client.get(url, headers=headers, timeout=10.0)
+                response.raise_for_status()
+
+                data = response.json()
+
+                # Extract skills from agent card
+                skills = data.get("skills", [])
+                return [skill.get("name", "") for skill in skills if skill.get("name")]
+
+            except httpx.HTTPError:
+                # If agent card is not available, return empty list
+                return []

adcp/protocols/base.py

@@ -0,0 +1,38 @@
+"""Base protocol adapter interface."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from adcp.types.core import AgentConfig, TaskResult
+
+
+class ProtocolAdapter(ABC):
+    """Base class for protocol adapters."""
+
+    def __init__(self, agent_config: AgentConfig):
+        """Initialize adapter with agent configuration."""
+        self.agent_config = agent_config
+
+    @abstractmethod
+    async def call_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
+        """
+        Call a tool on the agent.
+
+        Args:
+            tool_name: Name of the tool to call
+            params: Tool parameters
+
+        Returns:
+            TaskResult with the response
+        """
+        pass
+
+    @abstractmethod
+    async def list_tools(self) -> list[str]:
+        """
+        List available tools from the agent.
+
+        Returns:
+            List of tool names
+        """
+        pass

adcp/protocols/mcp.py

@@ -0,0 +1,101 @@
+"""MCP protocol adapter using official Python MCP SDK."""
+
+from typing import Any
+from urllib.parse import urlparse
+
+try:
+    from mcp import ClientSession  # type: ignore[import-not-found]
+    from mcp.client.sse import sse_client  # type: ignore[import-not-found]
+
+    MCP_AVAILABLE = True
+except ImportError:
+    MCP_AVAILABLE = False
+    ClientSession = None
+
+from adcp.protocols.base import ProtocolAdapter
+from adcp.types.core import TaskResult, TaskStatus
+
+
+class MCPAdapter(ProtocolAdapter):
+    """Adapter for MCP protocol using official Python MCP SDK."""
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        if not MCP_AVAILABLE:
+            raise ImportError(
+                "MCP SDK not installed. Install with: pip install mcp (requires Python 3.10+)"
+            )
+        self._session: Any = None
+        self._exit_stack: Any = None
+
+    async def _get_session(self) -> ClientSession:
+        """Get or create MCP client session."""
+        if self._session is not None:
+            return self._session
+
+        # Parse the agent URI to determine transport type
+        parsed = urlparse(self.agent_config.agent_uri)
+
+        # Use SSE transport for HTTP/HTTPS endpoints
+        if parsed.scheme in ("http", "https"):
+            from contextlib import AsyncExitStack
+
+            self._exit_stack = AsyncExitStack()
+
+            # Create SSE client with authentication header
+            headers = {}
+            if self.agent_config.auth_token:
+                headers["x-adcp-auth"] = self.agent_config.auth_token
+
+            read, write = await self._exit_stack.enter_async_context(
+                sse_client(self.agent_config.agent_uri, headers=headers)
+            )
+
+            self._session = await self._exit_stack.enter_async_context(ClientSession(read, write))
+
+            # Initialize the session
+            await self._session.initialize()
+
+            return self._session
+        else:
+            raise ValueError(f"Unsupported transport scheme: {parsed.scheme}")
+
+    async def call_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
+        """Call a tool using MCP protocol."""
+        try:
+            session = await self._get_session()
+
+            # Call the tool using MCP client session
+            result = await session.call_tool(tool_name, params)
+
+            # MCP tool results contain a list of content items
+            # For AdCP, we expect the data in the content
+            return TaskResult[Any](
+                status=TaskStatus.COMPLETED,
+                data=result.content,
+                success=True,
+            )
+
+        except Exception as e:
+            return TaskResult[Any](
+                status=TaskStatus.FAILED,
+                error=str(e),
+                success=False,
+            )
+
+    async def list_tools(self) -> list[str]:
+        """List available tools from MCP agent."""
+        try:
+            session = await self._get_session()
+            result = await session.list_tools()
+            return [tool.name for tool in result.tools]
+        except Exception:
+            # Return empty list on error
+            return []
+
+    async def close(self) -> None:
+        """Close the MCP session."""
+        if self._exit_stack is not None:
+            await self._exit_stack.aclose()
+            self._exit_stack = None
+            self._session = None

adcp/types/__init__.py

@@ -0,0 +1,21 @@
+"""Type definitions for AdCP client."""
+
+from adcp.types.core import (
+    Activity,
+    ActivityType,
+    AgentConfig,
+    Protocol,
+    TaskResult,
+    TaskStatus,
+    WebhookMetadata,
+)
+
+__all__ = [
+    "AgentConfig",
+    "Protocol",
+    "TaskResult",
+    "TaskStatus",
+    "WebhookMetadata",
+    "Activity",
+    "ActivityType",
+]

adcp/types/core.py

@@ -0,0 +1,99 @@
+"""Core type definitions."""
+
+from enum import Enum
+from typing import Any, Generic, Literal, TypeVar
+
+from pydantic import BaseModel, Field
+
+
+class Protocol(str, Enum):
+    """Supported protocols."""
+
+    A2A = "a2a"
+    MCP = "mcp"
+
+
+class AgentConfig(BaseModel):
+    """Agent configuration."""
+
+    id: str
+    agent_uri: str
+    protocol: Protocol
+    auth_token: str | None = None
+    requires_auth: bool = False
+
+
+class TaskStatus(str, Enum):
+    """Task execution status."""
+
+    COMPLETED = "completed"
+    SUBMITTED = "submitted"
+    NEEDS_INPUT = "needs_input"
+    FAILED = "failed"
+    WORKING = "working"
+
+
+T = TypeVar("T")
+
+
+class SubmittedInfo(BaseModel):
+    """Information about submitted async task."""
+
+    webhook_url: str
+    operation_id: str
+
+
+class NeedsInputInfo(BaseModel):
+    """Information when agent needs clarification."""
+
+    message: str
+    field: str | None = None
+
+
+class TaskResult(BaseModel, Generic[T]):
+    """Result from task execution."""
+
+    status: TaskStatus
+    data: T | None = None
+    submitted: SubmittedInfo | None = None
+    needs_input: NeedsInputInfo | None = None
+    error: str | None = None
+    success: bool = Field(default=True)
+    metadata: dict[str, Any] | None = None
+
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class ActivityType(str, Enum):
+    """Types of activity events."""
+
+    PROTOCOL_REQUEST = "protocol_request"
+    PROTOCOL_RESPONSE = "protocol_response"
+    WEBHOOK_RECEIVED = "webhook_received"
+    HANDLER_CALLED = "handler_called"
+    STATUS_CHANGE = "status_change"
+
+
+class Activity(BaseModel):
+    """Activity event for observability."""
+
+    type: ActivityType
+    operation_id: str
+    agent_id: str
+    task_type: str
+    status: TaskStatus | None = None
+    timestamp: str
+    metadata: dict[str, Any] | None = None
+
+
+class WebhookMetadata(BaseModel):
+    """Metadata passed to webhook handlers."""
+
+    operation_id: str
+    agent_id: str
+    task_type: str
+    status: TaskStatus
+    sequence_number: int | None = None
+    notification_type: Literal["scheduled", "final", "delayed"] | None = None
+    timestamp: str

adcp/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utility functions."""
+
+from adcp.utils.operation_id import create_operation_id
+
+__all__ = ["create_operation_id"]

adcp/utils/operation_id.py

@@ -0,0 +1,13 @@
+"""Operation ID generation utilities."""
+
+from uuid import uuid4
+
+
+def create_operation_id() -> str:
+    """
+    Generate a unique operation ID.
+
+    Returns:
+        A unique operation ID in the format 'op_{hex}'
+    """
+    return f"op_{uuid4().hex[:12]}"

adcp-0.1.2.dist-info/METADATA

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: adcp
+Version: 0.1.2
+Summary: Official Python client for the Ad Context Protocol (AdCP)
+Author-email: AdCP Community <maintainers@adcontextprotocol.org>
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/adcontextprotocol/adcp-client-python
+Project-URL: Documentation, https://docs.adcontextprotocol.org
+Project-URL: Repository, https://github.com/adcontextprotocol/adcp-client-python
+Project-URL: Issues, https://github.com/adcontextprotocol/adcp-client-python/issues
+Keywords: adcp,mcp,a2a,protocol,advertising
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.5.0
+Requires-Dist: a2a-sdk>=0.3.0
+Requires-Dist: mcp>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# adcp - Python Client for Ad Context Protocol
+
+[![PyPI version](https://badge.fury.io/py/adcp.svg)](https://badge.fury.io/py/adcp)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+Official Python client for the **Ad Context Protocol (AdCP)**. Build distributed advertising operations that work synchronously OR asynchronously with the same code.
+
+## The Core Concept
+
+AdCP operations are **distributed and asynchronous by default**. An agent might:
+- Complete your request **immediately** (synchronous)
+- Need time to process and **send results via webhook** (asynchronous)
+- Ask for **clarifications** before proceeding
+- Send periodic **status updates** as work progresses
+
+**Your code stays the same.** You write handlers once, and they work for both sync completions and webhook deliveries.
+
+## Installation
+
+```bash
+pip install adcp
+```
+
+## Quick Start: Distributed Operations
+
+```python
+from adcp import ADCPMultiAgentClient
+from adcp.types import AgentConfig
+
+# Configure agents and handlers
+client = ADCPMultiAgentClient(
+    agents=[
+        AgentConfig(
+            id="agent_x",
+            agent_uri="https://agent-x.com",
+            protocol="a2a"
+        ),
+        AgentConfig(
+            id="agent_y",
+            agent_uri="https://agent-y.com/mcp/",
+            protocol="mcp"
+        )
+    ],
+    # Webhook URL template (macros: {agent_id}, {task_type}, {operation_id})
+    webhook_url_template="https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}",
+
+    # Activity callback - fires for ALL events
+    on_activity=lambda activity: print(f"[{activity.type}] {activity.task_type}"),
+
+    # Status change handlers
+    handlers={
+        "on_get_products_status_change": lambda response, metadata: (
+            db.save_products(metadata.operation_id, response.products)
+            if metadata.status == "completed" else None
+        )
+    }
+)
+
+# Execute operation - library handles operation IDs, webhook URLs, context management
+agent = client.agent("agent_x")
+result = await agent.get_products(brief="Coffee brands")
+
+# Check result
+if result.status == "completed":
+    # Agent completed synchronously!
+    print(f"✅ Sync completion: {len(result.data.products)} products")
+
+if result.status == "submitted":
+    # Agent will send webhook when complete
+    print(f"⏳ Async - webhook registered at: {result.submitted.webhook_url}")
+```
+
+## Features
+
+### Full Protocol Support
+- **A2A Protocol**: Native support for Agent-to-Agent protocol
+- **MCP Protocol**: Native support for Model Context Protocol
+- **Auto-detection**: Automatically detect which protocol an agent uses
+
+### Type Safety
+Full type hints with Pydantic validation:
+
+```python
+result = await agent.get_products(brief="Coffee brands")
+# result: TaskResult[GetProductsResponse]
+
+if result.success:
+    for product in result.data.products:
+        print(product.name, product.price)  # Full IDE autocomplete!
+```
+
+### Multi-Agent Operations
+Execute across multiple agents simultaneously:
+
+```python
+# Parallel execution across all agents
+results = await client.get_products(brief="Coffee brands")
+
+for result in results:
+    if result.status == "completed":
+        print(f"Sync: {len(result.data.products)} products")
+    elif result.status == "submitted":
+        print(f"Async: webhook to {result.submitted.webhook_url}")
+```
+
+### Webhook Handling
+Single endpoint handles all webhooks:
+
+```python
+from fastapi import FastAPI, Request
+
+app = FastAPI()
+
+@app.post("/webhook/{task_type}/{agent_id}/{operation_id}")
+async def webhook(task_type: str, agent_id: str, operation_id: str, request: Request):
+    payload = await request.json()
+    payload["task_type"] = task_type
+    payload["operation_id"] = operation_id
+
+    # Route to agent client - handlers fire automatically
+    agent = client.agent(agent_id)
+    await agent.handle_webhook(
+        payload,
+        request.headers.get("x-adcp-signature")
+    )
+
+    return {"received": True}
+```
+
+### Security
+Webhook signature verification built-in:
+
+```python
+client = ADCPMultiAgentClient(
+    agents=agents,
+    webhook_secret=os.getenv("WEBHOOK_SECRET")
+)
+# Signatures verified automatically on handle_webhook()
+```
+
+## Available Tools
+
+All AdCP tools with full type safety:
+
+**Media Buy Lifecycle:**
+- `get_products()` - Discover advertising products
+- `list_creative_formats()` - Get supported creative formats
+- `create_media_buy()` - Create new media buy
+- `update_media_buy()` - Update existing media buy
+- `sync_creatives()` - Upload/sync creative assets
+- `list_creatives()` - List creative assets
+- `get_media_buy_delivery()` - Get delivery performance
+
+**Audience & Targeting:**
+- `list_authorized_properties()` - Get authorized properties
+- `get_signals()` - Get audience signals
+- `activate_signal()` - Activate audience signals
+- `provide_performance_feedback()` - Send performance feedback
+
+## Property Discovery (AdCP v2.2.0)
+
+Build agent registries by discovering properties agents can sell:
+
+```python
+from adcp.discovery import PropertyCrawler, get_property_index
+
+# Crawl agents to discover properties
+crawler = PropertyCrawler()
+await crawler.crawl_agents([
+    {"agent_url": "https://agent-x.com", "protocol": "a2a"},
+    {"agent_url": "https://agent-y.com/mcp/", "protocol": "mcp"}
+])
+
+index = get_property_index()
+
+# Query 1: Who can sell this property?
+matches = index.find_agents_for_property("domain", "cnn.com")
+
+# Query 2: What can this agent sell?
+auth = index.get_agent_authorizations("https://agent-x.com")
+
+# Query 3: Find by tags
+premium = index.find_agents_by_property_tags(["premium", "ctv"])
+```
+
+## Environment Configuration
+
+```bash
+# .env
+WEBHOOK_URL_TEMPLATE="https://myapp.com/webhook/{task_type}/{agent_id}/{operation_id}"
+WEBHOOK_SECRET="your-webhook-secret"
+
+ADCP_AGENTS='[
+  {
+    "id": "agent_x",
+    "agent_uri": "https://agent-x.com",
+    "protocol": "a2a",
+    "auth_token_env": "AGENT_X_TOKEN"
+  }
+]'
+AGENT_X_TOKEN="actual-token-here"
+```
+
+```python
+# Auto-discover from environment
+client = ADCPMultiAgentClient.from_env()
+```
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Type checking
+mypy src/
+
+# Format code
+black src/ tests/
+ruff check src/ tests/
+```
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+Apache 2.0 License - see [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Documentation**: [docs.adcontextprotocol.org](https://docs.adcontextprotocol.org)
+- **Issues**: [GitHub Issues](https://github.com/adcontextprotocol/adcp-client-python/issues)
+- **Protocol Spec**: [AdCP Specification](https://github.com/adcontextprotocol/adcp)

adcp-0.1.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+adcp/__init__.py,sha256=TpXs5-627LCcgm351m2Q1oD5WsFawGoLfe3Fj6Wi4-o,424
+adcp/client.py,sha256=DaAA_5Jxw2N0xjRSdvplJdUU_QHHMJqNzow9QzeagJw,16095
+adcp/protocols/__init__.py,sha256=hAGf5yAfgqpqa_-pMWXL35Bl-Aeca8Zdt_E1uEeI0_M,226
+adcp/protocols/a2a.py,sha256=P9tnUYiVSRa8_OJPsZmr2_r1IasRIGS7z6LR8uTj0lg,5719
+adcp/protocols/base.py,sha256=RhaeFyOj4lxCxGJajUo1ydpNDW2OZPnnMJ6QmodOESw,915
+adcp/protocols/mcp.py,sha256=dLSmDs-qJrn_dcXUthABRblb2ripjNVYWi0wZ0VOOe8,3417
+adcp/types/__init__.py,sha256=LuiNdxbVfS91LIt2DTW7xX0BR-chmqwXz4ScYS6Hd44,334
+adcp/types/core.py,sha256=xybdwh1bsI_q1QiS8DB_6DiFdUNzWsycfVbi7sO2nfo,2119
+adcp/utils/__init__.py,sha256=ME5OVQipWgFdECX0Lur8-ThcVrqHfQOtx27TwjDe9LE,117
+adcp/utils/operation_id.py,sha256=_TcXbaSuaFhnN5F1zECspSJ5n08x_-LIzIWbdlkwzEQ,258
+adcp-0.1.2.dist-info/licenses/LICENSE,sha256=PF39NR3Ae8PLgBhg3Uxw6ju7iGVIf8hfv9LRWQdii_U,629
+adcp-0.1.2.dist-info/METADATA,sha256=pA0Ur9lBAYwdy_u-KsWhwPSYhWNHY_jzoWrPFsl8pGc,8429
+adcp-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+adcp-0.1.2.dist-info/top_level.txt,sha256=T1_NF0GefncFU9v_k56oDwKSJREyCqIM8lAwNZf0EOs,5
+adcp-0.1.2.dist-info/RECORD,,

adcp-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

adcp-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2025 AdCP Community
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

adcp-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+adcp