glaip-sdk 0.6.5b3__py3-none-any.whl → 0.7.17__py3-none-any.whl

glaip_sdk/agents/base.py

@@ -50,14 +50,17 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
 from glaip_sdk.registry import get_agent_registry, get_mcp_registry, get_tool_registry
-from glaip_sdk.utils.discovery import find_agent
 from glaip_sdk.utils.resource_refs import is_uuid
-from glaip_sdk.utils.runtime_config import normalize_runtime_config_keys
 
 if TYPE_CHECKING:
-    from glaip_sdk.models import AgentResponse
+    from glaip_sdk.client.schedules import AgentScheduleManager
+    from glaip_sdk.models import AgentResponse, Model
+    from glaip_sdk.guardrails import GuardrailManager
     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 +102,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 +133,8 @@ 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,
         _client: Any = None,
         **kwargs: Any,
     ) -> None:
@@ -147,8 +151,10 @@ 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.
             _client: Internal client reference (set automatically).
+
             **kwargs: Additional configuration parameters:
                 - timeout: Execution timeout in seconds.
                 - metadata: Optional metadata dictionary.
@@ -173,7 +179,8 @@ 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._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 +188,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 +217,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 +385,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 +500,11 @@ 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 a2a_profile(self) -> dict[str, Any] | None:
         """A2A (Agent-to-Agent) profile configuration.
@@ -513,6 +565,8 @@ class Agent:
         from glaip_sdk.utils.client import get_client  # noqa: PLC0415
 
         client = get_client()
+        from glaip_sdk.utils.discovery import find_agent  # noqa: PLC0415
+
         response = self._create_or_update_agent(config, client, find_agent)
 
         # Update self with deployed info
@@ -538,19 +592,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:
@@ -582,11 +650,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.
@@ -600,12 +677,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.
@@ -648,6 +733,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
@@ -683,6 +770,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:
@@ -698,7 +787,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.
@@ -710,12 +840,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,
@@ -799,19 +937,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,
@@ -819,13 +980,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
@@ -842,6 +1006,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,
@@ -864,7 +1058,7 @@ class Agent:
             ValueError: If the agent hasn't been deployed yet.
             RuntimeError: If client is not available.
         """
-        if not self.id:
+        if not self.id:  # pragma: no cover - defensive: called only when self.id is truthy
             raise ValueError(_AGENT_NOT_DEPLOYED_MSG)
         if not self._client:
             raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
@@ -878,6 +1072,10 @@ class Agent:
         }
 
         if runtime_config is not None:
+            from glaip_sdk.utils.runtime_config import (  # noqa: PLC0415
+                normalize_runtime_config_keys,
+            )
+
             call_kwargs["runtime_config"] = normalize_runtime_config_keys(
                 runtime_config,
                 tool_registry=get_tool_registry(),
@@ -888,18 +1086,87 @@ class Agent:
         call_kwargs.update(kwargs)
         return agent_client, call_kwargs
 
+    def _get_local_runner_or_raise(self) -> Any:
+        """Get the local runner if available, otherwise raise ValueError.
+
+        Returns:
+            The default local runner instance.
+
+        Raises:
+            ValueError: If local runtime is not available.
+        """
+        from glaip_sdk.runner import get_default_runner  # noqa: PLC0415
+        from glaip_sdk.runner.deps import (  # noqa: PLC0415
+            check_local_runtime_available,
+            get_local_runtime_missing_message,
+        )
+
+        if check_local_runtime_available():
+            return get_default_runner()
+
+        # 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,
+        message: str,
+        verbose: bool,
+        runtime_config: dict[str, Any] | None,
+        chat_history: list[dict[str, str]] | None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Prepare kwargs for local runner execution.
+
+        Args:
+            message: The message to send to the agent.
+            verbose: If True, print streaming output to console.
+            runtime_config: Optional runtime configuration.
+            chat_history: Optional list of prior conversation messages.
+            **kwargs: Additional arguments.
+
+        Returns:
+            Dictionary of prepared kwargs for runner.run() or runner.arun().
+        """
+        return {
+            "agent": self,
+            "message": message,
+            "verbose": verbose,
+            "runtime_config": runtime_config,
+            "chat_history": chat_history,
+            **kwargs,
+        }
+
     def run(
         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,
     ) -> str:
         """Run the agent synchronously with a message.
 
+        Supports two execution modes:
+        - **Server-backed**: When the agent is deployed (has an ID), execution
+          happens via the AIP backend server.
+        - **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.
+            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:
                 {
@@ -907,32 +1174,61 @@ class Agent:
                     "mcp_configs": {"mcp-id": {"setting": "on"}},
                     "agent_config": {"planning": True},
                 }
+                Defaults to None.
+            chat_history: Optional list of prior conversation messages for context.
+                Each message is a dict with "role" and "content" keys.
+                Defaults to None.
             **kwargs: Additional arguments to pass to the run API.
 
         Returns:
             The agent's response as a string.
 
         Raises:
-            ValueError: If the agent hasn't been deployed yet.
-            RuntimeError: If client is not available.
+            ValueError: If the agent is not deployed and local runtime is not available.
+            RuntimeError: If server-backed execution fails due to client issues.
         """
-        agent_client, call_kwargs = self._prepare_run_kwargs(
-            message, verbose, runtime_config or kwargs.get("runtime_config"), **kwargs
-        )
-        return agent_client.run_agent(**call_kwargs)
+        # Backend routing: deployed agents use server, undeployed use local (if available)
+        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,
+            )
+            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 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)
 
     async def arun(
         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,
     ) -> AsyncGenerator[dict, None]:
         """Run the agent asynchronously with streaming output.
 
+        Supports two execution modes:
+        - **Server-backed**: When the agent is deployed (has an ID), execution
+          happens via the AIP backend server with streaming.
+        - **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.
+            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:
                 {
@@ -940,20 +1236,47 @@ class Agent:
                     "mcp_configs": {"mcp-id": {"setting": "on"}},
                     "agent_config": {"planning": True},
                 }
+                Defaults to None.
+            chat_history: Optional list of prior conversation messages for context.
+                Each message is a dict with "role" and "content" keys.
+                Defaults to None.
             **kwargs: Additional arguments to pass to the run API.
 
         Yields:
             Streaming response chunks from the agent.
 
         Raises:
-            ValueError: If the agent hasn't been deployed yet.
-            RuntimeError: If client is not available.
+            ValueError: If the agent is not deployed and local runtime is not available.
+            RuntimeError: If server-backed execution fails due to client issues.
         """
-        agent_client, call_kwargs = self._prepare_run_kwargs(
-            message, verbose, runtime_config or kwargs.get("runtime_config"), **kwargs
-        )
-        async for chunk in agent_client.arun_agent(**call_kwargs):
-            yield chunk
+        # Backend routing: deployed agents use server, undeployed use local (if available)
+        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,
+            )
+            if chat_history is not None:
+                call_kwargs["chat_history"] = chat_history
+
+            async for chunk in agent_client.arun_agent(**call_kwargs):
+                yield chunk
+            return
+
+        # 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)
+        # Yield a final_response event for consistency with server-backed execution
+        # Include event_type for A2A event shape parity
+        yield {
+            "event_type": "final_response",
+            "metadata": {"kind": "final_response"},
+            "content": result,
+            "is_final": True,
+        }
 
     def update(self, **kwargs: Any) -> Agent:
         """Update the deployed agent with new configuration.