a2a-adapter 0.1.0__py3-none-any.whl

a2a_adapter/__init__.py

@@ -0,0 +1,42 @@
+"""
+A2A Adapters - Python SDK for A2A Protocol Integration.
+
+This package provides adapters to integrate various agent frameworks with the
+A2A (Agent-to-Agent) Protocol, enabling seamless inter-agent communication.
+
+Main exports:
+- load_a2a_agent: Factory function to create adapters from configuration
+- build_agent_app: Build an ASGI app for serving an A2A agent
+- serve_agent: Convenience function to start serving an A2A agent
+- BaseAgentAdapter: Abstract base class for creating custom adapters
+
+Example:
+    >>> import asyncio
+    >>> from a2a_adapter import load_a2a_agent, serve_agent
+    >>> from a2a.types import AgentCard
+    >>> 
+    >>> async def main():
+    ...     adapter = await load_a2a_agent({
+    ...         "adapter": "n8n",
+    ...         "webhook_url": "https://n8n.example.com/webhook"
+    ...     })
+    ...     card = AgentCard(name="My Agent", description="...")
+    ...     serve_agent(card, adapter, port=9000)
+    >>> 
+    >>> asyncio.run(main())
+"""
+
+__version__ = "0.1.0"
+
+from .adapter import BaseAgentAdapter
+from .client import build_agent_app, serve_agent
+from .loader import load_a2a_agent
+
+__all__ = [
+    "__version__",
+    "BaseAgentAdapter",
+    "load_a2a_agent",
+    "build_agent_app",
+    "serve_agent",
+]
+

a2a_adapter/adapter.py

@@ -0,0 +1,185 @@
+"""
+Core adapter abstraction for A2A Protocol integration.
+
+This module defines the BaseAgentAdapter abstract class that all framework-specific
+adapters must implement.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, AsyncIterator, Dict
+
+from a2a.types import Message, MessageSendParams, Task
+
+
+class BaseAgentAdapter(ABC):
+    """
+    Abstract base class for adapting agent frameworks to the A2A Protocol.
+    
+    This class provides the core interface for translating between A2A Protocol
+    messages and framework-specific inputs/outputs. Concrete implementations
+    handle the specifics of n8n, CrewAI, LangChain, etc.
+    
+    The adapter follows a three-step process:
+    1. to_framework: Convert A2A MessageSendParams to framework input
+    2. call_framework: Execute the framework-specific logic
+    3. from_framework: Convert framework output back to A2A Message/Task
+    
+    For adapters that support async task execution, the adapter can:
+    - Return a Task with state="submitted" or "working" immediately
+    - Run the actual work in the background
+    - Allow clients to poll for task status via get_task()
+    """
+
+    async def handle(self, params: MessageSendParams) -> Message | Task:
+        """
+        Handle a non-streaming A2A message request.
+        
+        Args:
+            params: A2A protocol message parameters
+            
+        Returns:
+            A2A Message or Task response
+            
+        Raises:
+            Exception: If the underlying framework call fails
+        """
+        framework_input = await self.to_framework(params)
+        framework_output = await self.call_framework(framework_input, params)
+        return await self.from_framework(framework_output, params)
+
+    async def handle_stream(
+        self, params: MessageSendParams
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """
+        Handle a streaming A2A message request.
+        
+        Default implementation raises NotImplementedError. Override this method
+        in subclasses that support streaming responses.
+        
+        Args:
+            params: A2A protocol message parameters
+            
+        Yields:
+            Server-Sent Events compatible dictionaries with 'event' and 'data' keys
+            
+        Raises:
+            NotImplementedError: If streaming is not supported by this adapter
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support streaming"
+        )
+
+    @abstractmethod
+    async def to_framework(self, params: MessageSendParams) -> Any:
+        """
+        Convert A2A message parameters to framework-specific input format.
+        
+        Args:
+            params: A2A protocol message parameters
+            
+        Returns:
+            Framework-specific input (format varies by implementation)
+        """
+        ...
+
+    @abstractmethod
+    async def call_framework(
+        self, framework_input: Any, params: MessageSendParams
+    ) -> Any:
+        """
+        Execute the underlying agent framework with the prepared input.
+        
+        Args:
+            framework_input: Framework-specific input from to_framework()
+            params: Original A2A message parameters (for context)
+            
+        Returns:
+            Framework-specific output
+        """
+        ...
+
+    @abstractmethod
+    async def from_framework(
+        self, framework_output: Any, params: MessageSendParams
+    ) -> Message | Task:
+        """
+        Convert framework output to A2A Message or Task.
+        
+        Args:
+            framework_output: Output from call_framework()
+            params: Original A2A message parameters (for context)
+            
+        Returns:
+            A2A Message or Task response
+        """
+        ...
+
+    def supports_streaming(self) -> bool:
+        """
+        Check if this adapter supports streaming responses.
+        
+        Returns:
+            True if streaming is supported, False otherwise
+        """
+        try:
+            # Check if handle_stream is overridden
+            return (
+                self.__class__.handle_stream
+                != BaseAgentAdapter.handle_stream
+            )
+        except AttributeError:
+            return False
+
+    def supports_async_tasks(self) -> bool:
+        """
+        Check if this adapter supports async task execution.
+        
+        Async task execution allows the adapter to return a Task immediately
+        with state="working" and process the request in the background.
+        Clients can then poll for task status via get_task().
+        
+        Returns:
+            True if async tasks are supported, False otherwise
+        """
+        return False
+
+    async def get_task(self, task_id: str) -> Task | None:
+        """
+        Get the current status of a task by ID.
+        
+        This method is used for polling task status in async task execution mode.
+        Override this method in subclasses that support async tasks.
+        
+        Args:
+            task_id: The ID of the task to retrieve
+            
+        Returns:
+            The Task object with current status, or None if not found
+            
+        Raises:
+            NotImplementedError: If async tasks are not supported by this adapter
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support async task execution"
+        )
+
+    async def cancel_task(self, task_id: str) -> Task | None:
+        """
+        Attempt to cancel a running task.
+        
+        This method is used to cancel async tasks that are still in progress.
+        Override this method in subclasses that support async tasks.
+        
+        Args:
+            task_id: The ID of the task to cancel
+            
+        Returns:
+            The updated Task object with state="canceled", or None if not found
+            
+        Raises:
+            NotImplementedError: If async tasks are not supported by this adapter
+        """
+        raise NotImplementedError(
+            f"{self.__class__.__name__} does not support async task execution"
+        )
+

a2a_adapter/client.py

@@ -0,0 +1,236 @@
+"""
+Single-agent A2A server helpers.
+
+This module provides utilities for creating and serving A2A-compliant
+agent servers using the official A2A.
+"""
+
+from typing import AsyncGenerator
+
+import uvicorn
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers.request_handler import RequestHandler
+from a2a.types import UnsupportedOperationError
+from a2a.utils.errors import ServerError
+from a2a.server.context import ServerCallContext
+from a2a.types import (
+    AgentCard,
+    CancelTaskRequest,
+    CancelTaskResponse,
+    DeleteTaskPushNotificationConfigParams,
+    DeleteTaskPushNotificationConfigResponse,
+    GetTaskPushNotificationConfigParams,
+    GetTaskPushNotificationConfigResponse,
+    GetTaskRequest,
+    GetTaskResponse,
+    ListTaskPushNotificationConfigParams,
+    ListTaskPushNotificationConfigResponse,
+    Message,
+    MessageSendParams,
+    SetTaskPushNotificationConfigRequest,
+    SetTaskPushNotificationConfigResponse,
+    Task,
+    TaskResubscriptionRequest,
+    TaskStatusUpdateEvent,
+)
+
+from .adapter import BaseAgentAdapter
+
+
+class AdapterRequestHandler(RequestHandler):
+    """
+    Wrapper that adapts BaseAgentAdapter to A2A's RequestHandler interface.
+    
+    This class bridges the gap between our adapter abstraction and the
+    official A2A SDK's RequestHandler protocol.
+    """
+
+    def __init__(self, adapter: BaseAgentAdapter):
+        """
+        Initialize the request handler with an adapter.
+        
+        Args:
+            adapter: The BaseAgentAdapter instance to wrap
+        """
+        self.adapter = adapter
+
+    async def on_message_send(
+        self, 
+        params: MessageSendParams,
+        context: ServerCallContext
+    ) -> Message | Task:
+        """
+        Handle a non-streaming message send request.
+        
+        Args:
+            params: A2A message parameters
+            context: Server call context
+            
+        Returns:
+            A2A Message or Task response
+        """
+        return await self.adapter.handle(params)
+
+    async def on_message_send_stream(
+        self,
+        params: MessageSendParams,
+        context: ServerCallContext
+    ) -> AsyncGenerator[Message, None]:
+        """
+        Handle a streaming message send request.
+        
+        Args:
+            params: A2A message parameters
+            context: Server call context
+            
+        Yields:
+            A2A Message responses
+        """
+        async for event in self.adapter.handle_stream(params):
+            yield event
+
+    # Task-related methods (not supported by default)
+    
+    async def on_get_task(
+        self,
+        params: GetTaskRequest,
+        context: ServerCallContext
+    ) -> GetTaskResponse:
+        """Get task status - not supported."""
+        raise ServerError(error=UnsupportedOperationError())
+
+    async def on_cancel_task(
+        self,
+        params: CancelTaskRequest,
+        context: ServerCallContext
+    ) -> CancelTaskResponse:
+        """Cancel task - not supported."""
+        raise ServerError(error=UnsupportedOperationError())
+
+    async def on_resubscribe_to_task(
+        self,
+        params: TaskResubscriptionRequest,
+        context: ServerCallContext
+    ) -> AsyncGenerator[TaskStatusUpdateEvent, None]:
+        """Resubscribe to task - not supported."""
+        raise ServerError(error=UnsupportedOperationError())
+        yield  # Make this an async generator
+
+    # Push notification methods (not supported by default)
+    
+    async def on_set_task_push_notification_config(
+        self,
+        params: SetTaskPushNotificationConfigRequest,
+        context: ServerCallContext
+    ) -> SetTaskPushNotificationConfigResponse:
+        """Set push notification config - not supported."""
+        raise ServerError(error=UnsupportedOperationError())
+
+    async def on_get_task_push_notification_config(
+        self,
+        params: GetTaskPushNotificationConfigParams,
+        context: ServerCallContext
+    ) -> GetTaskPushNotificationConfigResponse:
+        """Get push notification config - not supported."""
+        raise ServerError(error=UnsupportedOperationError())
+
+    async def on_list_task_push_notification_config(
+        self,
+        params: ListTaskPushNotificationConfigParams,
+        context: ServerCallContext
+    ) -> ListTaskPushNotificationConfigResponse:
+        """List push notification configs - not supported."""
+        raise ServerError(error=UnsupportedOperationError())
+
+    async def on_delete_task_push_notification_config(
+        self,
+        params: DeleteTaskPushNotificationConfigParams,
+        context: ServerCallContext
+    ) -> DeleteTaskPushNotificationConfigResponse:
+        """Delete push notification config - not supported."""
+        raise ServerError(error=UnsupportedOperationError())
+
+
+def build_agent_app(
+    agent_card: AgentCard,
+    adapter: BaseAgentAdapter,
+):
+    """
+    Build an ASGI application for a single A2A agent.
+    
+    This function creates a complete A2A-compliant server application using
+    the official A2A SDK, configured with the provided agent card and adapter.
+    
+    Args:
+        agent_card: A2A AgentCard describing the agent's capabilities
+        adapter: BaseAgentAdapter implementation for the agent framework
+        
+    Returns:
+        ASGI application ready to be served
+        
+    Example:
+        >>> from a2a.types import AgentCard
+        >>> from a2a_adapter.integrations.n8n import N8nAgentAdapter
+        >>> 
+        >>> card = AgentCard(
+        ...     name="Math Agent",
+        ...     description="Performs mathematical operations"
+        ... )
+        >>> adapter = N8nAgentAdapter(webhook_url="https://n8n.example.com/webhook")
+        >>> app = build_agent_app(card, adapter)
+    """
+    handler = AdapterRequestHandler(adapter)
+    
+    app_builder = A2AStarletteApplication(
+        agent_card=agent_card,
+        http_handler=handler,
+    )
+    
+    # Build and return the actual ASGI application
+    return app_builder.build()
+
+
+def serve_agent(
+    agent_card: AgentCard,
+    adapter: BaseAgentAdapter,
+    host: str = "0.0.0.0",
+    port: int = 9000,
+    log_level: str = "info",
+    **uvicorn_kwargs,
+) -> None:
+    """
+    Start serving a single A2A agent.
+
+    This is a convenience function that builds the agent application and
+    starts a uvicorn server to serve it.
+
+    Args:
+        agent_card: A2A AgentCard describing the agent's capabilities
+        adapter: BaseAgentAdapter implementation for the agent framework
+        host: Host address to bind to (default: "0.0.0.0")
+        port: Port to listen on (default: 9000)
+        log_level: Logging level (default: "info")
+        **uvicorn_kwargs: Additional arguments to pass to uvicorn.run()
+
+    Example:
+        >>> from a2a.types import AgentCard
+        >>> from a2a_adapter import load_a2a_agent, serve_agent
+        >>>
+        >>> adapter = await load_a2a_agent({
+        ...     "adapter": "n8n",
+        ...     "webhook_url": "https://n8n.example.com/webhook"
+        ... })
+        >>> card = AgentCard(name="My Agent", description="...")
+        >>> serve_agent(card, adapter, port=9000)
+    """
+    app = build_agent_app(agent_card, adapter)
+
+    # Use uvicorn.run directly (not inside asyncio.run context)
+    uvicorn.run(
+        app,
+        host=host,
+        port=port,
+        log_level=log_level,
+        **uvicorn_kwargs,
+    )
+

a2a_adapter/integrations/__init__.py

@@ -0,0 +1,33 @@
+"""
+Framework-specific adapter implementations.
+
+This package contains concrete adapter implementations for various agent frameworks:
+- n8n: HTTP webhook-based workflows
+- CrewAI: Multi-agent collaboration framework
+- LangChain: LLM application framework with LCEL support
+- Callable: Generic Python async function adapter
+"""
+
+__all__ = [
+    "N8nAgentAdapter",
+    "CrewAIAgentAdapter",
+    "LangChainAgentAdapter",
+    "CallableAgentAdapter",
+]
+
+# Lazy imports to avoid requiring all optional dependencies
+def __getattr__(name: str):
+    if name == "N8nAgentAdapter":
+        from .n8n import N8nAgentAdapter
+        return N8nAgentAdapter
+    elif name == "CrewAIAgentAdapter":
+        from .crewai import CrewAIAgentAdapter
+        return CrewAIAgentAdapter
+    elif name == "LangChainAgentAdapter":
+        from .langchain import LangChainAgentAdapter
+        return LangChainAgentAdapter
+    elif name == "CallableAgentAdapter":
+        from .callable import CallableAgentAdapter
+        return CallableAgentAdapter
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+

a2a_adapter/integrations/callable.py

@@ -0,0 +1,172 @@
+"""
+Generic callable adapter for A2A Protocol.
+
+This adapter allows any async Python function to be exposed as an A2A-compliant
+agent, providing maximum flexibility for custom implementations.
+"""
+
+import json
+from typing import Any, AsyncIterator, Callable, Dict
+
+from a2a.types import Message, MessageSendParams, Task, TextPart
+
+
+class CallableAgentAdapter:
+    """
+    Adapter for integrating custom async functions as A2A agents.
+    
+    This adapter wraps any async callable (function, coroutine) and handles
+    the A2A protocol translation. The callable should accept a dictionary
+    input and return either a string or dictionary output.
+    """
+
+    def __init__(
+        self,
+        func: Callable,
+        supports_streaming: bool = False,
+    ):
+        """
+        Initialize the callable adapter.
+        
+        Args:
+            func: An async callable that processes the agent logic.
+                  For non-streaming: Should accept Dict[str, Any] and return str or Dict.
+                  For streaming: Should be an async generator yielding str chunks.
+            supports_streaming: Whether the function supports streaming (default: False)
+        """
+        self.func = func
+        self._supports_streaming = supports_streaming
+
+    async def handle(self, params: MessageSendParams) -> Message | Task:
+        """Handle a non-streaming A2A message request."""
+        framework_input = await self.to_framework(params)
+        framework_output = await self.call_framework(framework_input, params)
+        return await self.from_framework(framework_output, params)
+
+    async def handle_stream(
+        self, params: MessageSendParams
+    ) -> AsyncIterator[Dict[str, Any]]:
+        """
+        Handle a streaming A2A message request.
+        
+        The wrapped function must be an async generator for streaming to work.
+        """
+        if not self._supports_streaming:
+            raise NotImplementedError(
+                "CallableAgentAdapter: streaming not enabled for this function"
+            )
+
+        framework_input = await self.to_framework(params)
+
+        # Call the async generator function
+        async for chunk in self.func(framework_input):
+            # Convert chunk to string if needed
+            text = str(chunk) if not isinstance(chunk, str) else chunk
+
+            # Yield SSE-compatible event
+            if text:
+                yield {
+                    "event": "message",
+                    "data": json.dumps({
+                        "type": "content",
+                        "content": text,
+                    }),
+                }
+
+        # Send completion event
+        yield {
+            "event": "done",
+            "data": json.dumps({"status": "completed"}),
+        }
+
+    def supports_streaming(self) -> bool:
+        """Check if this adapter supports streaming."""
+        return self._supports_streaming
+
+    async def to_framework(self, params: MessageSendParams) -> Dict[str, Any]:
+        """
+        Convert A2A message parameters to a dictionary for the callable.
+        
+        Args:
+            params: A2A message parameters
+            
+        Returns:
+            Dictionary with input data for the callable
+        """
+        # Extract text from the last user message
+        user_message = ""
+        if params.messages:
+            last_message = params.messages[-1]
+            if hasattr(last_message, "content"):
+                if isinstance(last_message.content, list):
+                    # Extract text from content blocks
+                    text_parts = [
+                        item.text
+                        for item in last_message.content
+                        if hasattr(item, "text")
+                    ]
+                    user_message = " ".join(text_parts)
+                elif isinstance(last_message.content, str):
+                    user_message = last_message.content
+
+        # Build input dictionary
+        return {
+            "message": user_message,
+            "messages": params.messages,
+            "session_id": getattr(params, "session_id", None),
+            "context": getattr(params, "context", None),
+        }
+
+    async def call_framework(
+        self, framework_input: Dict[str, Any], params: MessageSendParams
+    ) -> Any:
+        """
+        Execute the callable function with the provided input.
+        
+        Args:
+            framework_input: Input dictionary for the function
+            params: Original A2A parameters (for context)
+            
+        Returns:
+            Function execution output
+            
+        Raises:
+            Exception: If function execution fails
+        """
+        result = await self.func(framework_input)
+        return result
+
+    async def from_framework(
+        self, framework_output: Any, params: MessageSendParams
+    ) -> Message | Task:
+        """
+        Convert callable output to A2A Message.
+        
+        Args:
+            framework_output: Output from the callable
+            params: Original A2A parameters
+            
+        Returns:
+            A2A Message with the function's response
+        """
+        # Convert output to string
+        if isinstance(framework_output, dict):
+            # If output has a 'response' or 'output' key, use that
+            if "response" in framework_output:
+                response_text = str(framework_output["response"])
+            elif "output" in framework_output:
+                response_text = str(framework_output["output"])
+            else:
+                response_text = json.dumps(framework_output, indent=2)
+        else:
+            response_text = str(framework_output)
+
+        return Message(
+            role="assistant",
+            content=[TextPart(type="text", text=response_text)],
+        )
+
+    def supports_streaming(self) -> bool:
+        """Check if this adapter supports streaming responses."""
+        return False
+