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

aip_agents/a2a/server/base_executor.pyi

@@ -0,0 +1,73 @@
+from _typeshed import Incomplete
+from a2a.server.agent_execution import AgentExecutor as A2ASDKExecutor, RequestContext
+from a2a.server.events.event_queue import EventQueue
+from abc import ABC, abstractmethod
+from aip_agents.types import A2AEvent as A2AEvent, A2AStreamEventType as A2AStreamEventType
+from aip_agents.utils import serialize_references_for_metadata as serialize_references_for_metadata
+from aip_agents.utils.artifact_helpers import ArtifactHandler as ArtifactHandler
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.metadata_helper import MetadataFieldKeys as MetadataFieldKeys
+from collections.abc import Callable as Callable
+from dataclasses import dataclass
+from typing import Any
+
+logger: Incomplete
+
+@dataclass
+class StatusUpdateParams:
+    """Parameters for status updates."""
+    metadata: dict[str, Any] | None = ...
+    final: bool = ...
+    task_id: str | None = ...
+    context_id: str | None = ...
+
+class BaseA2AExecutor(A2ASDKExecutor, ABC):
+    """Abstract base class for GLLM Agent framework's A2A server-side executors.
+
+    This class extends the A2A SDK's `AgentExecutor`. It serves as a common
+    foundation for specific executors tailored to different agent types within the
+    `aip-agents` framework, such as `LangGraphA2AExecutor` or
+    `GoogleADKA2AExecutor`.
+
+    Subclasses are required to implement the `execute` method to handle A2A
+    requests. The `cancel` method has a common implementation.
+
+    Attributes:
+        _active_tasks (dict[str, asyncio.Task]): A dictionary mapping task IDs to
+            their corresponding asyncio.Task instances for active agent executions.
+    """
+    def __init__(self) -> None:
+        """Initializes the BaseA2AExecutor."""
+    @abstractmethod
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        """Processes an incoming agent request and manages its execution.
+
+        Implementations should interact with the underlying agent (e.g., a LangGraph
+        or Google ADK agent) based on the provided `context`. All communications
+        regarding task status, artifacts, and completion must be sent through
+        the `event_queue`.
+
+        This method typically involves:
+        1. Calling `_handle_initial_execute_checks` for validation and setup.
+        2. Defining an agent-specific coroutine for processing (e.g., `_process_stream`).
+        3. Calling `_execute_agent_processing` to manage the lifecycle of this coroutine.
+
+        Args:
+            context (RequestContext): The request context containing information about the incoming
+                     message, task, and other relevant data.
+            event_queue (EventQueue): The queue used to send events (e.g., task status updates,
+                         artifacts) back to the A2A server infrastructure.
+        """
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        """Handles a request to cancel an ongoing agent task.
+
+        This method attempts to cancel an active asyncio.Task associated with the
+        given `context.task_id`. It waits for a short period for the task to handle
+        the cancellation gracefully. The `event_queue` is used to report the
+        outcome of the cancellation attempt (e.g., success, error during cleanup).
+
+        Args:
+            context (RequestContext): The request context for the task to be cancelled,
+                primarily used to get the `task_id` and `context_id`.
+            event_queue (EventQueue): The queue for sending cancellation status events.
+        """

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/google_adk_executor.pyi

@@ -0,0 +1,51 @@
+from _typeshed import Incomplete
+from a2a.server.agent_execution import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from aip_agents.a2a.server.base_executor import BaseA2AExecutor as BaseA2AExecutor, StatusUpdateParams as StatusUpdateParams
+from aip_agents.agent.google_adk_constants import DEFAULT_AUTH_URL as DEFAULT_AUTH_URL
+from aip_agents.agent.interfaces import GoogleADKAgentProtocol as GoogleADKAgentProtocol
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+
+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`.
+        """
+    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.
+        """

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/langflow_executor.pyi

@@ -0,0 +1,43 @@
+from _typeshed import Incomplete
+from a2a.server.agent_execution import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from abc import ABC
+from aip_agents.a2a.server.base_executor import BaseA2AExecutor as BaseA2AExecutor, StatusUpdateParams as StatusUpdateParams
+from aip_agents.agent.interfaces import LangflowAgentProtocol as LangflowAgentProtocol
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+
+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`.
+        """
+    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.
+        """