aip-agents-binary 0.5.22__py3-none-any.whl → 0.5.24__py3-none-any.whl

aip_agents/agent/google_adk_agent.pyi

@@ -1,141 +0,0 @@
-from _typeshed import Incomplete
-from a2a.types import AgentCard
-from aip_agents.agent.base_agent import BaseAgent as BaseAgent
-from aip_agents.agent.google_adk_constants import DEFAULT_AUTH_URL as DEFAULT_AUTH_URL
-from aip_agents.mcp.client.google_adk.client import GoogleADKMCPClient as GoogleADKMCPClient
-from aip_agents.utils.a2a_connector import A2AConnector as A2AConnector
-from aip_agents.utils.logger import get_logger as get_logger
-from collections.abc import AsyncGenerator, AsyncIterator
-from google.adk.agents import LlmAgent
-from google.adk.tools.langchain_tool import LangchainTool
-from langchain.tools import BaseTool as LangchainBaseTool
-from pydantic import BaseModel
-from typing import Any
-
-logger: Incomplete
-MODEL_TEMPERATURE: float
-
-class A2AToolInput(BaseModel):
-    """Input for the A2ATool."""
-    query: str
-
-class A2ATool(LangchainBaseTool):
-    """A tool that communicates with an A2A agent."""
-    name: str
-    description: str
-    args_schema: type[BaseModel]
-    agent_card: AgentCard
-
-def create_a2a_tool(agent_card: AgentCard) -> LangchainTool:
-    """Create a LangChain tool from an A2A agent card.
-
-    Args:
-        agent_card (AgentCard): The A2A agent card to create a tool for.
-
-    Returns:
-        LangchainTool: A LangChain tool that can communicate with the A2A agent.
-    """
-
-class GoogleADKAgent(BaseAgent):
-    """An agent that wraps a native Google ADK Agent with MCP support.
-
-    This class implements the AgentInterface and uses Google's LlmAgent
-    to handle the core conversation and tool execution logic via ADK's
-    async-first design. It includes persistent MCP session management for
-    stateful tool execution across multiple calls.
-
-    The agent supports:
-    - Native ADK tools (FunctionTool, LangchainTool)
-    - MCP tools via GoogleADKMCPClient with session persistence
-    - Sub-agent delegation using ADK's built-in multi-agent capabilities
-    - A2A communication through tool integration
-    """
-    adk_native_agent: LlmAgent
-    model: Incomplete
-    max_iterations: Incomplete
-    tools: Incomplete
-    agents: Incomplete
-    session_service: Incomplete
-    name: Incomplete
-    def __init__(self, name: str, instruction: str, model: str, tools: list[Any] | None = None, description: str | None = None, max_iterations: int = 3, agents: list['GoogleADKAgent'] | None = None, **kwargs: Any) -> None:
-        '''Initializes the GoogleADKAgent with MCP support.
-
-        Args:
-            name: The name of this wrapper agent.
-            instruction: The instruction for this wrapper agent.
-            model: The name of the Google ADK model to use (e.g., "gemini-1.5-pro-latest").
-            tools: An optional list of callable tools for the ADK agent.
-            description: An optional human-readable description.
-            max_iterations: Maximum number of iterations to run (default: 3).
-            agents: Optional list of sub-agents that this agent can delegate to using ADK\'s
-                   built-in multi-agent capabilities. These will be passed as sub_agents to the
-                   underlying LlmAgent.
-            **kwargs: Additional keyword arguments passed to the parent `__init__`.
-        '''
-    def run(self, query: str, **kwargs: Any) -> dict[str, Any]:
-        '''Synchronously runs the Google ADK agent by wrapping the internal async run method.
-
-        Args:
-            query: The input query for the agent.
-            **kwargs: Additional keyword arguments passed to the internal async run method.
-                      Supports "session_id", "user_id", "app_name".
-
-        Returns:
-            A dictionary containing the agent\'s response.
-
-        Raises:
-            RuntimeError: If `asyncio.run()` is called from an already running event loop,
-                          or for other unhandled errors during synchronous execution.
-        '''
-    async def arun(self, query: str, **kwargs: Any) -> dict[str, Any]:
-        '''Asynchronously runs the agent with MCP tool support.
-
-        This method ensures MCP tools are properly initialized before execution
-        and provides persistent session management for stateful MCP tools.
-
-        Args:
-            query: The user\'s query to process.
-            **kwargs: Additional keyword arguments. Supports "session_id", "user_id", "app_name".
-
-        Returns:
-            A dictionary containing the output, tool_calls, and session_id.
-        '''
-    async def cleanup(self) -> None:
-        """Clean up ADK and MCP resources."""
-    async def arun_stream(self, query: str, **kwargs: Any) -> AsyncIterator[str]:
-        '''Runs the agent with the given query and streams the response parts.
-
-        Args:
-            query: The user\'s query to process.
-            **kwargs: Additional keyword arguments. Supports "session_id", "user_id", "app_name".
-
-        Yields:
-            Text response chunks from the model. If an error occurs, the error message is yielded.
-        '''
-    def register_a2a_agents(self, agent_cards: list[AgentCard]) -> None:
-        """Convert known A2A agents to LangChain tools.
-
-        This method takes the agents from a2a_config.known_agents, creates A2AAgent
-        instances for each one, and wraps them in LangChain tools.
-
-        Args:
-            agent_cards (list[AgentCard]): List of A2A agent cards to register as tools.
-
-        Returns:
-            None: The tools are added to the existing tools list.
-        """
-    async def arun_a2a_stream(self, query: str, configurable: dict[str, Any] | None = None, **kwargs: Any) -> AsyncGenerator[dict[str, Any], None]:
-        '''Asynchronously streams the agent\'s response in a format compatible with A2A.
-
-        This method formats the ADK agent\'s streaming responses into a consistent format
-        that the A2A executor can understand and process.
-
-        Args:
-            query: The input query for the agent.
-            configurable: Optional dictionary for configuration, may include:
-                - thread_id: The A2A task ID (used as session_id).
-            **kwargs: Additional keyword arguments. Supports "user_id", "app_name".
-
-        Yields:
-            Dictionary with \'status\' and \'content\' fields that describe the agent\'s response state.
-        '''

aip_agents/agent/google_adk_constants.pyi

@@ -1,3 +0,0 @@
-__all__ = ['DEFAULT_AUTH_URL']
-
-DEFAULT_AUTH_URL: str

aip_agents/agent/hitl/__init__.pyi

@@ -1,6 +0,0 @@
-from aip_agents.agent.hitl.config import ToolApprovalConfig as ToolApprovalConfig
-from aip_agents.agent.hitl.manager import ApprovalManager as ApprovalManager
-from aip_agents.agent.hitl.prompt import BasePromptHandler as BasePromptHandler, DeferredPromptHandler as DeferredPromptHandler
-from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalLogEntry as ApprovalLogEntry, ApprovalRequest as ApprovalRequest
-
-__all__ = ['ToolApprovalConfig', 'ApprovalManager', 'ApprovalDecision', 'ApprovalLogEntry', 'ApprovalRequest', 'BasePromptHandler', 'DeferredPromptHandler']

aip_agents/agent/hitl/config.pyi

@@ -1,15 +0,0 @@
-from dataclasses import dataclass
-
-@dataclass
-class ToolApprovalConfig:
-    """Configuration for HITL approval behavior attached to a tool.
-
-    Supplying this configuration marks the tool as requiring approval. Only the
-    timeout is configurable; timeouts always result in a safe skip.
-
-    Attributes:
-        timeout_seconds: Defaults to 300; must be >0.
-    """
-    timeout_seconds: int = ...
-    def __post_init__(self) -> None:
-        """Validate configuration after initialization."""

aip_agents/agent/hitl/langgraph_hitl_mixin.pyi

@@ -1,42 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.agent.hitl.config import ToolApprovalConfig as ToolApprovalConfig
-from aip_agents.agent.hitl.manager import ApprovalManager as ApprovalManager
-from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalRequest as ApprovalRequest, HitlMetadata as HitlMetadata
-from aip_agents.schema.langgraph import ToolCallResult as ToolCallResult
-from aip_agents.tools.tool_config_injector import TOOL_CONFIGS_KEY as TOOL_CONFIGS_KEY
-from aip_agents.utils.datetime import ensure_utc_datetime as ensure_utc_datetime
-from aip_agents.utils.logger import get_logger as get_logger
-from collections.abc import Callable
-from typing import Any
-
-logger: Incomplete
-MAX_CONTEXT_MESSAGE_LENGTH: int
-
-class LangGraphHitLMixin:
-    """Provide Human-in-the-Loop helpers for LangGraph agents."""
-    tool_configs: dict[str, Any] | None
-    name: str
-    @property
-    def hitl_manager(self) -> ApprovalManager | None:
-        """Return the active ``ApprovalManager``, creating one if needed."""
-    @hitl_manager.setter
-    def hitl_manager(self, manager: ApprovalManager | None) -> None:
-        """Set the HITL approval manager instance.
-
-        Args:
-            manager: ApprovalManager instance or None.
-        """
-    def ensure_hitl_manager(self) -> ApprovalManager | None:
-        """Ensure an ``ApprovalManager`` exists when HITL configs are present."""
-    def use_hitl_manager(self, manager: ApprovalManager) -> None:
-        """Replace the current ``ApprovalManager`` with the supplied instance.
-
-        Args:
-            manager: The ApprovalManager instance to use for HITL approvals.
-        """
-    def register_hitl_notifier(self, notifier: Callable[[ApprovalRequest], None]) -> None:
-        """Register a notifier callback to receive HITL approval requests.
-
-        Args:
-            notifier: Callback function that will be called with approval requests.
-        """

aip_agents/agent/hitl/manager.pyi

@@ -1,200 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.agent.hitl.config import ToolApprovalConfig as ToolApprovalConfig
-from aip_agents.agent.hitl.prompt import BasePromptHandler as BasePromptHandler, DeferredPromptHandler as DeferredPromptHandler
-from aip_agents.agent.hitl.registry import hitl_registry as hitl_registry
-from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalLogEntry as ApprovalLogEntry, ApprovalRequest as ApprovalRequest
-from collections.abc import Callable as Callable, Iterable
-from typing import Any
-
-MAX_ARGUMENTS_PREVIEW_LENGTH: int
-DECISION_MESSAGE_MAP: Incomplete
-TOOL_EXECUTION_BLOCKING_DECISIONS: Incomplete
-
-class ApprovalManager:
-    """Manages the HITL approval workflow for tools.
-
-    This class coordinates the approval process from configuration through
-    to final decision, handling timeouts and cleanup.
-    """
-    def __init__(self, prompt_handler: BasePromptHandler | None = None) -> None:
-        """Initialize the approval manager.
-
-        Args:
-            prompt_handler: Optional prompt handler for user interaction.
-                Defaults to DeferredPromptHandler which exposes pending requests
-                for out-of-band resolution.
-        """
-    def create_approval_request(self, tool_name: str, arguments: dict[str, Any], config: ToolApprovalConfig, context: dict[str, str] | None = None) -> ApprovalRequest:
-        """Create a new approval request for a tool call.
-
-        Args:
-            tool_name: Name of the tool being called.
-            arguments: Tool arguments (will be JSON serialized).
-            config: Approval configuration for this tool.
-            context: Optional context metadata. Defaults to None.
-
-        Returns:
-            The created approval request.
-        """
-    def get_pending_request(self, request_id: str) -> ApprovalRequest | None:
-        """Get a pending approval request by ID.
-
-        Args:
-            request_id: The unique identifier of the approval request.
-
-        Returns:
-            The pending approval request if found, None otherwise.
-        """
-    def approve_request(self, request: ApprovalRequest, operator_input: str = 'approved') -> ApprovalDecision:
-        '''Record an approval decision for a request.
-
-        This method creates an approval decision, calculates latency metrics,
-        and removes the request from the active requests queue.
-
-        Args:
-            request: The approval request to approve.
-            operator_input: Raw operator input that led to this decision. Defaults to "approved".
-
-        Returns:
-            The recorded approval decision.
-        '''
-    def reject_request(self, request: ApprovalRequest, operator_input: str = 'rejected') -> ApprovalDecision:
-        '''Record a rejection decision for a request.
-
-        This method creates a rejection decision, calculates latency metrics,
-        and removes the request from the active requests queue.
-
-        Args:
-            request: The approval request to reject.
-            operator_input: Raw operator input that led to this decision. Defaults to "rejected".
-
-        Returns:
-            The recorded rejection decision.
-        '''
-    def skip_request(self, request: ApprovalRequest, operator_input: str = 'skipped') -> ApprovalDecision:
-        '''Record a skip decision for a request.
-
-        This method creates a skip decision, calculates latency metrics,
-        and removes the request from the active requests queue.
-
-        Args:
-            request: The approval request to skip.
-            operator_input: Raw operator input that led to this decision. Defaults to "skipped".
-
-        Returns:
-            The recorded skip decision.
-        '''
-    def timeout_request(self, request: ApprovalRequest, operator_input: str = 'TIMEOUT') -> ApprovalDecision:
-        '''Record a timeout decision for a request, always skipping the tool.
-
-        Args:
-            request (ApprovalRequest): The approval request that timed out.
-            operator_input (str, optional): Input from the operator (defaults to "TIMEOUT").
-
-        Returns:
-            ApprovalDecision: The timeout decision.
-        '''
-    def check_timeout(self, request: ApprovalRequest) -> ApprovalDecision | None:
-        """Check if a request has timed out and return timeout decision if so.
-
-        Args:
-            request: The approval request to check.
-
-        Returns:
-            Timeout decision if timed out, None otherwise.
-        """
-    async def prompt_for_decision(self, request: ApprovalRequest, timeout_seconds: int, context_keys: list[str] | None = None) -> ApprovalDecision:
-        """Prompt for a decision using the configured handler.
-
-        This method delegates to the configured prompt handler to obtain
-        an approval decision from the operator. The handler may be interactive
-        (CLI) or deferred (programmatic, resume-in-place).
-
-        Args:
-            request: The approval request to prompt for.
-            timeout_seconds: How long to wait for input.
-            context_keys: Optional keys to display from context. Defaults to None.
-
-        Returns:
-            The operator's decision on the request.
-        """
-    def list_pending_requests(self) -> Iterable[ApprovalRequest]:
-        """Return a snapshot of currently pending requests.
-
-        This method provides a thread-safe snapshot of all currently active
-        approval requests that are waiting for operator decisions.
-
-        Returns:
-            An iterable of all pending approval requests.
-        """
-    def resolve_pending_request(self, request_id: str, decision: str, operator_input: str = '') -> ApprovalDecision:
-        '''Resolve a pending request with an explicit decision.
-
-        Args:
-            request_id: The unique identifier of the pending approval request.
-            decision: The decision string (e.g., "approved", "rejected", "skipped").
-            operator_input: Optional raw operator input, defaults to the decision string. Defaults to "".
-
-        Returns:
-            The recorded approval decision.
-
-        Raises:
-            KeyError: If no pending request exists with the given request_id.
-            ValueError: If the decision string is not supported.
-        '''
-    def create_log_entry(self, decision: ApprovalDecision, tool_name: str, agent_id: str | None = None, thread_id: str | None = None, additional_context: dict[str, Any] | None = None) -> ApprovalLogEntry:
-        """Create a log entry for a decision.
-
-        Args:
-            decision: The approval decision.
-            tool_name: Name of the tool.
-            agent_id: Optional agent identifier. Defaults to None.
-            thread_id: Optional thread/session identifier. Defaults to None.
-            additional_context: Optional additional logging context. Defaults to None.
-
-        Returns:
-            Structured log entry.
-        """
-    def cleanup_expired_requests(self) -> int:
-        """Clean up expired requests and return count of cleaned requests.
-
-        This method removes all approval requests that have exceeded their
-        timeout period from the active requests queue. This is typically
-        called periodically to prevent memory leaks from abandoned requests.
-
-        Returns:
-            The number of expired requests that were cleaned up.
-        """
-    def register_waiter(self, request_id: str, future: Any) -> None:
-        """Register a waiter future for an approval request.
-
-        Args:
-            request_id: The id for which to wait.
-            future: An asyncio.Future that will receive a tuple(decision, operator_input).
-        """
-    def unregister_waiter(self, request_id: str) -> None:
-        """Unregister a waiter if present (used on timeout/cancellation).
-
-        Args:
-            request_id (str): The ID of the request to unregister the waiter for.
-        """
-    async def wait_for_pending_decision(self, request: ApprovalRequest, timeout_seconds: int) -> ApprovalDecision:
-        """Wait for a pending request to be resolved and return the final decision.
-
-        Args:
-            request: The pending approval request to wait for.
-            timeout_seconds: Maximum time to wait before treating as timeout.
-
-        Returns:
-            The finalized approval decision.
-        """
-    @staticmethod
-    def get_decision_message(decision: ApprovalDecision) -> str:
-        """Get the appropriate message for a HITL decision.
-
-        Args:
-            decision: The approval decision to get a message for.
-
-        Returns:
-            A human-readable message explaining the decision outcome.
-        """

aip_agents/agent/hitl/models.pyi

@@ -1,3 +0,0 @@
-from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalLogEntry as ApprovalLogEntry, ApprovalRequest as ApprovalRequest
-
-__all__ = ['ApprovalDecisionType', 'ApprovalRequest', 'ApprovalDecision', 'ApprovalLogEntry']

aip_agents/agent/hitl/prompt/__init__.pyi

@@ -1,4 +0,0 @@
-from aip_agents.agent.hitl.prompt.base import BasePromptHandler as BasePromptHandler
-from aip_agents.agent.hitl.prompt.deferred import DeferredPromptHandler as DeferredPromptHandler
-
-__all__ = ['BasePromptHandler', 'DeferredPromptHandler']

aip_agents/agent/hitl/prompt/base.pyi

@@ -1,24 +0,0 @@
-from abc import ABC, abstractmethod
-from aip_agents.agent.hitl.manager import ApprovalManager as ApprovalManager
-from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalRequest as ApprovalRequest
-
-class BasePromptHandler(ABC):
-    """Abstract base class for prompt handlers used in HITL flows."""
-    def attach_manager(self, manager: ApprovalManager) -> None:
-        """Optionally attach the ``ApprovalManager`` coordinating approvals.
-
-        Args:
-            manager (ApprovalManager): The approval manager instance to attach.
-        """
-    @abstractmethod
-    async def prompt_for_decision(self, request: ApprovalRequest, timeout_seconds: int, context_keys: list[str] | None = None) -> ApprovalDecision:
-        """Collect and return a decision for the given approval request.
-
-        Args:
-            request (ApprovalRequest): The approval request to prompt for.
-            timeout_seconds (int): Maximum time to wait for a decision in seconds.
-            context_keys (list[str] | None, optional): Optional keys for additional context. Defaults to None.
-
-        Returns:
-            ApprovalDecision: The decision made for the approval request.
-        """

aip_agents/agent/hitl/prompt/deferred.pyi

@@ -1,30 +0,0 @@
-from aip_agents.agent.hitl.manager import ApprovalManager as ApprovalManager
-from aip_agents.agent.hitl.prompt.base import BasePromptHandler as BasePromptHandler
-from aip_agents.schema.hitl import ApprovalDecision as ApprovalDecision, ApprovalDecisionType as ApprovalDecisionType, ApprovalRequest as ApprovalRequest
-from collections.abc import Callable
-
-class DeferredPromptHandler(BasePromptHandler):
-    """Prompt handler that defers tool execution until an external decision is received."""
-    def __init__(self, notify: Callable[[ApprovalRequest], None] | None = None) -> None:
-        """Initialize the deferred prompt handler.
-
-        Args:
-            notify: Optional callback function to notify when an approval request is made.
-        """
-    def attach_manager(self, manager: ApprovalManager) -> None:
-        """Attach the ApprovalManager orchestrating approvals.
-
-        Args:
-            manager: The ApprovalManager instance to attach for handling approval decisions.
-        """
-    async def prompt_for_decision(self, request: ApprovalRequest, timeout_seconds: int, context_keys: list[str] | None = None) -> ApprovalDecision:
-        """Register a waiter and return a pending decision sentinel.
-
-        Args:
-            request: The approval request containing the tool call details and context.
-            timeout_seconds: Number of seconds to wait for approval before timing out.
-            context_keys: Optional list of context keys to include in the approval request.
-
-        Returns:
-            ApprovalDecision with PENDING status and registered waiter for external resolution.
-        """

aip_agents/agent/hitl/registry.pyi

@@ -1,101 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.agent.hitl.manager import ApprovalManager as 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")
-    '''
-    def __new__(cls) -> HITLManagerRegistry:
-        """Ensure only one instance exists (singleton pattern).
-
-        Returns:
-            The singleton HITLManagerRegistry 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)
-        '''
-    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")
-        '''
-    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")
-        '''
-    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
-        """
-    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}")
-        '''
-
-hitl_registry: Incomplete

aip_agents/agent/interface.pyi

@@ -1,81 +0,0 @@
-from a2a.types import AgentCard as AgentCard
-from abc import ABC, abstractmethod
-from aip_agents.schema.agent import BaseAgentConfig as BaseAgentConfig
-from collections.abc import AsyncGenerator
-from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
-from typing import Any
-
-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
-    config: BaseAgentConfig | None
-    def __init__(self, name: str, instruction: str, description: str | None = None, lm_invoker: BaseLMInvoker | None = None, config: BaseAgentConfig | None = None, **kwargs: Any) -> None:
-        """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.
-        """
-    @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': ...}.
-        """
-    @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': ...}.
-        """
-    @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).
-        """
-    @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.
-        """
-    @abstractmethod
-    def register_a2a_agents(self, agents: list[AgentCard]):
-        """Registers A2A agents from a list of AgentCards.
-
-        Args:
-            agents: A list of AgentCard instances.
-        """