Feat/add guardrails task recipient (#448)

Author: dianapirvulescu

pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "uipath-langchain"
-version = "0.4.21"
+version = "0.4.22"
 description = "Python SDK that enables developers to build and deploy LangGraph agents to the UiPath Cloud Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
 dependencies = [
-    "uipath>=2.5.22,<2.6.0",
+    "uipath>=2.5.23,<2.6.0",
     "uipath-runtime>=0.5.1,<0.6.0",
     "langgraph>=1.0.0, <2.0.0",
     "langchain-core>=1.2.5, <2.0.0",

src/uipath_langchain/agent/guardrails/actions/escalate_action.py

@@ -78,7 +78,7 @@ async def _node(
             state: AgentGuardrailsGraphState,
         ) -> Dict[str, Any] | Command[Any]:
             # Resolve recipient value (handles both StandardRecipient and AssetRecipient)
-            assignee = await resolve_recipient_value(self.recipient)
+            task_recipient = await resolve_recipient_value(self.recipient)
 
             # Validate message count based on execution stage
             _validate_message_count(state, execution_stage)
@@ -140,7 +140,7 @@ async def _node(
                     app_folder_path=self.app_folder_path,
                     title="Agents Guardrail Task",
                     data=data,
-                    assignee=assignee,
+                    recipient=task_recipient,
                 )
             )
 

src/uipath_langchain/agent/tools/escalation_tool.py

@@ -9,12 +9,14 @@
 from uipath.agent.models.agent import (
     AgentEscalationChannel,
     AgentEscalationRecipient,
+    AgentEscalationRecipientType,
     AgentEscalationResourceConfig,
     AssetRecipient,
     StandardRecipient,
 )
 from uipath.eval.mocks import mockable
 from uipath.platform import UiPath
+from uipath.platform.action_center.tasks import TaskRecipient, TaskRecipientType
 from uipath.platform.common import CreateEscalation
 from uipath.runtime.errors import UiPathErrorCode
 
@@ -32,13 +34,24 @@ class EscalationAction(str, Enum):
     END = "end"
 
 
-async def resolve_recipient_value(recipient: AgentEscalationRecipient) -> str | None:
+async def resolve_recipient_value(
+    recipient: AgentEscalationRecipient,
+) -> TaskRecipient | None:
     """Resolve recipient value based on recipient type."""
     if isinstance(recipient, AssetRecipient):
-        return await resolve_asset(recipient.asset_name, recipient.folder_path)
+        value = await resolve_asset(recipient.asset_name, recipient.folder_path)
+        type = None
+        if recipient.type == AgentEscalationRecipientType.ASSET_USER_EMAIL:
+            type = TaskRecipientType.EMAIL
+        elif recipient.type == AgentEscalationRecipientType.ASSET_GROUP_NAME:
+            type = TaskRecipientType.GROUP_NAME
+        return TaskRecipient(value=value, type=type)
 
     if isinstance(recipient, StandardRecipient):
-        return recipient.value
+        type = TaskRecipientType(recipient.type)
+        if recipient.type == AgentEscalationRecipientType.USER_EMAIL:
+            type = TaskRecipientType.EMAIL
+        return TaskRecipient(value=recipient.value, type=type)
 
     return None
 
@@ -86,21 +99,21 @@ async def create_escalation_tool(
     async def escalation_tool_fn(**kwargs: Any) -> dict[str, Any]:
         task_title = channel.task_title or "Escalation Task"
 
-        assignee: str | None = (
+        recipient: TaskRecipient | None = (
             await resolve_recipient_value(channel.recipients[0])
             if channel.recipients
             else None
         )
 
-        # Assignee requires runtime resolution, store in metadata after resolving
+        # Recipient requires runtime resolution, store in metadata after resolving
         if tool.metadata is not None:
-            tool.metadata["assignee"] = assignee
+            tool.metadata["recipient"] = recipient
 
         result = interrupt(
             CreateEscalation(
                 title=task_title,
                 data=kwargs,
-                assignee=assignee,
+                recipient=recipient,
                 app_name=channel.properties.app_name,
                 app_folder_path=channel.properties.folder_name,
                 app_version=channel.properties.app_version,

tests/agent/guardrails/actions/test_escalate_action.py

@@ -13,6 +13,7 @@
     AssetRecipient,
     StandardRecipient,
 )
+from uipath.platform.action_center.tasks import TaskRecipient, TaskRecipientType
 from uipath.platform.guardrails import GuardrailScope
 from uipath.runtime.errors import UiPathErrorCode
 
@@ -184,7 +185,10 @@ async def test_node_interrupts_with_correct_message_data(
         assert call_args.app_name == "TestApp"
         assert call_args.app_folder_path == "TestFolder"
         assert call_args.title == "Agents Guardrail Task"
-        assert call_args.assignee == "test@example.com"
+        assert call_args.assignee == ""
+        assert call_args.recipient == TaskRecipient(
+            value="test@example.com", type=TaskRecipientType.EMAIL
+        )
         assert call_args.data["GuardrailName"] == "Test Guardrail"
         assert call_args.data["GuardrailDescription"] == "Test description"
         assert call_args.data["ExecutionStage"] == expected_stage
@@ -248,7 +252,10 @@ async def test_node_post_agent_interrupts_with_correct_agent_result_data(
         assert call_args.app_name == "TestApp"
         assert call_args.app_folder_path == "TestFolder"
         assert call_args.title == "Agents Guardrail Task"
-        assert call_args.assignee == "test@example.com"
+        assert call_args.assignee == ""
+        assert call_args.recipient == TaskRecipient(
+            value="test@example.com", type=TaskRecipientType.EMAIL
+        )
         assert call_args.data["GuardrailName"] == "Test Guardrail"
         assert call_args.data["GuardrailDescription"] == "Test description"
         assert call_args.data["ExecutionStage"] == "PostExecution"
@@ -1524,10 +1531,22 @@ async def test_validate_message_count_empty_messages_raises_exception(self):
     @pytest.mark.parametrize(
         "recipient,expected_value",
         [
-            (STANDARD_USER_EMAIL_RECIPIENT, "user@example.com"),
-            (STANDARD_GROUP_NAME_RECIPIENT, "AdminGroup"),
-            (ASSET_USER_EMAIL_RECIPIENT, "user@example.com"),
-            (ASSET_GROUP_NAME_RECIPIENT, "AdminGroup"),
+            (
+                STANDARD_USER_EMAIL_RECIPIENT,
+                TaskRecipient(value="user@example.com", type=TaskRecipientType.EMAIL),
+            ),
+            (
+                STANDARD_GROUP_NAME_RECIPIENT,
+                TaskRecipient(value="AdminGroup", type=TaskRecipientType.GROUP_NAME),
+            ),
+            (
+                ASSET_USER_EMAIL_RECIPIENT,
+                TaskRecipient(value="user@example.com", type=TaskRecipientType.EMAIL),
+            ),
+            (
+                ASSET_GROUP_NAME_RECIPIENT,
+                TaskRecipient(value="AdminGroup", type=TaskRecipientType.GROUP_NAME),
+            ),
         ],
     )
     @patch(
@@ -1575,7 +1594,7 @@ async def test_node_resolves_recipient_correctly(
         # Verify interrupt was called with the resolved assignee
         assert mock_interrupt.called
         call_args = mock_interrupt.call_args[0][0]
-        assert call_args.assignee == expected_value
+        assert call_args.recipient == expected_value
 
     @pytest.mark.asyncio
     @patch(

tests/agent/tools/test_escalation_tool.py

@@ -11,6 +11,7 @@
     AssetRecipient,
     StandardRecipient,
 )
+from uipath.platform.action_center.tasks import TaskRecipient, TaskRecipientType
 
 from uipath_langchain.agent.tools.escalation_tool import (
     create_escalation_tool,
@@ -113,7 +114,9 @@ async def test_resolve_recipient_asset_user_email(self, mock_resolve_asset):
 
         result = await resolve_recipient_value(recipient)
 
-        assert result == "resolved@example.com"
+        assert result == TaskRecipient(
+            value="resolved@example.com", type=TaskRecipientType.EMAIL
+        )
         mock_resolve_asset.assert_called_once_with("email_asset", "/Test/Folder")
 
     @pytest.mark.asyncio
@@ -130,7 +133,9 @@ async def test_resolve_recipient_asset_group_name(self, mock_resolve_asset):
 
         result = await resolve_recipient_value(recipient)
 
-        assert result == "ResolvedGroup"
+        assert result == TaskRecipient(
+            value="ResolvedGroup", type=TaskRecipientType.GROUP_NAME
+        )
         mock_resolve_asset.assert_called_once_with("group_asset", "/Test/Folder")
 
     @pytest.mark.asyncio
@@ -143,7 +148,9 @@ async def test_resolve_recipient_user_email(self):
 
         result = await resolve_recipient_value(recipient)
 
-        assert result == "direct@example.com"
+        assert result == TaskRecipient(
+            value="direct@example.com", type=TaskRecipientType.EMAIL
+        )
 
     @pytest.mark.asyncio
     @patch("uipath_langchain.agent.tools.escalation_tool.resolve_asset")
@@ -262,10 +269,10 @@ async def test_escalation_tool_metadata_has_channel_type(self, escalation_resour
 
     @pytest.mark.asyncio
     @patch("uipath_langchain.agent.tools.escalation_tool.interrupt")
-    async def test_escalation_tool_metadata_has_assignee(
+    async def test_escalation_tool_metadata_has_recipient(
         self, mock_interrupt, escalation_resource
     ):
-        """Test that metadata contains assignee when recipient is USER_EMAIL."""
+        """Test that metadata contains recipient when recipient is USER_EMAIL."""
         # Mock interrupt to return a result
         mock_result = MagicMock()
         mock_result.action = None
@@ -278,14 +285,16 @@ async def test_escalation_tool_metadata_has_assignee(
         await tool.ainvoke({})
 
         assert tool.metadata is not None
-        assert tool.metadata["assignee"] == "user@example.com"
+        assert tool.metadata["recipient"] == TaskRecipient(
+            value="user@example.com", type=TaskRecipientType.EMAIL
+        )
 
     @pytest.mark.asyncio
     @patch("uipath_langchain.agent.tools.escalation_tool.interrupt")
-    async def test_escalation_tool_metadata_assignee_none_when_no_recipients(
+    async def test_escalation_tool_metadata_recipient_none_when_no_recipients(
         self, mock_interrupt, escalation_resource_no_recipient
     ):
-        """Test that assignee is None when no recipients configured."""
+        """Test that recipient is None when no recipients configured."""
         # Mock interrupt to return a result
         mock_result = MagicMock()
         mock_result.action = None
@@ -298,4 +307,4 @@ async def test_escalation_tool_metadata_assignee_none_when_no_recipients(
         await tool.ainvoke({})
 
         assert tool.metadata is not None
-        assert tool.metadata["assignee"] is None
+        assert tool.metadata["recipient"] is None