aip-agents-binary 0.5.23__py3-none-macosx_13_0_arm64.whl → 0.5.25__py3-none-macosx_13_0_arm64.whl

aip_agents/agent/base_langgraph_agent.py

@@ -1225,6 +1225,12 @@ class BaseLangGraphAgent(BaseAgent):
             async for chunk in transformer.transform_stream(self.arun_a2a_stream(query, **kwargs)):
                 yield chunk
         except Exception as e:
+            # Lazy import to support optional guardrails dependency
+            from aip_agents.guardrails.exceptions import GuardrailViolationError
+
+            if isinstance(e, GuardrailViolationError):
+                # Re-raise guardrail violations without modification
+                raise
             logger.error(f"Agent '{self.name}': Error in arun_sse_stream: {e}", exc_info=True)
             yield SSEChunkTransformer._create_error_chunk(f"Error during streaming: {e}")
 

aip_agents/agent/langgraph_react_agent.py

@@ -6,8 +6,11 @@ Authors:
     Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
     Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
     Raymond Christopher (raymond.christopher@gdplabs.id)
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
 """
 
+from __future__ import annotations
+
 import asyncio
 import time
 import uuid
@@ -15,9 +18,12 @@ from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import asdict, dataclass
 from functools import reduce
 from textwrap import dedent
-from typing import Annotated, Any
+from typing import TYPE_CHECKING, Annotated, Any
 
 from deprecated import deprecated
+
+if TYPE_CHECKING:
+    from aip_agents.guardrails.manager import GuardrailManager
 from gllm_core.event import EventEmitter
 from gllm_core.schema import Chunk
 from langchain_core.language_models import BaseChatModel
@@ -157,6 +163,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         tool_output_manager: ToolOutputManager | None = None,
         planning: bool = False,
         middlewares: Sequence[AgentMiddleware] | None = None,
+        guardrail: GuardrailManager | None = None,
         step_limit_config: StepLimitConfig | None = None,
         **kwargs: Any,
     ):
@@ -178,8 +185,12 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             planning: Enable planning capabilities with TodoListMiddleware. Defaults to False.
             middlewares: Optional sequence of custom middleware to COMPOSE (not override) with built-in middleware.
                         Execution order: [TodoListMiddleware (if planning=True),
+                                         GuardrailMiddleware (if guardrail provided),
                                          ...custom middlewares in order provided]
                         All middleware hooks execute - this extends capabilities, never replaces them.
+            guardrail: Optional GuardrailManager for content filtering and safety checks.
+                     When provided, automatically wraps in GuardrailMiddleware for transparent
+                     input/output filtering during agent execution.
             enable_pii: Optional toggle to enable PII handling for tool inputs and outputs.
             step_limit_config: Optional configuration for step limits and delegation depth.
             **kwargs: Additional keyword arguments passed to BaseLangGraphAgent.
@@ -212,6 +223,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         # Setup middleware
         self._middleware_manager = self._setup_middleware(
             planning=planning,
+            guardrail=guardrail,
             custom_middlewares=middlewares,
         )
 
@@ -224,15 +236,17 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
     def _setup_middleware(
         self,
         planning: bool,
+        guardrail: GuardrailManager | None,
         custom_middlewares: Sequence[AgentMiddleware] | None,
     ) -> MiddlewareManager | None:
         """Setup middleware based on configuration.
 
-        Creates auto-configured middleware (planning) and composes
+        Creates auto-configured middleware (planning, guardrails) and composes
         with custom middleware if provided.
 
         Args:
             planning: Whether to enable TodoListMiddleware.
+            guardrail: Optional GuardrailManager to wrap in GuardrailMiddleware.
             custom_middlewares: Optional custom middlewares to append.
 
         Returns:
@@ -244,6 +258,12 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         if planning:
             middleware_list.append(TodoListMiddleware())
 
+        # Auto-configure GuardrailMiddleware if guardrail provided
+        if guardrail:
+            from aip_agents.guardrails.middleware import GuardrailMiddleware
+
+            middleware_list.append(GuardrailMiddleware(guardrail))
+
         # Append custom middlewares
         if custom_middlewares:
             middleware_list.extend(custom_middlewares)
@@ -579,14 +599,29 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             current_messages = state["messages"]
 
             # Execute LLM call
-            if self.lm_invoker:
-                result = await self._handle_lm_invoker_call(current_messages, state, config)
-            elif isinstance(self.model, BaseChatModel):
-                result = await self._handle_langchain_model_call(current_messages, state, config)
-            else:
-                raise ValueError(
-                    f"Agent '{self.name}': No valid LMInvoker or LangChain model configured for ReAct agent node."
-                )
+            try:
+                if self.lm_invoker:
+                    result = await self._handle_lm_invoker_call(current_messages, state, config)
+                elif isinstance(self.model, BaseChatModel):
+                    result = await self._handle_langchain_model_call(current_messages, state, config)
+                else:
+                    raise ValueError(
+                        f"Agent '{self.name}': No valid LMInvoker or LangChain model configured for ReAct agent node."
+                    )
+            except Exception as e:
+                # Lazy import to support optional guardrails dependency
+                from aip_agents.guardrails.exceptions import GuardrailViolationError
+
+                if isinstance(e, GuardrailViolationError):
+                    return {
+                        "messages": [
+                            AIMessage(
+                                content=f"⚠️ Guardrail violation: {e.result.reason}",
+                                response_metadata={"finish_reason": "stop"},
+                            )
+                        ]
+                    }
+                raise
 
             # Increment step counter after successful execution
             manager.increment_step()
@@ -1954,6 +1989,47 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         )
         writer(a2a_event)
 
+    async def _execute_abefore_model_hook(self, state: dict[str, Any]) -> None:
+        """Asynchronously execute abefore_model middleware hook and update state.
+
+        Args:
+            state: Current agent state to potentially update.
+        """
+        if self._middleware_manager:
+            try:
+                before_updates = await self._middleware_manager.abefore_model(state)
+                if before_updates:
+                    state.update(before_updates)
+            except Exception as e:
+                # Lazy import to support optional guardrails dependency
+                from aip_agents.guardrails.exceptions import GuardrailViolationError
+
+                if isinstance(e, GuardrailViolationError):
+                    # Re-raise guardrail violations to be caught by the agent node
+                    raise
+                logger.error(f"Agent '{self.name}': Middleware abefore_model hook failed: {e}")
+
+    async def _execute_aafter_model_hook(self, state_updates: dict[str, Any], state: dict[str, Any]) -> None:
+        """Asynchronously execute aafter_model middleware hook.
+
+        Args:
+            state_updates: Updates to be merged into state.
+            state: Current agent state for context.
+        """
+        if self._middleware_manager:
+            try:
+                after_updates = await self._middleware_manager.aafter_model(state)
+                if after_updates:
+                    state_updates.update(after_updates)
+            except Exception as e:
+                # Lazy import to support optional guardrails dependency
+                from aip_agents.guardrails.exceptions import GuardrailViolationError
+
+                if isinstance(e, GuardrailViolationError):
+                    # Re-raise guardrail violations
+                    raise
+                logger.error(f"Agent '{self.name}': Middleware aafter_model hook failed: {e}")
+
     def _execute_before_model_hook(self, state: dict[str, Any]) -> None:
         """Execute before_model middleware hook and update state.
 
@@ -1966,6 +2042,12 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
                 if before_updates:
                     state.update(before_updates)
             except Exception as e:
+                # Lazy import to support optional guardrails dependency
+                from aip_agents.guardrails.exceptions import GuardrailViolationError
+
+                if isinstance(e, GuardrailViolationError):
+                    # Re-raise guardrail violations to be caught by the agent node
+                    raise
                 logger.error(f"Agent '{self.name}': Middleware before_model hook failed: {e}")
 
     def _execute_modify_model_request_hook(
@@ -2029,7 +2111,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             dict[str, Any]: A dictionary containing the new messages and updated token usage.
         """
         # Execute before_model middleware hook
-        self._execute_before_model_hook(state)
+        await self._execute_abefore_model_hook(state)
 
         # Build tool output aware instruction
         enhanced_instruction = self._build_tool_output_aware_instruction(self.instruction, state, config)
@@ -2063,7 +2145,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         state_updates.update(token_usage_updates)
 
         # Execute after_model middleware hook
-        self._execute_after_model_hook(state_updates, state)
+        await self._execute_aafter_model_hook(state_updates, state)
 
         return state_updates
 
@@ -2081,7 +2163,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             dict[str, Any]: A dictionary containing the new messages and updated token usage.
         """
         # Execute before_model middleware hook
-        self._execute_before_model_hook(state)
+        await self._execute_abefore_model_hook(state)
 
         # Build tool output aware instruction
         enhanced_instruction = self._build_tool_output_aware_instruction(self.instruction, state, config)
@@ -2113,7 +2195,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
         state_updates.update(token_usage_updates)
 
         # Execute after_model middleware hook
-        self._execute_after_model_hook(state_updates, state)
+        await self._execute_aafter_model_hook(state_updates, state)
 
         return state_updates
 

aip_agents/agent/langgraph_react_agent.pyi

@@ -2,6 +2,7 @@ from _typeshed import Incomplete
 from aip_agents.agent.base_langgraph_agent import BaseLangGraphAgent as BaseLangGraphAgent
 from aip_agents.agent.hitl.langgraph_hitl_mixin import LangGraphHitLMixin as LangGraphHitLMixin
 from aip_agents.agent.hitl.manager import TOOL_EXECUTION_BLOCKING_DECISIONS as TOOL_EXECUTION_BLOCKING_DECISIONS
+from aip_agents.guardrails.manager import GuardrailManager as GuardrailManager
 from aip_agents.middleware.base import AgentMiddleware as AgentMiddleware, ModelRequest as ModelRequest
 from aip_agents.middleware.manager import MiddlewareManager as MiddlewareManager
 from aip_agents.middleware.todolist import TodoList as TodoList, TodoListMiddleware as TodoListMiddleware
@@ -85,7 +86,7 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
     """
     tool_output_manager: Incomplete
     step_limit_config: Incomplete
-    def __init__(self, name: str, instruction: str = ..., model: BaseChatModel | str | Any | None = None, tools: Sequence[BaseTool] | None = None, agents: Sequence[Any] | None = None, description: str | None = None, thread_id_key: str = 'thread_id', event_emitter: EventEmitter | None = None, tool_output_manager: ToolOutputManager | None = None, planning: bool = False, middlewares: Sequence[AgentMiddleware] | None = None, step_limit_config: StepLimitConfig | None = None, **kwargs: Any) -> None:
+    def __init__(self, name: str, instruction: str = ..., model: BaseChatModel | str | Any | None = None, tools: Sequence[BaseTool] | None = None, agents: Sequence[Any] | None = None, description: str | None = None, thread_id_key: str = 'thread_id', event_emitter: EventEmitter | None = None, tool_output_manager: ToolOutputManager | None = None, planning: bool = False, middlewares: Sequence[AgentMiddleware] | None = None, guardrail: GuardrailManager | None = None, step_limit_config: StepLimitConfig | None = None, **kwargs: Any) -> None:
         """Initialize the LangGraph ReAct Agent.
 
         Args:
@@ -104,8 +105,12 @@ class LangGraphReactAgent(LangGraphHitLMixin, BaseLangGraphAgent):
             planning: Enable planning capabilities with TodoListMiddleware. Defaults to False.
             middlewares: Optional sequence of custom middleware to COMPOSE (not override) with built-in middleware.
                         Execution order: [TodoListMiddleware (if planning=True),
+                                         GuardrailMiddleware (if guardrail provided),
                                          ...custom middlewares in order provided]
                         All middleware hooks execute - this extends capabilities, never replaces them.
+            guardrail: Optional GuardrailManager for content filtering and safety checks.
+                     When provided, automatically wraps in GuardrailMiddleware for transparent
+                     input/output filtering during agent execution.
             enable_pii: Optional toggle to enable PII handling for tool inputs and outputs.
             step_limit_config: Optional configuration for step limits and delegation depth.
             **kwargs: Additional keyword arguments passed to BaseLangGraphAgent.

aip_agents/guardrails/__init__.py

@@ -0,0 +1,83 @@
+# flake8: noqa: F401
+"""Guardrails package for content filtering and safety checks.
+
+This package provides modular guardrail engines and managers for filtering
+harmful content in AI agent interactions. All components support lazy loading
+to work with optional dependencies.
+
+Example:
+    Basic usage with a phrase matcher engine:
+
+    .. code-block:: python
+
+        from aip_agents.guardrails import GuardrailManager, GuardrailMiddleware
+        from aip_agents.guardrails.engines import PhraseMatcherEngine
+        from aip_agents.guardrails.schemas import GuardrailMode
+
+        # Create a guardrail engine
+        engine = PhraseMatcherEngine(
+            banned_phrases=["spam", "inappropriate"]
+        )
+
+        # Create a manager
+        manager = GuardrailManager(engines=[engine])
+
+        # Create middleware for agent integration
+        middleware = GuardrailMiddleware(guardrail_manager=manager)
+
+        # Use with agent (components are lazy-loaded)
+        from aip_agents.agent import LangGraphReactAgent
+        agent = LangGraphReactAgent(
+            name="my_agent",
+            guardrail=manager,
+            # ... other agent config
+        )
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aip_agents.guardrails.exceptions import GuardrailViolationError
+    from aip_agents.guardrails.manager import GuardrailManager
+    from aip_agents.guardrails.middleware import GuardrailMiddleware
+    from aip_agents.guardrails.schemas import (
+        BaseGuardrailEngineConfig,
+        GuardrailInput,
+        GuardrailMode,
+        GuardrailResult,
+    )
+
+
+_IMPORT_MAP = {
+    "GuardrailViolationError": "aip_agents.guardrails.exceptions",
+    "GuardrailManager": "aip_agents.guardrails.manager",
+    "GuardrailMiddleware": "aip_agents.guardrails.middleware",
+    "BaseGuardrailEngineConfig": "aip_agents.guardrails.schemas",
+    "GuardrailMode": "aip_agents.guardrails.schemas",
+    "GuardrailInput": "aip_agents.guardrails.schemas",
+    "GuardrailResult": "aip_agents.guardrails.schemas",
+}
+
+_cache: dict[str, Any] = {}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import components on first access."""
+    if name in _cache:
+        return _cache[name]
+
+    if name in _IMPORT_MAP:
+        try:
+            module = __import__(_IMPORT_MAP[name], fromlist=[name])
+            _cache[name] = getattr(module, name)
+            return _cache[name]
+        except ImportError as e:
+            raise ImportError(f"Failed to import {name}. Optional dependencies may be missing: {e}") from e
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = list(_IMPORT_MAP.keys())

aip_agents/guardrails/__init__.pyi

@@ -0,0 +1,6 @@
+from aip_agents.guardrails.exceptions import GuardrailViolationError as GuardrailViolationError
+from aip_agents.guardrails.manager import GuardrailManager as GuardrailManager
+from aip_agents.guardrails.middleware import GuardrailMiddleware as GuardrailMiddleware
+from aip_agents.guardrails.schemas import BaseGuardrailEngineConfig as BaseGuardrailEngineConfig, GuardrailInput as GuardrailInput, GuardrailMode as GuardrailMode, GuardrailResult as GuardrailResult
+
+__all__ = ['GuardrailViolationError', 'GuardrailManager', 'GuardrailMiddleware', 'BaseGuardrailEngineConfig', 'GuardrailMode', 'GuardrailInput', 'GuardrailResult']

aip_agents/guardrails/engines/__init__.py

@@ -0,0 +1,69 @@
+# flake8: noqa: F401
+"""Guardrail engines package with lazy loading support.
+
+This package provides guardrail engines that wrap GL SDK implementations.
+Engines are loaded lazily to support optional dependencies.
+
+Example:
+    Import and use guardrail engines:
+
+    .. code-block:: python
+
+        # Lazy import - works even if gllm-guardrail is not installed
+        from aip_agents.guardrails.engines import PhraseMatcherEngine, NemoGuardrailEngine
+
+        # Create a phrase matcher engine
+        phrase_engine = PhraseMatcherEngine(
+            banned_phrases=["spam", "inappropriate"]
+        )
+
+        # Create a NeMo guardrail engine (requires gllm-guardrail)
+        nemo_engine = NemoGuardrailEngine(
+            # NeMo-specific configuration
+        )
+
+        # Use with GuardrailManager
+        from aip_agents.guardrails import GuardrailManager
+        manager = GuardrailManager(engines=[phrase_engine, nemo_engine])
+
+Note:
+    All engines support lazy loading. If `gllm-guardrail` is not installed,
+    importing these engines will raise an ImportError only when actually
+    instantiated, not at import time.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+"""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from aip_agents.guardrails.engines.nemo import NemoGuardrailEngine
+    from aip_agents.guardrails.engines.phrase_matcher import PhraseMatcherEngine
+
+
+_IMPORT_MAP = {
+    "NemoGuardrailEngine": "aip_agents.guardrails.engines.nemo",
+    "PhraseMatcherEngine": "aip_agents.guardrails.engines.phrase_matcher",
+}
+
+_cache: dict[str, Any] = {}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import engines on first access."""
+    if name in _cache:
+        return _cache[name]
+
+    if name in _IMPORT_MAP:
+        try:
+            module = __import__(_IMPORT_MAP[name], fromlist=[name])
+            _cache[name] = getattr(module, name)
+            return _cache[name]
+        except ImportError as e:
+            raise ImportError(f"Failed to import {name}. Optional dependencies may be missing: {e}") from e
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = list(_IMPORT_MAP.keys())

aip_agents/guardrails/engines/__init__.pyi

@@ -0,0 +1,4 @@
+from aip_agents.guardrails.engines.nemo import NemoGuardrailEngine as NemoGuardrailEngine
+from aip_agents.guardrails.engines.phrase_matcher import PhraseMatcherEngine as PhraseMatcherEngine
+
+__all__ = ['NemoGuardrailEngine', 'PhraseMatcherEngine']

aip_agents/guardrails/engines/base.py

@@ -0,0 +1,90 @@
+"""Base interfaces and protocols for guardrail engines.
+
+This module defines the base protocol that all guardrail engines must implement,
+providing a consistent interface for content safety checking.
+
+Authors:
+    Reinhart Linanda (reinhart.linanda@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from abc import ABC, abstractmethod
+from typing import Protocol
+
+from aip_agents.guardrails.schemas import (
+    BaseGuardrailEngineConfig,
+    GuardrailResult,
+)
+
+
+class GuardrailEngine(Protocol):
+    """Protocol defining the interface for guardrail engines.
+
+    All guardrail engines must implement this protocol to be compatible
+    with GuardrailManager. Engines check content for safety violations.
+
+    Attributes:
+        config: Configuration for this engine's behavior
+    """
+
+    config: BaseGuardrailEngineConfig
+
+    @abstractmethod
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content for safety violations.
+
+        Args:
+            content: The user input content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+        ...
+
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations.
+
+        Args:
+            content: The AI output content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+        ...
+
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        ...
+
+
+class BaseGuardrailEngine(ABC):
+    """Abstract base class for guardrail engines.
+
+    Provides common functionality and ensures proper configuration handling.
+    Concrete engines should inherit from this class.
+    """
+
+    def __init__(self, config: BaseGuardrailEngineConfig | None = None) -> None:
+        """Initialize the engine with configuration.
+
+        Args:
+            config: Engine configuration. Uses defaults if None provided.
+        """
+        self.config = config or BaseGuardrailEngineConfig()
+
+    @abstractmethod
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content for safety violations."""
+        ...
+
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations."""
+        ...
+
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+        ...

aip_agents/guardrails/engines/base.pyi

@@ -0,0 +1,61 @@
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from aip_agents.guardrails.schemas import BaseGuardrailEngineConfig as BaseGuardrailEngineConfig, GuardrailResult as GuardrailResult
+from typing import Protocol
+
+class GuardrailEngine(Protocol):
+    """Protocol defining the interface for guardrail engines.
+
+    All guardrail engines must implement this protocol to be compatible
+    with GuardrailManager. Engines check content for safety violations.
+
+    Attributes:
+        config: Configuration for this engine's behavior
+    """
+    config: BaseGuardrailEngineConfig
+    @abstractmethod
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content for safety violations.
+
+        Args:
+            content: The user input content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations.
+
+        Args:
+            content: The AI output content to check
+
+        Returns:
+            GuardrailResult indicating if content is safe
+        """
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""
+
+class BaseGuardrailEngine(ABC):
+    """Abstract base class for guardrail engines.
+
+    Provides common functionality and ensures proper configuration handling.
+    Concrete engines should inherit from this class.
+    """
+    config: Incomplete
+    def __init__(self, config: BaseGuardrailEngineConfig | None = None) -> None:
+        """Initialize the engine with configuration.
+
+        Args:
+            config: Engine configuration. Uses defaults if None provided.
+        """
+    @abstractmethod
+    async def check_input(self, content: str) -> GuardrailResult:
+        """Check user input content for safety violations."""
+    @abstractmethod
+    async def check_output(self, content: str) -> GuardrailResult:
+        """Check AI output content for safety violations."""
+    @abstractmethod
+    def model_dump(self) -> dict:
+        """Serialize engine configuration into a JSON-compatible dictionary."""