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

glaip_sdk/agents/base.py

@@ -46,8 +46,6 @@ import inspect
 import logging
 import warnings
 from collections.abc import AsyncGenerator
-
-
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -55,9 +53,15 @@ from glaip_sdk.registry import get_agent_registry, get_mcp_registry, get_tool_re
 from glaip_sdk.utils.resource_refs import is_uuid
 
 if TYPE_CHECKING:
-    from glaip_sdk.models import AgentResponse
+    from glaip_sdk.client.schedules import AgentScheduleManager
+    from glaip_sdk.guardrails import GuardrailManager
+    from glaip_sdk.models import AgentResponse, Model
+    from glaip_sdk.ptc import PTC
     from glaip_sdk.registry import AgentRegistry, MCPRegistry, ToolRegistry
 
+# Import model validation utility
+from glaip_sdk.models._validation import _validate_model
+
 logger = logging.getLogger(__name__)
 
 _AGENT_NOT_DEPLOYED_MSG = "Agent must be deployed before running. Call deploy() first."
@@ -99,11 +103,11 @@ class Agent:
         - instruction: Agent instruction text (required)
         - description: Agent description (default: "")
         - tools: List of tools (default: [])
+        - model: Optional model override (default: None)
         - agents: List of sub-agents (default: [])
         - mcps: List of MCPs (default: [])
         - timeout: Timeout in seconds (default: 300)
         - metadata: Optional metadata dict (default: None)
-        - model: Optional model override (default: None)
         - framework: Agent framework (default: "langchain")
         - version: Agent version (default: "1.0.0")
         - agent_type: Agent type (default: "config")
@@ -130,7 +134,9 @@ class Agent:
         tools: list | None = None,
         agents: list | None = None,
         mcps: list | None = None,
-        model: str | None = _UNSET,  # type: ignore[assignment]
+        model: str | Model | None = _UNSET,  # type: ignore[assignment]
+        guardrail: GuardrailManager | None = None,
+        ptc: PTC | None = None,
         _client: Any = None,
         **kwargs: Any,
     ) -> None:
@@ -147,8 +153,11 @@ class Agent:
             tools: List of tools (Tool classes, SDK Tool objects, or strings).
             agents: List of sub-agents (Agent classes, instances, or strings).
             mcps: List of MCPs.
-            model: Model identifier.
+            model: Model identifier or Model configuration object.
+            guardrail: The guardrail manager for content safety.
+            ptc: PTC configuration for local runs (sandbox code execution).
             _client: Internal client reference (set automatically).
+
             **kwargs: Additional configuration parameters:
                 - timeout: Execution timeout in seconds.
                 - metadata: Optional metadata dictionary.
@@ -159,6 +168,7 @@ class Agent:
                 - tool_configs: Per-tool configuration overrides.
                 - mcp_configs: Per-MCP configuration overrides.
                 - a2a_profile: A2A profile configuration.
+                - ptc: PTC configuration (local runs only).
         """
         # Instance attributes for deployed agents
         self._id = id
@@ -173,7 +183,9 @@ class Agent:
         self._tools = tools
         self._agents = agents
         self._mcps = mcps
-        self._model = model
+        self._model = self._validate_and_set_model(model)
+        self._guardrail = guardrail
+        self._ptc = ptc
         self._language_model_id: str | None = None
         # Extract parameters from kwargs with _UNSET defaults
         self._timeout = kwargs.pop("timeout", Agent._UNSET)  # type: ignore[assignment]
@@ -181,9 +193,25 @@ class Agent:
         self._framework = kwargs.pop("framework", Agent._UNSET)  # type: ignore[assignment]
         self._version = kwargs.pop("version", Agent._UNSET)  # type: ignore[assignment]
         self._agent_type = kwargs.pop("agent_type", Agent._UNSET)  # type: ignore[assignment]
+
+        # Handle 'type' as a legacy alias for 'agent_type'
+        legacy_type = kwargs.pop("type", Agent._UNSET)
+        if legacy_type is not Agent._UNSET:
+            warnings.warn(
+                "The 'type' parameter is deprecated and will be removed in a future version. Use 'agent_type' instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if self._agent_type is Agent._UNSET:
+                self._agent_type = legacy_type
+
         self._agent_config = kwargs.pop("agent_config", Agent._UNSET)  # type: ignore[assignment]
         self._tool_configs = kwargs.pop("tool_configs", Agent._UNSET)  # type: ignore[assignment]
-        self._mcp_configs = kwargs.pop("mcp_configs", Agent._UNSET)  # type: ignore[assignment]
+        mcp_configs = kwargs.pop("mcp_configs", Agent._UNSET)
+        if mcp_configs is not Agent._UNSET and isinstance(mcp_configs, dict):
+            self._mcp_configs = self._normalize_mcp_configs(mcp_configs)
+        else:
+            self._mcp_configs = mcp_configs  # type: ignore[assignment]
         self._a2a_profile = kwargs.pop("a2a_profile", Agent._UNSET)  # type: ignore[assignment]
 
         # Warn about unexpected kwargs
@@ -194,6 +222,30 @@ class Agent:
                 stacklevel=2,
             )
 
+    def _validate_and_set_model(self, model: str | Any) -> str | Any:
+        """Validate and normalize model parameter.
+
+        Supports both string model identifiers and Model objects:
+        - String: Simple model identifier (e.g., "openai/gpt-4o" or OpenAI.GPT_4O)
+        - Model: Model object with credentials/hyperparameters for local execution
+
+        Args:
+            model: Model identifier (string) or Model object.
+
+        Returns:
+            Validated model (string or Model object).
+        """
+        if model is None or model is Agent._UNSET:
+            return model
+
+        from glaip_sdk.models import Model  # noqa: PLC0415
+
+        if isinstance(model, str):
+            return _validate_model(model)
+        elif isinstance(model, Model):
+            return model
+        return model
+
     # ─────────────────────────────────────────────────────────────────
     # Properties (override in subclasses OR pass to __init__)
     # ─────────────────────────────────────────────────────────────────
@@ -338,11 +390,11 @@ class Agent:
         return None
 
     @property
-    def model(self) -> str | None:
+    def model(self) -> str | Model | None:
         """Optional model override.
 
         Returns:
-            Model identifier string or None to use default.
+            Model identifier string, Model object, or None to use default.
         """
         if self._model is not self._UNSET:
             return self._model
@@ -453,6 +505,16 @@ class Agent:
             return self._mcp_configs
         return None
 
+    @property
+    def guardrail(self) -> GuardrailManager | None:
+        """The guardrail manager for content safety."""
+        return self._guardrail
+
+    @property
+    def ptc(self) -> PTC | None:
+        """PTC configuration for local runs (sandbox code execution)."""
+        return self._ptc
+
     @property
     def a2a_profile(self) -> dict[str, Any] | None:
         """A2A (Agent-to-Agent) profile configuration.
@@ -499,6 +561,15 @@ class Agent:
         """
         logger.info("Deploying agent: %s", self.name)
 
+        if self._ptc is not None:
+            warnings.warn(
+                "PTC (Programmatic Tool Calling) is configured but not supported for remote deployments yet. "
+                "PTC will only work for local runs (agent.run(..., local=True)). "
+                "The PTC configuration will not be included in the deployed agent.",
+                UserWarning,
+                stacklevel=2,
+            )
+
         # Resolve tools FIRST - this uploads them and populates the registry
         tool_ids = self._resolve_tools(get_tool_registry())
 
@@ -540,19 +611,33 @@ class Agent:
             "framework": self.framework,
             "version": self.version,
             "agent_type": self.agent_type,
-            "model": self.model,
         }
 
+        if self.model:
+            if isinstance(self.model, str):
+                config["model"] = self.model
+            else:
+                config["model"] = self.model.id
+
         # Handle metadata (default to empty dict if None)
         config["metadata"] = self.metadata or {}
 
         # Handle agent_config with timeout
         # The timeout property is a convenience that maps to agent_config.execution_timeout
-        agent_config = dict(self.agent_config) if self.agent_config else {}
+        raw_config = self.agent_config if self.agent_config is not self._UNSET else {}
+        agent_config = dict(raw_config) if raw_config else {}
+
         if self.timeout and "execution_timeout" not in agent_config:
             agent_config["execution_timeout"] = self.timeout
-        if agent_config:
-            config["agent_config"] = agent_config
+
+        if self.guardrail:
+            from glaip_sdk.guardrails.serializer import (  # noqa: PLC0415
+                serialize_guardrail_manager,
+            )
+
+            agent_config["guardrails"] = serialize_guardrail_manager(self.guardrail)
+
+        config["agent_config"] = agent_config
 
         # Handle tool_configs - resolve tool names/classes to IDs
         if self.tool_configs:
@@ -584,11 +669,20 @@ class Agent:
 
         Returns:
             List of resolved MCP IDs for the API payload.
+
+        Raises:
+            ValueError: If an MCP fails to resolve to a valid ID.
         """
         if not self.mcps:
             return []
 
-        return [registry.resolve(mcp_ref).id for mcp_ref in self.mcps]
+        resolved_ids: list[str] = []
+        for mcp_ref in self.mcps:
+            mcp = registry.resolve(mcp_ref)
+            if not mcp.id:
+                raise ValueError(f"Failed to resolve ID for MCP: {mcp_ref}")
+            resolved_ids.append(mcp.id)
+        return resolved_ids
 
     def _resolve_tools(self, registry: ToolRegistry) -> list[str]:
         """Resolve tool references to IDs using ToolRegistry.
@@ -602,12 +696,20 @@ class Agent:
 
         Returns:
             List of resolved tool IDs for the API payload.
+
+        Raises:
+            ValueError: If a tool fails to resolve to a valid ID.
         """
         if not self.tools:
             return []
 
-        # Resolve each tool reference to a Tool object, extract ID
-        return [registry.resolve(tool_ref).id for tool_ref in self.tools]
+        resolved_ids: list[str] = []
+        for tool_ref in self.tools:
+            tool = registry.resolve(tool_ref)
+            if not tool.id:
+                raise ValueError(f"Failed to resolve ID for tool: {tool_ref}")
+            resolved_ids.append(tool.id)
+        return resolved_ids
 
     def _resolve_tool_configs(self, registry: ToolRegistry) -> dict[str, Any]:
         """Resolve tool_configs keys from tool names/classes to tool IDs.
@@ -650,6 +752,8 @@ class Agent:
             try:
                 # Resolve key (tool name/class) to Tool object, get ID
                 tool = registry.resolve(key)
+                if not tool.id:
+                    raise ValueError(f"Resolved tool has no ID: {key}")
                 resolved[tool.id] = config
             except (ValueError, KeyError) as e:
                 raise ValueError(f"Failed to resolve tool config key: {key}") from e
@@ -685,6 +789,8 @@ class Agent:
                     resolved_id = key
                 else:
                     mcp = registry.resolve(key)
+                    if not mcp.id:
+                        raise ValueError(f"Resolved MCP has no ID: {key}")
                     resolved_id = mcp.id
 
                 if resolved_id in resolved:
@@ -700,7 +806,48 @@ class Agent:
 
         return resolved
 
-    def _resolve_agents(self, registry: AgentRegistry) -> list:
+    def _normalize_mcp_configs(self, mcp_configs: dict[Any, Any]) -> dict[Any, Any]:
+        """Normalize mcp_configs by wrapping misplaced transport keys in 'config'.
+
+        This ensures that flat transport settings (e.g. {'url': '...'}) provided
+        by the user are correctly moved into the 'config' block required by the
+        Platform, ensuring parity between local and remote execution.
+
+        Args:
+            mcp_configs: The raw mcp_configs dictionary.
+
+        Returns:
+            Normalized mcp_configs dictionary.
+        """
+        from glaip_sdk.runner.langgraph import _MCP_TRANSPORT_KEYS  # noqa: PLC0415
+
+        normalized = {}
+        for mcp_key, override in mcp_configs.items():
+            if not isinstance(override, dict):
+                normalized[mcp_key] = override
+                continue
+
+            misplaced = {k: v for k, v in override.items() if k in _MCP_TRANSPORT_KEYS}
+
+            if misplaced:
+                new_override = override.copy()
+                config_block = new_override.get("config", {})
+                if not isinstance(config_block, dict):
+                    config_block = {}
+
+                config_block.update(misplaced)
+                new_override["config"] = config_block
+
+                for k in misplaced:
+                    new_override.pop(k, None)
+
+                normalized[mcp_key] = new_override
+            else:
+                normalized[mcp_key] = override
+
+        return normalized
+
+    def _resolve_agents(self, registry: AgentRegistry) -> list[str]:
         """Resolve sub-agent references using AgentRegistry.
 
         Uses the global AgentRegistry to cache Agent objects across deployments.
@@ -712,12 +859,20 @@ class Agent:
 
         Returns:
             List of resolved agent IDs for the API payload.
+
+        Raises:
+            ValueError: If an agent fails to resolve to a valid ID.
         """
         if not self.agents:
             return []
 
-        # Resolve each agent reference to a deployed Agent, extract ID
-        return [registry.resolve(agent_ref).id for agent_ref in self.agents]
+        resolved_ids: list[str] = []
+        for agent_ref in self.agents:
+            agent = registry.resolve(agent_ref)
+            if not agent.id:
+                raise ValueError(f"Failed to resolve ID for agent: {agent_ref}")
+            resolved_ids.append(agent.id)
+        return resolved_ids
 
     def _create_or_update_agent(
         self,
@@ -793,6 +948,19 @@ class Agent:
 
         return content
 
+    def to_component(self) -> Any:
+        """Convert this Agent into a pipeline-compatible Component.
+
+        The returned AgentComponent wraps this agent instance and allows it
+        to be used within a Pipeline (from gllm-pipeline).
+
+        Returns:
+            An AgentComponent instance wrapping this agent.
+        """
+        from glaip_sdk.agents.component import AgentComponent  # noqa: PLC0415
+
+        return AgentComponent(self)
+
     # =========================================================================
     # API Methods - Available after deploy()
     # =========================================================================
@@ -801,19 +969,42 @@ class Agent:
         """Return a dict representation of the Agent.
 
         Provides Pydantic-style serialization for backward compatibility.
+        This implementation avoids triggering external tool resolution to ensure
+        it remains robust even when the environment is not fully configured.
 
         Args:
             exclude_none: If True, exclude None values from the output.
 
         Returns:
-            Dictionary containing Agent attributes.
+            Dictionary containing Agent attributes. Note: Mutable fields (dicts, lists)
+            are returned as references. Modify with caution or make a deep copy if needed.
         """
+        # Map convenience timeout to agent_config if not already present
+        agent_config = self.agent_config if self.agent_config is not self._UNSET else {}
+        agent_config = dict(agent_config) if agent_config else {}
+
+        if self.timeout and "execution_timeout" not in agent_config:
+            agent_config["execution_timeout"] = self.timeout
+
+        # Handle guardrail serialization without full config build
+        if self.guardrail:
+            try:
+                from glaip_sdk.guardrails.serializer import (  # noqa: PLC0415
+                    serialize_guardrail_manager,
+                )
+
+                agent_config["guardrails"] = serialize_guardrail_manager(self.guardrail)
+            except ImportError:  # pragma: no cover
+                # Serializer not available (optional dependency); skip guardrail data
+                pass
+
         data = {
             "id": self._id,
             "name": self.name,
             "instruction": self.instruction,
             "description": self.description,
-            "type": self.agent_type,
+            "agent_type": self.agent_type,
+            "type": self.agent_type,  # Legacy key for backward compatibility
             "framework": self.framework,
             "version": self.version,
             "tools": self.tools,
@@ -821,13 +1012,16 @@ class Agent:
             "mcps": self.mcps,
             "timeout": self.timeout,
             "metadata": self.metadata,
-            "agent_config": self.agent_config,
+            "model": self.model,
+            "agent_config": agent_config,
             "tool_configs": self.tool_configs,
             "mcp_configs": self.mcp_configs,
             "a2a_profile": self.a2a_profile,
+            "guardrail": self.guardrail,
             "created_at": self._created_at,
             "updated_at": self._updated_at,
         }
+
         if exclude_none:
             return {k: v for k, v in data.items() if v is not None}
         return data
@@ -844,6 +1038,36 @@ class Agent:
         self._client = client
         return self
 
+    @property
+    def schedule(self) -> AgentScheduleManager:
+        """Get the schedule manager for this agent.
+
+        Provides a convenient interface for managing schedules scoped to this agent.
+
+        Returns:
+            AgentScheduleManager for schedule operations
+
+        Raises:
+            ValueError: If agent is not deployed
+            RuntimeError: If agent is not bound to a client
+
+        Example:
+            >>> agent = client.get_agent_by_id("agent-id")
+            >>> schedules = agent.schedule.list()
+            >>> new_schedule = agent.schedule.create(
+            ...     input="Daily task",
+            ...     schedule="0 9 * * 1-5"
+            ... )
+        """
+        if not self.id:
+            raise ValueError(_AGENT_NOT_DEPLOYED_MSG)
+        if not self._client:
+            raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
+
+        from glaip_sdk.client.schedules import AgentScheduleManager  # noqa: PLC0415
+
+        return AgentScheduleManager(self, self._client.schedules)
+
     def _prepare_run_kwargs(
         self,
         message: str,
@@ -892,6 +1116,10 @@ class Agent:
             )
 
         call_kwargs.update(kwargs)
+
+        memory_user_id = call_kwargs.get("memory_user_id")
+        if memory_user_id and not call_kwargs.get("user_id"):
+            call_kwargs["user_id"] = memory_user_id
         return agent_client, call_kwargs
 
     def _get_local_runner_or_raise(self) -> Any:
@@ -911,7 +1139,16 @@ class Agent:
 
         if check_local_runtime_available():
             return get_default_runner()
-        raise ValueError(f"{_AGENT_NOT_DEPLOYED_MSG}\n\n{get_local_runtime_missing_message()}")
+
+        # If agent is not deployed, it *must* use local runtime
+        if not self.id:
+            raise ValueError(f"{_AGENT_NOT_DEPLOYED_MSG}\n\n{get_local_runtime_missing_message()}")
+
+        # If agent IS deployed but local execution was forced (local=True)
+        raise ValueError(
+            f"Local execution override was requested, but local runtime is missing.\n\n"
+            f"{get_local_runtime_missing_message()}"
+        )
 
     def _prepare_local_runner_kwargs(
         self,
@@ -946,6 +1183,7 @@ class Agent:
         self,
         message: str,
         verbose: bool = False,
+        local: bool = False,
         runtime_config: dict[str, Any] | None = None,
         chat_history: list[dict[str, str]] | None = None,
         **kwargs: Any,
@@ -958,9 +1196,13 @@ class Agent:
         - **Local**: When the agent is not deployed and glaip-sdk[local] is installed,
           execution happens locally via aip-agents (no server required).
 
+        You can force local execution for a deployed agent by passing `local=True`.
+
         Args:
             message: The message to send to the agent.
             verbose: If True, print streaming output to console. Defaults to False.
+            local: If True, force local execution even if the agent is deployed.
+                Defaults to False.
             runtime_config: Optional runtime configuration for tools, MCPs, and agents.
                 Keys can be SDK objects, UUIDs, or names. Example:
                 {
@@ -982,16 +1224,19 @@ class Agent:
             RuntimeError: If server-backed execution fails due to client issues.
         """
         # Backend routing: deployed agents use server, undeployed use local (if available)
-        if self.id:
+        if self.id and not local:
             # Server-backed execution path (agent is deployed)
             agent_client, call_kwargs = self._prepare_run_kwargs(
-                message, verbose, runtime_config or kwargs.get("runtime_config"), **kwargs
+                message,
+                verbose,
+                runtime_config or kwargs.get("runtime_config"),
+                **kwargs,
             )
             if chat_history is not None:
                 call_kwargs["chat_history"] = chat_history
             return agent_client.run_agent(**call_kwargs)
 
-        # Local execution path (agent is not deployed)
+        # Local execution path (agent is not deployed OR local=True)
         runner = self._get_local_runner_or_raise()
         local_kwargs = self._prepare_local_runner_kwargs(message, verbose, runtime_config, chat_history, **kwargs)
         return runner.run(**local_kwargs)
@@ -1000,6 +1245,7 @@ class Agent:
         self,
         message: str,
         verbose: bool = False,
+        local: bool = False,
         runtime_config: dict[str, Any] | None = None,
         chat_history: list[dict[str, str]] | None = None,
         **kwargs: Any,
@@ -1012,9 +1258,13 @@ class Agent:
         - **Local**: When the agent is not deployed and glaip-sdk[local] is installed,
           execution happens locally via aip-agents (no server required).
 
+        You can force local execution for a deployed agent by passing `local=True`.
+
         Args:
             message: The message to send to the agent.
             verbose: If True, print streaming output to console. Defaults to False.
+            local: If True, force local execution even if the agent is deployed.
+                Defaults to False.
             runtime_config: Optional runtime configuration for tools, MCPs, and agents.
                 Keys can be SDK objects, UUIDs, or names. Example:
                 {
@@ -1036,10 +1286,13 @@ class Agent:
             RuntimeError: If server-backed execution fails due to client issues.
         """
         # Backend routing: deployed agents use server, undeployed use local (if available)
-        if self.id:
+        if self.id and not local:
             # Server-backed execution path (agent is deployed)
             agent_client, call_kwargs = self._prepare_run_kwargs(
-                message, verbose, runtime_config or kwargs.get("runtime_config"), **kwargs
+                message,
+                verbose,
+                runtime_config or kwargs.get("runtime_config"),
+                **kwargs,
             )
             if chat_history is not None:
                 call_kwargs["chat_history"] = chat_history
@@ -1048,7 +1301,7 @@ class Agent:
                 yield chunk
             return
 
-        # Local execution path (agent is not deployed)
+        # Local execution path (agent is not deployed OR local=True)
         runner = self._get_local_runner_or_raise()
         local_kwargs = self._prepare_local_runner_kwargs(message, verbose, runtime_config, chat_history, **kwargs)
         result = await runner.arun(**local_kwargs)