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

aip_agents/agent/base_agent.py

@@ -0,0 +1,1437 @@
+"""Base class for concrete agent implementations.
+
+This class provides common functionalities like A2A client capabilities.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import asyncio
+from collections.abc import AsyncGenerator, Mapping
+from contextvars import ContextVar
+from importlib import import_module
+from pathlib import Path
+from types import MethodType
+from typing import Any
+from warnings import warn
+
+import httpx
+from a2a.server.apps import A2AStarletteApplication
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.types import AgentCard
+from gllm_core.schema import Tool as GLLMTool
+from gllm_core.utils.retry import RetryConfig
+from gllm_inference.lm_invoker.build_lm_invoker import build_lm_invoker
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+from gllm_inference.schema import ThinkingConfig
+
+try:
+    from gllm_inference.schema import Thinking
+except ImportError:  # pragma: no cover
+    from gllm_inference.schema import Reasoning as Thinking  # pragma: no cover
+from gllm_inference.schema.enums import OutputTransformerType
+from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
+from starlette.applications import Starlette
+
+from aip_agents.agent.interface import AgentInterface
+from aip_agents.agent.model_invocation_adapter import LMInvokerRuntimePolicy
+from aip_agents.credentials.manager import CredentialsManager
+from aip_agents.mcp.client.base_mcp_client import BaseMCPClient
+from aip_agents.schema.agent import A2AClientConfig, AgentConfig, BaseAgentConfig, CredentialType
+from aip_agents.schema.model_id import ModelId, ModelProvider
+from aip_agents.utils.a2a_connector import A2AConnector
+from aip_agents.utils.logger import get_logger
+from aip_agents.utils.name_preprocessor.name_preprocessor import NamePreprocessor
+
+logger = get_logger(__name__)
+
+
+def _get_agent_executor_mapping() -> dict[str, str]:
+    """Map agent class names to their executor import paths."""
+    return {
+        "LangGraphReactAgent": "aip_agents.a2a.server.langgraph_executor.LangGraphA2AExecutor",
+        "LangGraphAgent": "aip_agents.a2a.server.langgraph_executor.LangGraphA2AExecutor",
+        "LangChainAgent": "aip_agents.a2a.server.langgraph_executor.LangGraphA2AExecutor",
+        "LangflowAgent": "aip_agents.a2a.server.langflow_executor.LangflowA2AExecutor",
+        "GoogleADKAgent": "aip_agents.a2a.server.google_adk_executor.GoogleADKExecutor",
+    }
+
+
+AGENT_EXECUTOR_MAPPING = _get_agent_executor_mapping()
+
+
+def _load_executor_class(candidate: Any) -> type[Any]:
+    """Resolve an executor class from a dotted path or a direct reference.
+
+    Args:
+        candidate (Any): Either a string path (e.g., "module.Class") or a class/type object.
+
+    Returns:
+        type[Any]: The resolved executor class.
+    """
+    if isinstance(candidate, str):
+        module_name, class_name = candidate.rsplit(".", 1)
+        module = import_module(module_name)
+        return getattr(module, class_name)
+
+    if isinstance(candidate, type):  # Already a class reference
+        return candidate
+
+    if callable(candidate):
+        return candidate  # type: ignore[return-value]
+
+    raise TypeError(f"Unsupported executor mapping entry: {candidate!r}")
+
+
+def _get_executor_class_for_agent(agent: "BaseAgent") -> type[Any]:
+    """Resolve the appropriate executor class for the given agent instance.
+
+    Args:
+        agent (BaseAgent): The agent instance to find an executor for.
+
+    Returns:
+        type[Any]: The appropriate executor class for the agent.
+    """
+    for cls in agent.__class__.__mro__:
+        executor_path = AGENT_EXECUTOR_MAPPING.get(cls.__name__)
+        if executor_path:
+            return _load_executor_class(executor_path)
+    raise KeyError(f"No A2A executor registered for agent class '{agent.__class__.__name__}'")
+
+
+DEFAULT_RETRY_CONFIG = RetryConfig(max_retries=5, timeout=240.0)
+
+LM_EXCLUDE_FIELDS = {
+    "a2ui",
+    "lm_base_url",
+    "lm_api_key",
+    "lm_name",
+    "lm_provider",
+    "lm_hyperparameters",
+    "lm_retry_config",
+    "lm_credentials",
+}
+
+CUSTOM_PROVIDERS = {
+    "openai-compatible/": ModelProvider.OPENAI_COMPATIBLE,
+    "azure-openai/": ModelProvider.AZURE_OPENAI,
+}
+
+OPENAI_COMPATIBLE_PREFIX = "openai-compatible/"
+OPENAI_CHAT_COMPLETIONS_PROVIDER = "openai-chat-completions"
+
+OUTPUT_ANALYTICS_KEY = "output_analytics"
+OUTPUT_TRANSFORMER_KEY = "output_transformer"
+ANTHROPIC_PROMPT_CACHE_CONFIG_KEY = "anthropic_prompt_cache"
+CACHE_CONTROL_KEY = "cache_control"
+_AIP_ANTHROPIC_CACHE_USAGE = ContextVar("aip_anthropic_cache_usage", default=None)
+DEFAULT_ANTHROPIC_CACHE_CONTROL = {"type": "ephemeral"}
+
+
+def _thinking_text(thinking: Thinking) -> str:
+    """Return reasoning text across Thinking/Reasoning schema variants."""
+    return str(getattr(thinking, "thinking", getattr(thinking, "reasoning", "")) or "")
+
+
+def _make_thinking(*, id_value: str, thinking_value: str) -> Thinking:
+    """Build a Thinking/Reasoning object across gllm-inference schema variants."""
+    fields = getattr(Thinking, "model_fields", {})
+    if "thinking" in fields:
+        return Thinking(id=id_value, thinking=thinking_value)
+    return Thinking(id=id_value, reasoning=thinking_value)  # pragma: no cover
+
+
+def _reasoning_block_text(block: Any) -> str:
+    """Extract reasoning text from OpenAI summary/content blocks."""
+    if isinstance(block, dict):
+        value = block.get("text", "")  # pragma: no cover
+    else:
+        value = getattr(block, "text", "")
+    return value if isinstance(value, str) else ""
+
+
+def _is_enabled_reasoning_invocation(invoker_self: Any) -> bool:
+    """Return whether runtime thinking is enabled on an invoker instance."""
+    return bool(getattr(getattr(invoker_self, "thinking", None), "enabled", False))
+
+
+def _existing_thinking_keys(output: Any) -> set[tuple[str, str]]:
+    """Build a stable key set for already-added reasoning blocks."""
+    return {
+        (str(getattr(thinking, "id", "") or ""), _thinking_text(thinking))
+        for thinking in (getattr(output, "thinkings", None) or [])
+    }
+
+
+def _reasoning_blocks(item: Any) -> list[Any]:
+    """Return OpenAI reasoning summary/content blocks as a flat list."""
+    return [
+        *(getattr(item, "summary", None) or []),
+        *(getattr(item, "content", None) or []),
+    ]
+
+
+def _recover_reasoning_thinkings(item: Any, output: Any) -> list[Thinking]:
+    """Recover non-duplicate reasoning thinkings from OpenAI reasoning items."""
+    if getattr(item, "type", None) != "reasoning":
+        return []  # pragma: no cover
+
+    item_id = str(getattr(item, "id", "") or "")
+    seen = _existing_thinking_keys(output)
+    recovered: list[Thinking] = []
+
+    for block in _reasoning_blocks(item):
+        text = _reasoning_block_text(block)
+        if not text.strip():
+            continue  # pragma: no cover
+
+        key = (item_id, text)
+        if key in seen:
+            continue
+
+        seen.add(key)
+        recovered.append(_make_thinking(id_value=item_id, thinking_value=text))
+
+    return recovered
+
+
+def _build_openai_reasoning_patch(original_process_thinkings: Any) -> Any:
+    """Build an instance-method wrapper for OpenAI reasoning extraction."""
+
+    def _patched_process_thinkings(invoker_self: Any, item: Any, output: Any) -> None:
+        original_process_thinkings(item, output)
+
+        if not _is_enabled_reasoning_invocation(invoker_self):
+            return  # pragma: no cover
+
+        recovered = _recover_reasoning_thinkings(item, output)
+        if recovered:
+            output.add_thinking(recovered)
+
+    return _patched_process_thinkings
+
+
+def _anthropic_usage_int(usage: Any, attr: str) -> int:
+    return int(getattr(usage, attr, 0) or 0)
+
+
+def _anthropic_cache_creation_tokens(usage: Any) -> int:
+    direct = _anthropic_usage_int(usage, "cache_creation_input_tokens")
+    cache_creation = getattr(usage, "cache_creation", None)
+    return direct or (
+        _anthropic_usage_int(cache_creation, "ephemeral_5m_input_tokens")
+        + _anthropic_usage_int(cache_creation, "ephemeral_1h_input_tokens")
+    )
+
+
+def _anthropic_cache_input_details(usage: Any) -> dict[str, int]:
+    creation_tokens = _anthropic_cache_creation_tokens(usage)
+    read_tokens = _anthropic_usage_int(usage, "cache_read_input_tokens")
+    if not creation_tokens and not read_tokens:
+        return {}
+    return {
+        "cache_creation_input_tokens": creation_tokens,
+        "cache_read_input_tokens": read_tokens,
+        "cached_tokens": read_tokens,
+    }
+
+
+def _detail_values(detail: Any) -> dict[str, int]:
+    if detail is None:
+        return {}
+    if isinstance(detail, dict):
+        return {str(key): int(value or 0) for key, value in detail.items() if isinstance(value, int | float)}
+    if hasattr(detail, "model_dump"):
+        dumped = detail.model_dump()
+        if isinstance(dumped, dict):
+            return {str(key): int(value or 0) for key, value in dumped.items() if isinstance(value, int | float)}
+    if hasattr(detail, "__dict__") and isinstance(detail.__dict__, dict):
+        return {str(key): int(value or 0) for key, value in detail.__dict__.items() if isinstance(value, int | float)}
+    return {}
+
+
+def _merge_anthropic_cache_usage(output: Any, raw_usage: Any) -> None:
+    cache_details = _anthropic_cache_input_details(raw_usage)
+    if not cache_details:
+        return
+
+    token_usage = getattr(output, "token_usage", None)
+    if isinstance(token_usage, dict):
+        input_tokens = int(token_usage.get("input_tokens", 0) or 0)
+        output_tokens = int(token_usage.get("output_tokens", 0) or 0)
+        input_details = _detail_values(token_usage.get("input_token_details"))
+        output_details = _detail_values(token_usage.get("output_token_details"))
+    else:
+        input_tokens = int(getattr(token_usage, "input_tokens", 0) or 0)
+        output_tokens = int(getattr(token_usage, "output_tokens", 0) or 0)
+        input_details = _detail_values(getattr(token_usage, "input_token_details", None))
+        output_details = _detail_values(getattr(token_usage, "output_token_details", None))
+
+    input_details.update(cache_details)
+    patched_usage: dict[str, Any] = {
+        "input_tokens": input_tokens,
+        "output_tokens": output_tokens,
+        "input_token_details": input_details,
+    }
+    if output_details:
+        patched_usage["output_token_details"] = output_details
+    output.token_usage = patched_usage
+
+
+class BaseAgent(AgentInterface):
+    """Base class for agents, providing common A2A client method implementations.
+
+    Concrete agent implementations (e.g., LangGraphAgent, GoogleADKAgent)
+    should inherit from this class if they need to utilize the shared A2A
+    client functionalities.
+
+    This class now supports flexible model handling:
+    - model: Optional[Any] - can be an lm_invoker, string/ModelId, LangChain BaseChatModel, or other types
+    - Automatically sets self.lm_invoker if an lm_invoker is provided or can be built
+    - Stores the original model in self.model for subclass use
+    - Enhanced credential support with automatic type detection
+    """
+
+    def __init__(  # noqa: PLR0913
+        self,
+        name: str,
+        instruction: str,
+        description: str | None = None,
+        model: Any | None = None,
+        tools: list[Any] | None = None,
+        config: BaseAgentConfig | dict[str, Any] | None = None,
+        tool_configs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ):
+        """Initializes the BaseAgent.
+
+        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.
+            model: The model to use. Can be:
+                - BaseLMInvoker instance (will be set as self.lm_invoker)
+                - String or ModelId (will build an lm_invoker)
+                - LangChain BaseChatModel (will be stored in self.model)
+                - Any other type (will be stored in self.model)
+            tools: List of tools available to the agent.
+            config: Additional configuration for the agent. Can be a BaseAgentConfig instance or dict.
+            tool_configs: Default tool configurations applied to all tool calls from this agent.
+            **kwargs: Additional keyword arguments for AgentInterface.
+        """
+        # Convert config to BaseAgentConfig if it's a dict (backward compatibility)
+        processed_config = self._process_config(config, tools)
+
+        # Process model parameter to set up lm_invoker and model attributes
+        processed_lm_invoker, processed_model = self._process_model_parameter(
+            name, model, tools or [], processed_config
+        )
+
+        # Pass the lm_invoker to the parent class
+        super().__init__(
+            name=name,
+            instruction=instruction,
+            description=description,
+            lm_invoker=processed_lm_invoker,
+            config=processed_config,
+            **kwargs,
+        )
+
+        # Store processed model and other attributes
+        self.model = processed_model
+        self.tools = tools or []
+        # Private MCP configuration to prevent tampering and maintain sync
+        self._mcp_config: dict[str, dict[str, Any]] = {}
+        self.tool_configs = tool_configs or {}
+
+        self._mcp_tools_initialized: bool = False
+        self.mcp_client: BaseMCPClient | None = None
+        self._mcp_init_lock: asyncio.Lock = asyncio.Lock()
+
+        self.name_preprocessor = self.get_name_preprocessor()
+
+    def get_name_preprocessor(self) -> NamePreprocessor:
+        """Get the name preprocessor based on the provider.
+
+        This will be used to correct the agent name and tool name. (mostly tool name)
+
+        Returns:
+            NamePreprocessor: The name preprocessor for the model.
+        """
+        return NamePreprocessor(self.model_provider)
+
+    @property
+    def model_provider(self) -> str:
+        """Get the provider of the model with simplified logic.
+
+        Returns:
+            str: The provider of the model.
+        """
+        if hasattr(self, "lm_invoker") and self.lm_invoker is not None:
+            return self.lm_invoker.model_provider
+
+        if hasattr(self, "model") and self.model is not None:
+            return self._detect_provider_from_model(self.model)
+
+        return "unknown"
+
+    def _detect_provider_from_model(self, model: Any) -> str:
+        """Detect provider from model object.
+
+        Args:
+            model: The model object.
+
+        Returns:
+            str: The provider of the model.
+        """
+        if isinstance(model, str):
+            return self._detect_provider_from_string(model)
+
+        if hasattr(model, "__class__"):
+            return self._detect_provider_from_class(model.__class__.__name__)
+
+        return "unknown"
+
+    def _detect_provider_from_string(self, model_str: str) -> str:
+        """Detect provider from model string.
+
+        Args:
+            model_str: The model string.
+
+        Returns:
+            str: The provider of the model.
+        """
+        model_lower = model_str.lower()
+
+        if model_lower.startswith(("gemini", "google")):
+            return "google"
+
+        if "/" in model_str:
+            return model_str.split("/")[0]
+        if ":" in model_str:
+            return model_str.split(":")[0]
+        return model_str
+
+    def _detect_provider_from_class(self, class_name: str) -> str:
+        """Detect provider from class name.
+
+        Args:
+            class_name: The class name.
+
+        Returns:
+            str: The provider of the model.
+        """
+        class_name_lower = class_name.lower()
+
+        provider_mappings = {"openai": "openai", "google": "google", "vertex": "google", "anthropic": "anthropic"}
+
+        for keyword, provider in provider_mappings.items():
+            if keyword in class_name_lower:
+                return provider
+
+        return "unknown"
+
+    def _process_config(
+        self, config: BaseAgentConfig | dict[str, Any] | None, tools: list[Any] | None = None
+    ) -> BaseAgentConfig | None:
+        """Process config parameter to ensure it's a BaseAgentConfig instance.
+
+        Args:
+            config: Configuration parameter that can be dict, BaseAgentConfig, or None.
+            tools: List of tools to include in config if not already present.
+
+        Returns:
+            BaseAgentConfig instance or None.
+        """
+        if config is None:
+            if tools:
+                return AgentConfig(tools=tools)
+            return None
+
+        if isinstance(config, BaseAgentConfig):
+            if tools and not config.tools:
+                config.tools = tools
+            return config
+
+        if isinstance(config, dict):
+            config_dict = config.copy()
+
+            if tools and "tools" not in config_dict:
+                config_dict["tools"] = tools
+
+            if "lm_hyperparameters" in config_dict and "default_hyperparameters" not in config_dict:
+                config_dict["default_hyperparameters"] = config_dict.pop("lm_hyperparameters")
+
+            return AgentConfig(**config_dict)
+
+        raise TypeError(f"Config must be BaseAgentConfig, dict, or None, got {type(config)}")
+
+    def _extract_credentials_from_config(
+        self, config: BaseAgentConfig | None
+    ) -> tuple[CredentialType, str | dict[str, Any] | None]:
+        """Extract and auto-detect credentials from config with ultra-simple logic.
+
+        This method supports multiple credential formats with automatic type detection:
+        - New lm_credentials field: Auto-detects type based on content
+        - Legacy lm_api_key field: For backward compatibility
+
+        Auto-detection logic:
+        - Dict: Passed through as-is (CredentialType.DICT)
+        - String + file exists: Treated as file path (CredentialType.FILE)
+        - String + file doesn't exist: Treated as API key (CredentialType.API_KEY)
+
+        Args:
+            config: Configuration object.
+
+        Returns:
+            Tuple containing:
+                - credential_type: CredentialType enum value
+                - credentials: The extracted credentials or None if not found
+        """
+        if not config:
+            return CredentialType.API_KEY, None
+
+        if hasattr(config, "lm_credentials") and config.lm_credentials is not None:
+            detected_type, formatted_creds = self._auto_detect_credential_type(config.lm_credentials)
+            return detected_type, formatted_creds
+
+        if hasattr(config, "lm_api_key") and config.lm_api_key:
+            warn(
+                (
+                    "The lm_api_key is deprecated as of version 0.5.0. "
+                    "Use lm_credentials instead which supports auto-detection of API keys, "
+                    "file paths, and dictionary credentials."
+                ),
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            return CredentialType.API_KEY, config.lm_api_key
+
+        return CredentialType.API_KEY, None
+
+    def _auto_detect_credential_type(self, credentials: Any) -> tuple[CredentialType, Any]:
+        """Automatically detect credential type using simple file existence rules.
+
+        This method uses ultra-simple detection logic:
+        1. If credentials is dict -> CredentialType.DICT (Bedrock, LangChain credentials)
+        2. If credentials is string and exists on disk -> CredentialType.FILE
+        3. Everything else -> CredentialType.API_KEY (simple fallback)
+
+        Args:
+            credentials: Raw credentials from config.
+
+        Returns:
+            Tuple containing:
+                - credential_type: CredentialType enum value
+                - formatted_credentials: The credentials in the detected format
+        """
+        if isinstance(credentials, dict):
+            return CredentialType.DICT, credentials
+
+        if isinstance(credentials, str):
+            if not credentials.strip():
+                return CredentialType.API_KEY, credentials
+
+            try:
+                path = Path(credentials)
+                if path.exists():
+                    return CredentialType.FILE, credentials
+            except (ValueError, OSError):
+                pass
+
+            return CredentialType.API_KEY, credentials
+
+        return CredentialType.API_KEY, str(credentials)
+
+    @property
+    def mcp_config(self) -> dict[str, dict[str, Any]]:
+        """Read-only view of MCP configuration.
+
+        Returns a copy to prevent direct mutation; use add_mcp_server() for changes.
+        """
+        return self._mcp_config.copy()
+
+    @mcp_config.setter
+    def mcp_config(self, value: dict[str, dict[str, Any]]) -> None:
+        """Set MCP configuration and maintain synchronization.
+
+        Automatically resets initialization flag and recreates client to ensure consistency.
+        Prefer using add_mcp_server() for proper validation.
+
+        Args:
+            value (dict[str, dict[str, Any]]): The MCP configuration to set.
+        """
+        if not isinstance(value, dict):
+            raise ValueError("mcp_config must be a dict[str, dict[str, Any]]")
+        self._mcp_config = value.copy()
+        # Reset flag and recreate client object to maintain sync. This is lightweight
+        # (no connections created) and safe to perform synchronously. Actual session
+        # initialization remains lazy in the event loop via _ensure_mcp_tools_initialized().
+        self._mcp_tools_initialized = False
+        if self._mcp_config:
+            self._initialize_mcp_client()
+        else:
+            # Clear client for empty config
+            self.mcp_client = None
+
+    def _get_credentials(self, model: str | ModelId, config: BaseAgentConfig | None) -> str | dict[str, Any] | None:
+        """Get credentials for the model with enhanced type support.
+
+        This method now supports multiple credential formats through the new
+        _extract_credentials_from_config method while maintaining backward compatibility.
+
+        Args:
+            model: Model identifier.
+            config: Configuration object.
+
+        Returns:
+            Credentials if found, None otherwise. Can be:
+            - str: For API keys or file paths
+            - dict: For structured credentials (Bedrock, LangChain)
+        """
+        credentials = None
+
+        if config:
+            _, credentials = self._extract_credentials_from_config(config)
+
+        if not credentials:
+            credentials = CredentialsManager.get_credentials(model)
+
+        return credentials
+
+    def _extract_retry_config(self, config: BaseAgentConfig | None, use_default: bool = True) -> RetryConfig | None:
+        """Extract and process retry config from agent config.
+
+        Args:
+            config: Configuration object.
+            use_default: If True, return a default RetryConfig when none is found.
+
+        Returns:
+            RetryConfig instance if found, default RetryConfig if use_default=True and none found, None otherwise.
+        """
+        if config and isinstance(config, AgentConfig) and config.lm_retry_config:
+            if isinstance(config.lm_retry_config, dict):
+                return RetryConfig(**config.lm_retry_config)
+            return config.lm_retry_config
+
+        if use_default:
+            return DEFAULT_RETRY_CONFIG
+
+        return None
+
+    def _update_config_with_tools(
+        self, tools: list[Any], config: BaseAgentConfig | None = None
+    ) -> dict[str, Any] | None:
+        """Update config with tools if not already present and convert to dict for lm_invoker.
+
+        Args:
+            tools: List of tools.
+            config: Configuration object.
+
+        Returns:
+            Configuration dictionary for lm_invoker.
+        """
+        lm_invoker_tools = self._prepare_tools_for_lm_invoker(tools)
+
+        if config is None:
+            config_dict = {"tools": lm_invoker_tools} if lm_invoker_tools else {}
+            config_dict["retry_config"] = self._extract_retry_config(config)
+            return config_dict
+
+        # Convert BaseAgentConfig to dict, excluding LM-specific fields
+        config_dict = config.model_dump(
+            exclude_none=True,
+            exclude=LM_EXCLUDE_FIELDS,
+        )
+        # Preserve extra config objects such as gllm ThinkingConfig; model_dump()
+        # serializes extras to dicts, but build_lm_invoker expects the original objects.
+        if getattr(config, "model_extra", None):
+            config_dict.update(config.model_extra or {})
+        if isinstance(config, AgentConfig) and config.lm_hyperparameters:
+            config_dict["default_hyperparameters"] = config.lm_hyperparameters
+
+        config_dict["retry_config"] = self._extract_retry_config(config)
+
+        if lm_invoker_tools:
+            config_dict["tools"] = lm_invoker_tools
+
+        return config_dict if config_dict else None
+
+    @staticmethod
+    def _resolve_tool_func(tool: BaseTool) -> Any:
+        """Extract the executable function from a LangChain tool.
+
+        Checks ``func``, ``coroutine``, ``_run``, and ``_arun`` in order.
+
+        Args:
+            tool: The LangChain tool to extract the function from.
+
+        Returns:
+            The function if found, or ``None``.
+        """
+        func = getattr(tool, "func", None) or getattr(tool, "coroutine", None)
+        if callable(func):
+            return func
+        func = getattr(tool, "_run", None) or getattr(tool, "_arun", None)
+        return func if callable(func) else None
+
+    @staticmethod
+    def _resolve_input_schema(tool: BaseTool) -> Any:
+        """Resolve the input schema for a LangChain tool.
+
+        Tries ``args_schema``, ``get_input_schema()``, then ``tool_call_schema``.
+
+        Args:
+            tool: The LangChain tool to resolve the schema for.
+
+        Returns:
+            The resolved schema, or ``None`` if no schema is available.
+        """
+        schema = getattr(tool, "args_schema", None)
+        if schema is not None:
+            return schema
+
+        if hasattr(tool, "get_input_schema"):
+            try:
+                return tool.get_input_schema()
+            except Exception as e:
+                logger.warning("Failed to get input schema for tool '%s': %s", tool.name, e)
+
+        return getattr(tool, "tool_call_schema", None)
+
+    def _convert_langchain_tool(self, tool: BaseTool) -> GLLMTool:
+        """Convert a single LangChain BaseTool to a GLLMTool for LM schema generation.
+
+        Extracts only name, description, input_schema, and func. LangChain wrapper
+        state (callbacks, metadata, config_schema) is intentionally discarded —
+        GLLMTools are for LM schema/description only; LangGraph retains ownership
+        of tool execution.
+
+        Falls back to ``GLLMTool.from_langchain`` when no input schema can be
+        resolved.
+
+        Args:
+            tool: The LangChain tool to convert.
+
+        Returns:
+            A ``GLLMTool`` instance.
+        """
+        input_schema = self._resolve_input_schema(tool)
+
+        if input_schema is not None:
+            func = self._resolve_tool_func(tool)
+            return GLLMTool(
+                name=tool.name,
+                description=tool.description,
+                input_schema=input_schema,
+                func=func,
+                is_async=asyncio.iscoroutinefunction(func) if callable(func) else False,
+            )
+
+        return GLLMTool.from_langchain(tool)
+
+    def _prepare_tools_for_lm_invoker(self, tools: list[Any] | None) -> list[Any]:
+        """Convert LangChain tools to gllm-core tools for LM invokers only.
+
+        Converts each LangChain BaseTool to a GLLMTool via _convert_langchain_tool.
+        Wrapper state (metadata, callbacks, config_schema) is intentionally stripped
+        — GLLMTools are for LM schema/description only; LangGraph retains ownership
+        of tool execution. Non-BaseTool items are passed through unchanged.
+
+        Args:
+            tools: List of tools (LangChain BaseTool or other) to convert.
+
+        Returns:
+            List of tools ready for LM invoker configuration.
+        """
+        if not tools:
+            return []
+
+        prepared_tools: list[Any] = []
+        for tool in tools:
+            if isinstance(tool, BaseTool):
+                prepared_tools.append(self._convert_langchain_tool(tool))
+            else:
+                prepared_tools.append(tool)
+
+        return prepared_tools
+
+    def _finalize_lm_invoker_config(self, tools: list[Any], config: BaseAgentConfig | None) -> dict[str, Any]:
+        """Finalize lm_invoker config with tools and default output settings.
+
+        Ensures generated lm_invoker config includes default values when omitted:
+        - output_analytics=True
+        - output_transformer=OutputTransformerType.THINK_TAG
+
+        Args:
+            tools: List of tools.
+            config: Configuration object for lm_invoker.
+
+        Returns:
+            Configuration dictionary for lm_invoker.
+        """
+        processed_config = self._update_config_with_tools(tools, config)
+        if processed_config is None:
+            processed_config = {}
+
+        if processed_config.get(OUTPUT_ANALYTICS_KEY) is None:
+            processed_config[OUTPUT_ANALYTICS_KEY] = True
+
+        if processed_config.get(OUTPUT_TRANSFORMER_KEY) is None:
+            processed_config[OUTPUT_TRANSFORMER_KEY] = OutputTransformerType.THINK_TAG
+
+        return processed_config
+
+    def _apply_default_thinking_config(self, model: str | ModelId, config: dict[str, Any]) -> None:
+        """Enable provider thinking by default for models that can expose it.
+
+        Explicit caller configuration always wins, including ``thinking=False``.
+        """
+        if "thinking" in config:
+            return
+
+        provider, model_name = self._provider_and_model_name(model)
+        if provider == ModelProvider.OPENAI and self._is_openai_reasoning_model(model_name):
+            config["thinking"] = ThinkingConfig(enabled=True, kwargs={"effort": "low", "summary": "detailed"})
+        elif provider == ModelProvider.GOOGLE_GENAI and model_name.startswith(("gemini-2.5", "gemini-3")):
+            config["thinking"] = ThinkingConfig(enabled=True, kwargs={"thinking_budget": 512})
+
+    def _apply_anthropic_prompt_cache_config(self, model: str | ModelId, config: dict[str, Any]) -> None:
+        """Apply native Anthropic prompt-cache defaults without touching routed providers."""
+        provider, _model_name = self._provider_and_model_name(model)
+        prompt_cache_config = config.get(ANTHROPIC_PROMPT_CACHE_CONFIG_KEY, True)
+        if provider != ModelProvider.ANTHROPIC:
+            return
+        if prompt_cache_config is False:
+            config.pop(ANTHROPIC_PROMPT_CACHE_CONFIG_KEY, None)
+            return
+
+        config.pop(ANTHROPIC_PROMPT_CACHE_CONFIG_KEY, None)
+
+        hyperparameters = config.get("default_hyperparameters")
+        if hyperparameters is None:
+            hyperparameters = {}
+        elif isinstance(hyperparameters, Mapping):
+            hyperparameters = dict(hyperparameters)
+        else:
+            raise TypeError(
+                "default_hyperparameters must be a dict when Anthropic cache defaults are requested; "
+                f"got {type(hyperparameters).__name__}."
+            )
+
+        if isinstance(prompt_cache_config, dict):
+            hyperparameters[CACHE_CONTROL_KEY] = dict(prompt_cache_config)  # pragma: no cover
+        elif CACHE_CONTROL_KEY not in hyperparameters:
+            hyperparameters[CACHE_CONTROL_KEY] = dict(DEFAULT_ANTHROPIC_CACHE_CONTROL)
+
+        if hyperparameters:
+            config["default_hyperparameters"] = hyperparameters
+
+    def _provider_and_model_name(self, model: str | ModelId) -> tuple[str | None, str]:
+        """Return a normalized provider and model name for a model identifier."""
+        if isinstance(model, ModelId):
+            return model.provider, model.name.lower()
+
+        model_text = model.strip().lower()
+        provider = self._detect_provider_from_string(model_text)
+        if "/" in model_text:
+            model_name = model_text.rsplit("/", 1)[-1]
+        elif ":" in model_text:
+            model_name = model_text.rsplit(":", 1)[-1]
+        else:
+            model_name = model_text
+
+        return provider, model_name
+
+    @staticmethod
+    def _is_openai_reasoning_model(model_name: str) -> bool:
+        """Return True when an OpenAI model supports reasoning summaries."""
+        return model_name.startswith(("gpt-5", "o1", "o3", "o4"))
+
+    def _setup_lm_invoker_param(
+        self, model: str | ModelId, tools: list[Any], config: BaseAgentConfig | None = None
+    ) -> tuple[ModelId | str, str | None, dict[str, Any] | None]:
+        """Setup parameter for build_lm_invoker.
+
+        Args:
+            model (str | ModelId): The model identifier.
+            tools (list[Any]): List of tools.
+            config (BaseAgentConfig | None): Configuration object.
+
+        Returns:
+            - model_id: ModelId | str
+            - credentials: str | None
+            - config: dict[str, Any] | None
+            as tuple
+        """
+        model_id: str | ModelId = model
+        credentials: str | None = None
+        processed_as_custom = False
+        credential_lookup_model: str | ModelId = model
+
+        if isinstance(model, str):
+            for prefix, provider in CUSTOM_PROVIDERS.items():
+                if model.startswith(prefix):
+                    processed_as_custom = True
+
+                    if not config or not isinstance(config, AgentConfig):
+                        raise ValueError(f"AgentConfig is required for model '{model}'")
+
+                    try:
+                        model_id = ModelId.from_string(model)
+                        if prefix == OPENAI_COMPATIBLE_PREFIX:
+                            model_id = ModelId(  # pragma: no cover
+                                provider=OPENAI_CHAT_COMPLETIONS_PROVIDER,
+                                name=model_id.name,
+                                path=model_id.path or config.lm_base_url,
+                            )
+                    except ValueError as e:
+                        base_url = config.lm_base_url
+                        if not base_url:
+                            raise ValueError(f"lm_base_url in AgentConfig is required for model '{model}'") from e
+
+                        model_name = model.removeprefix(prefix)
+                        normalized_provider = (
+                            OPENAI_CHAT_COMPLETIONS_PROVIDER if prefix == OPENAI_COMPATIBLE_PREFIX else provider
+                        )
+                        model_id = ModelId(provider=normalized_provider, name=model_name, path=base_url)
+
+                    # Extract credentials using new enhanced method
+                    _, credentials = self._extract_credentials_from_config(config)
+                    if prefix == OPENAI_COMPATIBLE_PREFIX and credentials is None:
+                        credential_lookup_model = model  # pragma: no cover
+                    break
+
+        if not processed_as_custom or credentials is None:
+            credentials = self._get_credentials(credential_lookup_model if credentials is None else model_id, config)
+
+        processed_config = self._finalize_lm_invoker_config(tools, config)
+        self._apply_default_thinking_config(model_id, processed_config)
+        self._apply_anthropic_prompt_cache_config(model_id, processed_config)
+        return model_id, credentials, processed_config
+
+    def _process_model_parameter(
+        self, agent_name: str, model: Any | None, tools: list[Any], config: BaseAgentConfig | None = None
+    ) -> tuple[Any | None, Any | None]:
+        """Process the model parameter and determine lm_invoker and model attributes.
+
+        Args:
+            agent_name: The name of the agent (for logging).
+            model: The model parameter from initialization.
+            tools: List of tools for lm_invoker configuration.
+            config: Configuration object.
+
+        Returns:
+            Tuple of (lm_invoker, processed_model) where:
+            - lm_invoker: Built LM Invoker if model is string/ModelId or existing BaseLMInvoker, None otherwise
+            - processed_model: LangChain model if it's a BaseChatModel,
+                original model for other types, None if lm_invoker was created
+                or if model is None
+        """
+        # If model is already an lm_invoker instance
+        if BaseLMInvoker and isinstance(model, BaseLMInvoker):
+            logger.debug(f"Agent '{agent_name}': Using provided LM Invoker: {model.__class__.__name__}")
+            self._apply_lm_invoker_runtime_patches_for_invoker(model)
+            return model, None
+
+        # Check if model is a string or ModelId - build lm_invoker
+        if isinstance(model, str) or (ModelId and isinstance(model, ModelId)):
+            if not build_lm_invoker:
+                logger.warning(
+                    f"Agent '{agent_name}': gllm-inference not available, cannot build LM Invoker from {model}"
+                )
+                return None, model
+
+            logger.info(f"Agent '{agent_name}': Building LM Invoker from model identifier: {model}")
+            try:
+                model_id, credentials, preprocessed_config = self._setup_lm_invoker_param(model, tools, config)
+
+                lm_invoker = build_lm_invoker(
+                    model_id=model_id,
+                    credentials=credentials,
+                    config=preprocessed_config,
+                )
+                self._apply_lm_invoker_runtime_patches(model_id, lm_invoker)
+                return lm_invoker, None
+            except Exception as e:
+                logger.error(f"Agent '{agent_name}': Failed to build LM Invoker from {model}: {e}")
+                raise RuntimeError(f"Failed to build LM Invoker from model '{model}': {e}") from e
+
+        # If it's a LangChain model, use it directly
+        elif BaseChatModel and hasattr(model, "__class__") and issubclass(model.__class__, BaseChatModel):
+            logger.debug(f"Agent '{agent_name}': Using provided LangChain model: {model.__class__.__name__}")
+            return None, model
+
+        # If model is None, that's acceptable for some use cases
+        elif model is None:
+            logger.debug(f"Agent '{agent_name}': No model provided")
+            return None, None
+
+        # For any other type, store as model (e.g., Google ADK agent instance)
+        else:
+            logger.debug(f"Agent '{agent_name}': Using provided model of type: {type(model)}")
+            return None, model
+
+    def _apply_lm_invoker_runtime_patches(self, model: str | ModelId, lm_invoker: Any) -> None:
+        """Apply aip-agents-local runtime fixes to a built LM invoker.
+
+        These policy-layer patches let aip-agents ship narrow provider workarounds
+        without waiting for upstream gllm-inference changes.
+        """
+        self._lm_invoker_runtime_policy().apply_to_built_invoker(model, lm_invoker)
+
+    def _apply_lm_invoker_runtime_patches_for_invoker(self, lm_invoker: Any) -> None:
+        """Apply runtime patches to a caller-provided ``BaseLMInvoker`` instance.
+
+        Mirrors ``_apply_lm_invoker_runtime_patches`` for the path where the
+        caller already constructed an invoker. Reads the provider and model
+        name from the invoker's own properties to avoid coupling to the
+        ``ModelId`` serialization format used by different package shims.
+        """
+        self._lm_invoker_runtime_policy().apply_to_provided_invoker(lm_invoker)
+
+    def _lm_invoker_runtime_policy(self) -> LMInvokerRuntimePolicy:
+        """Build the private model-invocation runtime policy delegate."""
+        return LMInvokerRuntimePolicy(
+            provider_and_model_name=self._provider_and_model_name,
+            provider_and_model_name_for_invoker=self._provider_and_model_name_for_invoker,
+            is_openai_reasoning_model=self._is_openai_reasoning_model,
+            patch_openai_reasoning_thinking_extraction=self._patch_openai_reasoning_thinking_extraction,
+            patch_anthropic_cache_usage=self._patch_anthropic_cache_usage,
+        )
+
+    def _patch_anthropic_cache_usage(self, lm_invoker: Any) -> None:
+        """Preserve Anthropic prompt-cache counters dropped by current gllm-inference builds."""
+        if getattr(lm_invoker, "_aip_anthropic_cache_usage_patch_applied", False):
+            return
+
+        messages = getattr(getattr(getattr(lm_invoker, "client", None), "beta", None), "messages", None)
+        original_create = getattr(messages, "create", None)
+        original_invoke = getattr(lm_invoker, "invoke", None)
+        if not callable(original_create) or not callable(original_invoke):
+            return
+
+        async def _patched_create(*args: Any, **kwargs: Any) -> Any:
+            response = await original_create(*args, **kwargs)
+            _AIP_ANTHROPIC_CACHE_USAGE.set(getattr(response, "usage", None))
+            return response
+
+        async def _patched_invoke(*args: Any, **kwargs: Any) -> Any:
+            token = _AIP_ANTHROPIC_CACHE_USAGE.set(None)
+            try:
+                output = await original_invoke(*args, **kwargs)
+            finally:
+                latest_usage = _AIP_ANTHROPIC_CACHE_USAGE.get()
+                _AIP_ANTHROPIC_CACHE_USAGE.reset(token)
+
+            _merge_anthropic_cache_usage(output, latest_usage)
+            return output
+
+        messages.create = _patched_create
+        lm_invoker.invoke = _patched_invoke
+        lm_invoker._aip_anthropic_cache_usage_patch_applied = True
+
+    def _provider_and_model_name_for_invoker(self, lm_invoker: Any) -> tuple[str | None, str]:
+        """Return normalized provider/model_name for a caller-provided invoker.
+
+        Prefers the invoker's own provider/name properties to avoid coupling
+        to ModelId serialization format, which differs between
+        ``aip-agents`` and ``gllm-inference`` shims.
+        """
+        provider = getattr(lm_invoker, "model_provider", None)
+        model_name = getattr(lm_invoker, "model_name", None)
+        if provider and model_name:
+            return provider, model_name.lower()
+
+        model_id = getattr(lm_invoker, "model_id", None)
+        if model_id is not None:
+            return self._provider_and_model_name(str(model_id))  # pragma: no cover
+
+        return None, ""
+
+    def _patch_openai_reasoning_thinking_extraction(self, lm_invoker: Any) -> None:
+        """Recover OpenAI reasoning text from ``content`` when upstream omits it.
+
+        Some OpenAI Responses API reasoning items expose recoverable text in
+        ``content`` while leaving ``summary`` empty. Older gllm-inference builds
+        only read ``summary``, which drops provider reasoning before the SSE layer
+        ever sees it. This instance-local patch preserves aip-agents behavior
+        without mutating the upstream package globally.
+        """
+        if getattr(lm_invoker, "_aip_openai_reasoning_patch_applied", False):
+            return  # pragma: no cover
+
+        original_process_thinkings = getattr(lm_invoker, "_process_thinkings", None)
+        if not callable(original_process_thinkings):
+            return
+
+        lm_invoker._process_thinkings = MethodType(
+            _build_openai_reasoning_patch(original_process_thinkings), lm_invoker
+        )
+        lm_invoker._aip_openai_reasoning_patch_applied = True
+
+    def to_a2a(self, agent_card: AgentCard, **kwargs: Any) -> Starlette:
+        """Converts the agent to an A2A-compatible ASGI application.
+
+        This implementation provides a base setup for A2A server components.
+        Subclasses can override this method if they need custom executor
+        or task store implementations.
+
+        Args:
+            agent_card: The agent card to use for the A2A application.
+            **kwargs: Additional keyword arguments for ASGI application configuration.
+
+        Returns:
+            A Starlette ASGI application that can be used with any ASGI server.
+        """
+        # Use provided task store or create default in-memory store
+        task_store = kwargs.get("task_store", InMemoryTaskStore())
+
+        # Create default request handler if not provided
+        try:
+            executor_cls = _get_executor_class_for_agent(self)
+        except KeyError as exc:
+            raise ValueError(f"No A2A executor registered for agent type '{self.__class__.__name__}'.") from exc
+
+        agent_executor = executor_cls(self)
+        request_handler = kwargs.get(
+            "request_handler",
+            DefaultRequestHandler(
+                agent_executor=agent_executor,
+                task_store=task_store,
+            ),
+        )
+
+        # Create A2A application
+        a2a_app = A2AStarletteApplication(agent_card=agent_card, http_handler=request_handler)
+
+        # Get base routes from A2A app
+        routes = a2a_app.routes()
+
+        # Add any additional routes if provided
+        if "routes" in kwargs:
+            routes.extend(kwargs["routes"])
+
+        # Create and return Starlette application
+        return Starlette(routes=routes)
+
+    @classmethod
+    def discover_agents(cls, a2a_config: A2AClientConfig, **kwargs: Any) -> list[AgentCard]:
+        """Discover agents from the URLs specified in a2a_config.discovery_urls.
+
+        This concrete implementation fetches and parses .well-known/agent.json
+        from each discovery URL to build a list of available agents.
+
+        Args:
+            a2a_config: Configuration containing discovery URLs and other A2A settings.
+            **kwargs: Additional keyword arguments (unused in this implementation).
+
+        Returns:
+            A list of AgentCard objects representing discovered agents.
+        """
+        discovered_cards: list[AgentCard] = []
+
+        if not a2a_config or not a2a_config.discovery_urls:
+            logger.debug("No discovery URLs configured")
+            return discovered_cards
+
+        httpx_client_options = {}
+        if a2a_config.httpx_client_options:
+            httpx_client_options = a2a_config.httpx_client_options.model_dump(exclude_none=True)
+
+        with httpx.Client(**httpx_client_options) as client:
+            for base_url in a2a_config.discovery_urls:
+                try:
+                    agent_json_url = f"{base_url.rstrip('/')}/.well-known/agent.json"
+
+                    response = client.get(agent_json_url)
+                    response.raise_for_status()
+
+                    try:
+                        agent_card = AgentCard.model_validate(response.json())
+                        discovered_cards.append(agent_card)
+                        logger.info(f"Successfully discovered agent '{agent_card.name}' at {base_url}")
+                    except Exception as parse_error:
+                        logger.error(f"Error parsing agent card from {agent_json_url}: {parse_error}")
+                        continue
+
+                except Exception as e:
+                    logger.error(f"Unexpected error discovering agents from {base_url}: {e}")
+                    continue
+
+        agent_list = "\n".join([f"{i + 1}. {agent.name}" for i, agent in enumerate(discovered_cards)])
+        logger.info(f"Discovered agents ({len(discovered_cards)} Agents): \n{agent_list}")
+        return discovered_cards
+
+    def send_to_agent(
+        self,
+        agent_card: AgentCard,
+        message: str | dict[str, Any],
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Synchronously sends a message to another agent using the A2A protocol.
+
+        This method is a synchronous wrapper around asend_to_agent. It handles the creation
+        of an event loop if one doesn't exist, and manages the asynchronous call internally.
+
+        Args:
+            agent_card: The AgentCard instance containing the target agent's details including
+                URL, authentication requirements, and capabilities.
+            message: The message to send to the agent. Can be either a string for simple text
+                messages or a dictionary for structured data.
+            **kwargs: Additional keyword arguments passed to asend_to_agent.
+
+        Returns:
+            A dictionary containing the response details:
+                - status (str): 'success' or 'error'
+                - content (str): Extracted text content from the response
+                - task_id (str, optional): ID of the created/updated task
+                - task_state (str, optional): Current state of the task
+                - raw_response (str): Complete JSON response from the A2A client
+                - error_type (str, optional): Type of error if status is 'error'
+                - message (str, optional): Error message if status is 'error'
+
+        Raises:
+            RuntimeError: If called from within an existing event loop or if asend_to_agent
+                encounters an unhandled exception.
+        """
+        try:
+            return A2AConnector.send_to_agent(agent_card, message, **kwargs)
+        except RuntimeError as e:
+            raise RuntimeError(f"Agent '{self.name}': Error in sync 'send_to_agent'. Original error: {e}") from e
+
+    async def asend_to_agent(
+        self,
+        agent_card: AgentCard,
+        message: str | dict[str, Any],
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Asynchronously sends a message to another agent using the A2A protocol.
+
+        This method handles the core A2A communication logic, creating and sending properly
+        formatted A2A messages and processing the responses.
+
+        Args:
+            agent_card: The AgentCard instance containing the target agent's details including
+                URL, authentication requirements, and capabilities.
+            message: The message to send to the agent. Can be either a string for simple text
+                messages or a dictionary for structured data.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            A dictionary containing the response details:
+                - status (str): 'success' or 'error'
+                - content (str): Extracted text content from the response
+                - task_id (str, optional): ID of the created/updated task
+                - task_state (str, optional): Current state of the task
+                - raw_response (str): Complete JSON response from the A2A client
+                - error_type (str, optional): Type of error if status is 'error'
+                - message (str, optional): Error message if status is 'error'
+
+        Raises:
+            httpx.HTTPError: If there's an HTTP-related error during the request.
+            Exception: For any other unexpected errors during message sending or processing.
+        """
+        return await A2AConnector.asend_to_agent(agent_card, message, **kwargs)
+
+    async def astream_to_agent(
+        self,
+        agent_card: AgentCard,
+        message: str | dict[str, Any],
+        **kwargs: Any,
+    ) -> AsyncGenerator[dict[str, Any], None]:
+        """Asynchronously sends a streaming message to another agent using the A2A protocol.
+
+        This method supports streaming responses from the target agent, yielding chunks of
+        the response as they become available. It handles various types of streaming events
+        including task status updates, artifact updates, and message parts.
+
+        Args:
+            agent_card: The AgentCard instance containing the target agent's details including
+                URL, authentication requirements, and capabilities.
+            message: The message to send to the agent. Can be either a string for simple text
+                messages or a dictionary for structured data.
+            **kwargs: Additional keyword arguments.
+
+        Yields:
+            Dictionaries containing streaming response chunks:
+                For successful chunks:
+                    - status (str): 'success'
+                    - content (str): Extracted text content from the chunk
+                    - task_id (str): ID of the associated task
+                    - task_state (str): Current state of the task
+                    - final (bool): Whether this is the final chunk
+                    - artifact_name (str, optional): Name of the artifact if chunk is an artifact update
+                For error chunks:
+                    - status (str): 'error'
+                    - error_type (str): Type of error encountered
+                    - message (str): Error description
+
+        Raises:
+            httpx.HTTPError: If there's an HTTP-related error during the streaming request.
+            Exception: For any other unexpected errors during message streaming or processing.
+        """
+        # Default to the richer A2A event payload so integrations (e.g. HITL streaming) receive
+        async for chunk in A2AConnector.astream_to_agent(agent_card, message, **kwargs):
+            yield chunk
+
+    @staticmethod
+    def format_agent_description(agent_card: AgentCard) -> str:
+        """Format the description of an agent card including skills information.
+
+        Args:
+            agent_card (AgentCard): The agent card to format.
+
+        Returns:
+            str: The formatted description including skills.
+        """
+        # Start with the base description
+        formatted_description = agent_card.description or ""
+
+        if agent_card.skills:
+            formatted_description += "\n\nSkills:"
+            for skill in agent_card.skills:
+                formatted_description += f"\n• {skill.name}: {skill.description}"
+
+                if skill.tags:
+                    tags_str = ", ".join(skill.tags)
+                    formatted_description += f" (Tags: {tags_str})"
+
+                if skill.examples:
+                    formatted_description += "\n  Examples:"
+                    for example in skill.examples:
+                        formatted_description += f"\n    - {example}"
+
+        return formatted_description
+
+    def add_mcp_server(self, mcp_config: dict[str, dict[str, Any]]) -> None:
+        """Adds MCP servers to the agent.
+
+        Args:
+            mcp_config: A dictionary containing MCP server configurations.
+
+        Raises:
+            ValueError: If the MCP configuration is empty or None.
+            KeyError: If a server with the same name already exists in the MCP configuration.
+        """
+        if not mcp_config:
+            raise ValueError("MCP configuration must not be empty or None")
+
+        for server_name, config in mcp_config.items():
+            if server_name in self.mcp_config:
+                raise KeyError(f"Server '{server_name}' already exists in MCP configuration")
+            if not isinstance(config, dict):
+                raise ValueError(f"Configuration for server '{server_name}' must be a dictionary")
+            if not config:
+                raise ValueError(f"Configuration for server '{server_name}' must not be empty")
+
+            # Validate that either URL or command is present
+            required_keys = ["url"] if "url" in config else ["command"]
+            if not any(key in config for key in required_keys):
+                raise ValueError(
+                    f"Server '{server_name}' missing required configuration: must have either 'url' or 'command'"
+                )
+
+        self._mcp_config.update(mcp_config)
+        # Initialize/recreate MCP client object (lightweight, no sessions yet)
+        # This satisfies existing unit tests and keeps lazy async session init intact.
+        self._initialize_mcp_client()
+        # Mark that we need to initialize MCP tools (lazy initialization)
+        self._mcp_tools_initialized = False
+
+    def _initialize_mcp_client(self) -> None:
+        """Initialize/recreate MCP client with current config.
+
+        To be implemented by child agents as each agent type has its own MCP client.
+        For agents that don't support MCP (e.g., LangflowAgent), this can be a no-op.
+        """
+        # Default implementation is no-op for agents that don't support MCP
+        pass
+
+    def _set_mcp_client_safely(self, new_client: BaseMCPClient | None) -> None:
+        """Replace current MCP client with cleanup of the previous instance.
+
+        This helper ensures we don't leak persistent sessions when recreating the client.
+        It attempts asynchronous cleanup when an event loop is running, otherwise performs
+        a synchronous cleanup using asyncio.run.
+
+        Args:
+            new_client (BaseMCPClient | None): The new MCP client to set, or None to clear the current client.
+        """
+        prev_client = self.mcp_client
+        self.mcp_client = new_client
+        if prev_client is not None and prev_client is not new_client:
+            try:
+                loop = asyncio.get_running_loop()
+                loop.create_task(prev_client.cleanup())
+            except RuntimeError:
+                try:
+                    asyncio.run(prev_client.cleanup())
+                except Exception:
+                    # Best-effort cleanup; ignore failures
+                    pass
+
+    async def _ensure_mcp_tools_initialized(self) -> None:
+        """Ensure MCP tools are initialized lazily (one-time operation).
+
+        This method ensures MCP tools are initialized only once during the first run,
+        avoiding event loop issues by doing initialization in the correct event loop.
+        """
+        if self._mcp_tools_initialized:
+            return
+
+        # Prevent concurrent initialization across simultaneous runs
+        async with self._mcp_init_lock:
+            if self._mcp_tools_initialized:
+                return
+
+            await self._handle_mcp_client_initialization()
+
+            # If we have a client at this point, proceed with tool registration
+            if self.mcp_client is not None:
+                await self._perform_mcp_tool_registration()
+
+    async def _handle_mcp_client_initialization(self) -> None:
+        """Handle MCP client initialization based on current state.
+
+        Sets the initialization flag appropriately for different scenarios.
+        """
+        if self.mcp_client is not None:
+            return  # Client already exists
+
+        if not self._mcp_config:
+            # No config at all - skip and mark as initialized to avoid repeated logs
+            logger.debug(f"Agent '{self.name}': MCP client not configured; skipping MCP tool registration")
+            self._mcp_tools_initialized = True
+            return
+
+        # Config exists but no client - try to initialize
+        self._initialize_mcp_client()
+        if self.mcp_client is None:
+            # Still no client after init - agent type doesn't support MCP
+            logger.warning(f"Agent '{self.name}': MCP config present but agent type doesn't support MCP")
+
+    async def _perform_mcp_tool_registration(self) -> None:
+        """Perform the actual MCP tool registration.
+
+        Raises:
+            RuntimeError: If tool registration fails
+        """
+        try:
+            await self._register_mcp_tools()
+            self._mcp_tools_initialized = True
+        except Exception as e:
+            logger.error(f"Agent '{self.name}': Failed to initialize MCP tools: {e}", exc_info=True)
+            raise RuntimeError(f"Agent '{self.name}': MCP tool initialization failed: {e}") from e
+
+    async def _register_mcp_tools(self) -> None:
+        """Register MCP tools with the agent.
+
+        To be implemented by child agents as each agent type has its own way
+        of registering tools. For agents that don't support MCP, this can be a no-op.
+        """
+        # Default implementation is no-op for agents that don't support MCP
+        pass