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

aip_agents/agent/hitl/registry.py

@@ -0,0 +1,149 @@
+"""Registry for tracking HITL approval manager ownership across agent hierarchies.
+
+This module provides a thread-safe singleton registry that maps request IDs to their
+owning ApprovalManager instances. This enables proper decision routing in hierarchical
+agent architectures where sub-agents have HITL enabled but parents do not.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING
+from weakref import WeakValueDictionary
+
+if TYPE_CHECKING:
+    from aip_agents.agent.hitl.manager import ApprovalManager
+
+
+class HITLManagerRegistry:
+    """Global registry mapping request_id → owning ApprovalManager.
+
+    Uses weak references to avoid preventing manager garbage collection.
+    Thread-safe for concurrent agent execution.
+
+    This singleton registry allows the HITL decision endpoint to route decisions
+    to the correct manager in hierarchical agent setups, where a sub-agent may
+    create a pending request but the parent agent receives the decision.
+
+    Example:
+        >>> from aip_agents.agent.hitl.registry import hitl_registry
+        >>> # Manager auto-registers when creating requests
+        >>> manager.create_approval_request(...)
+        >>> # Later, decision handler looks up the owning manager
+        >>> owning_manager = hitl_registry.get_manager(request_id)
+        >>> owning_manager.resolve_pending_request(request_id, "approved")
+    """
+
+    _instance: HITLManagerRegistry | None = None
+    _lock = threading.RLock()
+    _registry: WeakValueDictionary[str, ApprovalManager]
+    _registry_lock: threading.RLock
+
+    def __new__(cls) -> HITLManagerRegistry:
+        """Ensure only one instance exists (singleton pattern).
+
+        Returns:
+            The singleton HITLManagerRegistry instance.
+        """
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    instance = super().__new__(cls)
+                    instance._registry = WeakValueDictionary()
+                    instance._registry_lock = threading.RLock()
+                    cls._instance = instance
+        return cls._instance
+
+    def register(self, request_id: str, manager: ApprovalManager) -> None:
+        """Register a pending request with its owning manager.
+
+        This method is typically called automatically by ApprovalManager when
+        creating a new pending request. It establishes the ownership mapping
+        needed for proper decision routing.
+
+        Args:
+            request_id: Unique identifier for the pending request
+            manager: ApprovalManager instance that owns this request
+
+        Example:
+            >>> hitl_registry.register("req_abc123", my_manager)
+        """
+        with self._registry_lock:
+            self._registry[request_id] = manager
+
+    def unregister(self, request_id: str) -> None:
+        """Remove a request from the registry.
+
+        This method is called when a request is resolved, times out, or expires.
+        It's important for cleanup to prevent the registry from growing unbounded.
+
+        Args:
+            request_id: Unique identifier to remove
+
+        Example:
+            >>> hitl_registry.unregister("req_abc123")
+        """
+        with self._registry_lock:
+            self._registry.pop(request_id, None)
+
+    def get_manager(self, request_id: str) -> ApprovalManager | None:
+        """Retrieve the manager owning a specific request.
+
+        This is the primary lookup method used by decision handlers to route
+        decisions to the correct manager in hierarchical agent setups.
+
+        Args:
+            request_id: Unique identifier to lookup
+
+        Returns:
+            ApprovalManager instance if found, None otherwise. None can indicate
+            the request was resolved, timed out, or the manager was garbage collected.
+
+        Example:
+            >>> manager = hitl_registry.get_manager("req_abc123")
+            >>> if manager:
+            ...     manager.resolve_pending_request("req_abc123", "approved")
+        """
+        with self._registry_lock:
+            return self._registry.get(request_id)
+
+    def clear(self) -> None:
+        """Clear all registrations.
+
+        This method is primarily intended for testing to ensure a clean state
+        between test cases. It removes all registered mappings.
+
+        Warning:
+            This should not be called in production code as it will prevent
+            pending requests from being resolved.
+
+        Example:
+            >>> hitl_registry.clear()  # For testing only
+        """
+        with self._registry_lock:
+            self._registry.clear()
+
+    def list_all(self) -> list[str]:
+        """List all currently registered request IDs.
+
+        Returns:
+            List of request IDs currently in the registry.
+
+        Note:
+            Due to weak references, managers may be garbage collected between
+            calling this method and accessing them, so the actual available
+            managers might be fewer than the returned list length.
+
+        Example:
+            >>> request_ids = hitl_registry.list_all()
+            >>> print(f"Pending requests: {request_ids}")
+        """
+        with self._registry_lock:
+            return list(self._registry.keys())
+
+
+# Global singleton instance
+hitl_registry = HITLManagerRegistry()

aip_agents/agent/interface.py

@@ -0,0 +1,138 @@
+"""Defines the abstract base class AgentInterface for all agent implementations, now with MCP and A2A support.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncGenerator
+from typing import Any
+
+from a2a.types import AgentCard
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+
+from aip_agents.schema.agent import BaseAgentConfig
+
+
+class AgentInterface(ABC):
+    """A general and minimal interface for agent implementations.
+
+    Defines core execution methods (`__init__`, `run`, `arun`, `arun_stream`).
+    Concrete subclasses must implement all abstract methods.
+    """
+
+    name: str
+    instruction: str
+    description: str | None
+    mcp_config: dict[str, Any] = {}
+    lm_invoker: BaseLMInvoker | None = None
+    config: BaseAgentConfig | None = None
+
+    def __init__(
+        self,
+        name: str,
+        instruction: str,
+        description: str | None = None,
+        lm_invoker: BaseLMInvoker | None = None,
+        config: BaseAgentConfig | None = None,
+        **kwargs: Any,
+    ):
+        """Initializes the agent.
+
+        Args:
+            name: The name of the agent.
+            instruction: The core directive or system prompt for the agent.
+            description: Human-readable description. Defaults to instruction if not provided.
+            lm_invoker: The language model invoker to use for LLM interactions. Defaults to None.
+            config: Additional configuration for the agent.
+            **kwargs: Additional keyword arguments for concrete implementations.
+        """
+        self.name = name
+        self.instruction = instruction
+        self.description = description or self.instruction
+        self.lm_invoker = lm_invoker
+        self.config = config
+
+    @abstractmethod
+    def run(
+        self,
+        query: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Synchronously runs the agent.
+
+        Args:
+            query: The input query for the agent.
+            **kwargs: Additional keyword arguments for execution.
+
+        Returns:
+            Dict containing at least {'output': ...}.
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'run' method."
+        )  # pragma: no cover
+
+    @abstractmethod
+    async def arun(
+        self,
+        query: str,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Asynchronously runs the agent.
+
+        Args:
+            query: The input query for the agent.
+            **kwargs: Additional keyword arguments for execution.
+
+        Returns:
+            Dict containing at least {'output': ...}.
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'arun' method."
+        )  # pragma: no cover
+
+    @abstractmethod
+    async def arun_stream(
+        self,
+        query: str,
+        **kwargs: Any,
+    ) -> AsyncGenerator[str | dict[str, Any], None]:
+        """Asynchronously streams the agent's response.
+
+        Args:
+            query: The input query.
+            **kwargs: Extra parameters for execution.
+
+        Yields:
+            Chunks of output (strings or dicts).
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'arun_stream' method."
+        )  # pragma: no cover
+
+    @abstractmethod
+    def add_mcp_server(self, mcp_config: dict[str, dict[str, Any]]) -> None:
+        """Adds a new MCP server configuration.
+
+        Args:
+            mcp_config: Dictionary containing server name as key and its configuration as value.
+
+        Raises:
+            ValueError: If mcp_config is empty or None, or if any server configuration is invalid.
+            KeyError: If any server name already exists in the configuration.
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'add_mcp_server' method."
+        )  # pragma: no cover
+
+    @abstractmethod
+    def register_a2a_agents(self, agents: list[AgentCard]):
+        """Registers A2A agents from a list of AgentCards.
+
+        Args:
+            agents: A list of AgentCard instances.
+        """
+        raise NotImplementedError(
+            f"'{self.__class__.__name__}' has not implemented the 'register_a2a_agents' method."
+        )  # pragma: no cover

aip_agents/agent/interfaces.py

@@ -0,0 +1,65 @@
+"""Common agent-facing protocols used by A2A executors.
+
+These runtime-checkable protocols let executors validate agent instances
+without importing the concrete implementation classes, which avoids
+introducing circular import chains at runtime.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LangGraphAgentProtocol(Protocol):
+    """Minimal interface required by LangGraphA2AExecutor."""
+
+    name: str
+
+    async def arun_a2a_stream(self, query: str, **kwargs: Any) -> AsyncIterator[dict[str, Any]]:
+        """Stream A2A-compatible chunks for the given query.
+
+        Args:
+            query (str): The query to execute and stream.
+            **kwargs (Any): Additional keyword arguments for execution.
+
+        Yields:
+            dict[str, Any]: A2A-compatible streaming chunks.
+        """
+
+
+@runtime_checkable
+class LangflowAgentProtocol(Protocol):
+    """Minimal interface required by LangflowA2AExecutor."""
+
+    name: str
+
+    async def arun_a2a_stream(self, query: str, **kwargs: Any) -> AsyncIterator[dict[str, Any]]:
+        """Stream A2A-compatible chunks for the given query.
+
+        Args:
+            query (str): The query to execute and stream.
+            **kwargs (Any): Additional keyword arguments for execution.
+
+        Yields:
+            dict[str, Any]: A2A-compatible streaming chunks.
+        """
+
+
+@runtime_checkable
+class GoogleADKAgentProtocol(Protocol):
+    """Minimal interface required by GoogleADKExecutor."""
+
+    name: str
+
+    async def arun_a2a_stream(self, query: str, **kwargs: Any) -> AsyncIterator[dict[str, Any]]:
+        """Stream A2A-compatible chunks for the given query.
+
+        Args:
+            query (str): The query to execute and stream.
+            **kwargs (Any): Additional keyword arguments for execution.
+
+        Yields:
+            dict[str, Any]: A2A-compatible streaming chunks.
+        """