Merge branch 'main' into feat/add-analyze-file-tool

Author: cristian-groza

.github/workflows/integration_tests.yml

@@ -21,6 +21,7 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Discover testcases
+      # Skip common directory - it's shared utilities, not a testcase
       id: discover
       run: |
         # Find all testcase folders (excluding common folders like README, etc.)

.gitignore

@@ -180,5 +180,6 @@ cython_debug/
 **/__uipath/
 **/.langgraph_api
 **/testcases/**/uipath.json
-
-/playground.py
+
+/playground.py
+/.claude/settings.local.json

pyproject.toml

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

src/uipath_langchain/chat/mapper.py

@@ -41,6 +41,7 @@ class UiPathChatMessagesMapper:
     def __init__(self):
         """Initialize the mapper with empty state."""
         self.tool_call_to_ai_message: dict[str, str] = {}
+        self.current_message: AIMessageChunk
         self.seen_message_ids: set[str] = set()
 
     def _extract_text(self, content: Any) -> str:
@@ -141,7 +142,7 @@ def _map_messages_internal(
     def map_event(
         self,
         message: BaseMessage,
-    ) -> UiPathConversationMessageEvent | None:
+    ) -> list[UiPathConversationMessageEvent] | None:
         """Convert LangGraph BaseMessage (chunk or full) into a UiPathConversationMessageEvent.
 
         Args:
@@ -168,16 +169,45 @@ def map_event(
 
             # Check if this is the last chunk by examining chunk_position
             if message.chunk_position == "last":
+                events: list[UiPathConversationMessageEvent] = []
+
+                # Loop through all content_blocks in current_message and create toolCallStart events for each tool_call_chunk
+                if self.current_message and self.current_message.content_blocks:
+                    for block in self.current_message.content_blocks:
+                        if block.get("type") == "tool_call_chunk":
+                            tool_chunk_block = cast(ToolCallChunk, block)
+                            tool_call_id = tool_chunk_block.get("id")
+                            tool_name = tool_chunk_block.get("name")
+                            tool_args = tool_chunk_block.get("args")
+
+                            if tool_call_id:
+                                tool_event = UiPathConversationMessageEvent(
+                                    message_id=message.id,
+                                    tool_call=UiPathConversationToolCallEvent(
+                                        tool_call_id=tool_call_id,
+                                        start=UiPathConversationToolCallStartEvent(
+                                            tool_name=tool_name,
+                                            timestamp=timestamp,
+                                            input=UiPathInlineValue(inline=tool_args),
+                                        ),
+                                    ),
+                                )
+                                events.append(tool_event)
+
+                # Create the final event for the message
                 msg_event.end = UiPathConversationMessageEndEvent(timestamp=timestamp)
                 msg_event.content_part = UiPathConversationContentPartEvent(
                     content_part_id=f"chunk-{message.id}-0",
                     end=UiPathConversationContentPartEndEvent(),
                 )
-                return msg_event
+                events.append(msg_event)
+
+                return events
 
             # For every new message_id, start a new message
             if message.id not in self.seen_message_ids:
                 self.seen_message_ids.add(message.id)
+                self.current_message = message
                 msg_event.start = UiPathConversationMessageStartEvent(
                     role="assistant", timestamp=timestamp
                 )
@@ -200,7 +230,6 @@ def map_event(
                             content_part_id=f"chunk-{message.id}-0",
                             chunk=UiPathConversationContentPartChunkEvent(
                                 data=text,
-                                content_part_sequence=0,
                             ),
                         )
 
@@ -210,19 +239,10 @@ def map_event(
                         tool_call_id = tool_chunk_block.get("id")
                         if tool_call_id:
                             # Track tool_call_id -> ai_message_id mapping
-                            self.tool_call_to_ai_message[str(tool_call_id)] = message.id
-
-                        args = tool_chunk_block.get("args") or ""
+                            self.tool_call_to_ai_message[tool_call_id] = message.id
 
-                        msg_event.content_part = UiPathConversationContentPartEvent(
-                            content_part_id=f"chunk-{message.id}-0",
-                            chunk=UiPathConversationContentPartChunkEvent(
-                                data=args,
-                                content_part_sequence=0,
-                            ),
-                        )
-                        # Continue so that multiple tool_call_chunks in the same block list
-                        # are handled correctly
+                        # Accumulate the message chunk
+                        self.current_message = self.current_message + message
                         continue
 
             # Fallback: raw string content on the chunk (rare when using content_blocks)
@@ -231,7 +251,6 @@ def map_event(
                     content_part_id=f"content-{message.id}",
                     chunk=UiPathConversationContentPartChunkEvent(
                         data=message.content,
-                        content_part_sequence=0,
                     ),
                 )
 
@@ -241,7 +260,7 @@ def map_event(
                 or msg_event.tool_call
                 or msg_event.end
             ):
-                return msg_event
+                return [msg_event]
 
             return None
 
@@ -275,35 +294,34 @@ def map_event(
                     # Keep as string if not valid JSON
                     pass
 
-            return UiPathConversationMessageEvent(
-                message_id=result_message_id or str(uuid4()),
-                tool_call=UiPathConversationToolCallEvent(
-                    tool_call_id=message.tool_call_id,
-                    start=UiPathConversationToolCallStartEvent(
-                        tool_name=message.name,
-                        arguments=None,
-                        timestamp=timestamp,
+            return [
+                UiPathConversationMessageEvent(
+                    message_id=result_message_id or str(uuid4()),
+                    tool_call=UiPathConversationToolCallEvent(
+                        tool_call_id=message.tool_call_id,
+                        end=UiPathConversationToolCallEndEvent(
+                            timestamp=timestamp,
+                            output=UiPathInlineValue(inline=content_value),
+                        ),
                     ),
-                    end=UiPathConversationToolCallEndEvent(
-                        timestamp=timestamp,
-                        output=UiPathInlineValue(inline=content_value),
-                    ),
-                ),
-            )
+                )
+            ]
 
         # --- Fallback for other BaseMessage types ---
         text_content = self._extract_text(message.content)
-        return UiPathConversationMessageEvent(
-            message_id=message.id,
-            start=UiPathConversationMessageStartEvent(
-                role="assistant", timestamp=timestamp
-            ),
-            content_part=UiPathConversationContentPartEvent(
-                content_part_id=f"cp-{message.id}",
-                chunk=UiPathConversationContentPartChunkEvent(data=text_content),
-            ),
-            end=UiPathConversationMessageEndEvent(),
-        )
+        return [
+            UiPathConversationMessageEvent(
+                message_id=message.id,
+                start=UiPathConversationMessageStartEvent(
+                    role="assistant", timestamp=timestamp
+                ),
+                content_part=UiPathConversationContentPartEvent(
+                    content_part_id=f"cp-{message.id}",
+                    chunk=UiPathConversationContentPartChunkEvent(data=text_content),
+                ),
+                end=UiPathConversationMessageEndEvent(),
+            )
+        ]
 
 
 __all__ = ["UiPathChatMessagesMapper"]

src/uipath_langchain/runtime/runtime.py

@@ -3,6 +3,7 @@
 from typing import Any, AsyncGenerator
 from uuid import uuid4
 
+from langchain_core.callbacks import BaseCallbackHandler
 from langchain_core.runnables.config import RunnableConfig
 from langgraph.errors import EmptyInputError, GraphRecursionError, InvalidUpdateError
 from langgraph.graph.state import CompiledStateGraph
@@ -41,6 +42,7 @@ def __init__(
         graph: CompiledStateGraph[Any, Any, Any, Any],
         runtime_id: str | None = None,
         entrypoint: str | None = None,
+        callbacks: list[BaseCallbackHandler] | None = None,
     ):
         """
         Initialize the runtime.
@@ -53,6 +55,7 @@ def __init__(
         self.graph: CompiledStateGraph[Any, Any, Any, Any] = graph
         self.runtime_id: str = runtime_id or "default"
         self.entrypoint: str | None = entrypoint
+        self.callbacks: list[BaseCallbackHandler] = callbacks or []
         self.chat = UiPathChatMessagesMapper()
         self._middleware_node_names: set[str] = self._detect_middleware_nodes()
 
@@ -135,10 +138,17 @@ async def stream(
                 if chunk_type == "messages":
                     if isinstance(data, tuple):
                         message, _ = data
-                        event = UiPathRuntimeMessageEvent(
-                            payload=self.chat.map_event(message),
-                        )
-                        yield event
+                        try:
+                            events = self.chat.map_event(message)
+                        except Exception as e:
+                            logger.warning(f"Error mapping message event: {e}")
+                            events = None
+                        if events:
+                            for mapped_event in events:
+                                event = UiPathRuntimeMessageEvent(
+                                    payload=mapped_event,
+                                )
+                                yield event
 
                 # Emit UiPathRuntimeStateEvent for state updates
                 elif chunk_type == "updates":
@@ -189,7 +199,7 @@ def _get_graph_config(self) -> RunnableConfig:
         """Build graph execution configuration."""
         graph_config: RunnableConfig = {
             "configurable": {"thread_id": self.runtime_id},
-            "callbacks": [],
+            "callbacks": self.callbacks,
         }
 
         # Add optional config from environment

testcases/common/__init__.py

@@ -0,0 +1,15 @@
+"""Common testing utilities for UiPath testcases."""
+
+from testcases.common.console import (
+    ConsoleTest,
+    PromptTest,
+    strip_ansi,
+    read_log,
+)
+
+__all__ = [
+    "ConsoleTest",
+    "PromptTest",
+    "strip_ansi",
+    "read_log",
+]