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

glaip_sdk/agents/base.py

@@ -0,0 +1,1126 @@
+"""Agent class for GL AIP platform.
+
+This module provides the Agent class that serves as the foundation
+for defining agents in glaip-sdk. The Agent class supports both:
+- Direct instantiation for simple agents
+- Subclassing for complex, reusable agent definitions
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+Example - Direct Instantiation:
+    >>> from glaip_sdk.agents import Agent
+    >>>
+    >>> agent = Agent(
+    ...     name="hello_agent",
+    ...     instruction="You are a helpful assistant.",
+    ... )
+    >>> agent.deploy()
+    >>> result = agent.run("Hello!")
+
+Example - Subclassing:
+    >>> from glaip_sdk.agents import Agent
+    >>>
+    >>> class WeatherAgent(Agent):
+    ...     @property
+    ...     def name(self) -> str:
+    ...         return "weather_agent"
+    ...
+    ...     @property
+    ...     def instruction(self) -> str:
+    ...         return "You are a helpful weather assistant."
+    ...
+    ...     @property
+    ...     def tools(self) -> list:
+    ...         return [WeatherAPITool, "web_search"]
+    >>>
+    >>> # Deploy and run the agent
+    >>> agent = WeatherAgent()
+    >>> agent.deploy()
+    >>> result = agent.run("What's the weather?")
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import warnings
+from collections.abc import AsyncGenerator
+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.runner import get_default_runner
+from glaip_sdk.runner.deps import (
+    check_local_runtime_available,
+    get_local_runtime_missing_message,
+)
+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.registry import AgentRegistry, MCPRegistry, ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+_AGENT_NOT_DEPLOYED_MSG = "Agent must be deployed before running. Call deploy() first."
+_CLIENT_NOT_AVAILABLE_MSG = "Client not available. Agent may not have been deployed properly."
+
+
+class Agent:
+    """Agent class for GL AIP platform.
+
+    Supports both direct instantiation and subclassing.
+    The deploy() method updates the agent in-place, so you can use the
+    same instance for deployment and running.
+
+    Direct instantiation (simple):
+        >>> agent = Agent(
+        ...     name="my_agent",
+        ...     instruction="You are helpful.",
+        ...     tools=["web_search"],
+        ... )
+        >>> agent.deploy()
+        >>> result = agent.run("Hello!")
+
+    Subclassing (complex):
+        >>> class MyAgent(Agent):
+        ...     @property
+        ...     def name(self) -> str:
+        ...         return "my_agent"
+        ...
+        ...     @property
+        ...     def instruction(self) -> str:
+        ...         return self.load_instruction_from_file("instructions.md")
+        ...
+        >>> agent = MyAgent()
+        >>> agent.deploy()
+        >>> result = agent.run("Hello!")
+
+    Properties (override in subclass OR pass to __init__):
+        - name: Agent name on the AIP platform (required)
+        - instruction: Agent instruction text (required)
+        - description: Agent description (default: "")
+        - tools: List of tools (default: [])
+        - 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")
+        - agent_config: Agent execution config (default: None)
+        - tool_configs: Per-tool config overrides (default: None)
+        - mcp_configs: Per-MCP config overrides (default: None)
+        - a2a_profile: A2A profile config (default: None)
+
+    Instance attributes (set after deployment or from_response):
+        - id: The agent's unique ID on the platform
+        - _client: Client reference for run/update/delete operations
+    """
+
+    # Sentinel value to detect unset optional params
+    _UNSET = object()
+
+    def __init__(
+        self,
+        name: str | None = None,
+        instruction: str | None = None,
+        *,
+        id: str | None = None,  # noqa: A002 - Allow shadowing builtin for API compat
+        description: str | None = _UNSET,  # type: ignore[assignment]
+        tools: list | None = None,
+        agents: list | None = None,
+        mcps: list | None = None,
+        model: str | None = _UNSET,  # type: ignore[assignment]
+        _client: Any = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize an Agent.
+
+        For direct instantiation, name and instruction are required.
+        For subclassing, override the properties instead.
+
+        Args:
+            name: Agent name (required for direct instantiation).
+            instruction: Agent instruction (required for direct instantiation).
+            id: Agent ID (set after deployment or when created from API response).
+            description: Agent description.
+            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.
+            _client: Internal client reference (set automatically).
+            **kwargs: Additional configuration parameters:
+                - timeout: Execution timeout in seconds.
+                - metadata: Optional metadata dictionary.
+                - framework: Agent framework identifier.
+                - version: Agent version string.
+                - agent_type: Agent type identifier.
+                - agent_config: Agent execution configuration.
+                - tool_configs: Per-tool configuration overrides.
+                - mcp_configs: Per-MCP configuration overrides.
+                - a2a_profile: A2A profile configuration.
+        """
+        # Instance attributes for deployed agents
+        self._id = id
+        self._client = _client
+        self._created_at: str | None = None
+        self._updated_at: str | None = None
+
+        # Store values (None/UNSET means "use property default or override")
+        self._name = name
+        self._instruction = instruction
+        self._description = description
+        self._tools = tools
+        self._agents = agents
+        self._mcps = mcps
+        self._model = model
+        self._language_model_id: str | None = None
+        # Extract parameters from kwargs with _UNSET defaults
+        self._timeout = kwargs.pop("timeout", Agent._UNSET)  # type: ignore[assignment]
+        self._metadata = kwargs.pop("metadata", Agent._UNSET)  # type: ignore[assignment]
+        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]
+        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]
+        self._a2a_profile = kwargs.pop("a2a_profile", Agent._UNSET)  # type: ignore[assignment]
+
+        # Warn about unexpected kwargs
+        if kwargs:
+            warnings.warn(
+                f"Unexpected keyword arguments: {list(kwargs.keys())}. These will be ignored.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+    # ─────────────────────────────────────────────────────────────────
+    # Properties (override in subclasses OR pass to __init__)
+    # ─────────────────────────────────────────────────────────────────
+
+    @property
+    def id(self) -> str | None:  # noqa: A003 - Allow shadowing builtin for API compat
+        """Agent ID on the platform.
+
+        This is set after deployment or when created from an API response.
+
+        Returns:
+            The unique ID or None if not deployed yet.
+        """
+        return self._id
+
+    @id.setter
+    def id(self, value: str | None) -> None:  # noqa: A003
+        """Set the agent ID."""
+        self._id = value
+
+    @property
+    def created_at(self) -> str | None:
+        """Timestamp when the agent was created.
+
+        Returns:
+            ISO format timestamp string or None if not deployed.
+        """
+        return self._created_at
+
+    @created_at.setter
+    def created_at(self, value: str | None) -> None:
+        """Set the created_at timestamp."""
+        self._created_at = value
+
+    @property
+    def updated_at(self) -> str | None:
+        """Timestamp when the agent was last updated.
+
+        Returns:
+            ISO format timestamp string or None if not deployed.
+        """
+        return self._updated_at
+
+    @updated_at.setter
+    def updated_at(self, value: str | None) -> None:
+        """Set the updated_at timestamp."""
+        self._updated_at = value
+
+    @property
+    def name(self) -> str:
+        """Agent name on the AIP platform.
+
+        Returns:
+            The unique identifier name for this agent.
+
+        Raises:
+            ValueError: If name is not provided via __init__ or property override.
+        """
+        if self._name is None:
+            raise ValueError(
+                "Agent name is required. Either pass name to __init__() or override the name property in a subclass."
+            )
+        return self._name
+
+    @property
+    def instruction(self) -> str:
+        """Agent instruction text.
+
+        Returns:
+            The instruction/prompt for the agent.
+
+        Raises:
+            ValueError: If instruction is not provided via __init__ or property
+                override.
+        """
+        if self._instruction is None:
+            raise ValueError(
+                "Agent instruction is required. Either pass instruction to __init__() "
+                "or override the instruction property in a subclass."
+            )
+        return self._instruction
+
+    @property
+    def description(self) -> str:
+        """Agent description.
+
+        Returns:
+            A description of what this agent does. Defaults to empty string.
+        """
+        if self._description is not self._UNSET:
+            return self._description or ""
+        return ""
+
+    @property
+    def tools(self) -> list:
+        """Tools available to this agent.
+
+        Tools can be:
+            - Tool class: Custom tool that will be auto-uploaded
+            - glaip_sdk.models.Tool: SDK Tool object (uses tool.id)
+            - str: Native tool name or ID (resolved by platform)
+
+        Returns:
+            List of tool references. Defaults to empty list.
+        """
+        return self._tools or []
+
+    @property
+    def agents(self) -> list:
+        """Sub-agents available to this agent.
+
+        Sub-agents can be:
+            - Agent class: Will be deployed recursively
+            - glaip_sdk.models.Agent: SDK Agent object (uses agent.id)
+            - str: Agent name or ID (resolved by platform)
+
+        Returns:
+            List of sub-agent references. Defaults to empty list.
+        """
+        return self._agents or []
+
+    @property
+    def timeout(self) -> int:
+        """Agent timeout in seconds.
+
+        Returns:
+            Timeout value in seconds. Defaults to 300.
+        """
+        if self._timeout is not self._UNSET and self._timeout is not None:
+            return self._timeout
+        return 300
+
+    @property
+    def metadata(self) -> dict[str, Any] | None:
+        """Optional metadata dictionary.
+
+        Returns:
+            Metadata dict or None.
+        """
+        if self._metadata is not self._UNSET:
+            return self._metadata
+        return None
+
+    @property
+    def model(self) -> str | None:
+        """Optional model override.
+
+        Returns:
+            Model identifier string or None to use default.
+        """
+        if self._model is not self._UNSET:
+            return self._model
+        return None
+
+    @property
+    def language_model_id(self) -> str | None:
+        """Language model ID from the API.
+
+        Returns:
+            The language model UUID or None.
+        """
+        return self._language_model_id
+
+    @property
+    def framework(self) -> str:
+        """Agent framework identifier.
+
+        Returns:
+            The framework name. Defaults to "langchain".
+        """
+        if self._framework is not self._UNSET and self._framework is not None:
+            return self._framework
+        return "langchain"
+
+    @property
+    def version(self) -> str:
+        """Agent version string.
+
+        Returns:
+            The version identifier. Defaults to "1.0.0".
+        """
+        if self._version is not self._UNSET and self._version is not None:
+            return self._version
+        return "1.0.0"
+
+    @property
+    def agent_type(self) -> str:
+        """Agent type identifier.
+
+        Returns:
+            The agent type. Defaults to "config".
+        """
+        if self._agent_type is not self._UNSET and self._agent_type is not None:
+            return self._agent_type
+        return "config"
+
+    @property
+    def agent_config(self) -> dict[str, Any] | None:
+        """Agent configuration for execution settings.
+
+        This is used for agent-level settings like execution_timeout.
+        Note: The `timeout` property is a convenience shortcut that
+        maps to agent_config.execution_timeout.
+
+        Returns:
+            Agent configuration dict or None.
+        """
+        if self._agent_config is not self._UNSET:
+            return self._agent_config
+        return None
+
+    @property
+    def tool_configs(self) -> dict[Any, dict[str, Any]] | None:
+        """Per-tool configuration overrides.
+
+        A mapping of tool references (classes, names, or IDs) to their
+        configuration overrides. Supports both class keys and string keys.
+
+        Example:
+            >>> @property
+            ... def tool_configs(self):
+            ...     return {
+            ...         MyToolClass: {"api_key": "xxx"},  # Class key
+            ...         "other_tool": {"setting": "value"},  # String key
+            ...     }
+
+        Returns:
+            Tool configurations dict or None.
+        """
+        if self._tool_configs is not self._UNSET:
+            return self._tool_configs
+        return None
+
+    @property
+    def mcps(self) -> list:
+        """MCPs (Model Context Protocols) available to this agent.
+
+        MCPs can be:
+            - glaip_sdk.models.MCP: SDK MCP object (uses mcp.id)
+            - str: MCP name or ID (resolved by platform)
+
+        Returns:
+            List of MCP references. Defaults to empty list.
+        """
+        return self._mcps or []
+
+    @property
+    def mcp_configs(self) -> dict[str, Any] | None:
+        """Per-MCP configuration overrides.
+
+        A mapping of MCP IDs to their configuration overrides.
+
+        Returns:
+            MCP configurations dict or None.
+        """
+        if self._mcp_configs is not self._UNSET:
+            return self._mcp_configs
+        return None
+
+    @property
+    def a2a_profile(self) -> dict[str, Any] | None:
+        """A2A (Agent-to-Agent) profile configuration.
+
+        Configuration for agent-to-agent communication capabilities.
+
+        Returns:
+            A2A profile dict or None.
+        """
+        if self._a2a_profile is not self._UNSET:
+            return self._a2a_profile
+        return None
+
+    def deploy(self) -> Agent:
+        """Deploy this agent (with tools and sub-agents) to GL AIP.
+
+        Performs the following steps:
+            1. Upload custom tools (Tool classes) - cached by ToolRegistry
+            2. Deploy sub-agents recursively (Agent classes) - cached by AgentRegistry
+            3. Resolve tool_configs (requires tools to be in registry first)
+            4. Create/update this agent
+
+        Tools and agents are cached globally by their respective registries
+        to avoid duplicate uploads across deployments.
+
+        After deployment, this Agent instance is updated in-place with:
+            - id: The agent's unique ID on the platform
+            - _client: A client reference for run/update/delete operations
+
+        Returns:
+            Self with id and _client set, ready for run() calls.
+
+        Raises:
+            Exception: If deployment fails due to API error.
+
+        Example:
+            >>> agent = Agent(
+            ...     name="my_agent",
+            ...     instruction="You are helpful.",
+            ... )
+            >>> agent.deploy()
+            >>> print(f"Deployed: {agent.name} (ID: {agent.id})")
+            >>> result = agent.run("Hello!")
+        """
+        logger.info("Deploying agent: %s", self.name)
+
+        # Resolve tools FIRST - this uploads them and populates the registry
+        tool_ids = self._resolve_tools(get_tool_registry())
+
+        # Resolve agents
+        agent_ids = self._resolve_agents(get_agent_registry())
+
+        # Now build config - tool_configs can be resolved because tools are in registry
+        config = self._build_config(get_tool_registry(), get_mcp_registry())
+        config["tools"] = tool_ids
+        config["agents"] = agent_ids
+
+        from glaip_sdk.utils.client import get_client  # noqa: PLC0415
+
+        client = get_client()
+        response = self._create_or_update_agent(config, client, find_agent)
+
+        # Update self with deployed info
+        self._id = response.id
+        self._client = client
+
+        return self
+
+    def _build_config(self, tool_registry: ToolRegistry, mcp_registry: MCPRegistry) -> dict[str, Any]:
+        """Build the base configuration dictionary.
+
+        Args:
+            tool_registry: The tool registry for resolving tool configs.
+            mcp_registry: The MCP registry for resolving MCPs.
+
+        Returns:
+            Dictionary with agent configuration.
+        """
+        config: dict[str, Any] = {
+            "name": self.name,
+            "instruction": self.instruction,
+            "description": self.description,
+            "framework": self.framework,
+            "version": self.version,
+            "agent_type": self.agent_type,
+            "model": self.model,
+        }
+
+        # 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 {}
+        if self.timeout and "execution_timeout" not in agent_config:
+            agent_config["execution_timeout"] = self.timeout
+        if agent_config:
+            config["agent_config"] = agent_config
+
+        # Handle tool_configs - resolve tool names/classes to IDs
+        if self.tool_configs:
+            config["tool_configs"] = self._resolve_tool_configs(tool_registry)
+
+        # Handle MCPs
+        if self.mcps:
+            config["mcps"] = self._resolve_mcps(mcp_registry)
+
+        # Handle mcp_configs - normalize keys to MCP IDs
+        if self.mcp_configs:
+            config["mcp_configs"] = self._resolve_mcp_configs(mcp_registry)
+
+        # Handle a2a_profile
+        if self.a2a_profile:
+            config["a2a_profile"] = self.a2a_profile
+
+        return config
+
+    def _resolve_mcps(self, registry: MCPRegistry) -> list[str]:
+        """Resolve MCP references to IDs using MCPRegistry.
+
+        Uses the global MCPRegistry to cache MCP objects across deployments.
+        The registry handles all MCP types: MCP helpers, strings, dicts,
+        and glaip_sdk.models.MCP objects.
+
+        Args:
+            registry: The MCP registry.
+
+        Returns:
+            List of resolved MCP IDs for the API payload.
+        """
+        if not self.mcps:
+            return []
+
+        return [registry.resolve(mcp_ref).id for mcp_ref in self.mcps]
+
+    def _resolve_tools(self, registry: ToolRegistry) -> list[str]:
+        """Resolve tool references to IDs using ToolRegistry.
+
+        Uses the global ToolRegistry to cache Tool objects across deployments.
+        The registry handles all tool types: Tool classes, LangChain BaseTool,
+        glaip_sdk.models.Tool, and string names.
+
+        Args:
+            registry: The tool registry.
+
+        Returns:
+            List of resolved tool IDs for the API payload.
+        """
+        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]
+
+    def _resolve_tool_configs(self, registry: ToolRegistry) -> dict[str, Any]:
+        """Resolve tool_configs keys from tool names/classes to tool IDs.
+
+        Allows tool_configs to be defined with tool names, class names, or
+        Tool classes as keys. These are resolved to actual tool IDs using
+        the ToolRegistry.
+
+        Supported key formats:
+            - Tool class: SyncReportSchedulerTool
+            - Tool name string: "sync_report_scheduler"
+            - Tool ID (UUID): Passed through unchanged
+
+        Args:
+            registry: The tool registry.
+
+        Returns:
+            Dict with resolved tool IDs as keys and configs as values.
+
+        Example:
+            >>> class MyAgent(Agent):
+            ...     @property
+            ...     def tool_configs(self):
+            ...         return {
+            ...             SyncReportSchedulerTool: {"api_key": "xxx"},
+            ...             "other_tool": {"setting": "value"},
+            ...         }
+        """
+        if not self.tool_configs:
+            return {}
+
+        resolved: dict[str, Any] = {}
+
+        for key, config in self.tool_configs.items():
+            # If key is already a UUID-like string, pass through
+            if isinstance(key, str) and is_uuid(key):
+                resolved[key] = config
+                continue
+
+            try:
+                # Resolve key (tool name/class) to Tool object, get ID
+                tool = registry.resolve(key)
+                resolved[tool.id] = config
+            except (ValueError, KeyError) as e:
+                raise ValueError(f"Failed to resolve tool config key: {key}") from e
+
+        return resolved
+
+    def _resolve_mcp_configs(self, registry: MCPRegistry) -> dict[str, Any]:
+        """Resolve mcp_configs keys from MCP names/objects to MCP IDs.
+
+        Allows mcp_configs to be defined with MCP names, MCP objects, or UUIDs
+        as keys. Keys are resolved to MCP IDs using the MCPRegistry.
+
+        Supported key formats:
+            - MCP object (with id): uses id directly
+            - MCP name string: resolved via registry to ID
+            - MCP ID (UUID string): passed through unchanged
+
+        Args:
+            registry: The MCP registry.
+
+        Returns:
+            Dict with resolved MCP IDs as keys and configs as values.
+        """
+        if not self.mcp_configs:
+            return {}
+
+        resolved: dict[str, Any] = {}
+
+        for key, config in self.mcp_configs.items():
+            try:
+                # If key is already a UUID-like string, pass through
+                if isinstance(key, str) and is_uuid(key):
+                    resolved_id = key
+                else:
+                    mcp = registry.resolve(key)
+                    resolved_id = mcp.id
+
+                if resolved_id in resolved:
+                    raise ValueError(
+                        f"Duplicate mcp_configs entries resolve to the same MCP id '{resolved_id}' (key={key!r})"
+                    )
+
+                resolved[resolved_id] = config
+            except (ValueError, KeyError) as exc:
+                raise ValueError(
+                    f"Failed to resolve mcp config key {key!r} (type={type(key).__name__}): {exc}"
+                ) from exc
+
+        return resolved
+
+    def _resolve_agents(self, registry: AgentRegistry) -> list:
+        """Resolve sub-agent references using AgentRegistry.
+
+        Uses the global AgentRegistry to cache Agent objects across deployments.
+        The registry handles all agent types: Agent classes, instances,
+        glaip_sdk.models.Agent, and string names.
+
+        Args:
+            registry: The agent registry.
+
+        Returns:
+            List of resolved agent IDs for the API payload.
+        """
+        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]
+
+    def _create_or_update_agent(
+        self,
+        config: dict[str, Any],
+        client: Any,
+        find_agent_fn: Any,
+    ) -> AgentResponse:
+        """Create or update the agent on the platform.
+
+        Args:
+            config: The agent configuration dictionary.
+            client: The API client.
+            find_agent_fn: Function to find existing agent by name.
+
+        Returns:
+            The created or updated AgentResponse from the API.
+        """
+        existing = find_agent_fn(self.name)
+
+        if existing:
+            logger.info("Updating existing agent: %s", self.name)
+            updated = client.update_agent(agent_id=existing.id, **config)
+            logger.info("✓ Agent '%s' updated successfully", self.name)
+            return updated
+
+        logger.info("Creating new agent: %s", self.name)
+        created = client.create_agent(**config)
+        logger.info("✓ Agent '%s' created successfully", self.name)
+        return created
+
+    @staticmethod
+    def load_instruction_from_file(
+        path: str,
+        base_path: Path | None = None,
+        variables: dict[str, str] | None = None,
+    ) -> str:
+        """Load instruction text from a markdown file.
+
+        Args:
+            path: File path (absolute or relative to base_path).
+            base_path: Base directory for relative paths. If None, auto-detected
+                from the caller's file location.
+            variables: Template variables for {{variable}} substitution.
+
+        Returns:
+            Loaded instruction text with variables substituted.
+
+        Raises:
+            FileNotFoundError: If the instruction file doesn't exist.
+
+        Example:
+            >>> instruction = Agent.load_instruction_from_file(
+            ...     "instructions/agent.md",
+            ...     variables={"agent_name": "Weather Bot"}
+            ... )
+        """
+        file_path = Path(path)
+
+        if not file_path.is_absolute():
+            if base_path is None:
+                caller_frame = inspect.stack()[1]
+                base_path = Path(caller_frame.filename).parent
+            file_path = base_path / path
+
+        if not file_path.exists():
+            raise FileNotFoundError(f"Instruction file not found: {file_path}")
+
+        content = file_path.read_text(encoding="utf-8")
+
+        if variables:
+            for key, value in variables.items():
+                content = content.replace(f"{{{{{key}}}}}", value)
+
+        return content
+
+    # =========================================================================
+    # API Methods - Available after deploy()
+    # =========================================================================
+
+    def model_dump(self, *, exclude_none: bool = False) -> dict[str, Any]:
+        """Return a dict representation of the Agent.
+
+        Provides Pydantic-style serialization for backward compatibility.
+
+        Args:
+            exclude_none: If True, exclude None values from the output.
+
+        Returns:
+            Dictionary containing Agent attributes.
+        """
+        data = {
+            "id": self._id,
+            "name": self.name,
+            "instruction": self.instruction,
+            "description": self.description,
+            "type": self.agent_type,
+            "framework": self.framework,
+            "version": self.version,
+            "tools": self.tools,
+            "agents": self.agents,
+            "mcps": self.mcps,
+            "timeout": self.timeout,
+            "metadata": self.metadata,
+            "agent_config": self.agent_config,
+            "tool_configs": self.tool_configs,
+            "mcp_configs": self.mcp_configs,
+            "a2a_profile": self.a2a_profile,
+            "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
+
+    def _set_client(self, client: Any) -> Agent:
+        """Set the client for API operations.
+
+        Args:
+            client: The Glaip client instance.
+
+        Returns:
+            Self for method chaining.
+        """
+        self._client = client
+        return self
+
+    def _prepare_run_kwargs(
+        self,
+        message: str,
+        verbose: bool,
+        runtime_config: dict[str, Any] | None,
+        **kwargs: Any,
+    ) -> tuple[Any, dict[str, Any]]:
+        """Prepare common arguments for run/arun methods.
+
+        Args:
+            message: The message to send to the agent.
+            verbose: If True, print streaming output to console.
+            runtime_config: Optional runtime configuration.
+            **kwargs: Additional arguments to pass to the run API.
+
+        Returns:
+            Tuple of (agent_client, call_kwargs).
+
+        Raises:
+            ValueError: If the agent hasn't been deployed yet.
+            RuntimeError: If client is not available.
+        """
+        if not self.id:
+            raise ValueError(_AGENT_NOT_DEPLOYED_MSG)
+        if not self._client:
+            raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
+
+        agent_client = getattr(self._client, "agents", self._client)
+
+        call_kwargs: dict[str, Any] = {
+            "agent_id": self.id,
+            "message": message,
+            "verbose": verbose,
+        }
+
+        if runtime_config is not None:
+            call_kwargs["runtime_config"] = normalize_runtime_config_keys(
+                runtime_config,
+                tool_registry=get_tool_registry(),
+                mcp_registry=get_mcp_registry(),
+                agent_registry=get_agent_registry(),
+            )
+
+        call_kwargs.update(kwargs)
+        return agent_client, call_kwargs
+
+    def run(
+        self,
+        message: str,
+        verbose: 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).
+
+        Args:
+            message: The message to send to the agent.
+            verbose: If True, print streaming output to console. Defaults to False.
+            runtime_config: Optional runtime configuration for tools, MCPs, and agents.
+                Keys can be SDK objects, UUIDs, or names. Example:
+                {
+                    "tool_configs": {"tool-id": {"param": "value"}},
+                    "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 is not deployed and local runtime is not available.
+            RuntimeError: If server-backed execution fails due to client issues.
+        """
+        # Backend routing: deployed agents use server, undeployed use local (if available)
+        if self.id:
+            # 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)
+        if check_local_runtime_available():
+            runner = get_default_runner()
+            return runner.run(
+                agent=self,
+                message=message,
+                verbose=verbose,
+                runtime_config=runtime_config,
+                chat_history=chat_history,
+                **kwargs,
+            )
+
+        # Neither deployed nor local runtime available - provide actionable error
+        raise ValueError(f"{_AGENT_NOT_DEPLOYED_MSG}\n\n{get_local_runtime_missing_message()}")
+
+    async def arun(
+        self,
+        message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> AsyncGenerator[dict, None]:
+        """Run the agent asynchronously with streaming output.
+
+        Args:
+            message: The message to send to the agent.
+            verbose: If True, print streaming output to console.
+            runtime_config: Optional runtime configuration for tools, MCPs, and agents.
+                Keys can be SDK objects, UUIDs, or names. Example:
+                {
+                    "tool_configs": {"tool-id": {"param": "value"}},
+                    "mcp_configs": {"mcp-id": {"setting": "on"}},
+                    "agent_config": {"planning": True},
+                }
+            **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.
+        """
+        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
+
+    def update(self, **kwargs: Any) -> Agent:
+        """Update the deployed agent with new configuration.
+
+        Args:
+            **kwargs: Agent properties to update (name, instruction, etc.).
+
+        Returns:
+            Self with updated properties.
+
+        Raises:
+            ValueError: If the agent hasn't been deployed yet.
+            RuntimeError: If client is not available.
+        """
+        if not self.id:
+            raise ValueError(_AGENT_NOT_DEPLOYED_MSG)
+        if not self._client:
+            raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
+
+        # _client can be either main Client or AgentClient
+        agent_client = getattr(self._client, "agents", self._client)
+        response = agent_client.update_agent(agent_id=self.id, **kwargs)
+
+        # Update local properties from response (read-only props via private attrs)
+        name = getattr(response, "name", None)
+        if name:
+            self._name = name
+
+        instruction = getattr(response, "instruction", None)
+        if instruction:
+            self._instruction = instruction
+
+        # Populate remaining fields like description, metadata, updated_at, etc.
+        type(self)._populate_from_response(self, response)
+
+        return self
+
+    def delete(self) -> None:
+        """Delete the deployed agent.
+
+        Raises:
+            ValueError: If the agent hasn't been deployed yet.
+            RuntimeError: If client is not available.
+        """
+        if not self.id:
+            raise ValueError(_AGENT_NOT_DEPLOYED_MSG)
+        if not self._client:
+            raise RuntimeError(_CLIENT_NOT_AVAILABLE_MSG)
+
+        # _client can be either main Client or AgentClient
+        agent_client = getattr(self._client, "agents", self._client)
+        agent_client.delete_agent(self.id)
+        self.id = None
+        self._client = None
+
+    @classmethod
+    def _populate_from_response(cls, agent: Agent, response: AgentResponse) -> None:
+        """Populate agent fields from API response."""
+        # Field mappings: (response_attr, agent_attr, require_truthy)
+        field_mappings = [
+            ("description", "_description", True),
+            ("model", "_model", True),
+            ("type", "_agent_type", True),
+            ("framework", "_framework", True),
+            ("version", "_version", True),
+            ("timeout", "_timeout", True),
+            ("metadata", "_metadata", True),
+            ("agent_config", "_agent_config", True),
+            ("tool_configs", "_tool_configs", True),
+            ("mcp_configs", "_mcp_configs", True),
+            ("a2a_profile", "_a2a_profile", True),
+            ("language_model_id", "_language_model_id", True),
+            ("created_at", "_created_at", False),
+            ("updated_at", "_updated_at", False),
+        ]
+
+        for resp_attr, agent_attr, require_truthy in field_mappings:
+            value = getattr(response, resp_attr, None)
+            if require_truthy:
+                if value:
+                    setattr(agent, agent_attr, value)
+            else:
+                if value is not None:
+                    setattr(agent, agent_attr, value)
+
+        # Copy relationship refs as-is (preserve full objects for serialization)
+        # Registry resolution handles extracting IDs during deployment
+        tools_val = getattr(response, "tools", None)
+        if tools_val:
+            agent._tools = tools_val
+
+        agents_val = getattr(response, "agents", None)
+        if agents_val:
+            agent._agents = agents_val
+
+        mcps_val = getattr(response, "mcps", None)
+        if mcps_val:
+            agent._mcps = mcps_val
+
+    @classmethod
+    def from_response(
+        cls,
+        response: AgentResponse,
+        client: Any = None,
+    ) -> Agent:
+        """Create an Agent instance from an API response.
+
+        This allows you to work with agents retrieved from the API
+        as full Agent instances with all methods available.
+
+        Args:
+            response: The AgentResponse from an API call.
+            client: The Glaip client instance for API operations.
+
+        Returns:
+            An Agent instance initialized from the response.
+
+        Example:
+            >>> response = client.agents.get("agent-123")
+            >>> agent = Agent.from_response(response, client)
+            >>> result = agent.run("Hello!")
+        """
+        agent = cls(
+            name=response.name,
+            instruction=response.instruction or "",
+            id=response.id,
+        )
+
+        cls._populate_from_response(agent, response)
+
+        if client:
+            agent._set_client(client)
+
+        return agent