uipath-langchain 0.1.34__py3-none-any.whl → 0.3.1__py3-none-any.whl

uipath_langchain/agent/guardrails/actions/filter_action.py

@@ -1,6 +1,9 @@
 import re
 from typing import Any
 
+from langchain_core.messages import AIMessage, ToolMessage
+from langgraph.types import Command
+from uipath.core.guardrails.guardrails import FieldReference, FieldSource
 from uipath.platform.guardrails import BaseGuardrail, GuardrailScope
 from uipath.runtime.errors import UiPathErrorCategory, UiPathErrorCode
 
@@ -14,11 +17,18 @@ from .base_action import GuardrailAction, GuardrailActionNode
 class FilterAction(GuardrailAction):
     """Action that filters inputs/outputs on guardrail failure.
 
-    For now, filtering is only supported for non-AGENT and non-LLM scopes.
-    If invoked for ``GuardrailScope.AGENT`` or ``GuardrailScope.LLM``, this action
-    raises an exception to indicate the operation is not supported yet.
+    For Tool scope, this action removes specified fields from tool call arguments.
+    For AGENT and LLM scopes, this action raises an exception as it's not supported yet.
     """
 
+    def __init__(self, fields: list[FieldReference] | None = None):
+        """Initialize FilterAction with fields to filter.
+
+        Args:
+            fields: List of FieldReference objects specifying which fields to filter.
+        """
+        self.fields = fields or []
+
     def action_node(
         self,
         *,
@@ -41,15 +51,240 @@ class FilterAction(GuardrailAction):
         raw_node_name = f"{scope.name}_{execution_stage.name}_{guardrail.name}_filter"
         node_name = re.sub(r"\W+", "_", raw_node_name.lower()).strip("_")
 
-        async def _node(_state: AgentGuardrailsGraphState) -> dict[str, Any]:
-            if scope in (GuardrailScope.AGENT, GuardrailScope.LLM):
-                raise AgentTerminationException(
-                    code=UiPathErrorCode.EXECUTION_ERROR,
-                    title="Guardrail filter action not supported",
-                    detail=f"FilterAction is not supported for scope [{scope.name}] at this time.",
-                    category=UiPathErrorCategory.USER,
+        async def _node(
+            _state: AgentGuardrailsGraphState,
+        ) -> dict[str, Any] | Command[Any]:
+            if scope == GuardrailScope.TOOL:
+                return _filter_tool_fields(
+                    _state,
+                    self.fields,
+                    execution_stage,
+                    guarded_component_name,
+                    guardrail.name,
                 )
-            # No-op for other scopes for now.
-            return {}
+
+            raise AgentTerminationException(
+                code=UiPathErrorCode.EXECUTION_ERROR,
+                title="Guardrail filter action not supported",
+                detail=f"FilterAction is not supported for scope [{scope.name}] at this time.",
+                category=UiPathErrorCategory.USER,
+            )
 
         return node_name, _node
+
+
+def _filter_tool_fields(
+    state: AgentGuardrailsGraphState,
+    fields_to_filter: list[FieldReference],
+    execution_stage: ExecutionStage,
+    tool_name: str,
+    guardrail_name: str,
+) -> dict[str, Any] | Command[Any]:
+    """Filter specified fields from tool call arguments or tool output.
+
+    The filter action filters fields based on the execution stage:
+    - PRE_EXECUTION: Only input fields are filtered
+    - POST_EXECUTION: Only output fields are filtered
+
+    Args:
+        state: The current agent graph state.
+        fields_to_filter: List of FieldReference objects specifying which fields to filter.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
+        tool_name: Name of the tool to filter.
+        guardrail_name: Name of the guardrail for logging purposes.
+
+    Returns:
+        Command to update messages with filtered tool call args or output.
+
+    Raises:
+        AgentTerminationException: If filtering fails.
+    """
+    try:
+        if not fields_to_filter:
+            return {}
+
+        if execution_stage == ExecutionStage.PRE_EXECUTION:
+            return _filter_tool_input_fields(state, fields_to_filter, tool_name)
+        else:
+            return _filter_tool_output_fields(state, fields_to_filter)
+
+    except Exception as e:
+        raise AgentTerminationException(
+            code=UiPathErrorCode.EXECUTION_ERROR,
+            title="Filter action failed",
+            detail=f"Failed to filter tool fields: {str(e)}",
+            category=UiPathErrorCategory.USER,
+        ) from e
+
+
+def _filter_tool_input_fields(
+    state: AgentGuardrailsGraphState,
+    fields_to_filter: list[FieldReference],
+    tool_name: str,
+) -> dict[str, Any] | Command[Any]:
+    """Filter specified input fields from tool call arguments (PRE_EXECUTION only).
+
+    This function is called at PRE_EXECUTION to filter input fields from tool call arguments
+    before the tool is executed.
+
+    Args:
+        state: The current agent graph state.
+        fields_to_filter: List of FieldReference objects specifying which fields to filter.
+        tool_name: Name of the tool to filter.
+
+    Returns:
+        Command to update messages with filtered tool call args, or empty dict if no input fields to filter.
+    """
+    # Check if there are any input fields to filter
+    has_input_fields = any(
+        field_ref.source == FieldSource.INPUT for field_ref in fields_to_filter
+    )
+
+    if not has_input_fields:
+        return {}
+
+    msgs = state.messages.copy()
+    if not msgs:
+        return {}
+
+    # Find the AIMessage with tool calls
+    # At PRE_EXECUTION, this is always the last message
+    ai_message = None
+    for i in range(len(msgs) - 1, -1, -1):
+        msg = msgs[i]
+        if isinstance(msg, AIMessage) and msg.tool_calls:
+            ai_message = msg
+            break
+
+    if ai_message is None:
+        return {}
+
+    # Find and filter the tool call with matching name
+    # Type assertion: we know ai_message is AIMessage from the check above
+    assert isinstance(ai_message, AIMessage)
+    tool_calls = list(ai_message.tool_calls)
+    modified = False
+
+    for tool_call in tool_calls:
+        call_name = (
+            tool_call.get("name")
+            if isinstance(tool_call, dict)
+            else getattr(tool_call, "name", None)
+        )
+
+        if call_name == tool_name:
+            # Get the current args
+            args = (
+                tool_call.get("args")
+                if isinstance(tool_call, dict)
+                else getattr(tool_call, "args", None)
+            )
+
+            if args and isinstance(args, dict):
+                # Filter out the specified input fields
+                filtered_args = args.copy()
+                for field_ref in fields_to_filter:
+                    # Only filter input fields
+                    if (
+                        field_ref.source == FieldSource.INPUT
+                        and field_ref.path in filtered_args
+                    ):
+                        del filtered_args[field_ref.path]
+                        modified = True
+
+                # Update the tool call with filtered args
+                if isinstance(tool_call, dict):
+                    tool_call["args"] = filtered_args
+                else:
+                    tool_call.args = filtered_args
+
+            break
+
+    if modified:
+        ai_message.tool_calls = tool_calls
+        return Command(update={"messages": msgs})
+
+    return {}
+
+
+def _filter_tool_output_fields(
+    state: AgentGuardrailsGraphState,
+    fields_to_filter: list[FieldReference],
+) -> dict[str, Any] | Command[Any]:
+    """Filter specified output fields from tool output (POST_EXECUTION only).
+
+    This function is called at POST_EXECUTION to filter output fields from tool results
+    after the tool has been executed.
+
+    Args:
+        state: The current agent graph state.
+        fields_to_filter: List of FieldReference objects specifying which fields to filter.
+
+    Returns:
+        Command to update messages with filtered tool output, or empty dict if no output fields to filter.
+    """
+    # Check if there are any output fields to filter
+    has_output_fields = any(
+        field_ref.source == FieldSource.OUTPUT for field_ref in fields_to_filter
+    )
+
+    if not has_output_fields:
+        return {}
+
+    msgs = state.messages.copy()
+    if not msgs:
+        return {}
+
+    last_message = msgs[-1]
+    if not isinstance(last_message, ToolMessage):
+        return {}
+
+    # Parse the tool output content
+    import json
+
+    content = last_message.content
+    if not content:
+        return {}
+
+    # Try to parse the content as JSON or dict
+    try:
+        if isinstance(content, dict):
+            output_data = content
+        elif isinstance(content, str):
+            try:
+                output_data = json.loads(content)
+            except json.JSONDecodeError:
+                # Try to parse as Python literal (dict representation)
+                import ast
+
+                try:
+                    output_data = ast.literal_eval(content)
+                    if not isinstance(output_data, dict):
+                        return {}
+                except (ValueError, SyntaxError):
+                    return {}
+        else:
+            # Content is not JSON-parseable, can't filter specific fields
+            return {}
+    except Exception:
+        return {}
+
+    if not isinstance(output_data, dict):
+        return {}
+
+    # Filter out the specified fields
+    filtered_output = output_data.copy()
+    modified = False
+
+    for field_ref in fields_to_filter:
+        # Only filter output fields
+        if field_ref.source == FieldSource.OUTPUT and field_ref.path in filtered_output:
+            del filtered_output[field_ref.path]
+            modified = True
+
+    if modified:
+        # Update the tool message content with filtered output
+        last_message.content = json.dumps(filtered_output)
+        return Command(update={"messages": msgs})
+
+    return {}

uipath_langchain/agent/guardrails/guardrail_nodes.py

@@ -18,8 +18,9 @@ from uipath.runtime.errors import UiPathErrorCode
 
 from uipath_langchain.agent.guardrails.types import ExecutionStage
 from uipath_langchain.agent.guardrails.utils import (
-    _extract_tool_input_data,
+    _extract_tool_args_from_message,
     _extract_tool_output_data,
+    _extract_tools_args_from_message,
     get_message_content,
 )
 from uipath_langchain.agent.react.types import AgentGuardrailsGraphState
@@ -117,10 +118,11 @@ def _create_guardrail_node(
     | None = None,
     output_data_extractor: Callable[[AgentGuardrailsGraphState], dict[str, Any]]
     | None = None,
+    tool_name: str | None = None,
 ) -> tuple[str, Callable[[AgentGuardrailsGraphState], Any]]:
     """Private factory for guardrail evaluation nodes.
 
-    Returns a node that evaluates the guardrail and routes via Command:
+    Returns a node with observability metadata attached as __metadata__ attribute:
     - goto success_node on validation pass
     - goto failure_node on validation fail
     """
@@ -149,12 +151,22 @@ def _create_guardrail_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)
 
@@ -166,6 +178,15 @@ def _create_guardrail_node(
             )
             raise
 
+    # Attach observability metadata as function attribute
+    node.__metadata__ = {  # type: ignore[attr-defined]
+        "guardrail_name": guardrail.name,
+        "guardrail_description": getattr(guardrail, "description", None),
+        "guardrail_scope": scope.value,
+        "guardrail_stage": execution_stage.value,
+        "tool_name": tool_name,
+    }
+
     return node_name, node
 
 
@@ -178,7 +199,11 @@ def create_llm_guardrail_node(
     def _payload_generator(state: AgentGuardrailsGraphState) -> str:
         if not state.messages:
             return ""
-        return get_message_content(state.messages[-1])
+        match execution_stage:
+            case ExecutionStage.PRE_EXECUTION:
+                return get_message_content(state.messages[-1])
+            case ExecutionStage.POST_EXECUTION:
+                return json.dumps(_extract_tools_args_from_message(state.messages[-1]))
 
     return _create_guardrail_node(
         guardrail,
@@ -263,8 +288,8 @@ def create_tool_guardrail_node(
             return ""
 
         if execution_stage == ExecutionStage.PRE_EXECUTION:
-            # Extract tool args as dict and convert to JSON string
-            args_dict = _extract_tool_input_data(state, tool_name, execution_stage)
+            last_message = state.messages[-1]
+            args_dict = _extract_tool_args_from_message(last_message, tool_name)
             if args_dict:
                 return json.dumps(args_dict)
 
@@ -272,7 +297,16 @@ def create_tool_guardrail_node(
 
     # Create closures for input/output data extraction (for deterministic guardrails)
     def _input_data_extractor(state: AgentGuardrailsGraphState) -> dict[str, Any]:
-        return _extract_tool_input_data(state, tool_name, execution_stage)
+        if execution_stage == ExecutionStage.PRE_EXECUTION:
+            if len(state.messages) < 1:
+                return {}
+            message = state.messages[-1]
+        else:  # POST_EXECUTION
+            if len(state.messages) < 2:
+                return {}
+            message = state.messages[-2]
+
+        return _extract_tool_args_from_message(message, tool_name)
 
     def _output_data_extractor(state: AgentGuardrailsGraphState) -> dict[str, Any]:
         return _extract_tool_output_data(state)
@@ -286,4 +320,5 @@ def create_tool_guardrail_node(
         failure_node,
         _input_data_extractor,
         _output_data_extractor,
+        tool_name,
     )

uipath_langchain/agent/guardrails/guardrails_factory.py

@@ -9,6 +9,7 @@ from uipath.agent.models.agent import (
     AgentGuardrail,
     AgentGuardrailBlockAction,
     AgentGuardrailEscalateAction,
+    AgentGuardrailFilterAction,
     AgentGuardrailLogAction,
     AgentGuardrailSeverityLevel,
     AgentNumberOperator,
@@ -16,6 +17,7 @@ from uipath.agent.models.agent import (
     AgentUnknownGuardrail,
     AgentWordOperator,
     AgentWordRule,
+    StandardRecipient,
 )
 from uipath.core.guardrails import (
     BooleanRule,
@@ -24,14 +26,16 @@ from uipath.core.guardrails import (
     UniversalRule,
     WordRule,
 )
-from uipath.platform.guardrails import BaseGuardrail
+from uipath.platform.guardrails import BaseGuardrail, GuardrailScope
 
 from uipath_langchain.agent.guardrails.actions import (
     BlockAction,
     EscalateAction,
+    FilterAction,
     GuardrailAction,
     LogAction,
 )
+from uipath_langchain.agent.guardrails.utils import _sanitize_selector_tool_names
 
 
 def _assert_value_not_none(value: str | None, operator: AgentWordOperator) -> str:
@@ -191,18 +195,21 @@ def _convert_agent_custom_guardrail_to_deterministic(
         guardrail: The agent custom guardrail to convert.
 
     Returns:
-        A DeterministicGuardrail with converted rules.
+        A DeterministicGuardrail with converted rules and sanitized selector.
     """
     converted_rules = [
         _convert_agent_rule_to_deterministic(rule) for rule in guardrail.rules
     ]
 
+    # Sanitize tool names in selector for Tool scope guardrails
+    sanitized_selector = _sanitize_selector_tool_names(guardrail.selector)
+
     return DeterministicGuardrail(
         id=guardrail.id,
         name=guardrail.name,
         description=guardrail.description,
         enabled_for_evals=guardrail.enabled_for_evals,
-        selector=guardrail.selector,
+        selector=sanitized_selector,
         guardrail_type="custom",
         rules=converted_rules,
     )
@@ -227,12 +234,27 @@ def build_guardrails_with_actions(
         if isinstance(guardrail, AgentUnknownGuardrail):
             continue
 
-        # Convert AgentCustomGuardrail to DeterministicGuardrail
-        converted_guardrail: BaseGuardrail = guardrail
+        converted_guardrail: BaseGuardrail
         if isinstance(guardrail, AgentCustomGuardrail):
             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."
+                )
+        else:
+            converted_guardrail = guardrail
+            _sanitize_selector_tool_names(converted_guardrail.selector)
 
         action = guardrail.action
 
@@ -252,15 +274,18 @@ def build_guardrails_with_actions(
                 )
             )
         elif isinstance(action, AgentGuardrailEscalateAction):
-            result.append(
-                (
-                    converted_guardrail,
-                    EscalateAction(
-                        app_name=action.app.name,
-                        app_folder_path=action.app.folder_name,
-                        version=action.app.version,
-                        assignee=action.recipient.value,
-                    ),
+            if isinstance(action.recipient, StandardRecipient):
+                result.append(
+                    (
+                        converted_guardrail,
+                        EscalateAction(
+                            app_name=action.app.name,
+                            app_folder_path=action.app.folder_name,
+                            version=action.app.version,
+                            assignee=action.recipient.value,
+                        ),
+                    )
                 )
-            )
+        elif isinstance(action, AgentGuardrailFilterAction):
+            result.append((converted_guardrail, FilterAction(fields=action.fields)))
     return result

uipath_langchain/agent/guardrails/utils.py

@@ -10,8 +10,8 @@ from langchain_core.messages import (
     ToolMessage,
 )
 
-from uipath_langchain.agent.guardrails.types import ExecutionStage
 from uipath_langchain.agent.react.types import AgentGuardrailsGraphState
+from uipath_langchain.agent.tools.utils import sanitize_tool_name
 
 logger = logging.getLogger(__name__)
 
@@ -60,45 +60,42 @@ def _extract_tool_args_from_message(
                             return parsed
                     except json.JSONDecodeError:
                         logger.warning(
-                            "Failed to parse tool args as JSON for tool '%s': %s",
-                            tool_name,
-                            args[:100] if len(args) > 100 else args,
+                            "Failed to parse tool args as JSON for tool '%s'", tool_name
                         )
                         return {}
 
     return {}
 
 
-def _extract_tool_input_data(
-    state: AgentGuardrailsGraphState, tool_name: str, execution_stage: ExecutionStage
-) -> dict[str, Any]:
-    """Extract tool call arguments as dict for deterministic guardrails.
-
-    Args:
-        state: The current agent graph state.
-        tool_name: Name of the tool to extract arguments from.
-        execution_stage: PRE_EXECUTION or POST_EXECUTION.
+def _extract_tools_args_from_message(message: AnyMessage) -> list[dict[str, Any]]:
+    if not isinstance(message, AIMessage):
+        return []
 
-    Returns:
-        Dict containing tool call arguments, or empty dict if not found.
-        - For PRE_EXECUTION: extracts from last message
-        - For POST_EXECUTION: extracts from second-to-last message
-    """
-    if not state.messages:
-        return {}
+    if not message.tool_calls:
+        return []
 
-    # For PRE_EXECUTION, look at last message
-    # For POST_EXECUTION, look at second-to-last message (before the ToolMessage)
-    if execution_stage == ExecutionStage.PRE_EXECUTION:
-        if len(state.messages) < 1:
-            return {}
-        message = state.messages[-1]
-    else:  # POST_EXECUTION
-        if len(state.messages) < 2:
-            return {}
-        message = state.messages[-2]
+    result: list[dict[str, Any]] = []
 
-    return _extract_tool_args_from_message(message, tool_name)
+    for tool_call in message.tool_calls:
+        args = (
+            tool_call.get("args")
+            if isinstance(tool_call, dict)
+            else getattr(tool_call, "args", None)
+        )
+        if args is not None:
+            # Args should already be a dict
+            if isinstance(args, dict):
+                result.append(args)
+            # If it's a JSON string, parse it
+            elif isinstance(args, str):
+                try:
+                    parsed = json.loads(args)
+                    if isinstance(parsed, dict):
+                        result.append(parsed)
+                except json.JSONDecodeError:
+                    logger.warning("Failed to parse tool args as JSON")
+
+    return result
 
 
 def _extract_tool_output_data(state: AgentGuardrailsGraphState) -> dict[str, Any]:
@@ -131,8 +128,18 @@ def _extract_tool_output_data(state: AgentGuardrailsGraphState) -> dict[str, Any
                 # JSON array or primitive - wrap it
                 return {"output": parsed}
         except json.JSONDecodeError:
-            logger.warning("Tool output is not valid JSON")
-            return {"output": content}
+            # Try to parse as Python literal (dict/list representation)
+            try:
+                import ast
+
+                parsed = ast.literal_eval(content)
+                if isinstance(parsed, dict):
+                    return parsed
+                else:
+                    return {"output": parsed}
+            except (ValueError, SyntaxError):
+                logger.warning("Tool output is not valid JSON or Python literal")
+                return {"output": content}
     elif isinstance(content, dict):
         return content
     else:
@@ -144,3 +151,27 @@ def get_message_content(msg: AnyMessage) -> str:
     if isinstance(msg, (HumanMessage, SystemMessage)):
         return msg.content if isinstance(msg.content, str) else str(msg.content)
     return str(getattr(msg, "content", "")) if hasattr(msg, "content") else ""
+
+
+def _sanitize_selector_tool_names(selector):
+    """Sanitize tool names in the selector's match_names for Tool scope guardrails.
+
+    This ensures that the tool names in the selector match the sanitized tool names
+    used in the actual tool nodes.
+
+    Args:
+        selector: The guardrail selector object.
+
+    Returns:
+        The selector with sanitized match_names (if applicable).
+    """
+    from uipath.platform.guardrails import GuardrailScope
+
+    # Only sanitize for Tool scope guardrails
+    if GuardrailScope.TOOL in selector.scopes and selector.match_names is not None:
+        # Sanitize each tool name in match_names
+        sanitized_names = [sanitize_tool_name(name) for name in selector.match_names]
+        # Update the selector with sanitized names
+        selector.match_names = sanitized_names
+
+    return selector

uipath_langchain/agent/react/agent.py

@@ -10,7 +10,6 @@ from pydantic import BaseModel
 from uipath.platform.guardrails import BaseGuardrail
 
 from ..guardrails.actions import GuardrailAction
-from ..tools import create_tool_node
 from .guardrails.guardrails_subgraph import (
     create_agent_init_guardrails_subgraph,
     create_agent_terminate_guardrails_subgraph,
@@ -67,6 +66,8 @@ def create_agent(
 
     Control flow tools (end_execution, raise_error) are auto-injected alongside regular tools.
     """
+    from ..tools import create_tool_node
+
     if config is None:
         config = AgentGraphConfig()
 
@@ -76,7 +77,8 @@ def create_agent(
     flow_control_tools: list[BaseTool] = create_flow_control_tools(output_schema)
     llm_tools: list[BaseTool] = [*agent_tools, *flow_control_tools]
 
-    init_node = create_init_node(messages)
+    init_node = create_init_node(messages, input_schema)
+
     tool_nodes = create_tool_node(agent_tools)
     tool_nodes_with_guardrails = create_tools_guardrails_subgraph(
         tool_nodes, guardrails