glaip-sdk 0.6.5b6__py3-none-any.whl → 0.7.12__py3-none-any.whl

glaip_sdk/runner/__init__.py

@@ -19,18 +19,19 @@ Example:
     >>> result = runner.run(agent, "Hello!")
 """
 
+from typing import TYPE_CHECKING, Any
+
 from glaip_sdk.runner.deps import (
     LOCAL_RUNTIME_AVAILABLE,
     check_local_runtime_available,
     get_local_runtime_missing_message,
 )
-from glaip_sdk.runner.langgraph import LangGraphRunner
 
 # Default runner instance
-_default_runner: LangGraphRunner | None = None
+_default_runner: Any | None = None
 
 
-def get_default_runner() -> LangGraphRunner:
+def get_default_runner() -> Any:
     """Get the default runner instance for local agent execution.
 
     Returns:
@@ -45,11 +46,17 @@ def get_default_runner() -> LangGraphRunner:
         raise RuntimeError(get_local_runtime_missing_message())
 
     if _default_runner is None:
+        # Lazy import to avoid requiring aip-agents when runner is not used
+        from glaip_sdk.runner.langgraph import LangGraphRunner  # noqa: PLC0415
+
         _default_runner = LangGraphRunner()
 
     return _default_runner
 
 
+if TYPE_CHECKING:
+    from glaip_sdk.runner.langgraph import LangGraphRunner
+
 __all__ = [
     "LOCAL_RUNTIME_AVAILABLE",
     "LangGraphRunner",
@@ -57,3 +64,13 @@ __all__ = [
     "get_default_runner",
     "get_local_runtime_missing_message",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import for LangGraphRunner to avoid requiring aip-agents when not used."""
+    if name == "LangGraphRunner":
+        from glaip_sdk.runner.langgraph import LangGraphRunner  # noqa: PLC0415
+
+        globals()["LangGraphRunner"] = LangGraphRunner
+        return LangGraphRunner
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

glaip_sdk/runner/deps.py

@@ -15,6 +15,8 @@ Example:
 
 from __future__ import annotations
 
+import importlib.util
+
 from gllm_core.utils import LoggerManager
 
 logger = LoggerManager().get_logger(__name__)
@@ -24,17 +26,12 @@ _local_runtime_available: bool | None = None
 
 
 def _probe_aip_agents_import() -> bool:
-    """Attempt to import aip_agents and return success status.
+    """Check if aip_agents is available without importing it.
 
     Returns:
-        True if aip_agents can be imported successfully, False otherwise.
+        True if aip_agents appears importable, False otherwise.
     """
-    try:
-        import aip_agents  # noqa: F401, PLC0415
-
-        return True
-    except ImportError:
-        return False
+    return importlib.util.find_spec("aip_agents") is not None
 
 
 def check_local_runtime_available() -> bool:

glaip_sdk/runner/langgraph.py

@@ -18,33 +18,102 @@ Example:
 from __future__ import annotations
 
 import asyncio
+import inspect
+import logging
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
+from gllm_core.utils import LoggerManager
+
+from glaip_sdk.client.run_rendering import AgentRunRenderingManager
+from glaip_sdk.hitl import PauseResumeCallback
 from glaip_sdk.runner.base import BaseRunner
 from glaip_sdk.runner.deps import (
     check_local_runtime_available,
     get_local_runtime_missing_message,
 )
-from glaip_sdk.utils.a2a import A2AEventStreamProcessor
-from gllm_core.utils import LoggerManager
+from glaip_sdk.utils.tool_storage_provider import build_tool_output_manager
 
 if TYPE_CHECKING:
+    from langchain_core.messages import BaseMessage
+
     from glaip_sdk.agents.base import Agent
 
+
+_AIP_LOGS_SWALLOWED = False
+
+
+def _swallow_aip_logs(level: int = logging.ERROR) -> None:
+    """Consume noisy AIPAgents logs once (opt-in via runner flag)."""
+    global _AIP_LOGS_SWALLOWED
+    if _AIP_LOGS_SWALLOWED:
+        return
+    prefixes = ("aip_agents.",)
+
+    def _silence(name: str) -> None:
+        lg = logging.getLogger(name)
+        lg.handlers = [logging.NullHandler()]
+        lg.propagate = False
+        lg.setLevel(level)
+
+    # Silence any already-registered loggers under the given prefixes
+    for logger_name in logging.root.manager.loggerDict:
+        if any(logger_name.startswith(prefix) for prefix in prefixes):
+            _silence(logger_name)
+
+    # Also set the base prefix loggers so future children inherit silence
+    for prefix in prefixes:
+        _silence(prefix.rstrip("."))
+    _AIP_LOGS_SWALLOWED = True
+
+
 logger = LoggerManager().get_logger(__name__)
 
-# Default A2A event processor
-_event_processor = A2AEventStreamProcessor()
+
+def _convert_chat_history_to_messages(
+    chat_history: list[dict[str, str]] | None,
+) -> list[BaseMessage]:
+    """Convert chat history dicts to LangChain messages.
+
+    Args:
+        chat_history: List of dicts with "role" and "content" keys.
+            Supported roles: "user"/"human", "assistant"/"ai", "system".
+
+    Returns:
+        List of LangChain BaseMessage instances.
+    """
+    if not chat_history:
+        return []
+
+    from langchain_core.messages import AIMessage, HumanMessage, SystemMessage  # noqa: PLC0415
+
+    messages: list[BaseMessage] = []
+    for msg in chat_history:
+        role = msg.get("role", "").lower()
+        content = msg.get("content", "")
+
+        if role in ("user", "human"):
+            messages.append(HumanMessage(content=content))
+        elif role in ("assistant", "ai"):
+            messages.append(AIMessage(content=content))
+        elif role == "system":
+            messages.append(SystemMessage(content=content))
+        else:
+            # Default to human message for unknown roles
+            logger.warning("Unknown chat history role '%s', treating as user message", role)
+            messages.append(HumanMessage(content=content))
+
+    return messages
 
 
 @dataclass(frozen=True, slots=True)
 class LangGraphRunner(BaseRunner):
     """Runner implementation using aip-agents LangGraphReactAgent.
 
-    MVP scope:
-    - Execute via `LangGraphReactAgent.arun_a2a_stream()`
-    - Extract and return final text from the emitted `final_response` event
+    Current behavior:
+    - Execute via `LangGraphReactAgent.arun_sse_stream()` (normalized SSE-compatible stream)
+    - Route all events through `AgentRunRenderingManager.async_process_stream_events`
+      for unified rendering between local and remote agents
 
     Attributes:
         default_model: Model name to use when agent.model is not set.
@@ -58,8 +127,10 @@ class LangGraphRunner(BaseRunner):
         agent: Agent,
         message: str,
         verbose: bool = False,
-        runtime_config: dict[str, Any] | None = None,  # noqa: ARG002 - Used in PR-04+
-        chat_history: (list[dict[str, str]] | None) = None,  # noqa: ARG002 - Used in PR-03
+        runtime_config: dict[str, Any] | None = None,
+        chat_history: list[dict[str, str]] | None = None,
+        *,
+        swallow_aip_logs: bool = True,
         **kwargs: Any,
     ) -> str:
         """Execute agent synchronously and return final response text.
@@ -72,7 +143,11 @@ class LangGraphRunner(BaseRunner):
             runtime_config: Optional runtime configuration for tools, MCPs, etc.
                 Defaults to None. (Implemented in PR-04+)
             chat_history: Optional list of prior conversation messages.
-                Defaults to None. (Implemented in PR-03)
+                Each message is a dict with "role" and "content" keys.
+                Defaults to None.
+            swallow_aip_logs: When True (default), silence noisy logs from aip-agents,
+                gllm_inference, OpenAILMInvoker, and httpx. Set to False to honor user
+                logging configuration.
             **kwargs: Additional keyword arguments passed to the backend.
 
         Returns:
@@ -85,23 +160,37 @@ class LangGraphRunner(BaseRunner):
         if not check_local_runtime_available():
             raise RuntimeError(get_local_runtime_missing_message())
 
-        return asyncio.run(
-            self._arun_internal(
-                agent=agent,
-                message=message,
-                verbose=verbose,
-                runtime_config=runtime_config,
-                **kwargs,
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            pass
+        else:
+            raise RuntimeError(
+                "LangGraphRunner.run() cannot be called from a running event loop. "
+                "Use 'await LangGraphRunner.arun(...)' instead."
             )
+
+        coro = self._arun_internal(
+            agent=agent,
+            message=message,
+            verbose=verbose,
+            runtime_config=runtime_config,
+            chat_history=chat_history,
+            swallow_aip_logs=swallow_aip_logs,
+            **kwargs,
         )
 
+        return asyncio.run(coro)
+
     async def arun(
         self,
         agent: Agent,
         message: str,
         verbose: bool = False,
         runtime_config: dict[str, Any] | None = None,
-        chat_history: (list[dict[str, str]] | None) = None,  # noqa: ARG002 - Used in PR-03
+        chat_history: list[dict[str, str]] | None = None,
+        *,
+        swallow_aip_logs: bool = True,
         **kwargs: Any,
     ) -> str:
         """Execute agent asynchronously and return final response text.
@@ -114,7 +203,9 @@ class LangGraphRunner(BaseRunner):
             runtime_config: Optional runtime configuration for tools, MCPs, etc.
                 Defaults to None. (Implemented in PR-04+)
             chat_history: Optional list of prior conversation messages.
-                Defaults to None. (Implemented in PR-03)
+                Each message is a dict with "role" and "content" keys.
+                Defaults to None.
+            swallow_aip_logs: When True (default), silence noisy AIPAgents logs.
             **kwargs: Additional keyword arguments passed to the backend.
 
         Returns:
@@ -128,6 +219,8 @@ class LangGraphRunner(BaseRunner):
             message=message,
             verbose=verbose,
             runtime_config=runtime_config,
+            chat_history=chat_history,
+            swallow_aip_logs=swallow_aip_logs,
             **kwargs,
         )
 
@@ -137,6 +230,9 @@ class LangGraphRunner(BaseRunner):
         message: str,
         verbose: bool = False,
         runtime_config: dict[str, Any] | None = None,
+        chat_history: list[dict[str, str]] | None = None,
+        *,
+        swallow_aip_logs: bool = True,
         **kwargs: Any,
     ) -> str:
         """Internal async implementation of agent execution.
@@ -146,28 +242,83 @@ class LangGraphRunner(BaseRunner):
             message: The user message to send to the agent.
             verbose: If True, emit debug trace output during execution.
             runtime_config: Optional runtime configuration for tools, MCPs, etc.
+            chat_history: Optional list of prior conversation messages.
+            swallow_aip_logs: When True (default), silence noisy AIPAgents logs.
             **kwargs: Additional keyword arguments passed to the backend.
 
         Returns:
             The final response text from the agent.
         """
+        # Optionally swallow noisy AIPAgents logs
+        if swallow_aip_logs:
+            _swallow_aip_logs()
+
+        # POC/MVP: Create pause/resume callback for interactive HITL input
+        pause_resume_callback = PauseResumeCallback()
+
         # Build the local LangGraphReactAgent from the glaip_sdk Agent
-        local_agent = self.build_langgraph_agent(agent, runtime_config=runtime_config)
+        local_agent = self.build_langgraph_agent(
+            agent, runtime_config=runtime_config, pause_resume_callback=pause_resume_callback
+        )
 
-        # Collect A2AEvents from the stream and extract final response
-        events: list[dict[str, Any]] = []
+        # Convert chat history to LangChain messages for the agent
+        langchain_messages = _convert_chat_history_to_messages(chat_history)
+        if langchain_messages:
+            kwargs["messages"] = langchain_messages
+            logger.debug(
+                "Passing %d chat history messages to agent '%s'",
+                len(langchain_messages),
+                agent.name,
+            )
+
+        # Use shared render manager for unified processing
+        render_manager = AgentRunRenderingManager(logger)
+        renderer = render_manager.create_renderer(kwargs.get("renderer"), verbose=verbose)
+
+        # POC/MVP: Set renderer on callback so LocalPromptHandler can pause/resume Live
+        pause_resume_callback.set_renderer(renderer)
+
+        meta = render_manager.build_initial_metadata(agent.name, message, kwargs)
+        render_manager.start_renderer(renderer, meta)
+
+        try:
+            # Use shared async stream processor for unified event handling
+            (
+                final_text,
+                stats_usage,
+                started_monotonic,
+                finished_monotonic,
+            ) = await render_manager.async_process_stream_events(
+                local_agent.arun_sse_stream(message, **kwargs),
+                renderer,
+                meta,
+                skip_final_render=True,
+            )
+        except KeyboardInterrupt:
+            try:
+                renderer.close()
+            finally:
+                raise
+        except Exception:
+            try:
+                renderer.close()
+            finally:
+                raise
 
-        async for event in local_agent.arun_a2a_stream(message, **kwargs):
-            if verbose:
-                self._log_event(event)
-            events.append(event)
+        # Use shared finalizer to avoid code duplication
+        from glaip_sdk.client.run_rendering import finalize_render_manager  # noqa: PLC0415
 
-        return _event_processor.extract_final_response(events)
+        return finalize_render_manager(
+            render_manager, renderer, final_text, stats_usage, started_monotonic, finished_monotonic
+        )
 
     def build_langgraph_agent(
         self,
         agent: Agent,
         runtime_config: dict[str, Any] | None = None,
+        shared_tool_output_manager: Any | None = None,
+        *,
+        pause_resume_callback: Any | None = None,
     ) -> Any:
         """Build a LangGraphReactAgent from a glaip_sdk Agent definition.
 
@@ -175,6 +326,10 @@ class LangGraphRunner(BaseRunner):
             agent: The glaip_sdk Agent to convert.
             runtime_config: Optional runtime configuration with tool_configs,
                 mcp_configs, agent_config, and agent-specific overrides.
+            shared_tool_output_manager: Optional ToolOutputManager to reuse across
+                agents with tool_output_sharing enabled.
+            pause_resume_callback: Optional callback used to pause/resume the renderer
+                during interactive HITL prompts.
 
         Returns:
             A configured LangGraphReactAgent instance.
@@ -184,17 +339,18 @@ class LangGraphRunner(BaseRunner):
             ValueError: If agent has unsupported tools, MCPs, or sub-agents for local mode.
         """
         from aip_agents.agent import LangGraphReactAgent  # noqa: PLC0415
+
         from glaip_sdk.runner.tool_adapter import LangChainToolAdapter  # noqa: PLC0415
 
         # Adapt tools for local execution
+        # NOTE: CLI parity waiver - local tool execution is SDK-only for MVP.
+        # See specs/f/local-agent-runtime/plan.md: "CLI parity is explicitly deferred
+        # and will require SDK Technical Lead sign-off per constitution principle IV."
         langchain_tools: list[Any] = []
         if agent.tools:
             adapter = LangChainToolAdapter()
             langchain_tools = adapter.adapt_tools(agent.tools)
 
-        # Build sub-agents recursively
-        sub_agent_instances = self._build_sub_agents(agent.agents, runtime_config)
-
         # Normalize runtime config: merge global and agent-specific configs
         normalized_config = self._normalize_runtime_config(runtime_config, agent)
 
@@ -208,6 +364,19 @@ class LangGraphRunner(BaseRunner):
         merged_agent_config = self._merge_agent_config(agent, normalized_config)
         agent_config_params, agent_config_kwargs = self._apply_agent_config(merged_agent_config)
 
+        tool_output_manager = self._resolve_tool_output_manager(
+            agent,
+            merged_agent_config,
+            shared_tool_output_manager,
+        )
+
+        # Build sub-agents recursively, sharing tool output manager when enabled.
+        sub_agent_instances = self._build_sub_agents(
+            agent.agents,
+            runtime_config,
+            shared_tool_output_manager=tool_output_manager,
+        )
+
         # Build the LangGraphReactAgent with tools, sub-agents, and configs
         local_agent = LangGraphReactAgent(
             name=agent.name,
@@ -217,6 +386,8 @@ class LangGraphRunner(BaseRunner):
             tools=langchain_tools,
             agents=sub_agent_instances if sub_agent_instances else None,
             tool_configs=tool_configs if tool_configs else None,
+            tool_output_manager=tool_output_manager,
+            guardrail=agent.guardrail,
             **agent_config_params,
             **agent_config_kwargs,
         )
@@ -224,6 +395,11 @@ class LangGraphRunner(BaseRunner):
         # Add MCP servers if configured
         self._add_mcp_servers(local_agent, agent, mcp_configs)
 
+        # Inject local HITL manager only if hitl_enabled is True (master switch).
+        # This matches remote behavior: hitl_enabled gates the HITL plumbing.
+        # Tool-level HITL configs are only enforced when hitl_enabled=True.
+        self._inject_hitl_manager(local_agent, merged_agent_config, agent.name, pause_resume_callback)
+
         logger.debug(
             "Built local LangGraphReactAgent for agent '%s' with %d tools, %d sub-agents, and %d MCPs",
             agent.name,
@@ -233,16 +409,63 @@ class LangGraphRunner(BaseRunner):
         )
         return local_agent
 
+    def _resolve_tool_output_manager(
+        self,
+        agent: Agent,
+        merged_agent_config: dict[str, Any],
+        shared_tool_output_manager: Any | None,
+    ) -> Any | None:
+        """Resolve tool output manager for local agent execution."""
+        tool_output_sharing_enabled = merged_agent_config.get("tool_output_sharing", False)
+        if not tool_output_sharing_enabled:
+            return None
+        if shared_tool_output_manager is not None:
+            return shared_tool_output_manager
+        return build_tool_output_manager(agent.name, merged_agent_config)
+
+    def _inject_hitl_manager(
+        self,
+        local_agent: Any,
+        merged_agent_config: dict[str, Any],
+        agent_name: str,
+        pause_resume_callback: Any | None,
+    ) -> None:
+        """Inject HITL manager when enabled, mirroring remote gating behavior."""
+        hitl_enabled = merged_agent_config.get("hitl_enabled", False)
+        if hitl_enabled:
+            try:
+                from aip_agents.agent.hitl.manager import ApprovalManager  # noqa: PLC0415
+                from glaip_sdk.hitl import LocalPromptHandler  # noqa: PLC0415
+
+                local_agent.hitl_manager = ApprovalManager(
+                    prompt_handler=LocalPromptHandler(pause_resume_callback=pause_resume_callback)
+                )
+                # Store callback reference for setting renderer later
+                if pause_resume_callback:
+                    local_agent._pause_resume_callback = pause_resume_callback
+                logger.debug("HITL manager injected for agent '%s' (hitl_enabled=True)", agent_name)
+            except ImportError as e:
+                # Missing dependencies - fail fast
+                raise ImportError("Local HITL requires aip_agents. Install with: pip install 'glaip-sdk[local]'") from e
+            except Exception as e:
+                # Other errors during HITL setup - fail fast
+                raise RuntimeError(f"Failed to initialize HITL manager for agent '{agent_name}'") from e
+        else:
+            logger.debug("HITL manager not injected for agent '%s' (hitl_enabled=False)", agent_name)
+
     def _build_sub_agents(
         self,
         sub_agents: list[Any] | None,
         runtime_config: dict[str, Any] | None,
+        shared_tool_output_manager: Any | None = None,
     ) -> list[Any]:
         """Build sub-agent instances recursively.
 
         Args:
             sub_agents: List of sub-agent definitions.
             runtime_config: Runtime config to pass to sub-agents.
+            shared_tool_output_manager: Optional ToolOutputManager to reuse across
+                agents with tool_output_sharing enabled.
 
         Returns:
             List of built sub-agent instances.
@@ -255,15 +478,14 @@ class LangGraphRunner(BaseRunner):
 
         sub_agent_instances = []
         for sub_agent in sub_agents:
-            if getattr(sub_agent, "_lookup_only", False):
-                agent_name = getattr(sub_agent, "name", "<unknown>")
-                raise ValueError(
-                    f"Sub-agent '{agent_name}' is not supported in local mode. "
-                    "Platform agents (from_id, from_native) cannot be used as "
-                    "sub-agents in local execution. "
-                    "Define the sub-agent locally with Agent(name=..., instruction=...) instead."
+            self._validate_sub_agent_for_local_mode(sub_agent)
+            sub_agent_instances.append(
+                self.build_langgraph_agent(
+                    sub_agent,
+                    runtime_config,
+                    shared_tool_output_manager=shared_tool_output_manager,
                 )
-            sub_agent_instances.append(self.build_langgraph_agent(sub_agent, runtime_config))
+            )
         return sub_agent_instances
 
     def _add_mcp_servers(
@@ -286,16 +508,12 @@ class LangGraphRunner(BaseRunner):
 
         mcp_adapter = LangChainMCPAdapter()
         base_mcp_configs = mcp_adapter.adapt_mcps(agent.mcps)
-        logger.debug("Base MCP configs from adapter: %s", base_mcp_configs)
 
         # Apply merged mcp_configs overrides (agent definition + runtime)
-        logger.debug("Merged mcp_configs to apply: %s", merged_mcp_configs)
         if merged_mcp_configs:
             base_mcp_configs = self._apply_runtime_mcp_configs(base_mcp_configs, merged_mcp_configs)
-            logger.debug("MCP configs after override: %s", base_mcp_configs)
 
         if base_mcp_configs:
-            logger.info("MCP configs being sent to aip-agents: %s", base_mcp_configs)
             local_agent.add_mcp_server(base_mcp_configs)
             logger.debug(
                 "Registered %d MCP server(s) for agent '%s'",
@@ -361,6 +579,7 @@ class LangGraphRunner(BaseRunner):
         Returns:
             Agent-specific config dict, or empty dict if not found.
         """
+        from glaip_sdk.utils.resource_refs import is_uuid  # noqa: PLC0415
         from glaip_sdk.utils.runtime_config import get_name_from_key  # noqa: PLC0415
 
         # Reserved keys at the top level
@@ -371,6 +590,14 @@ class LangGraphRunner(BaseRunner):
             if key in reserved_keys:
                 continue  # Skip global configs
 
+            if isinstance(key, str) and is_uuid(key):
+                logger.warning(
+                    "UUID agent override key '%s' is not supported in local mode; skipping. "
+                    "Use agent name string or Agent instance as the key instead.",
+                    key,
+                )
+                continue
+
             # Check if this key matches the agent
             try:
                 key_name = get_name_from_key(key)
@@ -505,7 +732,13 @@ class LangGraphRunner(BaseRunner):
         if "planning" in agent_config:
             direct_params["planning"] = agent_config["planning"]
 
+        if "enable_a2a_token_streaming" in agent_config:
+            direct_params["enable_a2a_token_streaming"] = agent_config["enable_a2a_token_streaming"]
+
         # Kwargs parameters (passed through **kwargs to BaseAgent)
+        if "enable_pii" in agent_config:
+            kwargs_params["enable_pii"] = agent_config["enable_pii"]
+
         if "memory" in agent_config:
             # Map "memory" to "memory_backend" for aip-agents compatibility
             kwargs_params["memory_backend"] = agent_config["memory"]
@@ -579,6 +812,49 @@ class LangGraphRunner(BaseRunner):
 
         return merged
 
+    def _validate_sub_agent_for_local_mode(self, sub_agent: Any) -> None:
+        """Validate that a sub-agent reference is supported for local execution.
+
+        Args:
+            sub_agent: The sub-agent reference to validate.
+
+        Raises:
+            ValueError: If the sub-agent is not supported in local mode.
+        """
+        # String references are allowed by SDK API but not for local mode
+        if isinstance(sub_agent, str):
+            raise ValueError(
+                f"Sub-agent '{sub_agent}' is a string reference and cannot be used in local mode. "
+                "String sub-agent references are only supported for server execution. "
+                "For local mode, define the sub-agent with Agent(name=..., instruction=...)."
+            )
+
+        # Validate sub-agent is not a class
+        if inspect.isclass(sub_agent):
+            raise ValueError(
+                f"Sub-agent '{sub_agent.__name__}' is a class, not an instance. "
+                "Local mode requires Agent INSTANCES. "
+                "Did you forget to instantiate it? e.g., Agent(...), not Agent"
+            )
+
+        # Validate sub-agent is an Agent-like object (has required attributes)
+        if not hasattr(sub_agent, "name") or not hasattr(sub_agent, "instruction"):
+            raise ValueError(
+                f"Sub-agent {type(sub_agent).__name__} is not supported in local mode. "
+                "Local mode requires Agent instances with 'name' and 'instruction' attributes. "
+                "Define the sub-agent with Agent(name=..., instruction=...)."
+            )
+
+        # Validate sub-agent is not platform-only (from_id, from_native)
+        if getattr(sub_agent, "_lookup_only", False):
+            agent_name = getattr(sub_agent, "name", "<unknown>")
+            raise ValueError(
+                f"Sub-agent '{agent_name}' is not supported in local mode. "
+                "Platform agents (from_id, from_native) cannot be used as "
+                "sub-agents in local execution. "
+                "Define the sub-agent locally with Agent(name=..., instruction=...) instead."
+            )
+
     def _log_event(self, event: dict[str, Any]) -> None:
         """Log an A2AEvent for verbose debug output.