glaip-sdk 0.6.6__py3-none-any.whl → 0.6.9__py3-none-any.whl

glaip_sdk/agents/base.py

@@ -46,10 +46,17 @@ 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
@@ -864,7 +871,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)
@@ -888,18 +895,67 @@ 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.
+        """
+        if check_local_runtime_available():
+            return get_default_runner()
+        raise ValueError(f"{_AGENT_NOT_DEPLOYED_MSG}\n\n{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,
         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.
+            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:
                 {
@@ -907,32 +963,53 @@ 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:
+            # 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)
+        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,
         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).
+
         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.
             runtime_config: Optional runtime configuration for tools, MCPs, and agents.
                 Keys can be SDK objects, UUIDs, or names. Example:
                 {
@@ -940,20 +1017,44 @@ 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:
+            # 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)
+        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.

glaip_sdk/cli/commands/configure.py

@@ -22,7 +22,7 @@ from glaip_sdk.branding import ACCENT_STYLE, ERROR_STYLE, INFO, NEUTRAL, SUCCESS
 # Optional import for gitignore support; warn when missing to avoid silent expansion
 try:
     import pathspec  # type: ignore[import-untyped]  # noqa: PLC0415
-except ImportError:
+except ImportError:  # pragma: no cover - optional dependency
     pathspec = None  # type: ignore[assignment]
 from glaip_sdk.cli.account_store import get_account_store
 from glaip_sdk.cli.commands.common_config import check_connection, render_branding_header

glaip_sdk/registry/tool.py

@@ -160,19 +160,13 @@ class ToolRegistry(BaseRegistry["Tool"]):
             True if ref is a custom tool that needs uploading.
         """
         try:
-            from langchain_core.tools import BaseTool  # noqa: PLC0415
-
-            # LangChain BaseTool class
-            if isinstance(ref, type) and issubclass(ref, BaseTool):
-                return True
-
-            # LangChain BaseTool instance
-            if isinstance(ref, BaseTool):
-                return True
+            from glaip_sdk.utils.tool_detection import (  # noqa: PLC0415
+                is_langchain_tool,
+            )
         except ImportError:
-            pass
+            return False
 
-        return False
+        return is_langchain_tool(ref)
 
     def resolve(self, ref: Any) -> Tool:
         """Resolve a tool reference to a platform Tool object.

glaip_sdk/runner/__init__.py

@@ -0,0 +1,59 @@
+"""Local agent execution runners.
+
+This module provides runners for executing glaip-sdk agents locally
+without requiring the AIP backend server. The primary runner is
+LangGraphRunner which uses the aip-agents library.
+
+To use local execution, install with the [local] extra:
+    pip install "glaip-sdk[local]"
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+Example:
+    >>> from glaip_sdk.runner import get_default_runner
+    >>> from glaip_sdk.agents import Agent
+    >>>
+    >>> agent = Agent(name="my-agent", instruction="You are helpful.")
+    >>> runner = get_default_runner()
+    >>> result = runner.run(agent, "Hello!")
+"""
+
+from glaip_sdk.runner.deps import (
+    LOCAL_RUNTIME_AVAILABLE,
+    check_local_runtime_available,
+    get_local_runtime_missing_message,
+)
+from glaip_sdk.runner.langgraph import LangGraphRunner
+
+# Default runner instance
+_default_runner: LangGraphRunner | None = None
+
+
+def get_default_runner() -> LangGraphRunner:
+    """Get the default runner instance for local agent execution.
+
+    Returns:
+        The default LangGraphRunner instance.
+
+    Raises:
+        RuntimeError: If local runtime dependencies are not available.
+    """
+    global _default_runner
+
+    if not check_local_runtime_available():
+        raise RuntimeError(get_local_runtime_missing_message())
+
+    if _default_runner is None:
+        _default_runner = LangGraphRunner()
+
+    return _default_runner
+
+
+__all__ = [
+    "LOCAL_RUNTIME_AVAILABLE",
+    "LangGraphRunner",
+    "check_local_runtime_available",
+    "get_default_runner",
+    "get_local_runtime_missing_message",
+]

glaip_sdk/runner/base.py

@@ -0,0 +1,84 @@
+"""Abstract base class for agent execution runners.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from glaip_sdk.agents.base import Agent
+
+
+class BaseRunner(ABC):
+    """Abstract base class for agent execution runners.
+
+    Runners are responsible for executing glaip-sdk Agent instances
+    and returning results. Different runner implementations may use
+    different execution backends (LangGraph, Google ADK, etc.).
+    """
+
+    @abstractmethod
+    def run(
+        self,
+        agent: Agent,
+        message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,
+        chat_history: list[dict[str, str]] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute agent synchronously and return final response text.
+
+        Args:
+            agent: The glaip_sdk Agent to execute.
+            message: The user message to send to the agent.
+            verbose: If True, emit debug trace output during execution.
+                Defaults to False.
+            runtime_config: Optional runtime configuration for tools, MCPs, etc.
+                Defaults to None.
+            chat_history: Optional list of prior conversation messages.
+                Defaults to None.
+            **kwargs: Additional keyword arguments passed to the backend.
+
+        Returns:
+            The final response text from the agent.
+
+        Raises:
+            RuntimeError: If execution fails.
+        """
+        ...
+
+    @abstractmethod
+    async def arun(
+        self,
+        agent: Agent,
+        message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,
+        chat_history: list[dict[str, str]] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute agent asynchronously and return final response text.
+
+        Args:
+            agent: The glaip_sdk Agent to execute.
+            message: The user message to send to the agent.
+            verbose: If True, emit debug trace output during execution.
+                Defaults to False.
+            runtime_config: Optional runtime configuration for tools, MCPs, etc.
+                Defaults to None.
+            chat_history: Optional list of prior conversation messages.
+                Defaults to None.
+            **kwargs: Additional keyword arguments passed to the backend.
+
+        Returns:
+            The final response text from the agent.
+
+        Raises:
+            RuntimeError: If execution fails.
+        """
+        ...

glaip_sdk/runner/deps.py

@@ -0,0 +1,115 @@
+"""Dependency detection utilities for the runner module.
+
+This module provides helpers to detect whether the local runtime dependencies
+(aip-agents) are installed and to generate actionable error messages when they
+are not available.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+Example:
+    >>> from glaip_sdk.runner.deps import check_local_runtime_available
+    >>> if not check_local_runtime_available():
+    ...     print(get_local_runtime_missing_message())
+"""
+
+from __future__ import annotations
+
+from gllm_core.utils import LoggerManager
+
+logger = LoggerManager().get_logger(__name__)
+
+# Module-level cache for import availability check
+_local_runtime_available: bool | None = None
+
+
+def _probe_aip_agents_import() -> bool:
+    """Attempt to import aip_agents and return success status.
+
+    Returns:
+        True if aip_agents can be imported successfully, False otherwise.
+    """
+    try:
+        import aip_agents  # noqa: F401, PLC0415
+
+        return True
+    except ImportError:
+        return False
+
+
+def check_local_runtime_available() -> bool:
+    """Check if the local runtime dependencies are installed and importable.
+
+    This function probes for the aip_agents module which provides the
+    LangGraphReactAgent for local execution. Results are cached for efficiency.
+
+    Returns:
+        True if local runtime is available, False otherwise.
+    """
+    global _local_runtime_available
+
+    if _local_runtime_available is None:
+        _local_runtime_available = _probe_aip_agents_import()
+        if _local_runtime_available:
+            logger.debug("Local runtime dependencies (aip-agents) detected")
+        else:
+            logger.debug("Local runtime dependencies (aip-agents) not available")
+
+    return _local_runtime_available
+
+
+# Cached availability flag for use in conditions without function call overhead
+LOCAL_RUNTIME_AVAILABLE: bool = check_local_runtime_available()
+
+
+def get_local_runtime_missing_message() -> str:
+    """Generate an actionable error message when local runtime is not available.
+
+    Returns:
+        A user-friendly message explaining how to install local runtime dependencies
+        or how to use server-backed execution as an alternative.
+    """
+    return (
+        "Local runtime dependencies are not installed. "
+        "To run agents locally without an AIP server, install with:\n\n"
+        '    pip install "glaip-sdk[local]"\n\n'
+        "Alternatively, call deploy() to run this agent on the AIP server."
+    )
+
+
+def get_local_mode_not_supported_for_tool_message(tool_ref: str) -> str:
+    """Generate an error message for tools that cannot be used in local mode.
+
+    Args:
+        tool_ref: A string identifier for the tool (name, ID, or type description).
+
+    Returns:
+        Error message explaining that the tool type is not supported locally.
+    """
+    return (
+        f"Tool '{tool_ref}' cannot be used in local mode. "
+        "Local runtime only supports LangChain-compatible tool classes/instances "
+        "and Tool.from_langchain(...) references. "
+        "Native platform tools (Tool.from_native()) require server-backed execution "
+        "via deploy()."
+    )
+
+
+def get_uuid_not_supported_message(key_type: str, uuid_value: str) -> str:
+    """Generate an error message when a UUID is used in local mode.
+
+    In local mode, runtime_config keys must be tool/agent/MCP objects or names,
+    not UUIDs which require platform registry resolution.
+
+    Args:
+        key_type: The type of key (e.g., "tool", "agent", "mcp").
+        uuid_value: The UUID that was incorrectly provided.
+
+    Returns:
+        Error message explaining that UUIDs are not supported in local mode.
+    """
+    return (
+        f"UUID-like {key_type} key '{uuid_value}' is not supported in local mode. "
+        f"Local runtime cannot resolve {key_type} IDs - pass the {key_type} "
+        f"class/instance or name instead."
+    )