feat: enforce deterministic guardrails tool-level scope

- Add scope validation in build_guardrails_with_actions
- Add explicit filtering in LLM/AGENT guardrail subgraph builders
- Improve runtime error messages for invalid scope configurations
- Add comprehensive tests for scope validation

Author: ctiliescuuipath

src/uipath_langchain/agent/guardrails/guardrail_nodes.py

@@ -149,12 +149,22 @@ async def node(
                     state, guardrail, payload_generator
                 )
             else:
-                raise AgentTerminationException(
-                    code=UiPathErrorCode.EXECUTION_ERROR,
-                    title="Unsupported guardrail type",
-                    detail=f"Guardrail type '{type(guardrail).__name__}' is not supported. "
-                    f"Expected DeterministicGuardrail or BuiltInValidatorGuardrail.",
-                )
+                # Provide specific error message for DeterministicGuardrails with wrong scope
+                if isinstance(guardrail, DeterministicGuardrail):
+                    raise AgentTerminationException(
+                        code=UiPathErrorCode.EXECUTION_ERROR,
+                        title="Invalid guardrail scope",
+                        detail=f"DeterministicGuardrail '{guardrail.name}' can only be used with TOOL scope. "
+                        f"Current scope: {scope.name}. "
+                        f"Please configure this guardrail to use only TOOL scope.",
+                    )
+                else:
+                    raise AgentTerminationException(
+                        code=UiPathErrorCode.EXECUTION_ERROR,
+                        title="Unsupported guardrail type",
+                        detail=f"Guardrail type '{type(guardrail).__name__}' is not supported. "
+                        f"Expected DeterministicGuardrail (TOOL scope only) or BuiltInValidatorGuardrail.",
+                    )
 
             return _create_validation_command(result, success_node, failure_node)
 

src/uipath_langchain/agent/guardrails/guardrails_factory.py

@@ -24,7 +24,7 @@
     UniversalRule,
     WordRule,
 )
-from uipath.platform.guardrails import BaseGuardrail
+from uipath.platform.guardrails import BaseGuardrail, GuardrailScope
 
 from uipath_langchain.agent.guardrails.actions import (
     BlockAction,
@@ -233,6 +233,19 @@ def build_guardrails_with_actions(
             converted_guardrail = _convert_agent_custom_guardrail_to_deterministic(
                 guardrail
             )
+            # Validate that DeterministicGuardrails only have TOOL scope
+            non_tool_scopes = [
+                scope
+                for scope in converted_guardrail.selector.scopes
+                if scope != GuardrailScope.TOOL
+            ]
+
+            if non_tool_scopes:
+                raise ValueError(
+                    f"Deterministic guardrail '{converted_guardrail.name}' can only be used with TOOL scope. "
+                    f"Found invalid scopes: {[scope.name for scope in non_tool_scopes]}. "
+                    f"Please configure this guardrail to use only TOOL scope."
+                )
 
         action = guardrail.action
 

src/uipath_langchain/agent/react/guardrails/guardrails_subgraph.py

@@ -4,6 +4,7 @@
 from langgraph._internal._runnable import RunnableCallable
 from langgraph.constants import END, START
 from langgraph.graph import StateGraph
+from uipath.core.guardrails import DeterministicGuardrail
 from uipath.platform.guardrails import (
     BaseGuardrail,
     BuiltInValidatorGuardrail,
@@ -207,6 +208,7 @@ def create_llm_guardrails_subgraph(
         (guardrail, _)
         for (guardrail, _) in (guardrails or [])
         if GuardrailScope.LLM in guardrail.selector.scopes
+        and not isinstance(guardrail, DeterministicGuardrail)
     ]
     if applicable_guardrails is None or len(applicable_guardrails) == 0:
         return llm_node[1]
@@ -247,6 +249,7 @@ def create_agent_init_guardrails_subgraph(
         (guardrail, _)
         for (guardrail, _) in (guardrails or [])
         if GuardrailScope.AGENT in guardrail.selector.scopes
+        and not isinstance(guardrail, DeterministicGuardrail)
     ]
     if applicable_guardrails is None or len(applicable_guardrails) == 0:
         return init_node[1]
@@ -277,6 +280,7 @@ def terminate_wrapper(state: Any) -> dict[str, Any]:
         (guardrail, _)
         for (guardrail, _) in (guardrails or [])
         if GuardrailScope.AGENT in guardrail.selector.scopes
+        and not isinstance(guardrail, DeterministicGuardrail)
     ]
     if applicable_guardrails is None or len(applicable_guardrails) == 0:
         return terminate_node[1]

tests/agent/guardrails/test_guardrails_factory.py

@@ -158,6 +158,148 @@ def test_escalate_action_is_mapped_with_app_and_recipient(self) -> None:
         assert action.version == 2
         assert action.assignee == "admin@example.com"
 
+    def test_deterministic_guardrail_with_llm_scope_raises_value_error(self) -> None:
+        """DeterministicGuardrails (AgentCustomGuardrails) with LLM scope should raise ValueError."""
+        guardrail = AgentCustomGuardrail.model_validate(
+            {
+                "$guardrailType": "custom",
+                "id": "test-llm-scope",
+                "name": "test-guardrail-llm",
+                "description": "Test guardrail with LLM scope",
+                "enabledForEvals": True,
+                "selector": {
+                    "$selectorType": "scoped",
+                    "scopes": ["llm"],  # LLM scope - should be rejected
+                    "matchNames": None,
+                },
+                "rules": [
+                    {
+                        "$ruleType": "word",
+                        "fieldSelector": {
+                            "$selectorType": "specific",
+                            "fields": [{"path": "message.content", "source": "input"}],
+                        },
+                        "operator": "contains",
+                        "value": "forbidden",
+                    }
+                ],
+                "action": {"$actionType": "block", "reason": "test"},
+            }
+        )
+
+        with pytest.raises(
+            ValueError,
+            match=r"Deterministic guardrail 'test-guardrail-llm' can only be used with TOOL scope.*Found invalid scopes.*LLM",
+        ):
+            build_guardrails_with_actions([guardrail])
+
+    def test_deterministic_guardrail_with_agent_scope_raises_value_error(self) -> None:
+        """DeterministicGuardrails with AGENT scope should raise ValueError."""
+        guardrail = AgentCustomGuardrail.model_validate(
+            {
+                "$guardrailType": "custom",
+                "id": "test-agent-scope",
+                "name": "test-guardrail-agent",
+                "description": "Test guardrail with AGENT scope",
+                "enabledForEvals": True,
+                "selector": {
+                    "$selectorType": "scoped",
+                    "scopes": ["agent"],  # AGENT scope - should be rejected
+                    "matchNames": None,
+                },
+                "rules": [
+                    {
+                        "$ruleType": "word",
+                        "fieldSelector": {
+                            "$selectorType": "specific",
+                            "fields": [{"path": "message.content", "source": "input"}],
+                        },
+                        "operator": "contains",
+                        "value": "forbidden",
+                    }
+                ],
+                "action": {"$actionType": "block", "reason": "test"},
+            }
+        )
+
+        with pytest.raises(
+            ValueError,
+            match=r"Deterministic guardrail 'test-guardrail-agent' can only be used with TOOL scope.*Found invalid scopes.*AGENT",
+        ):
+            build_guardrails_with_actions([guardrail])
+
+    def test_deterministic_guardrail_with_tool_scope_succeeds(self) -> None:
+        """DeterministicGuardrails with TOOL scope should be accepted."""
+        guardrail = AgentCustomGuardrail.model_validate(
+            {
+                "$guardrailType": "custom",
+                "id": "test-tool-scope",
+                "name": "test-guardrail-tool",
+                "description": "Test guardrail with TOOL scope",
+                "enabledForEvals": True,
+                "selector": {
+                    "$selectorType": "scoped",
+                    "scopes": ["tool"],  # TOOL scope - should be accepted
+                    "matchNames": ["my_tool"],
+                },
+                "rules": [
+                    {
+                        "$ruleType": "word",
+                        "fieldSelector": {
+                            "$selectorType": "specific",
+                            "fields": [{"path": "message.content", "source": "input"}],
+                        },
+                        "operator": "contains",
+                        "value": "forbidden",
+                    }
+                ],
+                "action": {"$actionType": "block", "reason": "test"},
+            }
+        )
+
+        result = build_guardrails_with_actions([guardrail])
+
+        assert len(result) == 1
+        converted_guardrail, action = result[0]
+        assert isinstance(converted_guardrail, DeterministicGuardrail)
+        assert converted_guardrail.name == "test-guardrail-tool"
+        assert isinstance(action, BlockAction)
+
+    def test_deterministic_guardrail_with_mixed_scopes_raises_value_error(self) -> None:
+        """DeterministicGuardrails with mixed scopes including non-TOOL should raise ValueError."""
+        guardrail = AgentCustomGuardrail.model_validate(
+            {
+                "$guardrailType": "custom",
+                "id": "test-mixed-scope",
+                "name": "test-guardrail-mixed",
+                "description": "Test guardrail with mixed scopes",
+                "enabledForEvals": True,
+                "selector": {
+                    "$selectorType": "scoped",
+                    "scopes": ["tool", "llm"],  # Mixed scopes - should be rejected
+                    "matchNames": ["my_tool"],
+                },
+                "rules": [
+                    {
+                        "$ruleType": "word",
+                        "fieldSelector": {
+                            "$selectorType": "specific",
+                            "fields": [{"path": "message.content", "source": "input"}],
+                        },
+                        "operator": "contains",
+                        "value": "forbidden",
+                    }
+                ],
+                "action": {"$actionType": "block", "reason": "test"},
+            }
+        )
+
+        with pytest.raises(
+            ValueError,
+            match=r"Deterministic guardrail 'test-guardrail-mixed' can only be used with TOOL scope.*Found invalid scopes.*LLM",
+        ):
+            build_guardrails_with_actions([guardrail])
+
 
 class TestCreateWordRuleFunc:
     """Tests for _create_word_rule_func."""