aip-agents-binary 0.5.20__py3-none-any.whl

aip_agents/a2a/server/google_adk_executor.py

@@ -0,0 +1,198 @@
+"""A2A server-side executor for Google ADK agent instances.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import asyncio
+from typing import Any
+
+from a2a.server.agent_execution import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a.server.tasks import TaskUpdater
+from a2a.types import TaskState
+from a2a.utils import new_agent_text_message
+
+from aip_agents.a2a.server.base_executor import BaseA2AExecutor, StatusUpdateParams
+from aip_agents.agent.google_adk_constants import DEFAULT_AUTH_URL
+from aip_agents.agent.interfaces import GoogleADKAgentProtocol
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class GoogleADKExecutor(BaseA2AExecutor):
+    """A2A Executor for serving a `GoogleADKAgent`.
+
+    This executor bridges the A2A server protocol with a `aip_agents.agent.GoogleADKAgent`.
+    It handles incoming requests by invoking the agent's `arun_a2a_stream` method,
+    which is specifically designed to yield ADK events in an A2A-compatible dictionary
+    format. This executor's `_process_stream` method is tailored to handle this stream,
+    including ADK-specific statuses like "auth_required", before delegating common
+    status handling to `BaseA2AExecutor._handle_stream_event`.
+
+    It leverages common functionality from `BaseA2AExecutor` for task management,
+    initial request checks, and cancellation.
+
+    Attributes:
+        agent (GoogleADKAgentProtocol): The instance of `GoogleADKAgent`-compatible class to execute.
+    """
+
+    agent: GoogleADKAgentProtocol
+
+    def __init__(self, agent: GoogleADKAgentProtocol) -> None:
+        """Initializes the GoogleADKExecutor.
+
+        Args:
+            agent: Component implementing `GoogleADKAgentProtocol`.
+
+        Raises:
+            TypeError: If the provided agent does not satisfy `GoogleADKAgentProtocol`.
+        """
+        super().__init__()
+
+        if not isinstance(agent, GoogleADKAgentProtocol):
+            raise TypeError(
+                f"GoogleADKExecutor expected an agent implementing GoogleADKAgentProtocol, got {type(agent).__name__}"
+            )
+        self.agent = agent
+        self._default_auth_url = DEFAULT_AUTH_URL
+
+    async def execute(
+        self,
+        context: RequestContext,
+        event_queue: EventQueue,
+    ) -> None:
+        """Processes an incoming agent request using the `GoogleADKAgent`.
+
+        This method first performs initial checks using `_handle_initial_execute_checks`
+        from the base class. If successful, it prepares the `_process_stream` coroutine
+        and passes it to `_execute_agent_processing` (also from the base class) to
+        manage its execution lifecycle. The `_process_stream` method is responsible for
+        calling the agent's `arun_a2a_stream` and handling its ADK-specific output.
+
+        Args:
+            context (RequestContext): The A2A request context containing message details,
+                task ID, and context ID.
+            event_queue (EventQueue): The queue for sending A2A events (task status,
+                artifacts) back to the server.
+        """
+        updater, query, metadata = await self._handle_initial_execute_checks(context, event_queue)
+        if not updater or query is None:  # Checks failed, status already sent by base method
+            return
+
+        agent_processing_coro = self._process_stream(
+            query=query,
+            updater=updater,
+            task_id=context.task_id,
+            context_id=context.context_id,
+            event_queue=event_queue,
+            metadata=metadata,
+        )
+
+        await self._execute_agent_processing(
+            agent_processing_coro=agent_processing_coro,
+            updater=updater,
+            task_id=context.task_id,
+            context_id=context.context_id,
+        )
+
+    async def _process_stream(  # noqa: PLR0913
+        self,
+        query: str,
+        updater: TaskUpdater,
+        task_id: str,
+        context_id: str,
+        event_queue: EventQueue,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Processes the streaming response from the `GoogleADKAgent`.
+
+        This coroutine invokes `self.agent.arun_a2a_stream`, which is designed to yield
+        dictionary chunks adapting native Google ADK `Event` objects into an A2A-compatible
+        format. This method specifically handles the "auth_required" status that can be
+        yielded by the agent's stream. For all other statuses, it delegates to the
+        `self._handle_stream_event` method from `BaseA2AExecutor` for common processing.
+
+        The `GoogleADKAgent.arun_a2a_stream` and its helper methods are responsible for
+        the ADK-specific event transformation. This executor's role here is to consume
+        that adapted stream.
+
+        If `asyncio.CancelledError` is raised (e.g., by the task managed by
+        `_execute_agent_processing`), it is re-raised to be handled by the base class.
+        Other exceptions during streaming are caught, logged, an A2A 'failed' status
+        is sent, and the exception is re-raised.
+
+        Args:
+            query (str): The query string to be processed by the agent.
+            updater (TaskUpdater): The `TaskUpdater` instance for sending status updates.
+            task_id (str): The A2A task ID.
+            context_id (str): The A2A context ID.
+            event_queue (EventQueue): The A2A event queue, used by the base handler
+                for sending artifact events.
+            metadata (dict[str, Any] | None): Optional metadata from the A2A request.
+
+        Raises:
+            asyncio.CancelledError: If the task is cancelled externally.
+            Exception: If any other error occurs during the agent's stream processing.
+        """
+        try:
+            async for chunk in self.agent.arun_a2a_stream(
+                query=query,
+                configurable={"thread_id": task_id, "context_id": context_id},
+            ):
+                # Handle ADK-specific statuses first
+                if chunk.get("status") == "auth_required":
+                    auth_content = chunk.get("content", {})
+                    auth_url = (
+                        auth_content.get("auth_url", self._default_auth_url)
+                        if isinstance(auth_content, dict)
+                        else self._default_auth_url
+                    )
+                    auth_message = (
+                        auth_content.get("message", "Authorization is required.")
+                        if isinstance(auth_content, dict)
+                        else "Authorization is required."
+                    )
+                    full_message = f"{auth_message} Visit {auth_url}"
+
+                    await self._update_status(
+                        updater,
+                        TaskState.auth_required,
+                        message=new_agent_text_message(full_message, context_id=context_id, task_id=task_id),
+                        params=StatusUpdateParams(final=True, task_id=task_id, context_id=context_id),
+                    )
+                    return  # Terminate stream processing as auth is required
+
+                # For other statuses, use the common handler from BaseA2AExecutor
+                should_terminate = await self._handle_stream_event(
+                    chunk=chunk,
+                    updater=updater,
+                    task_id=task_id,
+                    context_id=context_id,
+                    event_queue=event_queue,
+                    metadata=metadata,
+                )
+                if should_terminate:
+                    return
+
+        except asyncio.CancelledError:
+            logger.info(f"ADK Stream processing for task {task_id} was cancelled.")
+            # Re-raise for _execute_agent_processing to handle and set A2A status
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error during ADK agent streaming for task {task_id}: {e}",
+                exc_info=True,
+            )
+            await self._update_status(
+                updater,
+                TaskState.failed,
+                message=new_agent_text_message(
+                    f"Error during streaming: {str(e)}",
+                    context_id=context_id,
+                    task_id=task_id,
+                ),
+                params=StatusUpdateParams(final=True, task_id=task_id, context_id=context_id),
+            )
+            raise

aip_agents/a2a/server/langflow_executor.py

@@ -0,0 +1,180 @@
+"""A2A executor for Langflow agents.
+
+This module provides the LangflowA2AExecutor class that extends BaseA2AExecutor
+to handle A2A requests for Langflow agents, similar to how LangGraphA2AExecutor
+works for LangGraph agents.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+import typing
+from abc import ABC
+
+from a2a.server.agent_execution import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a.server.tasks import TaskUpdater
+from a2a.types import TaskState
+from a2a.utils import new_agent_text_message
+
+from aip_agents.a2a.server.base_executor import BaseA2AExecutor, StatusUpdateParams
+from aip_agents.agent.interfaces import LangflowAgentProtocol
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class LangflowA2AExecutor(BaseA2AExecutor, ABC):
+    """A2A executor for Langflow agents.
+
+    This class extends BaseA2AExecutor to provide A2A execution capabilities
+    for Langflow agents. It follows the same patterns as LangGraphA2AExecutor
+    but handles Langflow-specific streaming and execution logic.
+
+    Attributes:
+        agent: The LangflowAgent-compatible instance to be executed.
+    """
+
+    agent: LangflowAgentProtocol
+
+    def __init__(self, langflow_agent_instance: LangflowAgentProtocol) -> None:
+        """Initialize the LangflowA2AExecutor.
+
+        Args:
+            langflow_agent_instance: Component implementing `LangflowAgentProtocol`.
+
+        Raises:
+            TypeError: If the agent does not satisfy `LangflowAgentProtocol`.
+        """
+        super().__init__()
+
+        if not isinstance(langflow_agent_instance, LangflowAgentProtocol):
+            type_name = type(langflow_agent_instance).__name__
+            raise TypeError(
+                f"LangflowA2AExecutor expected an agent implementing LangflowAgentProtocol, got {type_name}"
+            )
+
+        self.agent = langflow_agent_instance
+        logger.info(f"Initialized LangflowA2AExecutor for agent '{self.agent.name}'")
+
+    async def execute(
+        self,
+        context: RequestContext,
+        event_queue: EventQueue,
+    ) -> None:
+        """Process an incoming agent request using a Langflow agent.
+
+        This method handles the execution lifecycle for Langflow agents:
+        1. Performs initial validation and setup
+        2. Creates agent processing coroutine
+        3. Manages the execution lifecycle through BaseA2AExecutor
+
+        Args:
+            context: The A2A request context containing message details,
+                task ID, and context ID.
+            event_queue: The queue for sending A2A events back to the server.
+        """
+        updater, query, metadata = await self._handle_initial_execute_checks(context, event_queue)
+        if not updater or query is None:
+            return
+
+        agent_processing_coro = self._process_stream(
+            query=query,
+            updater=updater,
+            task_id=context.task_id,
+            context_id=context.context_id,
+            event_queue=event_queue,
+            metadata=metadata,
+        )
+
+        await self._execute_agent_processing(
+            agent_processing_coro=agent_processing_coro,
+            updater=updater,
+            task_id=context.task_id,
+            context_id=context.context_id,
+        )
+
+    def _get_configurable_kwargs(self, task_id: str) -> dict[str, typing.Any]:
+        """Get configurable kwargs for agent execution.
+
+        For Langflow agents, we use thread_id for session management.
+
+        Args:
+            task_id: The A2A task ID to use as thread_id.
+
+        Returns:
+            Dictionary with configurable parameters for the agent.
+        """
+        return {"configurable": {"thread_id": task_id}}
+
+    async def _process_stream(  # noqa: PLR0913
+        self,
+        query: str,
+        updater: TaskUpdater,
+        task_id: str,
+        context_id: str,
+        event_queue: EventQueue,
+        metadata: dict[str, typing.Any] | None = None,
+    ) -> None:
+        """Process the streaming response from a Langflow agent.
+
+        This method invokes the agent's arun_a2a_stream method and processes
+        the A2A events it yields. It handles event routing through the base
+        class's _handle_stream_event method.
+
+        Args:
+            query: The query string to be processed by the agent.
+            updater: The TaskUpdater instance for sending status updates.
+            task_id: The A2A task ID.
+            context_id: The A2A context ID.
+            event_queue: The A2A event queue for sending artifact events.
+            metadata: Optional metadata from the A2A request.
+
+        Raises:
+            asyncio.CancelledError: If the task is cancelled externally.
+            Exception: If any other error occurs during streaming.
+        """
+        try:
+            kwargs = self._get_configurable_kwargs(task_id)
+            if metadata:
+                kwargs["metadata"] = metadata
+
+            logger.debug(f"Starting Langflow agent stream for task {task_id}")
+
+            current_metadata: dict[str, typing.Any] = metadata.copy() if metadata else {}
+
+            async for chunk in self.agent.arun_a2a_stream(query=query, **kwargs):
+                chunk_metadata = chunk.get("metadata")
+                if chunk_metadata and isinstance(chunk_metadata, dict):
+                    try:
+                        current_metadata.update(chunk_metadata)
+                    except Exception as e:
+                        logger.warning(f"Invalid metadata in chunk: {chunk_metadata}, error: {e}")
+
+                should_terminate = await self._handle_stream_event(
+                    chunk=chunk,
+                    updater=updater,
+                    task_id=task_id,
+                    context_id=context_id,
+                    event_queue=event_queue,
+                    metadata=current_metadata if current_metadata else None,
+                )
+
+                if should_terminate:
+                    logger.debug(f"Stream terminated for task {task_id}")
+                    return
+
+        except Exception as e:
+            logger.error(f"Error during Langflow agent streaming for task {task_id}: {e}", exc_info=True)
+
+            await self._update_status(
+                updater,
+                TaskState.failed,
+                message=new_agent_text_message(
+                    f"Error during Langflow execution: {str(e)}",
+                    context_id=context_id,
+                    task_id=task_id,
+                ),
+                params=StatusUpdateParams(final=True, task_id=task_id, context_id=context_id),
+            )
+            raise

aip_agents/a2a/server/langgraph_executor.py

@@ -0,0 +1,270 @@
+"""Base executor class for LangChain-based A2A executors.
+
+This module provides a common base class for executors that work with LangChain-based
+agents, such as LangChainAgent and LangGraphAgent. It implements shared functionality
+for handling streaming responses and managing agent execution.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import asyncio
+from abc import ABC
+from typing import Any
+
+from a2a.server.agent_execution import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a.server.tasks import TaskUpdater
+from a2a.types import TaskState
+from a2a.utils import new_agent_text_message
+
+from aip_agents.a2a.server.base_executor import BaseA2AExecutor, StatusUpdateParams
+from aip_agents.agent.interfaces import LangGraphAgentProtocol
+from aip_agents.schema.step_limit import StepLimitConfig
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class LangGraphA2AExecutor(BaseA2AExecutor, ABC):
+    """Base class for LangChain-based A2A executors.
+
+    This class extends BaseA2AExecutor to provide common functionality for executors
+    that work with LangChain-based agents (LangChainAgent and LangGraphAgent).
+    It implements shared methods for handling streaming responses and managing
+    agent execution, while leaving agent-specific initialization to subclasses.
+
+    Attributes:
+        agent (LangGraphAgentProtocol): The LangChain-based agent instance to be executed.
+    """
+
+    agent: LangGraphAgentProtocol
+
+    def __init__(self, langgraph_agent_instance: LangGraphAgentProtocol) -> None:
+        """Initializes the LangGraphA2AExecutor.
+
+        Args:
+            langgraph_agent_instance: Component implementing `LangGraphAgentProtocol`.
+
+        Raises:
+            TypeError: If the provided agent does not satisfy `LangGraphAgentProtocol`.
+        """
+        super().__init__()
+
+        if not isinstance(langgraph_agent_instance, LangGraphAgentProtocol):
+            _type_name = type(langgraph_agent_instance).__name__
+            raise TypeError(
+                f"LangGraphA2AExecutor expected an agent implementing LangGraphAgentProtocol, got {_type_name}"
+            )
+        self.agent = langgraph_agent_instance
+
+    async def execute(
+        self,
+        context: RequestContext,
+        event_queue: EventQueue,
+    ) -> None:
+        """Processes an incoming agent request using a LangChain-based agent.
+
+        This method first performs initial checks using _handle_initial_execute_checks.
+        If successful, it prepares the _process_stream coroutine and passes it to
+        _execute_agent_processing from the base class to manage its lifecycle.
+        The _process_stream method is responsible for calling the agent's
+        arun_a2a_stream and handling its output.
+
+        Args:
+            context (RequestContext): The A2A request context containing message details,
+                task ID, and context ID.
+            event_queue (EventQueue): The queue for sending A2A events (task status,
+                artifacts) back to the server.
+        """
+        updater, query, metadata = await self._handle_initial_execute_checks(context, event_queue)
+        if not updater or query is None:  # Checks failed, status already sent
+            return
+
+        agent_processing_coro = self._process_stream(
+            query=query,
+            updater=updater,
+            task_id=context.task_id,
+            context_id=context.context_id,
+            event_queue=event_queue,
+            metadata=metadata,
+        )
+
+        await self._execute_agent_processing(
+            agent_processing_coro=agent_processing_coro,
+            updater=updater,
+            task_id=context.task_id,
+            context_id=context.context_id,
+        )
+
+    def _get_configurable_kwargs(self, task_id: str) -> dict[str, Any]:
+        """Get configurable kwargs for agent delegation.
+
+        Args:
+            task_id: The A2A task ID.
+
+        Returns:
+            dict[str, Any]: A dictionary with 'configurable' key if the agent
+                            has 'thread_id_key', otherwise an empty dictionary.
+        """
+        if hasattr(self.agent, "thread_id_key"):
+            return {"configurable": {self.agent.thread_id_key: task_id}}
+        return {}
+
+    def _build_agent_kwargs(
+        self,
+        task_id: str,
+        metadata: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        """Build kwargs for agent stream execution from task and metadata.
+
+        Args:
+            task_id: The A2A task ID for configurable threading settings.
+            metadata: Optional request metadata, including files and overrides.
+
+        Returns:
+            dict[str, Any]: Keyword arguments to pass to the agent's stream method.
+        """
+        kwargs = self._get_configurable_kwargs(task_id)
+
+        files: list[str | dict[str, Any]] = self._extract_files_from_metadata(metadata)
+        if metadata is not None:
+            kwargs["metadata"] = metadata
+            if isinstance(metadata, dict):
+                raw_user_id = metadata.get("memory_user_id") or metadata.get("user_id")
+                if raw_user_id:
+                    kwargs["memory_user_id"] = str(raw_user_id)
+
+                raw_pii_mapping = metadata.get("pii_mapping")
+                if isinstance(raw_pii_mapping, dict) and raw_pii_mapping:
+                    kwargs["pii_mapping"] = dict(raw_pii_mapping)
+
+                # Extract invocation-level step limit overrides (Docs-1)
+                raw_step_limit_config = metadata.get("step_limit_config")
+                if isinstance(raw_step_limit_config, dict | StepLimitConfig):
+                    kwargs["step_limit_config"] = raw_step_limit_config
+        if files:
+            kwargs["files"] = files
+
+        return kwargs
+
+    async def _process_stream(  # noqa: PLR0913
+        self,
+        query: str,
+        updater: TaskUpdater,
+        task_id: str,
+        context_id: str,
+        event_queue: EventQueue,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Processes the streaming response from a LangChain-based agent.
+
+        This coroutine invokes the agent.arun_a2a_stream method with the given query and metadata.
+        It then iterates over the asynchronous stream of dictionary chunks yielded by
+        the agent. Each chunk is passed to _handle_stream_event from the base class
+        to interpret common A2A statuses (working, completed, failed, etc.) and update
+        the A2A task accordingly.
+
+        If asyncio.CancelledError is raised (typically from the task managed by
+        _execute_agent_processing), it is re-raised to be handled by the base class.
+        Other exceptions during streaming are caught, logged, an A2A 'failed' status
+        is sent, and the exception is re-raised.
+
+        Args:
+            query (str): The query string to be processed by the agent.
+            updater (TaskUpdater): The TaskUpdater instance for sending status updates.
+            task_id (str): The A2A task ID.
+            context_id (str): The A2A context ID.
+            event_queue (EventQueue): The A2A event queue for sending artifact events.
+            metadata (dict[str, Any] | None): Optional metadata from the A2A request.
+
+        Raises:
+            asyncio.CancelledError: If the task is cancelled externally.
+            Exception: If any other error occurs during the agent's stream processing.
+        """
+        stream = None
+        try:
+            kwargs = self._build_agent_kwargs(task_id=task_id, metadata=metadata)
+
+            stream = self.agent.arun_a2a_stream(query=query, **kwargs)
+
+            current_metadata: dict[str, Any] = metadata.copy() if metadata else {}
+
+            async for chunk in stream:
+                chunk_metadata = chunk.get("metadata")
+                if chunk_metadata is not None:
+                    try:
+                        current_metadata.update(chunk_metadata)
+                    except Exception as e:
+                        logger.warning(f"Invalid metadata payload from chunk: {chunk_metadata}, error: {e}")
+
+                should_terminate = await self._handle_stream_event(
+                    chunk=chunk,
+                    updater=updater,
+                    task_id=task_id,
+                    context_id=context_id,
+                    event_queue=event_queue,
+                    metadata=current_metadata if current_metadata else None,
+                )
+                if should_terminate:
+                    return
+
+        except asyncio.CancelledError:
+            logger.info(f"LangChain stream processing for task {task_id} was cancelled.")
+            raise
+        except Exception as e:
+            logger.error(
+                f"Error during LangChain agent streaming for task {task_id}: {e}",
+                exc_info=True,
+            )
+            await self._update_status(
+                updater,
+                TaskState.failed,
+                message=new_agent_text_message(
+                    f"Error during streaming: {str(e)}",
+                    context_id=context_id,
+                    task_id=task_id,
+                ),
+                params=StatusUpdateParams(final=True, task_id=task_id, context_id=context_id),
+            )
+            raise
+
+    @staticmethod
+    def _extract_files_from_metadata(metadata: dict[str, Any] | None) -> list[str | dict[str, Any]]:
+        """Extract file paths from metadata, removing them since they are passed via kwargs.
+
+        Args:
+            metadata: Metadata dict from the request, potentially containing files.
+
+        Returns:
+            List of non-empty file path strings or file metadata dictionaries.
+        """
+        if not isinstance(metadata, dict):
+            return []
+
+        try:
+            raw_files = metadata.pop("files", None)
+        except AttributeError:
+            return []
+        if raw_files is None:
+            return []
+
+        if not isinstance(raw_files, list):
+            logger.warning("Invalid 'files' metadata received; expected list of strings or dicts.")
+            return []
+
+        normalized_files: list[str | dict[str, Any]] = []
+        invalid_entry_logged = False
+        for entry in raw_files:
+            if isinstance(entry, str) and entry:
+                normalized_files.append(entry)
+                continue
+            if isinstance(entry, dict):
+                normalized_files.append(entry)
+                continue
+            if not invalid_entry_logged:
+                logger.warning("Invalid file metadata entry received; expected string or dict.")
+                invalid_entry_logged = True
+
+        return normalized_files