uipath-langchain 0.1.24__py3-none-any.whl → 0.1.28__py3-none-any.whl

uipath_langchain/agent/guardrails/actions/base_action.py

@@ -18,6 +18,7 @@ class GuardrailAction(ABC):
         guardrail: BaseGuardrail,
         scope: GuardrailScope,
         execution_stage: ExecutionStage,
+        guarded_component_name: str,
     ) -> GuardrailActionNode:
         """Create and return the Action node to execute on validation failure."""
         ...

uipath_langchain/agent/guardrails/actions/block_action.py

@@ -26,6 +26,7 @@ class BlockAction(GuardrailAction):
         guardrail: BaseGuardrail,
         scope: GuardrailScope,
         execution_stage: ExecutionStage,
+        guarded_component_name: str,
     ) -> GuardrailActionNode:
         raw_node_name = f"{scope.name}_{execution_stage.name}_{guardrail.name}_block"
         node_name = re.sub(r"\W+", "_", raw_node_name.lower()).strip("_")

uipath_langchain/agent/guardrails/actions/escalate_action.py

@@ -4,7 +4,7 @@ import json
 import re
 from typing import Any, Dict, Literal
 
-from langchain_core.messages import AIMessage, ToolMessage
+from langchain_core.messages import AIMessage, ToolCall, ToolMessage
 from langgraph.types import Command, interrupt
 from uipath.platform.common import CreateEscalation
 from uipath.platform.guardrails import (
@@ -34,6 +34,14 @@ class EscalateAction(GuardrailAction):
         version: int,
         assignee: str,
     ):
+        """Initialize EscalateAction with escalation app configuration.
+
+        Args:
+            app_name: Name of the escalation app.
+            app_folder_path: Folder path where the escalation app is located.
+            version: Version of the escalation app.
+            assignee: User or role assigned to handle the escalation.
+        """
         self.app_name = app_name
         self.app_folder_path = app_folder_path
         self.version = version
@@ -45,13 +53,27 @@ class EscalateAction(GuardrailAction):
         guardrail: BaseGuardrail,
         scope: GuardrailScope,
         execution_stage: ExecutionStage,
+        guarded_component_name: str,
     ) -> GuardrailActionNode:
+        """Create a HITL escalation node for the guardrail.
+
+        Args:
+            guardrail: The guardrail that triggered this escalation action.
+            scope: The guardrail scope (LLM/AGENT/TOOL).
+            execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
+
+        Returns:
+            A tuple of (node_name, node_function) where the node function triggers
+            a HITL interruption and processes the escalation response.
+        """
         node_name = _get_node_name(execution_stage, guardrail, scope)
 
         async def _node(
             state: AgentGuardrailsGraphState,
         ) -> Dict[str, Any] | Command[Any]:
-            input = _extract_escalation_content(state, scope, execution_stage)
+            input = _extract_escalation_content(
+                state, scope, execution_stage, guarded_component_name
+            )
             escalation_field = _execution_stage_to_escalation_field(execution_stage)
 
             data = {
@@ -75,7 +97,11 @@ class EscalateAction(GuardrailAction):
 
             if escalation_result.action == "Approve":
                 return _process_escalation_response(
-                    state, escalation_result.data, scope, execution_stage
+                    state,
+                    escalation_result.data,
+                    scope,
+                    execution_stage,
+                    guarded_component_name,
                 )
 
             raise AgentTerminationException(
@@ -95,46 +121,58 @@ def _get_node_name(
     return node_name
 
 
-def _execution_stage_to_string(
+def _process_escalation_response(
+    state: AgentGuardrailsGraphState,
+    escalation_result: Dict[str, Any],
+    scope: GuardrailScope,
     execution_stage: ExecutionStage,
-) -> Literal["PreExecution", "PostExecution"]:
-    """Convert ExecutionStage enum to string literal.
+    guarded_node_name: str,
+) -> Dict[str, Any] | Command[Any]:
+    """Process escalation response and route to appropriate handler based on scope.
 
     Args:
-        execution_stage: The execution stage enum.
+        state: The current agent graph state.
+        escalation_result: The result from the escalation interrupt containing reviewed inputs/outputs.
+        scope: The guardrail scope (LLM/AGENT/TOOL).
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
 
     Returns:
-        "PreExecution" for PRE_EXECUTION, "PostExecution" for POST_EXECUTION.
+        For LLM/TOOL scope: Command to update messages with reviewed inputs/outputs, or empty dict.
+        For AGENT scope: Empty dict (no message alteration).
     """
-    if execution_stage == ExecutionStage.PRE_EXECUTION:
-        return "PreExecution"
-    return "PostExecution"
+    match scope:
+        case GuardrailScope.LLM:
+            return _process_llm_escalation_response(
+                state, escalation_result, execution_stage
+            )
+        case GuardrailScope.TOOL:
+            return _process_tool_escalation_response(
+                state, escalation_result, execution_stage, guarded_node_name
+            )
+        case GuardrailScope.AGENT:
+            return {}
 
 
-def _process_escalation_response(
+def _process_llm_escalation_response(
     state: AgentGuardrailsGraphState,
     escalation_result: Dict[str, Any],
-    scope: GuardrailScope,
     execution_stage: ExecutionStage,
 ) -> Dict[str, Any] | Command[Any]:
-    """Process escalation response and update state based on guardrail scope.
+    """Process escalation response for LLM scope guardrails.
+
+    Updates message content or tool calls based on reviewed inputs/outputs from escalation.
 
     Args:
         state: The current agent graph state.
-        escalation_result: The result from the escalation interrupt.
-        scope: The guardrail scope (LLM/AGENT/TOOL).
-        execution_stage: The hook type ("PreExecution" or "PostExecution").
+        escalation_result: The result from the escalation interrupt containing reviewed inputs/outputs.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
 
     Returns:
-        For LLM scope: Command to update messages with reviewed inputs/outputs.
-        For non-LLM scope: Empty dict (no message alteration).
+        Command to update messages with reviewed inputs/outputs, or empty dict if no updates needed.
 
     Raises:
         AgentTerminationException: If escalation response processing fails.
     """
-    if scope != GuardrailScope.LLM:
-        return {}
-
     try:
         reviewed_field = (
             "ReviewedInputs"
@@ -200,33 +238,140 @@ def _process_escalation_response(
         ) from e
 
 
+def _process_tool_escalation_response(
+    state: AgentGuardrailsGraphState,
+    escalation_result: Dict[str, Any],
+    execution_stage: ExecutionStage,
+    tool_name: str,
+) -> Dict[str, Any] | Command[Any]:
+    """Process escalation response for TOOL scope guardrails.
+
+    Updates the tool call arguments (PreExecution) or tool message content (PostExecution)
+    for the specific tool matching the tool_name. For PreExecution, finds the tool call
+    with the matching name and updates only that tool call's args with the reviewed dict.
+    For PostExecution, updates the tool message content.
+
+    Args:
+        state: The current agent graph state.
+        escalation_result: The result from the escalation interrupt containing reviewed inputs/outputs.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
+        tool_name: Name of the tool to update. Only the tool call matching this name will be updated.
+
+    Returns:
+        Command to update messages with reviewed tool call args or content, or empty dict if no updates needed.
+
+    Raises:
+        AgentTerminationException: If escalation response processing fails.
+    """
+    try:
+        reviewed_field = (
+            "ReviewedInputs"
+            if execution_stage == ExecutionStage.PRE_EXECUTION
+            else "ReviewedOutputs"
+        )
+
+        msgs = state.messages.copy()
+        if not msgs or reviewed_field not in escalation_result:
+            return {}
+
+        last_message = msgs[-1]
+        if execution_stage == ExecutionStage.PRE_EXECUTION:
+            if not isinstance(last_message, AIMessage):
+                return {}
+
+            # Get reviewed tool calls args from escalation result
+            reviewed_inputs_json = escalation_result[reviewed_field]
+            if not reviewed_inputs_json:
+                return {}
+
+            reviewed_tool_calls_args = json.loads(reviewed_inputs_json)
+            if not isinstance(reviewed_tool_calls_args, dict):
+                return {}
+
+            # Find and update only the tool call with matching name
+            if last_message.tool_calls:
+                tool_calls = list(last_message.tool_calls)
+                for tool_call in tool_calls:
+                    call_name = extract_tool_name(tool_call)
+                    if call_name == tool_name:
+                        # Update args for the matching tool call
+                        if isinstance(reviewed_tool_calls_args, dict):
+                            if isinstance(tool_call, dict):
+                                tool_call["args"] = reviewed_tool_calls_args
+                            else:
+                                tool_call.args = reviewed_tool_calls_args
+                        break
+                last_message.tool_calls = tool_calls
+        else:
+            if not isinstance(last_message, ToolMessage):
+                return {}
+
+            # PostExecution: update tool message content
+            reviewed_outputs_json = escalation_result[reviewed_field]
+            if reviewed_outputs_json:
+                last_message.content = reviewed_outputs_json
+
+        return Command[Any](update={"messages": msgs})
+    except Exception as e:
+        raise AgentTerminationException(
+            code=UiPathErrorCode.EXECUTION_ERROR,
+            title="Escalation rejected",
+            detail=str(e),
+        ) from e
+
+
 def _extract_escalation_content(
     state: AgentGuardrailsGraphState,
     scope: GuardrailScope,
     execution_stage: ExecutionStage,
+    guarded_node_name: str,
 ) -> str | list[str | Dict[str, Any]]:
     """Extract escalation content from state based on guardrail scope and execution stage.
 
     Args:
         state: The current agent graph state.
         scope: The guardrail scope (LLM/AGENT/TOOL).
-        execution_stage: The execution stage enum.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
 
     Returns:
-        For non-LLM scope: Empty string.
-        For LLM PreExecution: JSON string with message content.
-        For LLM PostExecution: JSON array with tool call content and message content.
-    """
-    if scope != GuardrailScope.LLM:
-        return ""
+        str or list[str | Dict[str, Any]]: For LLM scope, returns JSON string or list with message/tool call content.
+        For AGENT scope, returns empty string. For TOOL scope, returns JSON string or list with tool-specific content.
 
+    Raises:
+        AgentTerminationException: If no messages are found in state.
+    """
     if not state.messages:
         raise AgentTerminationException(
             code=UiPathErrorCode.EXECUTION_ERROR,
             title="Invalid state message",
-            detail="No messages in state",
+            detail="No message found into agent state",
         )
 
+    match scope:
+        case GuardrailScope.LLM:
+            return _extract_llm_escalation_content(state, execution_stage)
+        case GuardrailScope.AGENT:
+            return _extract_agent_escalation_content(state, execution_stage)
+        case GuardrailScope.TOOL:
+            return _extract_tool_escalation_content(
+                state, execution_stage, guarded_node_name
+            )
+
+
+def _extract_llm_escalation_content(
+    state: AgentGuardrailsGraphState, execution_stage: ExecutionStage
+) -> str | list[str | Dict[str, Any]]:
+    """Extract escalation content for LLM scope guardrails.
+
+    Args:
+        state: The current agent graph state.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
+
+    Returns:
+        str or list[str | Dict[str, Any]]: For PreExecution, returns JSON string with message content or empty string.
+        For PostExecution, returns JSON string (array) with tool call content and message content.
+        Returns empty string if no content found.
+    """
     last_message = state.messages[-1]
     if execution_stage == ExecutionStage.PRE_EXECUTION:
         if isinstance(last_message, ToolMessage):
@@ -260,6 +405,70 @@ def _extract_escalation_content(
     return _message_text(last_message)
 
 
+def _extract_agent_escalation_content(
+    state: AgentGuardrailsGraphState, execution_stage: ExecutionStage
+) -> str | list[str | Dict[str, Any]]:
+    """Extract escalation content for AGENT scope guardrails.
+
+    Args:
+        state: The current agent graph state.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
+
+    Returns:
+        str: Empty string (AGENT scope guardrails do not extract escalation content).
+    """
+    return ""
+
+
+def _extract_tool_escalation_content(
+    state: AgentGuardrailsGraphState, execution_stage: ExecutionStage, tool_name: str
+) -> str | list[str | Dict[str, Any]]:
+    """Extract escalation content for TOOL scope guardrails.
+
+    Args:
+        state: The current agent graph state.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
+        tool_name: Optional tool name to filter tool calls. If provided, only extracts args for matching tool.
+
+    Returns:
+        str or list[str | Dict[str, Any]]: For PreExecution, returns JSON string with tool call arguments
+        for the specified tool name, or empty string if not found. For PostExecution, returns string with
+        tool message content, or empty string if message type doesn't match.
+    """
+    last_message = state.messages[-1]
+    if execution_stage == ExecutionStage.PRE_EXECUTION:
+        if not isinstance(last_message, AIMessage):
+            return ""
+        if not last_message.tool_calls:
+            return ""
+
+        # Find the tool call with matching name
+        for tool_call in last_message.tool_calls:
+            call_name = extract_tool_name(tool_call)
+            if call_name == tool_name:
+                # Extract args from the matching tool call
+                args = (
+                    tool_call.get("args")
+                    if isinstance(tool_call, dict)
+                    else getattr(tool_call, "args", None)
+                )
+                if args is not None:
+                    return json.dumps(args)
+        return ""
+    else:
+        if not isinstance(last_message, ToolMessage):
+            return ""
+        return last_message.content
+
+
+def extract_tool_name(tool_call: ToolCall) -> Any | None:
+    return (
+        tool_call.get("name")
+        if isinstance(tool_call, dict)
+        else getattr(tool_call, "name", None)
+    )
+
+
 def _execution_stage_to_escalation_field(
     execution_stage: ExecutionStage,
 ) -> str:
@@ -272,3 +481,19 @@ def _execution_stage_to_escalation_field(
         "Inputs" for PRE_EXECUTION, "Outputs" for POST_EXECUTION.
     """
     return "Inputs" if execution_stage == ExecutionStage.PRE_EXECUTION else "Outputs"
+
+
+def _execution_stage_to_string(
+    execution_stage: ExecutionStage,
+) -> Literal["PreExecution", "PostExecution"]:
+    """Convert ExecutionStage enum to string literal.
+
+    Args:
+        execution_stage: The execution stage enum.
+
+    Returns:
+        "PreExecution" for PRE_EXECUTION, "PostExecution" for POST_EXECUTION.
+    """
+    if execution_stage == ExecutionStage.PRE_EXECUTION:
+        return "PreExecution"
+    return "PostExecution"

uipath_langchain/agent/guardrails/actions/log_action.py

@@ -31,6 +31,7 @@ class LogAction(GuardrailAction):
         guardrail: BaseGuardrail,
         scope: GuardrailScope,
         execution_stage: ExecutionStage,
+        guarded_component_name: str,
     ) -> GuardrailActionNode:
         """Create a guardrail action node that logs validation failures.
 

uipath_langchain/agent/guardrails/guardrail_nodes.py

@@ -1,8 +1,9 @@
+import json
 import logging
 import re
 from typing import Any, Callable
 
-from langchain_core.messages import AnyMessage, HumanMessage, SystemMessage
+from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, SystemMessage
 from langgraph.types import Command
 from uipath.platform import UiPath
 from uipath.platform.guardrails import (
@@ -108,11 +109,58 @@ def create_tool_guardrail_node(
     execution_stage: ExecutionStage,
     success_node: str,
     failure_node: str,
+    tool_name: str,
 ) -> tuple[str, Callable[[AgentGuardrailsGraphState], Any]]:
-    # To be implemented in future PR
+    """Create a guardrail node for TOOL scope guardrails.
+
+    Args:
+        guardrail: The guardrail to evaluate.
+        execution_stage: The execution stage (PRE_EXECUTION or POST_EXECUTION).
+        success_node: Node to route to on validation pass.
+        failure_node: Node to route to on validation fail.
+        tool_name: Name of the tool to extract arguments from.
+
+    Returns:
+        A tuple of (node_name, node_function) for the guardrail evaluation node.
+    """
+
     def _payload_generator(state: AgentGuardrailsGraphState) -> str:
+        """Extract tool call arguments for the specified tool name.
+
+        Args:
+            state: The current agent graph state.
+
+        Returns:
+            JSON string of the tool call arguments, or empty string if not found.
+        """
         if not state.messages:
             return ""
+
+        if execution_stage == ExecutionStage.PRE_EXECUTION:
+            if not isinstance(state.messages[-1], AIMessage):
+                return ""
+            message = state.messages[-1]
+
+            if not message.tool_calls:
+                return ""
+
+            # Find the first tool call with matching name
+            for tool_call in message.tool_calls:
+                call_name = (
+                    tool_call.get("name")
+                    if isinstance(tool_call, dict)
+                    else getattr(tool_call, "name", None)
+                )
+                if call_name == tool_name:
+                    # Extract args from the tool call
+                    args = (
+                        tool_call.get("args")
+                        if isinstance(tool_call, dict)
+                        else getattr(tool_call, "args", None)
+                    )
+                    if args is not None:
+                        return json.dumps(args)
+
         return _message_text(state.messages[-1])
 
     return _create_guardrail_node(

uipath_langchain/agent/guardrails/guardrails_subgraph.py

@@ -1,7 +1,9 @@
+from functools import partial
 from typing import Any, Callable, Sequence
 
 from langgraph.constants import END, START
 from langgraph.graph import StateGraph
+from langgraph.prebuilt import ToolNode
 from uipath.platform.guardrails import (
     BaseGuardrail,
     BuiltInValidatorGuardrail,
@@ -90,6 +92,7 @@ def _create_guardrails_subgraph(
             ExecutionStage.PRE_EXECUTION,
             node_factory,
             inner_name,
+            inner_name,
         )
         subgraph.add_edge(START, first_pre_exec_guardrail_node)
     else:
@@ -107,6 +110,7 @@ def _create_guardrails_subgraph(
             ExecutionStage.POST_EXECUTION,
             node_factory,
             END,
+            inner_node,
         )
         subgraph.add_edge(inner_name, first_post_exec_guardrail_node)
     else:
@@ -130,6 +134,7 @@ def _build_guardrail_node_chain(
         GuardrailActionNode,
     ],
     next_node: str,
+    guarded_node_name: str,
 ) -> str:
     """Recursively build a chain of guardrail nodes in reverse order.
 
@@ -157,7 +162,10 @@ def _build_guardrail_node_chain(
     remaining_guardrails = guardrails[:-1]
 
     fail_node_name, fail_node = action.action_node(
-        guardrail=guardrail, scope=scope, execution_stage=execution_stage
+        guardrail=guardrail,
+        scope=scope,
+        execution_stage=execution_stage,
+        guarded_component_name=guarded_node_name,
     )
 
     # Create the guardrail evaluation node.
@@ -179,6 +187,7 @@ def _build_guardrail_node_chain(
         execution_stage,
         node_factory,
         guardrail_node_name,
+        guarded_node_name,
     )
 
     return previous_node_name
@@ -193,6 +202,9 @@ def create_llm_guardrails_subgraph(
         for (guardrail, _) in (guardrails or [])
         if GuardrailScope.LLM in guardrail.selector.scopes
     ]
+    if applicable_guardrails is None or len(applicable_guardrails) == 0:
+        return llm_node[1]
+
     return _create_guardrails_subgraph(
         main_inner_node=llm_node,
         guardrails=applicable_guardrails,
@@ -202,6 +214,24 @@ def create_llm_guardrails_subgraph(
     )
 
 
+def create_tools_guardrails_subgraph(
+    tool_nodes: dict[str, ToolNode],
+    guardrails: Sequence[tuple[BaseGuardrail, GuardrailAction]] | None,
+) -> dict[str, ToolNode]:
+    """Create tool nodes with guardrails.
+    Args:
+    """
+    result: dict[str, ToolNode] = {}
+    for tool_name, tool_node in tool_nodes.items():
+        subgraph = create_tool_guardrails_subgraph(
+            (tool_name, tool_node),
+            guardrails,
+        )
+        result[tool_name] = subgraph
+
+    return result
+
+
 def create_agent_guardrails_subgraph(
     agent_node: tuple[str, Any],
     guardrails: Sequence[tuple[BaseGuardrail, GuardrailAction]] | None,
@@ -217,6 +247,9 @@ def create_agent_guardrails_subgraph(
         for (guardrail, _) in (guardrails or [])
         if GuardrailScope.AGENT in guardrail.selector.scopes
     ]
+    if applicable_guardrails is None or len(applicable_guardrails) == 0:
+        return agent_node[1]
+
     return _create_guardrails_subgraph(
         main_inner_node=agent_node,
         guardrails=applicable_guardrails,
@@ -238,10 +271,13 @@ def create_tool_guardrails_subgraph(
         and guardrail.selector.match_names is not None
         and tool_name in guardrail.selector.match_names
     ]
+    if applicable_guardrails is None or len(applicable_guardrails) == 0:
+        return tool_node[1]
+
     return _create_guardrails_subgraph(
         main_inner_node=tool_node,
         guardrails=applicable_guardrails,
         scope=GuardrailScope.TOOL,
         execution_stages=[ExecutionStage.PRE_EXECUTION, ExecutionStage.POST_EXECUTION],
-        node_factory=create_tool_guardrail_node,
+        node_factory=partial(create_tool_guardrail_node, tool_name=tool_name),
     )

uipath_langchain/agent/react/agent.py

@@ -11,6 +11,7 @@ from uipath.platform.guardrails import BaseGuardrail
 
 from ..guardrails import create_llm_guardrails_subgraph
 from ..guardrails.actions import GuardrailAction
+from ..guardrails.guardrails_subgraph import create_tools_guardrails_subgraph
 from ..tools import create_tool_node
 from .init_node import (
     create_init_node,
@@ -73,6 +74,9 @@ def create_agent(
 
     init_node = create_init_node(messages)
     tool_nodes = create_tool_node(agent_tools)
+    tool_nodes_with_guardrails = create_tools_guardrails_subgraph(
+        tool_nodes, guardrails
+    )
     terminate_node = create_terminate_node(output_schema)
 
     InnerAgentGraphState = create_state_with_input(
@@ -84,7 +88,7 @@ def create_agent(
     )
     builder.add_node(AgentGraphNode.INIT, init_node)
 
-    for tool_name, tool_node in tool_nodes.items():
+    for tool_name, tool_node in tool_nodes_with_guardrails.items():
         builder.add_node(tool_name, tool_node)
 
     builder.add_node(AgentGraphNode.TERMINATE, terminate_node)
@@ -98,7 +102,7 @@ def create_agent(
     builder.add_node(AgentGraphNode.AGENT, llm_with_guardrails_subgraph)
     builder.add_edge(AgentGraphNode.INIT, AgentGraphNode.AGENT)
 
-    tool_node_names = list(tool_nodes.keys())
+    tool_node_names = list(tool_nodes_with_guardrails.keys())
     builder.add_conditional_edges(
         AgentGraphNode.AGENT,
         route_agent,

uipath_langchain/chat/openai.py

@@ -4,6 +4,7 @@ from typing import Optional
 
 import httpx
 from langchain_openai import AzureChatOpenAI
+from uipath._utils._ssl_context import get_httpx_client_kwargs
 from uipath.utils import EndpointManager
 
 from .supported_models import OpenAIModels
@@ -87,11 +88,11 @@ class UiPathChatOpenAI(AzureChatOpenAI):
             default_headers=self._build_headers(token),
             http_async_client=httpx.AsyncClient(
                 transport=UiPathURLRewriteTransport(verify=True),
-                verify=True,
+                **get_httpx_client_kwargs(),
             ),
             http_client=httpx.Client(
                 transport=UiPathSyncURLRewriteTransport(verify=True),
-                verify=True,
+                **get_httpx_client_kwargs(),
             ),
             api_key=token,
             api_version=api_version,