glaip-sdk 0.6.19__py3-none-any.whl → 0.7.27__py3-none-any.whl

glaip_sdk/runner/langgraph.py

@@ -1,3 +1,4 @@
+# pylint: disable=duplicate-code
 """LangGraph-based runner for local agent execution.
 
 This module provides the LangGraphRunner which executes glaip-sdk agents
@@ -23,16 +24,20 @@ import logging
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any
 
-from aip_agents.agent.hitl.manager import ApprovalManager  # noqa: PLC0415
 from gllm_core.utils import LoggerManager
 
 from glaip_sdk.client.run_rendering import AgentRunRenderingManager
-from glaip_sdk.hitl import LocalPromptHandler, PauseResumeCallback
+from glaip_sdk.hitl import PauseResumeCallback
+from glaip_sdk.models import DEFAULT_MODEL
 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.runner.ptc_adapter import (
+    normalize_ptc_for_aip_agents,
+    validate_ptc_for_local_run,
+)
 from glaip_sdk.utils.tool_storage_provider import build_tool_output_manager
 
 if TYPE_CHECKING:
@@ -71,6 +76,10 @@ def _swallow_aip_logs(level: int = logging.ERROR) -> None:
 logger = LoggerManager().get_logger(__name__)
 
 
+# Constants for MCP configuration validation
+_MCP_TRANSPORT_KEYS = {"url", "command", "args", "env", "timeout", "headers"}
+
+
 def _convert_chat_history_to_messages(
     chat_history: list[dict[str, str]] | None,
 ) -> list[BaseMessage]:
@@ -86,7 +95,11 @@ def _convert_chat_history_to_messages(
     if not chat_history:
         return []
 
-    from langchain_core.messages import AIMessage, HumanMessage, SystemMessage  # noqa: PLC0415
+    from langchain_core.messages import (  # noqa: PLC0415
+        AIMessage,
+        HumanMessage,
+        SystemMessage,
+    )
 
     messages: list[BaseMessage] = []
     for msg in chat_history:
@@ -121,7 +134,7 @@ class LangGraphRunner(BaseRunner):
             Defaults to "gpt-4o-mini".
     """
 
-    default_model: str = "openai/gpt-4o-mini"
+    default_model: str = DEFAULT_MODEL
 
     def run(
         self,
@@ -259,7 +272,9 @@ class LangGraphRunner(BaseRunner):
 
         # Build the local LangGraphReactAgent from the glaip_sdk Agent
         local_agent = self.build_langgraph_agent(
-            agent, runtime_config=runtime_config, pause_resume_callback=pause_resume_callback
+            agent,
+            runtime_config=runtime_config,
+            pause_resume_callback=pause_resume_callback,
         )
 
         # Convert chat history to LangChain messages for the agent
@@ -305,12 +320,26 @@ class LangGraphRunner(BaseRunner):
                 renderer.close()
             finally:
                 raise
+        finally:
+            # Cleanup PTC sandbox and MCP sessions
+            # Isolated cleanup steps so one failure doesn't skip the other
+            try:
+                await local_agent.cleanup()
+            except Exception as e:
+                logger.warning("Failed to cleanup agent resources: %s", e)
 
         # Use shared finalizer to avoid code duplication
-        from glaip_sdk.client.run_rendering import finalize_render_manager  # noqa: PLC0415
+        from glaip_sdk.client.run_rendering import (  # noqa: PLC0415
+            finalize_render_manager,
+        )
 
         return finalize_render_manager(
-            render_manager, renderer, final_text, stats_usage, started_monotonic, finished_monotonic
+            render_manager,
+            renderer,
+            final_text,
+            stats_usage,
+            started_monotonic,
+            finished_monotonic,
         )
 
     def build_langgraph_agent(
@@ -365,6 +394,17 @@ 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)
 
+        # Validate and normalize PTC configuration for local runs
+        ptc_config = validate_ptc_for_local_run(
+            agent_ptc=agent.ptc if hasattr(agent, "ptc") else None,
+            agent_config_ptc=None,  # Already validated in _merge_agent_config
+            runtime_config_ptc=None,  # Already validated in _normalize_runtime_config
+        )
+        normalized_ptc = normalize_ptc_for_aip_agents(ptc_config)
+
+        # Resolve model and merge its configuration into agent kwargs
+        model_string = self._resolve_local_model(agent, agent_config_kwargs)
+
         tool_output_manager = self._resolve_tool_output_manager(
             agent,
             merged_agent_config,
@@ -378,16 +418,18 @@ class LangGraphRunner(BaseRunner):
             shared_tool_output_manager=tool_output_manager,
         )
 
-        # Build the LangGraphReactAgent with tools, sub-agents, and configs
+        # Build the LangGraphReactAgent with tools, sub-agents, configs, and PTC
         local_agent = LangGraphReactAgent(
             name=agent.name,
             instruction=agent.instruction,
             description=agent.description,
-            model=agent.model or self.default_model,
+            model=model_string,
             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,
+            ptc_config=normalized_ptc,
             **agent_config_params,
             **agent_config_kwargs,
         )
@@ -434,13 +476,22 @@ class LangGraphRunner(BaseRunner):
         hitl_enabled = merged_agent_config.get("hitl_enabled", False)
         if hitl_enabled:
             try:
+                from aip_agents.agent.hitl.manager import (  # noqa: PLC0415
+                    ApprovalManager,
+                )
+
+                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)
+                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
@@ -448,7 +499,10 @@ class LangGraphRunner(BaseRunner):
                 # 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)
+            logger.debug(
+                "HITL manager not injected for agent '%s' (hitl_enabled=False)",
+                agent_name,
+            )
 
     def _build_sub_agents(
         self,
@@ -543,6 +597,14 @@ class LangGraphRunner(BaseRunner):
         if not runtime_config:
             return {}
 
+        # Check for unsupported runtime_config.ptc (v1 constraint)
+        if "ptc" in runtime_config:
+            validate_ptc_for_local_run(
+                agent_ptc=None,
+                agent_config_ptc=None,
+                runtime_config_ptc=runtime_config["ptc"],
+            )
+
         # 1. Extract global configs and normalize keys
         global_tool_configs = normalize_local_config_keys(runtime_config.get("tool_configs", {}))
         global_mcp_configs = normalize_local_config_keys(runtime_config.get("mcp_configs", {}))
@@ -702,6 +764,14 @@ class LangGraphRunner(BaseRunner):
         # Get runtime agent_config
         runtime_agent_config = normalized_config.get("agent_config", {})
 
+        # Check for unsupported agent_config.ptc (local runs constraint)
+        if "ptc" in agent_agent_config or "ptc" in runtime_agent_config:
+            validate_ptc_for_local_run(
+                agent_ptc=None,
+                agent_config_ptc=agent_agent_config.get("ptc") or runtime_agent_config.get("ptc"),
+                runtime_config_ptc=None,
+            )
+
         # Merge: agent definition < runtime config
         return merge_configs(agent_agent_config, runtime_agent_config)
 
@@ -724,6 +794,7 @@ class LangGraphRunner(BaseRunner):
         """
         direct_params = {}
         kwargs_params = {}
+        config_dict = {}
 
         # Direct constructor parameters
         if "planning" in agent_config:
@@ -735,6 +806,7 @@ class LangGraphRunner(BaseRunner):
         # Kwargs parameters (passed through **kwargs to BaseAgent)
         if "enable_pii" in agent_config:
             kwargs_params["enable_pii"] = agent_config["enable_pii"]
+            config_dict["enable_pii"] = agent_config["enable_pii"]
 
         if "memory" in agent_config:
             # Map "memory" to "memory_backend" for aip-agents compatibility
@@ -746,8 +818,73 @@ class LangGraphRunner(BaseRunner):
             if key in agent_config:
                 kwargs_params[key] = agent_config[key]
 
+        # Ensure we pass a config dictionary to BaseAgent, which uses it for
+        # LM configuration (api keys, etc.). Memory settings are passed only
+        # via kwargs to avoid leaking into LM invoker config.
+        if config_dict:
+            kwargs_params["config"] = config_dict
+
         return direct_params, kwargs_params
 
+    def _convert_model_for_local(self, model: Any) -> tuple[str, dict[str, Any]]:
+        """Convert model to aip_agents format for local execution.
+
+        Args:
+            model: Model object or string identifier.
+
+        Returns:
+            Tuple of (model_string, config_dict).
+        """
+        from glaip_sdk.models._validation import (  # noqa: PLC0415
+            convert_model_for_local_execution,
+        )
+
+        return convert_model_for_local_execution(model)
+
+    def _resolve_local_model(self, agent: Agent, agent_config_kwargs: dict[str, Any]) -> str:
+        """Resolve model string and merge its configuration into agent kwargs.
+
+        This method extracts model-specific credentials and hyperparameters from a Model
+        object and merges them into the 'config' dictionary within agent_config_kwargs.
+        This is required because BaseAgent expects LM settings (api keys, etc.) to be
+        inside the 'config' parameter, not top-level kwargs.
+
+        Example:
+            If agent has:
+                - model = Model(id="deepinfra/model", credentials="key-123")
+                - agent_config_kwargs = {"enable_pii": True, "config": {"enable_pii": True}}
+
+            _resolve_local_model will:
+                1. Resolve model_string to "openai-compatible/model"
+                2. Extract model_config as {"lm_api_key": "key-123"}
+                3. Update agent_config_kwargs["config"] to:
+                   {"enable_pii": True, "lm_api_key": "key-123"}
+
+        Args:
+            agent: The glaip_sdk Agent.
+            agent_config_kwargs: Agent config kwargs to update (modified in-place).
+
+        Returns:
+            The model identifier string for local execution.
+        """
+        model_to_use = agent.model or self.default_model
+        model_string, model_config = self._convert_model_for_local(model_to_use)
+
+        if model_config:
+            # Normalize config to a dict early to simplify merging
+            config_val = agent_config_kwargs.get("config", {})
+            if hasattr(config_val, "model_dump"):
+                config_val = config_val.model_dump()
+
+            if not isinstance(config_val, dict):
+                config_val = {}
+
+            # Use a single merge path for model configuration
+            config_val.update(model_config)
+            agent_config_kwargs["config"] = config_val
+
+        return model_string
+
     def _apply_runtime_mcp_configs(
         self,
         base_configs: dict[str, Any],
@@ -776,39 +913,126 @@ class LangGraphRunner(BaseRunner):
         base_config: dict[str, Any],
         override: dict[str, Any] | None,
     ) -> dict[str, Any]:
-        """Merge a single MCP config with runtime override.
+        """Merge a single MCP config with a runtime override, handling normalization and parity fixes.
+
+        This method orchestrates the merging of base MCP settings (from the object definition)
+        with runtime overrides. It enforces Platform parity by prioritizing the nested 'config'
+        block while maintaining robustness for local development by auto-fixing flat transport keys.
+
+        The merge follows these priority rules (highest to lowest):
+        1. Misplaced flat keys in the override (e.g., 'url' at top level) - Auto-fixed with warning.
+        2. Nested 'config' block in the override (Matches Platform/Constructor schema).
+        3. Authentication objects in the override (Converted to HTTP headers).
+        4. Structural settings in the override (e.g., 'allowed_tools').
+        5. Base configuration from the MCP object definition.
+
+        Examples:
+            >>> # 1. Strict Nested Style (Recommended)
+            >>> override = {"config": {"url": "https://new.api"}, "allowed_tools": ["t1"]}
+            >>> self._merge_single_mcp_config("mcp", base, override)
+            >>> # Result: {"url": "https://new.api", "allowed_tools": ["t1"], ...}
+
+            >>> # 2. Flat Legacy Style (Auto-fixed with warning)
+            >>> override = {"url": "https://new.api"}
+            >>> self._merge_single_mcp_config("mcp", base, override)
+            >>> # Result: {"url": "https://new.api", ...}
+
+            >>> # 3. Header Merging (Preserves Auth)
+            >>> base = {"headers": {"Authorization": "Bearer token"}}
+            >>> override = {"headers": {"X-Custom": "val"}}
+            >>> self._merge_single_mcp_config("mcp", base, override)
+            >>> # Result: {"headers": {"Authorization": "Bearer token", "X-Custom": "val"}, ...}
 
         Args:
-            server_name: Name of the MCP server.
-            base_config: Base config from adapter.
-            override: Optional runtime override config.
+            server_name: Name of the MCP server being configured.
+            base_config: Base configuration dictionary derived from the MCP object.
+            override: Optional dictionary of runtime overrides.
 
         Returns:
-            Merged config dict.
+            A fully merged and normalized configuration dictionary ready for the local runner.
         """
         merged = base_config.copy()
 
         if not override:
             return merged
 
-        from glaip_sdk.runner.mcp_adapter.mcp_config_builder import (  # noqa: PLC0415
-            MCPConfigBuilder,
-        )
+        # 1. Check for misplaced keys and warn (DX/Parity guidance)
+        self._warn_if_mcp_override_misplaced(server_name, override)
+
+        # 2. Apply Authentication (Converted to headers)
+        self._apply_mcp_auth_override(server_name, merged, override)
+
+        # 3. Apply Transport Settings (Nested 'config')
+        if "config" in override and isinstance(override["config"], dict):
+            merged.update(override["config"])
 
-        # Handle authentication override
-        if "authentication" in override:
-            headers = MCPConfigBuilder.build_headers_from_auth(override["authentication"])
-            if headers:
-                merged["headers"] = headers
-                logger.debug("Applied runtime authentication headers for MCP '%s'", server_name)
+        # 4. Apply Structural Settings (e.g., allowed_tools)
+        if "allowed_tools" in override:
+            merged["allowed_tools"] = override["allowed_tools"]
 
-        # Merge other config keys (excluding authentication since we converted it)
+        # 5. Preserve unknown top-level keys (backward compatibility)
+        known_keys = _MCP_TRANSPORT_KEYS | {"config", "authentication", "allowed_tools"}
         for key, value in override.items():
-            if key != "authentication":
+            if key not in known_keys:
                 merged[key] = value
 
+        # 6. Apply Auto-fix for misplaced keys (Local Success)
+        for key in [k for k in override if k in _MCP_TRANSPORT_KEYS]:
+            val = override[key]
+            # Special case: Merge headers instead of overwriting to preserve auth
+            if key == "headers" and isinstance(val, dict) and isinstance(merged.get("headers"), dict):
+                merged["headers"].update(val)
+            else:
+                merged[key] = val
+
         return merged
 
+    def _warn_if_mcp_override_misplaced(self, server_name: str, override: dict[str, Any]) -> None:
+        """Log a warning if transport keys are found at the top level of an override.
+
+        Args:
+            server_name: Name of the MCP server.
+            override: The raw override dictionary.
+        """
+        misplaced = [k for k in override if k in _MCP_TRANSPORT_KEYS]
+        if misplaced:
+            logger.warning(
+                "MCP '%s' override contains transport keys at the top level: %s. "
+                "This structure is inconsistent with the Platform and MCP constructor. "
+                "Transport settings should be nested within a 'config' dictionary. "
+                "Example: mcp_configs={'%s': {'config': {'%s': '...'}}}. "
+                "Automatically merging top-level keys for local execution parity.",
+                server_name,
+                misplaced,
+                server_name,
+                misplaced[0],
+            )
+
+    def _apply_mcp_auth_override(
+        self,
+        server_name: str,
+        merged_config: dict[str, Any],
+        override: dict[str, Any],
+    ) -> None:
+        """Convert authentication override to headers and apply to config.
+
+        Args:
+            server_name: Name of the MCP server.
+            merged_config: The configuration being built (mutated in place).
+            override: The raw override dictionary.
+        """
+        if "authentication" not in override:
+            return
+
+        from glaip_sdk.runner.mcp_adapter.mcp_config_builder import (  # noqa: PLC0415
+            MCPConfigBuilder,
+        )
+
+        headers = MCPConfigBuilder.build_headers_from_auth(override["authentication"])
+        if headers:
+            merged_config["headers"] = headers
+            logger.debug("Applied runtime authentication headers for MCP '%s'", server_name)
+
     def _validate_sub_agent_for_local_mode(self, sub_agent: Any) -> None:
         """Validate that a sub-agent reference is supported for local execution.
 

glaip_sdk/runner/logging_config.py

@@ -0,0 +1,77 @@
+"""Logging configuration for CLI to suppress noisy dependency warnings.
+
+This module provides centralized logging suppression for optional dependencies
+that emit noisy warnings during CLI usage. Warnings are suppressed by default
+but can be shown using GLAIP_LOG_LEVEL=DEBUG.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import logging
+import os
+import warnings
+
+NOISY_LOGGERS = ["transformers", "gllm_privacy", "google.cloud.aiplatform"]
+
+
+class NameFilter(logging.Filter):
+    """Filter logs by logger name prefix."""
+
+    def __init__(self, prefixes: list[str]) -> None:
+        """Initialize filter with logger name prefixes to suppress.
+
+        Args:
+            prefixes: List of logger name prefixes to filter out.
+        """
+        super().__init__()
+        self.prefixes = prefixes
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Filter log records by name prefix.
+
+        Args:
+            record: Log record to filter.
+
+        Returns:
+            False if record should be suppressed, True otherwise.
+        """
+        return not any(record.name.startswith(p) for p in self.prefixes)
+
+
+def setup_cli_logging() -> None:
+    """Suppress INFO from noisy third-party libraries.
+
+    Use GLAIP_LOG_LEVEL=DEBUG to see all warnings.
+    This function is idempotent - calling it multiple times is safe.
+    """
+    # Check env level FIRST before any suppression
+    env_level = os.getenv("GLAIP_LOG_LEVEL", "").upper()
+    is_debug = env_level == "DEBUG"
+
+    if is_debug:
+        # Debug mode: show everything, no suppression
+        if env_level and hasattr(logging, env_level):
+            logging.basicConfig(level=getattr(logging, env_level))
+        return
+
+    # Default mode: suppress noisy warnings
+    if env_level and hasattr(logging, env_level):
+        logging.basicConfig(level=getattr(logging, env_level))
+
+    # Add handler filter to suppress by name prefix (handles child loggers)
+    # Check if filter already exists to ensure idempotency
+    root_logger = logging.getLogger()
+    has_name_filter = any(isinstance(f, NameFilter) for h in root_logger.handlers for f in h.filters)
+
+    if not has_name_filter:
+        handler = logging.StreamHandler()
+        handler.addFilter(NameFilter(NOISY_LOGGERS))
+        root_logger.addHandler(handler)
+
+    # Suppress FutureWarning for GCS (idempotent - multiple calls are safe)
+    warnings.filterwarnings(
+        "ignore",
+        category=FutureWarning,
+        message=r".*google-cloud-storage.*",
+    )

glaip_sdk/runner/mcp_adapter/mcp_config_builder.py

@@ -60,19 +60,42 @@ class MCPConfigBuilder:
     def _handle_custom_header(authentication: dict[str, Any]) -> dict[str, str] | None:
         """Handle custom-header auth type."""
         headers = authentication.get("headers")
-        if isinstance(headers, dict) and all(isinstance(k, str) and isinstance(v, str) for k, v in headers.items()):
-            return headers
-        logger.warning("custom-header auth requires 'headers' dict with string keys/values")
+        if isinstance(headers, dict):
+            cleaned_headers = MCPConfigBuilder._clean_headers(headers)
+            if cleaned_headers:
+                return cleaned_headers
+
+        logger.warning("custom-header auth requires 'headers' dict with at least one non-null key/value")
         return None
 
+    @staticmethod
+    def _clean_headers(headers: dict[str, Any]) -> dict[str, str] | None:
+        """Clean header dict by filtering None keys/values and stringifying values.
+
+        Args:
+            headers: Raw headers dict potentially containing None or non-string values.
+
+        Returns:
+            Cleaned headers dict with string keys/values, or None if empty after cleaning.
+        """
+        cleaned: dict[str, str] = {}
+        for key, value in headers.items():
+            if key is None:
+                logger.warning("Dropping header with null key")
+                continue
+            if value is None:
+                logger.warning("Dropping header '%s' with null value", key)
+                continue
+            cleaned[str(key)] = str(value)
+
+        return cleaned if cleaned else None
+
     @staticmethod
     def _handle_bearer_token(authentication: dict[str, Any]) -> dict[str, str] | None:
         """Handle bearer-token auth type."""
-        # Check if headers provided directly
         headers = authentication.get("headers")
         if isinstance(headers, dict):
-            return headers
-        # Otherwise build from token
+            return MCPConfigBuilder._clean_headers(headers)
         token = authentication.get("token")
         if token:
             return {"Authorization": f"Bearer {token}"}
@@ -82,11 +105,9 @@ class MCPConfigBuilder:
     @staticmethod
     def _handle_api_key(authentication: dict[str, Any]) -> dict[str, str] | None:
         """Handle api-key auth type."""
-        # Check if headers provided directly
         headers = authentication.get("headers")
         if isinstance(headers, dict):
-            return headers
-        # Otherwise build from key/value
+            return MCPConfigBuilder._clean_headers(headers)
         key = authentication.get("key")
         value = authentication.get("value")
         if key and value:

glaip_sdk/runner/ptc_adapter.py

@@ -0,0 +1,98 @@
+"""PTC adapter for local runner integration.
+
+This module provides validation and normalization of PTC configuration
+for use in the local LangGraph runner. It ensures PTC is configured
+correctly and rejects unsupported configuration sources.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from glaip_sdk.exceptions import ValidationError
+
+if TYPE_CHECKING:
+    from glaip_sdk.ptc import PTC
+
+
+def validate_ptc_for_local_run(
+    agent_ptc: PTC | None,
+    agent_config_ptc: Any | None,
+    runtime_config_ptc: Any | None,
+) -> PTC | None:
+    """Validate PTC configuration for local runs.
+
+    Args:
+        agent_ptc: PTC object from Agent.ptc parameter.
+        agent_config_ptc: PTC from agent_config (should be None for local).
+        runtime_config_ptc: PTC from runtime_config (should be None for v1).
+
+    Returns:
+        Validated PTC object if enabled, None otherwise.
+
+    Raises:
+        ValidationError: If agent_config.ptc or runtime_config.ptc are provided,
+            or if agent_ptc is not a PTC instance when provided.
+    """
+    if agent_config_ptc is not None:
+        msg = (
+            "PTC configuration via agent_config.ptc is not supported for local runs. "
+            "Please configure PTC using the Agent.ptc parameter instead: "
+            "Agent(name='...', ptc=PTC(enabled=True), ...)"
+        )
+        raise ValidationError(msg)
+
+    if runtime_config_ptc is not None:
+        msg = (
+            "PTC configuration via runtime_config.ptc is not supported in v1. "
+            "PTC configuration must be set at Agent initialization time using "
+            "the Agent.ptc parameter and cannot be overridden at runtime. "
+            "This preserves local/remote parity and prevents ambiguous precedence."
+        )
+        raise ValidationError(msg)
+
+    if agent_ptc is None:
+        return None
+
+    from glaip_sdk.ptc import PTC  # noqa: PLC0415
+
+    if not isinstance(agent_ptc, PTC):
+        msg = (
+            f"Agent.ptc must be a PTC instance, got {type(agent_ptc).__name__}. "
+            "Example: Agent(name='...', ptc=PTC(enabled=True), ...)"
+        )
+        raise ValidationError(msg)
+
+    if not agent_ptc.enabled:
+        return None
+
+    return agent_ptc
+
+
+def normalize_ptc_for_aip_agents(ptc: PTC | None) -> Any:
+    """Normalize PTC config for aip-agents LangGraphReactAgent.
+
+    Args:
+        ptc: Validated PTC object or None.
+
+    Returns:
+        PTCSandboxConfig for aip-agents or None if PTC disabled.
+    """
+    if ptc is None or not ptc.enabled:
+        return None
+
+    from aip_agents.ptc import PromptConfig, PTCSandboxConfig  # noqa: PLC0415
+
+    # Build PromptConfig if prompt dict is provided.
+    prompt_config = None
+    if ptc.prompt is not None:
+        prompt_config = PromptConfig(**ptc.prompt)
+
+    return PTCSandboxConfig(
+        enabled=ptc.enabled,
+        sandbox_timeout=ptc.sandbox_timeout,
+        prompt=prompt_config,
+    )