feat(escalation): return task_id and assigned_to from escalation tool (#517)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: saksharthakkar

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-langchain"
-version = "0.5.28"
+version = "0.5.29"
 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"

src/uipath_langchain/agent/tools/escalation_tool.py

@@ -6,7 +6,7 @@
 from langchain_core.messages.tool import ToolCall
 from langchain_core.tools import BaseTool, StructuredTool
 from langgraph.types import interrupt
-from pydantic import BaseModel, TypeAdapter
+from pydantic import BaseModel
 from uipath.agent.models.agent import (
     AgentEscalationChannel,
     AgentEscalationRecipient,
@@ -98,6 +98,15 @@ def _resolve_task_title(
     return "Escalation Task"
 
 
+def _get_user_email(user: Any) -> str | None:
+    """Extract email from user object/dict."""
+    if user is None:
+        return None
+    if isinstance(user, dict):
+        return user.get("emailAddress")
+    return getattr(user, "emailAddress", None)
+
+
 def create_escalation_tool(
     resource: AgentEscalationResourceConfig,
 ) -> StructuredTool:
@@ -134,7 +143,7 @@ async def escalation_tool_fn(**kwargs: Any) -> dict[str, Any]:
             example_calls=channel.properties.example_calls,
         )
         async def escalate():
-            interrupt(
+            return interrupt(
                 CreateEscalation(
                     title=task_title,
                     data=kwargs,
@@ -149,11 +158,13 @@ async def escalate():
             )
 
         result = await escalate()
-        if isinstance(result, dict):
-            result = TypeAdapter(EscalationToolOutput).validate_python(result)
 
-        escalation_action = getattr(result, "action", None)
-        escalation_output = getattr(result, "data", {})
+        # Extract task info before validation
+        task_id = result.id
+        assigned_to = _get_user_email(result.assigned_to_user)
+
+        escalation_action = result.action
+        escalation_output = result.data or {}
 
         outcome_str = (
             channel.outcome_mapping.get(escalation_action)
@@ -167,7 +178,9 @@ async def escalate():
         return {
             "action": outcome,
             "output": escalation_output,
-            "escalation_action": escalation_action,
+            "outcome": escalation_action,
+            "task_id": task_id,
+            "assigned_to": assigned_to,
         }
 
     async def escalation_wrapper(
@@ -182,14 +195,17 @@ async def escalation_wrapper(
             channel.task_title, sanitize_dict_for_serialization(dict(state))
         )
 
+        tool.metadata["_call_id"] = call.get("id")
+        tool.metadata["_call_args"] = dict(call.get("args", {}))
+
         call["args"] = handle_static_args(resource, state, call["args"])
         result = await tool.ainvoke(call["args"])
 
         if result["action"] == EscalationAction.END:
             output_detail = f"Escalation output: {result['output']}"
             termination_title = (
                 f"Agent run ended based on escalation outcome {result['action']} "
-                f"with directive {result['escalation_action']}"
+                f"with directive {result['outcome']}"
             )
 
             raise AgentTerminationException(
@@ -198,7 +214,12 @@ async def escalation_wrapper(
                 detail=output_detail,
             )
 
-        return result["output"]
+        return {
+            **result["output"],
+            "outcome": result["outcome"],
+            "task_id": result["task_id"],
+            "assigned_to": result["assigned_to"],
+        }
 
     tool = StructuredToolWithArgumentProperties(
         name=tool_name,

tests/agent/tools/test_escalation_tool.py

@@ -15,6 +15,7 @@
 from uipath.platform.action_center.tasks import TaskRecipient, TaskRecipientType
 
 from uipath_langchain.agent.tools.escalation_tool import (
+    _get_user_email,
     create_escalation_tool,
     resolve_asset,
     resolve_recipient_value,
@@ -509,6 +510,9 @@ async def test_escalation_tool_result_validation(
         """Test that tool properly processes and validates results."""
         # Mock interrupt to return a proper result object with action and data
         mock_result = MagicMock()
+        mock_result.id = 123
+        mock_result.key = None
+        mock_result.assigned_to_user = None
         mock_result.action = "approve"
         mock_result.data = {}
         mock_interrupt.return_value = mock_result
@@ -519,9 +523,11 @@ async def test_escalation_tool_result_validation(
         # Invoke through the wrapper
         result = await tool.awrapper(tool, call, {})  # type: ignore[attr-defined]
 
-        # Should successfully process the result
+        # Should successfully process the result with task info
         assert isinstance(result, dict)
-        assert result == {}
+        assert result["outcome"] == "approve"
+        assert result["task_id"] == 123
+        assert result["assigned_to"] is None
 
     @pytest.mark.asyncio
     @patch("uipath_langchain.agent.tools.escalation_tool.interrupt")
@@ -546,14 +552,19 @@ async def test_escalation_tool_extracts_action_from_result(
 
     @pytest.mark.asyncio
     @patch("uipath_langchain.agent.tools.escalation_tool.interrupt")
-    async def test_escalation_tool_with_outcome_mapping(self, mock_interrupt):
-        """Test escalation tool with outcome mapping for actions."""
+    async def test_escalation_tool_with_outcome_mapping_end(self, mock_interrupt):
+        """Test escalation tool with outcome mapping that ends agent."""
+        from uipath_langchain.agent.exceptions import AgentTerminationException
+
         mock_result = MagicMock()
+        mock_result.id = 456
+        mock_result.key = None
+        mock_result.assigned_to_user = None
         mock_result.action = "approve"
         mock_result.data = {"approved": True}
         mock_interrupt.return_value = mock_result
 
-        # Create resource with outcome mapping
+        # Create resource with outcome mapping where approve -> end
         channel_dict = {
             "name": "action_center",
             "type": "actionCenter",
@@ -578,8 +589,106 @@ async def test_escalation_tool_with_outcome_mapping(self, mock_interrupt):
         tool = create_escalation_tool(resource)
         call = ToolCall(args={}, id="test-call", name=tool.name)
 
-        # Invoke through the wrapper
-        await tool.awrapper(tool, call, {})  # type: ignore[attr-defined]
+        # Invoke through the wrapper - should raise AgentTerminationException
+        with pytest.raises(AgentTerminationException):
+            await tool.awrapper(tool, call, {})  # type: ignore[attr-defined]
 
-        # Verify interrupt was called with approval action
         assert mock_interrupt.called
+
+
+class TestGetUserEmail:
+    """Test the _get_user_email helper function."""
+
+    def test_none_returns_none(self):
+        """Test that None input returns None."""
+        assert _get_user_email(None) is None
+
+    def test_dict_with_email_address(self):
+        """Test extraction from dict with emailAddress field."""
+        user = {"emailAddress": "test@example.com", "name": "Test"}
+        assert _get_user_email(user) == "test@example.com"
+
+    def test_dict_without_email_address(self):
+        """Test dict without emailAddress returns None."""
+        user = {"name": "Test", "id": 123}
+        assert _get_user_email(user) is None
+
+    def test_object_with_email_address(self):
+        """Test extraction from object with emailAddress attribute."""
+        user = MagicMock(emailAddress="test@example.com")
+        assert _get_user_email(user) == "test@example.com"
+
+    def test_object_without_email_address(self):
+        """Test object without emailAddress attribute returns None."""
+        user = MagicMock(spec=["name", "id"])
+        assert _get_user_email(user) is None
+
+
+class TestEscalationToolTaskInfo:
+    """Test that escalation tool extracts task_id and assigned_to."""
+
+    @pytest.fixture
+    def escalation_resource(self):
+        """Create a minimal escalation tool resource config."""
+        return AgentEscalationResourceConfig(
+            name="approval",
+            description="Request approval",
+            channels=[
+                AgentEscalationChannel(
+                    name="action_center",
+                    type="actionCenter",
+                    description="Action Center channel",
+                    input_schema={"type": "object", "properties": {}},
+                    output_schema={"type": "object", "properties": {}},
+                    properties=AgentEscalationChannelProperties(
+                        app_name="ApprovalApp",
+                        app_version=1,
+                        resource_key="test-key",
+                    ),
+                    recipients=[],
+                )
+            ],
+        )
+
+    @pytest.mark.asyncio
+    @patch("uipath_langchain.agent.tools.escalation_tool.interrupt")
+    async def test_wrapper_returns_task_id_and_assigned_to(
+        self, mock_interrupt, escalation_resource
+    ):
+        """Test that wrapper result includes task_id and assigned_to from Task."""
+        mock_result = MagicMock()
+        mock_result.id = 12345
+        mock_result.key = None
+        mock_result.assigned_to_user = {"emailAddress": "user@example.com"}
+        mock_result.action = "approve"
+        mock_result.data = {"reason": "looks good"}
+        mock_interrupt.return_value = mock_result
+
+        tool = create_escalation_tool(escalation_resource)
+        call = ToolCall(args={}, id="test-call", name=tool.name)
+        result = await tool.awrapper(tool, call, {})  # type: ignore[attr-defined]
+
+        assert result["task_id"] == 12345
+        assert result["assigned_to"] == "user@example.com"
+        assert result["outcome"] == "approve"
+
+    @pytest.mark.asyncio
+    @patch("uipath_langchain.agent.tools.escalation_tool.interrupt")
+    async def test_wrapper_handles_missing_assigned_to_user(
+        self, mock_interrupt, escalation_resource
+    ):
+        """Test that wrapper handles None assigned_to_user gracefully."""
+        mock_result = MagicMock()
+        mock_result.id = 99999
+        mock_result.key = None
+        mock_result.assigned_to_user = None
+        mock_result.action = "reject"
+        mock_result.data = {}
+        mock_interrupt.return_value = mock_result
+
+        tool = create_escalation_tool(escalation_resource)
+        call = ToolCall(args={}, id="test-call", name=tool.name)
+        result = await tool.awrapper(tool, call, {})  # type: ignore[attr-defined]
+
+        assert result["task_id"] == 99999
+        assert result["assigned_to"] is None