adcp 0.1.2__py3-none-any.whl → 1.0.2__py3-none-any.whl

adcp/config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+"""Configuration management for AdCP CLI."""
+
+import json
+from pathlib import Path
+from typing import Any, cast
+
+CONFIG_DIR = Path.home() / ".adcp"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def ensure_config_dir() -> None:
+    """Ensure config directory exists."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def load_config() -> dict[str, Any]:
+    """Load configuration file."""
+    if not CONFIG_FILE.exists():
+        return {"agents": {}}
+
+    with open(CONFIG_FILE) as f:
+        return cast(dict[str, Any], json.load(f))
+
+
+def save_config(config: dict[str, Any]) -> None:
+    """Save configuration file with atomic write."""
+    ensure_config_dir()
+
+    # Write to temporary file first
+    temp_file = CONFIG_FILE.with_suffix(".tmp")
+    with open(temp_file, "w") as f:
+        json.dump(config, f, indent=2)
+
+    # Atomic rename
+    temp_file.replace(CONFIG_FILE)
+
+
+def save_agent(
+    alias: str, url: str, protocol: str | None = None, auth_token: str | None = None
+) -> None:
+    """Save agent configuration."""
+    config = load_config()
+
+    if "agents" not in config:
+        config["agents"] = {}
+
+    config["agents"][alias] = {
+        "agent_uri": url,
+        "protocol": protocol or "mcp",
+    }
+
+    if auth_token:
+        config["agents"][alias]["auth_token"] = auth_token
+
+    save_config(config)
+
+
+def get_agent(alias: str) -> dict[str, Any] | None:
+    """Get agent configuration by alias."""
+    config = load_config()
+    result = config.get("agents", {}).get(alias)
+    return cast(dict[str, Any], result) if result is not None else None
+
+
+def list_agents() -> dict[str, Any]:
+    """List all saved agents."""
+    config = load_config()
+    return cast(dict[str, Any], config.get("agents", {}))
+
+
+def remove_agent(alias: str) -> bool:
+    """Remove agent configuration."""
+    config = load_config()
+
+    if alias in config.get("agents", {}):
+        del config["agents"][alias]
+        save_config(config)
+        return True
+
+    return False

adcp/exceptions.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+"""Exception hierarchy for AdCP client."""
+
+
+class ADCPError(Exception):
+    """Base exception for all AdCP client errors."""
+
+    def __init__(
+        self,
+        message: str,
+        agent_id: str | None = None,
+        agent_uri: str | None = None,
+        suggestion: str | None = None,
+    ):
+        """Initialize exception with context."""
+        self.message = message
+        self.agent_id = agent_id
+        self.agent_uri = agent_uri
+        self.suggestion = suggestion
+
+        full_message = message
+        if agent_id:
+            full_message = f"[Agent: {agent_id}] {full_message}"
+        if agent_uri:
+            full_message = f"{full_message}\n  URI: {agent_uri}"
+        if suggestion:
+            full_message = f"{full_message}\n  💡 {suggestion}"
+
+        super().__init__(full_message)
+
+
+class ADCPConnectionError(ADCPError):
+    """Connection to agent failed."""
+
+    def __init__(self, message: str, agent_id: str | None = None, agent_uri: str | None = None):
+        """Initialize connection error."""
+        suggestion = (
+            "Check that the agent URI is correct and the agent is running.\n"
+            "     Try testing with: python -m adcp test --config <agent-id>"
+        )
+        super().__init__(message, agent_id, agent_uri, suggestion)
+
+
+class ADCPAuthenticationError(ADCPError):
+    """Authentication failed (401, 403)."""
+
+    def __init__(self, message: str, agent_id: str | None = None, agent_uri: str | None = None):
+        """Initialize authentication error."""
+        suggestion = (
+            "Check that your auth_token is valid and not expired.\n"
+            "     Verify auth_type ('bearer' vs 'token') and auth_header are correct.\n"
+            "     Some agents (like Optable) require auth_type='bearer' and "
+            "auth_header='Authorization'"
+        )
+        super().__init__(message, agent_id, agent_uri, suggestion)
+
+
+class ADCPTimeoutError(ADCPError):
+    """Request timed out."""
+
+    def __init__(
+        self,
+        message: str,
+        agent_id: str | None = None,
+        agent_uri: str | None = None,
+        timeout: float | None = None,
+    ):
+        """Initialize timeout error."""
+        suggestion = (
+            f"The request took longer than {timeout}s." if timeout else "The request timed out."
+        )
+        suggestion += "\n     Try increasing the timeout value or check if the agent is overloaded."
+        super().__init__(message, agent_id, agent_uri, suggestion)
+
+
+class ADCPProtocolError(ADCPError):
+    """Protocol-level error (malformed response, unexpected format)."""
+
+    def __init__(self, message: str, agent_id: str | None = None, protocol: str | None = None):
+        """Initialize protocol error."""
+        suggestion = (
+            f"The agent returned an unexpected {protocol} response format."
+            if protocol
+            else "Unexpected response format."
+        )
+        suggestion += "\n     Enable debug mode to see the full request/response."
+        super().__init__(message, agent_id, None, suggestion)
+
+
+class ADCPToolNotFoundError(ADCPError):
+    """Requested tool not found on agent."""
+
+    def __init__(
+        self, tool_name: str, agent_id: str | None = None, available_tools: list[str] | None = None
+    ):
+        """Initialize tool not found error."""
+        message = f"Tool '{tool_name}' not found on agent"
+        suggestion = "List available tools with: python -m adcp list-tools --config <agent-id>"
+        if available_tools:
+            tools_list = ", ".join(available_tools[:5])
+            if len(available_tools) > 5:
+                tools_list += f", ... ({len(available_tools)} total)"
+            suggestion = f"Available tools: {tools_list}"
+        super().__init__(message, agent_id, None, suggestion)
+
+
+class ADCPWebhookError(ADCPError):
+    """Webhook handling error."""
+
+
+class ADCPWebhookSignatureError(ADCPWebhookError):
+    """Webhook signature verification failed."""
+
+    def __init__(self, message: str = "Invalid webhook signature", agent_id: str | None = None):
+        """Initialize webhook signature error."""
+        suggestion = (
+            "Verify that the webhook_secret matches the secret configured on the agent.\n"
+            "     Webhook signatures use HMAC-SHA256 for security."
+        )
+        super().__init__(message, agent_id, None, suggestion)

adcp/protocols/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """Protocol adapters for AdCP."""
 
 from adcp.protocols.a2a import A2AAdapter

adcp/protocols/a2a.py

@@ -1,21 +1,59 @@
+from __future__ import annotations
+
 """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.
 """
 
+import logging
+import time
 from typing import Any
 from uuid import uuid4
 
 import httpx
 
+from adcp.exceptions import (
+    ADCPAuthenticationError,
+    ADCPConnectionError,
+    ADCPTimeoutError,
+)
 from adcp.protocols.base import ProtocolAdapter
-from adcp.types.core import TaskResult, TaskStatus
+from adcp.types.core import AgentConfig, DebugInfo, TaskResult, TaskStatus
+
+logger = logging.getLogger(__name__)
 
 
 class A2AAdapter(ProtocolAdapter):
     """Adapter for A2A protocol following the Agent2Agent specification."""
 
+    def __init__(self, agent_config: AgentConfig):
+        """Initialize A2A adapter with reusable HTTP client."""
+        super().__init__(agent_config)
+        self._client: httpx.AsyncClient | None = None
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Get or create the HTTP client with connection pooling."""
+        if self._client is None:
+            # Configure connection pooling for better performance
+            limits = httpx.Limits(
+                max_keepalive_connections=10,
+                max_connections=20,
+                keepalive_expiry=30.0,
+            )
+            self._client = httpx.AsyncClient(limits=limits)
+            logger.debug(
+                f"Created HTTP client with connection pooling for agent {self.agent_config.id}"
+            )
+        return self._client
+
+    async def close(self) -> None:
+        """Close the HTTP client and clean up resources."""
+        if self._client is not None:
+            logger.debug(f"Closing A2A adapter client for agent {self.agent_config.id}")
+            await self._client.aclose()
+            self._client = None
+
     async def call_tool(self, tool_name: str, params: dict[str, Any]) -> TaskResult[Any]:
         """
         Call a tool using A2A protocol.
@@ -23,80 +61,117 @@ class A2AAdapter(ProtocolAdapter):
         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),
-                    }
-                ],
+        start_time = time.time() if self.agent_config.debug else None
+        client = await self._get_client()
+
+        headers = {"Content-Type": "application/json"}
+
+        if self.agent_config.auth_token:
+            # Support custom auth headers and types
+            if self.agent_config.auth_type == "bearer":
+                headers[self.agent_config.auth_header] = f"Bearer {self.agent_config.auth_token}"
+            else:
+                headers[self.agent_config.auth_header] = 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()),
+        }
+
+        debug_info = None
+        if self.agent_config.debug:
+            debug_request = {
+                "url": url,
+                "method": "POST",
+                "headers": {
+                    k: v
+                    if k.lower() not in ("authorization", self.agent_config.auth_header.lower())
+                    else "***"
+                    for k, v in headers.items()
+                },
+                "body": request_data,
             }
 
-            # A2A uses message/send endpoint
-            url = f"{self.agent_config.agent_uri}/message/send"
+        try:
+            response = await client.post(
+                url,
+                json=request_data,
+                headers=headers,
+                timeout=self.agent_config.timeout,
+            )
+            response.raise_for_status()
+
+            data = response.json()
+
+            if self.agent_config.debug and start_time:
+                duration_ms = (time.time() - start_time) * 1000
+                debug_info = DebugInfo(
+                    request=debug_request,
+                    response={"status": response.status_code, "body": data},
+                    duration_ms=duration_ms,
+                )
 
-            request_data = {
-                "message": message,
-                "context_id": str(uuid4()),
-            }
+            # Parse A2A response format
+            # A2A tasks have lifecycle: submitted, working, completed, failed, input-required
+            task_status = data.get("task", {}).get("status")
 
-            try:
-                response = await client.post(
-                    url,
-                    json=request_data,
-                    headers=headers,
-                    timeout=30.0,
+            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")},
+                    debug_info=debug_info,
                 )
-                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:
+            elif task_status == "failed":
                 return TaskResult[Any](
                     status=TaskStatus.FAILED,
-                    error=str(e),
+                    error=data.get("message", {}).get("parts", [{}])[0].get("text", "Task failed"),
                     success=False,
+                    debug_info=debug_info,
+                )
+            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")},
+                    debug_info=debug_info,
                 )
 
+        except httpx.HTTPError as e:
+            if self.agent_config.debug and start_time:
+                duration_ms = (time.time() - start_time) * 1000
+                debug_info = DebugInfo(
+                    request=debug_request,
+                    response={"error": str(e)},
+                    duration_ms=duration_ms,
+                )
+            return TaskResult[Any](
+                status=TaskStatus.FAILED,
+                error=str(e),
+                success=False,
+                debug_info=debug_info,
+            )
+
     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
@@ -135,25 +210,64 @@ class A2AAdapter(ProtocolAdapter):
         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 []
+        client = await self._get_client()
+
+        headers = {"Content-Type": "application/json"}
+
+        if self.agent_config.auth_token:
+            # Support custom auth headers and types
+            if self.agent_config.auth_type == "bearer":
+                headers[self.agent_config.auth_header] = f"Bearer {self.agent_config.auth_token}"
+            else:
+                headers[self.agent_config.auth_header] = self.agent_config.auth_token
+
+        # Try to fetch agent card from standard A2A location
+        # A2A spec uses /.well-known/agent.json for agent card
+        url = f"{self.agent_config.agent_uri}/.well-known/agent.json"
+
+        logger.debug(f"Fetching A2A agent card for {self.agent_config.id} from {url}")
+
+        try:
+            response = await client.get(url, headers=headers, timeout=self.agent_config.timeout)
+            response.raise_for_status()
+
+            data = response.json()
+
+            # Extract skills from agent card
+            skills = data.get("skills", [])
+            tool_names = [skill.get("name", "") for skill in skills if skill.get("name")]
+
+            logger.info(f"Found {len(tool_names)} tools from A2A agent {self.agent_config.id}")
+            return tool_names
+
+        except httpx.HTTPStatusError as e:
+            status_code = e.response.status_code
+            if status_code in (401, 403):
+                logger.error(f"Authentication failed for A2A agent {self.agent_config.id}")
+                raise ADCPAuthenticationError(
+                    f"Authentication failed: HTTP {status_code}",
+                    agent_id=self.agent_config.id,
+                    agent_uri=self.agent_config.agent_uri,
+                ) from e
+            else:
+                logger.error(f"HTTP {status_code} error fetching agent card: {e}")
+                raise ADCPConnectionError(
+                    f"Failed to fetch agent card: HTTP {status_code}",
+                    agent_id=self.agent_config.id,
+                    agent_uri=self.agent_config.agent_uri,
+                ) from e
+        except httpx.TimeoutException as e:
+            logger.error(f"Timeout fetching agent card for {self.agent_config.id}")
+            raise ADCPTimeoutError(
+                f"Timeout fetching agent card: {e}",
+                agent_id=self.agent_config.id,
+                agent_uri=self.agent_config.agent_uri,
+                timeout=self.agent_config.timeout,
+            ) from e
+        except httpx.HTTPError as e:
+            logger.error(f"HTTP error fetching agent card: {e}")
+            raise ADCPConnectionError(
+                f"Failed to fetch agent card: {e}",
+                agent_id=self.agent_config.id,
+                agent_uri=self.agent_config.agent_uri,
+            ) from e

adcp/protocols/base.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """Base protocol adapter interface."""
 
 from abc import ABC, abstractmethod
@@ -36,3 +38,12 @@ class ProtocolAdapter(ABC):
             List of tool names
         """
         pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        """
+        Close the adapter and clean up resources.
+
+        Implementations should close any open connections, clients, or other resources.
+        """
+        pass