uipath-langchain 0.0.143__py3-none-any.whl → 0.0.144__py3-none-any.whl

uipath_langchain/_cli/_runtime/_exception.py

@@ -1,17 +1,43 @@
-from typing import Optional
+from enum import Enum
+from typing import Optional, Union
 
-from uipath._cli._runtime._contracts import UiPathErrorCategory, UiPathRuntimeError
+from uipath._cli._runtime._contracts import (
+    UiPathBaseRuntimeError,
+    UiPathErrorCategory,
+    UiPathErrorCode,
+)
 
 
-class LangGraphRuntimeError(UiPathRuntimeError):
+class LangGraphErrorCode(Enum):
+    CONFIG_MISSING = "CONFIG_MISSING"
+    CONFIG_INVALID = "CONFIG_INVALID"
+
+    GRAPH_NOT_FOUND = "GRAPH_NOT_FOUND"
+    GRAPH_IMPORT_ERROR = "GRAPH_IMPORT_ERROR"
+    GRAPH_TYPE_ERROR = "GRAPH_TYPE_ERROR"
+    GRAPH_VALUE_ERROR = "GRAPH_VALUE_ERROR"
+    GRAPH_LOAD_ERROR = "GRAPH_LOAD_ERROR"
+    GRAPH_INVALID_UPDATE = "GRAPH_INVALID_UPDATE"
+    GRAPH_EMPTY_INPUT = "GRAPH_EMPTY_INPUT"
+
+    DB_QUERY_FAILED = "DB_QUERY_FAILED"
+    DB_TABLE_CREATION_FAILED = "DB_TABLE_CREATION_FAILED"
+    HITL_EVENT_CREATION_FAILED = "HITL_EVENT_CREATION_FAILED"
+    DB_INSERT_FAILED = "DB_INSERT_FAILED"
+    LICENSE_NOT_AVAILABLE = "LICENSE_NOT_AVAILABLE"
+
+
+class LangGraphRuntimeError(UiPathBaseRuntimeError):
     """Custom exception for LangGraph runtime errors with structured error information."""
 
     def __init__(
         self,
-        code: str,
+        code: Union[LangGraphErrorCode, UiPathErrorCode],
         title: str,
         detail: str,
         category: UiPathErrorCategory = UiPathErrorCategory.UNKNOWN,
         status: Optional[int] = None,
     ):
-        super().__init__(code, title, detail, category, status, prefix="LANGGRAPH")
+        super().__init__(
+            code.value, title, detail, category, status, prefix="LANGGRAPH"
+        )

uipath_langchain/_cli/_runtime/_graph_resolver.py

@@ -2,12 +2,10 @@ import asyncio
 from typing import Any, Awaitable, Callable, Optional
 
 from langgraph.graph.state import CompiledStateGraph, StateGraph
-from uipath._cli._runtime._contracts import (
-    UiPathErrorCategory,
-)
+from uipath._cli._runtime._contracts import UiPathErrorCategory, UiPathErrorCode
 
 from .._utils._graph import GraphConfig, LangGraphConfig
-from ._exception import LangGraphRuntimeError
+from ._exception import LangGraphErrorCode, LangGraphRuntimeError
 
 
 class LangGraphJsonResolver:
@@ -36,7 +34,7 @@ class LangGraphJsonResolver:
         config = LangGraphConfig()
         if not config.exists:
             raise LangGraphRuntimeError(
-                "CONFIG_MISSING",
+                LangGraphErrorCode.CONFIG_MISSING,
                 "Invalid configuration",
                 "Failed to load configuration",
                 UiPathErrorCategory.DEPLOYMENT,
@@ -46,7 +44,7 @@ class LangGraphJsonResolver:
             config.load_config()
         except Exception as e:
             raise LangGraphRuntimeError(
-                "CONFIG_INVALID",
+                LangGraphErrorCode.CONFIG_INVALID,
                 "Invalid configuration",
                 f"Failed to load configuration: {str(e)}",
                 UiPathErrorCategory.DEPLOYMENT,
@@ -59,7 +57,7 @@ class LangGraphJsonResolver:
         elif not entrypoint:
             graph_names = ", ".join(g.name for g in graphs)
             raise LangGraphRuntimeError(
-                "ENTRYPOINT_MISSING",
+                UiPathErrorCode.ENTRYPOINT_MISSING,
                 "Entrypoint required",
                 f"Multiple graphs available. Please specify one of: {graph_names}.",
                 UiPathErrorCategory.DEPLOYMENT,
@@ -69,7 +67,7 @@ class LangGraphJsonResolver:
         self.graph_config = config.get_graph(entrypoint)
         if not self.graph_config:
             raise LangGraphRuntimeError(
-                "GRAPH_NOT_FOUND",
+                LangGraphErrorCode.GRAPH_NOT_FOUND,
                 "Graph not found",
                 f"Graph '{entrypoint}' not found.",
                 UiPathErrorCategory.DEPLOYMENT,
@@ -83,28 +81,28 @@ class LangGraphJsonResolver:
             )
         except ImportError as e:
             raise LangGraphRuntimeError(
-                "GRAPH_IMPORT_ERROR",
+                LangGraphErrorCode.GRAPH_IMPORT_ERROR,
                 "Graph import failed",
                 f"Failed to import graph '{entrypoint}': {str(e)}",
                 UiPathErrorCategory.USER,
             ) from e
         except TypeError as e:
             raise LangGraphRuntimeError(
-                "GRAPH_TYPE_ERROR",
+                LangGraphErrorCode.GRAPH_TYPE_ERROR,
                 "Invalid graph type",
                 f"Graph '{entrypoint}' is not a valid StateGraph or CompiledStateGraph: {str(e)}",
                 UiPathErrorCategory.USER,
             ) from e
         except ValueError as e:
             raise LangGraphRuntimeError(
-                "GRAPH_VALUE_ERROR",
+                LangGraphErrorCode.GRAPH_VALUE_ERROR,
                 "Invalid graph value",
                 f"Invalid value in graph '{entrypoint}': {str(e)}",
                 UiPathErrorCategory.USER,
             ) from e
         except Exception as e:
             raise LangGraphRuntimeError(
-                "GRAPH_LOAD_ERROR",
+                LangGraphErrorCode.GRAPH_LOAD_ERROR,
                 "Failed to load graph",
                 f"Unexpected error loading graph '{entrypoint}': {str(e)}",
                 UiPathErrorCategory.USER,

uipath_langchain/_cli/_runtime/_input.py

@@ -13,7 +13,7 @@ from uipath._cli._runtime._hitl import HitlReader
 
 from ._context import LangGraphRuntimeContext
 from ._conversation import uipath_to_human_messages
-from ._exception import LangGraphRuntimeError
+from ._exception import LangGraphErrorCode, LangGraphRuntimeError
 
 logger = logging.getLogger(__name__)
 
@@ -140,7 +140,7 @@ async def _get_latest_trigger(
             return cast(tuple[str, str, str, str, str], tuple(result))
     except Exception as e:
         raise LangGraphRuntimeError(
-            "DB_QUERY_FAILED",
+            LangGraphErrorCode.DB_QUERY_FAILED,
             "Database query failed",
             f"Error querying resume trigger information: {str(e)}",
             UiPathErrorCategory.SYSTEM,

uipath_langchain/_cli/_runtime/_output.py

@@ -3,13 +3,10 @@ import logging
 from typing import Any
 
 from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
-from uipath._cli._runtime._contracts import (
-    UiPathErrorCategory,
-    UiPathResumeTrigger,
-)
+from uipath._cli._runtime._contracts import UiPathErrorCategory, UiPathResumeTrigger
 from uipath._cli._runtime._hitl import HitlProcessor
 
-from ._exception import LangGraphRuntimeError
+from ._exception import LangGraphErrorCode, LangGraphRuntimeError
 
 logger = logging.getLogger(__name__)
 
@@ -93,7 +90,7 @@ async def create_and_save_resume_trigger(
             """)
         except Exception as e:
             raise LangGraphRuntimeError(
-                "DB_TABLE_CREATION_FAILED",
+                LangGraphErrorCode.DB_TABLE_CREATION_FAILED,
                 "Failed to create resume triggers table",
                 f"Database error while creating table: {str(e)}",
                 UiPathErrorCategory.SYSTEM,
@@ -104,7 +101,7 @@ async def create_and_save_resume_trigger(
             resume_trigger = await hitl_processor.create_resume_trigger()
         except Exception as e:
             raise LangGraphRuntimeError(
-                "HITL_EVENT_CREATION_FAILED",
+                LangGraphErrorCode.HITL_EVENT_CREATION_FAILED,
                 "Failed to process HITL request",
                 f"Error while trying to process HITL request: {str(e)}",
                 UiPathErrorCategory.SYSTEM,
@@ -139,7 +136,7 @@ async def create_and_save_resume_trigger(
             await memory.conn.commit()
         except Exception as e:
             raise LangGraphRuntimeError(
-                "DB_INSERT_FAILED",
+                LangGraphErrorCode.DB_INSERT_FAILED,
                 "Failed to save resume trigger",
                 f"Database error while saving resume trigger: {str(e)}",
                 UiPathErrorCategory.SYSTEM,

uipath_langchain/_cli/_runtime/_runtime.py

@@ -12,6 +12,7 @@ from uipath._cli._runtime._contracts import (
     UiPathBaseRuntime,
     UiPathBreakpointResult,
     UiPathErrorCategory,
+    UiPathErrorCode,
     UiPathResumeTrigger,
     UiPathRuntimeResult,
     UiPathRuntimeStatus,
@@ -23,7 +24,7 @@ from uipath._events._events import (
 )
 
 from ._context import LangGraphRuntimeContext
-from ._exception import LangGraphRuntimeError
+from ._exception import LangGraphErrorCode, LangGraphRuntimeError
 from ._graph_resolver import AsyncResolver, LangGraphJsonResolver
 from ._input import get_graph_input
 from ._output import create_and_save_resume_trigger, serialize_output
@@ -79,7 +80,11 @@ class LangGraphRuntime(UiPathBaseRuntime):
                 graph_config = self._get_graph_config()
 
                 # Execute without streaming
-                graph_output = await compiled_graph.ainvoke(graph_input, graph_config)
+                graph_output = await compiled_graph.ainvoke(
+                    graph_input,
+                    graph_config,
+                    interrupt_before=self.context.breakpoints,
+                )
 
                 # Get final state and create result
                 self.context.result = await self._create_runtime_result(
@@ -140,6 +145,7 @@ class LangGraphRuntime(UiPathBaseRuntime):
                 async for stream_chunk in compiled_graph.astream(
                     graph_input,
                     graph_config,
+                    interrupt_before=self.context.breakpoints,
                     stream_mode=["messages", "updates"],
                     subgraphs=True,
                 ):
@@ -426,7 +432,7 @@ class LangGraphRuntime(UiPathBaseRuntime):
 
         if isinstance(e, GraphRecursionError):
             return LangGraphRuntimeError(
-                "GRAPH_RECURSION_ERROR",
+                LangGraphErrorCode.GRAPH_LOAD_ERROR,
                 "Graph recursion limit exceeded",
                 detail,
                 UiPathErrorCategory.USER,
@@ -434,7 +440,7 @@ class LangGraphRuntime(UiPathBaseRuntime):
 
         if isinstance(e, InvalidUpdateError):
             return LangGraphRuntimeError(
-                "GRAPH_INVALID_UPDATE",
+                LangGraphErrorCode.GRAPH_INVALID_UPDATE,
                 str(e),
                 detail,
                 UiPathErrorCategory.USER,
@@ -442,14 +448,14 @@ class LangGraphRuntime(UiPathBaseRuntime):
 
         if isinstance(e, EmptyInputError):
             return LangGraphRuntimeError(
-                "GRAPH_EMPTY_INPUT",
+                LangGraphErrorCode.GRAPH_EMPTY_INPUT,
                 "The input data is empty",
                 detail,
                 UiPathErrorCategory.USER,
             )
 
         return LangGraphRuntimeError(
-            "EXECUTION_ERROR",
+            UiPathErrorCode.EXECUTION_ERROR,
             "Graph execution failed",
             detail,
             UiPathErrorCategory.USER,

uipath_langchain/_utils/_request_mixin.py

@@ -20,7 +20,10 @@ from tenacity import (
 from uipath._cli._runtime._contracts import UiPathErrorCategory, UiPathRuntimeError
 from uipath._utils._ssl_context import get_httpx_client_kwargs
 
-from uipath_langchain._cli._runtime._exception import LangGraphRuntimeError
+from uipath_langchain._cli._runtime._exception import (
+    LangGraphErrorCode,
+    LangGraphRuntimeError,
+)
 from uipath_langchain._utils._settings import (
     UiPathClientFactorySettings,
     UiPathClientSettings,
@@ -371,7 +374,7 @@ class UiPathRequestMixin(BaseModel):
                 title = body.get("title", "").lower()
                 if title == "license not available":
                     raise LangGraphRuntimeError(
-                        code="LICENSE_NOT_AVAILABLE",
+                        code=LangGraphErrorCode.LICENSE_NOT_AVAILABLE,
                         title=body.get("title", "License Not Available"),
                         detail=body.get(
                             "detail", "License not available for this service"

uipath_langchain/agent/react/__init__.py

@@ -0,0 +1,12 @@
+"""UiPath ReAct Agent implementation"""
+
+from .agent import create_agent
+from .state import AgentGraphNode, AgentGraphState
+from .utils import resolve_output_model
+
+__all__ = [
+    "create_agent",
+    "AgentGraphState",
+    "AgentGraphNode",
+    "resolve_output_model",
+]

uipath_langchain/agent/react/agent.py

@@ -0,0 +1,76 @@
+import os
+from typing import Sequence, Type
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import HumanMessage, SystemMessage
+from langchain_core.tools import BaseTool
+from langgraph.constants import END, START
+from langgraph.graph import StateGraph
+from pydantic import BaseModel
+
+from ..tools import create_tool_node
+from .init_node import (
+    create_init_node,
+)
+from .llm_node import (
+    create_llm_node,
+)
+from .router import (
+    route_agent,
+)
+from .state import AgentGraphNode, AgentGraphState
+from .terminate_node import (
+    create_terminate_node,
+)
+from .tools import create_flow_control_tools
+
+
+def create_agent(
+    model: BaseChatModel,
+    tools: Sequence[BaseTool],
+    messages: Sequence[SystemMessage | HumanMessage],
+    *,
+    state_schema: Type[AgentGraphState] = AgentGraphState,
+    response_format: type[BaseModel] | None = None,
+    recursion_limit: int = 50,
+) -> StateGraph[AgentGraphState]:
+    """Build agent graph with INIT -> AGENT <-> TOOLS loop, terminated by control flow tools.
+
+    Control flow tools (end_execution, raise_error) are auto-injected alongside regular tools.
+    """
+    os.environ["LANGCHAIN_RECURSION_LIMIT"] = str(recursion_limit)
+
+    agent_tools = list(tools)
+    flow_control_tools: list[BaseTool] = create_flow_control_tools(response_format)
+    llm_tools: list[BaseTool] = [*agent_tools, *flow_control_tools]
+
+    init_node = create_init_node(messages)
+    agent_node = create_llm_node(model, llm_tools)
+    tool_nodes = create_tool_node(agent_tools)
+    terminate_node = create_terminate_node(response_format)
+
+    builder: StateGraph[AgentGraphState] = StateGraph(state_schema)
+    builder.add_node(AgentGraphNode.INIT, init_node)
+    builder.add_node(AgentGraphNode.AGENT, agent_node)
+
+    for tool_name, tool_node in tool_nodes.items():
+        builder.add_node(tool_name, tool_node)
+
+    builder.add_node(AgentGraphNode.TERMINATE, terminate_node)
+
+    builder.add_edge(START, AgentGraphNode.INIT)
+    builder.add_edge(AgentGraphNode.INIT, AgentGraphNode.AGENT)
+
+    tool_node_names = list(tool_nodes.keys())
+    builder.add_conditional_edges(
+        AgentGraphNode.AGENT,
+        route_agent,
+        [AgentGraphNode.AGENT, *tool_node_names, AgentGraphNode.TERMINATE],
+    )
+
+    for tool_name in tool_node_names:
+        builder.add_edge(tool_name, AgentGraphNode.AGENT)
+
+    builder.add_edge(AgentGraphNode.TERMINATE, END)
+
+    return builder

uipath_langchain/agent/react/constants.py

@@ -0,0 +1,2 @@
+# Agent routing configuration
+MAX_SUCCESSIVE_COMPLETIONS = 1

uipath_langchain/agent/react/exceptions.py

@@ -0,0 +1,11 @@
+"""Exceptions for the basic agent loop."""
+
+from uipath._cli._runtime._contracts import UiPathRuntimeError
+
+
+class AgentNodeRoutingException(Exception):
+    pass
+
+
+class AgentTerminationException(UiPathRuntimeError):
+    pass

uipath_langchain/agent/react/init_node.py

@@ -0,0 +1,16 @@
+"""State initialization node for the ReAct Agent graph."""
+
+from typing import Sequence
+
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from .state import AgentGraphState
+
+
+def create_init_node(
+    messages: Sequence[SystemMessage | HumanMessage],
+):
+    def graph_state_init(_: AgentGraphState):
+        return {"messages": list(messages)}
+
+    return graph_state_init

uipath_langchain/agent/react/llm_node.py

@@ -0,0 +1,44 @@
+"""LLM node implementation for LangGraph."""
+
+from typing import Sequence
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, AnyMessage
+from langchain_core.tools import BaseTool
+
+from .constants import MAX_SUCCESSIVE_COMPLETIONS
+from .state import AgentGraphState
+from .utils import count_successive_completions
+
+
+def create_llm_node(
+    model: BaseChatModel,
+    tools: Sequence[BaseTool] | None = None,
+):
+    """Invoke LLM with tools and dynamically control tool_choice based on successive completions.
+
+    When successive completions reach the limit, tool_choice is set to "required" to force
+    the LLM to use a tool and prevent infinite reasoning loops.
+    """
+    bindable_tools = list(tools) if tools else []
+    base_llm = model.bind_tools(bindable_tools) if bindable_tools else model
+
+    async def llm_node(state: AgentGraphState):
+        messages: list[AnyMessage] = state["messages"]
+
+        successive_completions = count_successive_completions(messages)
+
+        if successive_completions >= MAX_SUCCESSIVE_COMPLETIONS and bindable_tools:
+            llm = base_llm.bind(tool_choice="required")
+        else:
+            llm = base_llm
+
+        response = await llm.ainvoke(messages)
+        if not isinstance(response, AIMessage):
+            raise TypeError(
+                f"LLM returned {type(response).__name__} instead of AIMessage"
+            )
+
+        return {"messages": [response]}
+
+    return llm_node

uipath_langchain/agent/react/router.py

@@ -0,0 +1,97 @@
+"""Routing functions for conditional edges in the agent graph."""
+
+from typing import Literal
+
+from langchain_core.messages import AIMessage, AnyMessage, ToolCall
+from uipath.agent.react import END_EXECUTION_TOOL, RAISE_ERROR_TOOL
+
+from .constants import MAX_SUCCESSIVE_COMPLETIONS
+from .exceptions import AgentNodeRoutingException
+from .state import AgentGraphNode, AgentGraphState
+from .utils import count_successive_completions
+
+FLOW_CONTROL_TOOLS = [END_EXECUTION_TOOL.name, RAISE_ERROR_TOOL.name]
+
+
+def __filter_control_flow_tool_calls(
+    tool_calls: list[ToolCall],
+) -> list[ToolCall]:
+    """Remove control flow tools when multiple tool calls exist."""
+    if len(tool_calls) <= 1:
+        return tool_calls
+
+    return [tc for tc in tool_calls if tc.get("name") not in FLOW_CONTROL_TOOLS]
+
+
+def __has_control_flow_tool(tool_calls: list[ToolCall]) -> bool:
+    """Check if any tool call is of a control flow tool."""
+    return any(tc.get("name") in FLOW_CONTROL_TOOLS for tc in tool_calls)
+
+
+def __validate_last_message_is_AI(messages: list[AnyMessage]) -> AIMessage:
+    """Validate and return last message from state.
+
+    Raises:
+        AgentNodeRoutingException: If messages are empty or last message is not AIMessage
+    """
+    if not messages:
+        raise AgentNodeRoutingException(
+            "No messages in state - cannot route after agent"
+        )
+
+    last_message = messages[-1]
+    if not isinstance(last_message, AIMessage):
+        raise AgentNodeRoutingException(
+            f"Last message is not AIMessage (type: {type(last_message).__name__}) - cannot route after agent"
+        )
+
+    return last_message
+
+
+def route_agent(
+    state: AgentGraphState,
+) -> list[str] | Literal[AgentGraphNode.AGENT, AgentGraphNode.TERMINATE]:
+    """Route after agent: handles all routing logic including control flow detection.
+
+    Routing logic:
+    1. If multiple tool calls exist, filter out control flow tools (EndExecution, RaiseError)
+    2. If control flow tool(s) remain, route to TERMINATE
+    3. If regular tool calls remain, route to specific tool nodes (return list of tool names)
+    4. If no tool calls, handle successive completions
+
+    Returns:
+        - list[str]: Tool node names for parallel execution
+        - AgentGraphNode.AGENT: For successive completions
+        - AgentGraphNode.TERMINATE: For control flow termination
+
+    Raises:
+        AgentNodeRoutingException: When encountering unexpected state (empty messages, non-AIMessage, or excessive completions)
+    """
+    messages = state.get("messages", [])
+    last_message = __validate_last_message_is_AI(messages)
+
+    tool_calls = list(last_message.tool_calls) if last_message.tool_calls else []
+    tool_calls = __filter_control_flow_tool_calls(tool_calls)
+
+    if tool_calls and __has_control_flow_tool(tool_calls):
+        return AgentGraphNode.TERMINATE
+
+    if tool_calls:
+        return [tc["name"] for tc in tool_calls]
+
+    successive_completions = count_successive_completions(messages)
+
+    if successive_completions > MAX_SUCCESSIVE_COMPLETIONS:
+        raise AgentNodeRoutingException(
+            f"Agent exceeded successive completions limit without producing tool calls "
+            f"(completions: {successive_completions}, max: {MAX_SUCCESSIVE_COMPLETIONS}). "
+            f"This should not happen as tool_choice='required' is enforced at the limit."
+        )
+
+    if last_message.content:
+        return AgentGraphNode.AGENT
+
+    raise AgentNodeRoutingException(
+        f"Agent produced empty response without tool calls "
+        f"(completions: {successive_completions}, has_content: False)"
+    )

uipath_langchain/agent/react/state.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+from langgraph.graph import MessagesState
+
+
+class AgentGraphState(MessagesState):
+    """Agent Graph state for standard loop execution."""
+
+    pass
+
+
+class AgentGraphNode(StrEnum):
+    INIT = "init"
+    AGENT = "agent"
+    TOOLS = "tools"
+    TERMINATE = "terminate"

uipath_langchain/agent/react/terminate_node.py

@@ -0,0 +1,53 @@
+"""Termination node for the Agent graph."""
+
+from __future__ import annotations
+
+from langchain_core.messages import AIMessage
+from pydantic import BaseModel
+from uipath._cli._runtime._contracts import UiPathErrorCode
+from uipath.agent.react import END_EXECUTION_TOOL, RAISE_ERROR_TOOL
+
+from .exceptions import (
+    AgentNodeRoutingException,
+    AgentTerminationException,
+)
+from .state import AgentGraphState
+
+
+def create_terminate_node(
+    response_schema: type[BaseModel] | None = None,
+):
+    """Validates and returns end_execution args, or raises AgentTerminationException for raise_error."""
+
+    def terminate_node(state: AgentGraphState):
+        last_message = state["messages"][-1]
+        if not isinstance(last_message, AIMessage):
+            raise AgentNodeRoutingException(
+                f"Expected last message to be AIMessage, got {type(last_message).__name__}"
+            )
+
+        for tool_call in last_message.tool_calls:
+            tool_name = tool_call["name"]
+
+            if tool_name == END_EXECUTION_TOOL.name:
+                args = tool_call["args"]
+                output_schema = response_schema or END_EXECUTION_TOOL.args_schema
+                validated = output_schema.model_validate(args)
+                return validated.model_dump()
+
+            if tool_name == RAISE_ERROR_TOOL.name:
+                error_message = tool_call["args"].get(
+                    "message", "The LLM did not set the error message"
+                )
+                detail = tool_call["args"].get("details", "")
+                raise AgentTerminationException(
+                    code=UiPathErrorCode.EXECUTION_ERROR,
+                    title=error_message,
+                    detail=detail,
+                )
+
+        raise AgentNodeRoutingException(
+            "No control flow tool call found in terminate node. Unexpected state."
+        )
+
+    return terminate_node

uipath_langchain/agent/react/tools/__init__.py

@@ -0,0 +1,7 @@
+from .tools import (
+    create_flow_control_tools,
+)
+
+__all__ = [
+    "create_flow_control_tools",
+]

uipath_langchain/agent/react/tools/tools.py

@@ -0,0 +1,50 @@
+"""Control flow tools for agent execution."""
+
+from typing import Any
+
+from langchain_core.tools import BaseTool, StructuredTool
+from pydantic import BaseModel
+from uipath.agent.react import (
+    END_EXECUTION_TOOL,
+    RAISE_ERROR_TOOL,
+)
+
+
+def create_end_execution_tool(
+    agent_output_schema: type[BaseModel] | None = None,
+) -> StructuredTool:
+    """Never executed - routing intercepts and extracts args for successful termination."""
+    input_schema = agent_output_schema or END_EXECUTION_TOOL.args_schema
+
+    async def end_execution_fn(**kwargs: Any) -> dict[str, Any]:
+        return kwargs
+
+    return StructuredTool(
+        name=END_EXECUTION_TOOL.name,
+        description=END_EXECUTION_TOOL.description,
+        args_schema=input_schema,
+        coroutine=end_execution_fn,
+    )
+
+
+def create_raise_error_tool() -> StructuredTool:
+    """Never executed - routing intercepts and raises AgentTerminationException."""
+
+    async def raise_error_fn(**kwargs: Any) -> dict[str, Any]:
+        return kwargs
+
+    return StructuredTool(
+        name=RAISE_ERROR_TOOL.name,
+        description=RAISE_ERROR_TOOL.description,
+        args_schema=RAISE_ERROR_TOOL.args_schema,
+        coroutine=raise_error_fn,
+    )
+
+
+def create_flow_control_tools(
+    agent_output_schema: type[BaseModel] | None = None,
+) -> list[BaseTool]:
+    return [
+        create_end_execution_tool(agent_output_schema),
+        create_raise_error_tool(),
+    ]

uipath_langchain/agent/react/utils.py

@@ -0,0 +1,39 @@
+"""ReAct Agent loop utilities."""
+
+from typing import Any, Sequence
+
+from jsonschema_pydantic import jsonschema_to_pydantic  # type: ignore[import-untyped]
+from langchain_core.messages import AIMessage, BaseMessage
+from pydantic import BaseModel
+from uipath.agent.react import END_EXECUTION_TOOL
+
+
+def resolve_output_model(
+    output_schema: dict[str, Any] | None,
+) -> type[BaseModel]:
+    """Fallback to default end_execution tool schema when no agent output schema is provided."""
+    if output_schema:
+        return jsonschema_to_pydantic(output_schema)
+
+    return END_EXECUTION_TOOL.args_schema
+
+
+def count_successive_completions(messages: Sequence[BaseMessage]) -> int:
+    """Count consecutive AIMessages without tool calls at end of message history."""
+    if not messages:
+        return 0
+
+    count = 0
+    for message in reversed(messages):
+        if not isinstance(message, AIMessage):
+            break
+
+        if message.tool_calls:
+            break
+
+        if not message.content:
+            break
+
+        count += 1
+
+    return count

uipath_langchain/agent/tools/__init__.py

@@ -0,0 +1,8 @@
+"""Tool creation and management for LowCode agents."""
+
+from .tool_factory import (
+    create_tools_from_resources,
+)
+from .tool_node import create_tool_node
+
+__all__ = ["create_tools_from_resources", "create_tool_node"]

uipath_langchain/agent/tools/context_tool.py

@@ -0,0 +1,42 @@
+"""Context tool creation for semantic index retrieval."""
+
+from __future__ import annotations
+
+import json
+
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field
+from uipath.agent.models.agent import AgentContextResourceConfig
+
+from uipath_langchain.retrievers import ContextGroundingRetriever
+
+from .utils import sanitize_tool_name
+
+
+def create_context_tool(resource: AgentContextResourceConfig) -> StructuredTool:
+    tool_name = sanitize_tool_name(resource.name)
+    retriever = ContextGroundingRetriever(
+        index_name=resource.index_name,
+        folder_path=resource.folder_path,
+        number_of_results=resource.settings.result_count,
+    )
+
+    async def context_tool_fn(query: str) -> str:
+        docs = await retriever.ainvoke(query)
+
+        if not docs:
+            return ""
+
+        return json.dumps([doc.model_dump() for doc in docs], indent=2)
+
+    class ContextInputSchemaModel(BaseModel):
+        query: str = Field(
+            ..., description="The query to search for in the knowledge base"
+        )
+
+    return StructuredTool(
+        name=tool_name,
+        description=resource.description,
+        args_schema=ContextInputSchemaModel,
+        coroutine=context_tool_fn,
+    )

uipath_langchain/agent/tools/process_tool.py

@@ -0,0 +1,51 @@
+"""Process tool creation for UiPath process execution."""
+
+from __future__ import annotations
+
+from typing import Any, Type
+
+from jsonschema_pydantic import jsonschema_to_pydantic  # type: ignore[import-untyped]
+from langchain_core.tools import StructuredTool
+from langgraph.types import interrupt
+from pydantic import BaseModel
+from uipath.agent.models.agent import AgentProcessToolResourceConfig
+from uipath.models import InvokeProcess
+
+from .utils import sanitize_tool_name
+
+
+def create_process_tool(resource: AgentProcessToolResourceConfig) -> StructuredTool:
+    """Uses interrupt() to suspend graph execution until process completes (handled by runtime)."""
+    tool_name: str = sanitize_tool_name(resource.name)
+    process_name = resource.properties.process_name
+    folder_path = resource.properties.folder_path
+
+    input_model: Type[BaseModel] = jsonschema_to_pydantic(resource.input_schema)
+    output_model: Type[BaseModel] = jsonschema_to_pydantic(resource.output_schema)
+
+    async def process_tool_fn(**kwargs: Any):
+        try:
+            result = interrupt(
+                InvokeProcess(
+                    name=process_name,
+                    input_arguments=kwargs,
+                    process_folder_path=folder_path,
+                    process_folder_key=None,
+                )
+            )
+        except Exception:
+            raise
+
+        return result
+
+    class ProcessTool(StructuredTool):
+        """Process tool with OutputType for schema compatibility."""
+
+        OutputType: Type[BaseModel] = output_model
+
+    return ProcessTool(
+        name=tool_name,
+        description=resource.description,
+        args_schema=input_model,
+        coroutine=process_tool_fn,
+    )

uipath_langchain/agent/tools/tool_factory.py

@@ -0,0 +1,39 @@
+"""Factory functions for creating tools from agent resources."""
+
+from __future__ import annotations
+
+from langchain_core.tools import BaseTool, StructuredTool
+from uipath.agent.models.agent import (
+    AgentContextResourceConfig,
+    AgentProcessToolResourceConfig,
+    BaseAgentResourceConfig,
+    LowCodeAgentDefinition,
+)
+
+from .context_tool import create_context_tool
+from .process_tool import create_process_tool
+
+
+async def create_tools_from_resources(
+    agent: LowCodeAgentDefinition,
+) -> list[BaseTool]:
+    tools: list[BaseTool] = []
+
+    for resource in agent.resources:
+        tool = await _build_tool_for_resource(resource)
+        if tool is not None:
+            tools.append(tool)
+
+    return tools
+
+
+async def _build_tool_for_resource(
+    resource: BaseAgentResourceConfig,
+) -> StructuredTool | None:
+    if isinstance(resource, AgentProcessToolResourceConfig):
+        return create_process_tool(resource)
+
+    elif isinstance(resource, AgentContextResourceConfig):
+        return create_context_tool(resource)
+
+    return None

uipath_langchain/agent/tools/tool_node.py

@@ -0,0 +1,22 @@
+"""Tool node factory wiring directly to LangGraph's ToolNode."""
+
+from collections.abc import Sequence
+
+from langchain_core.tools import BaseTool
+from langgraph.prebuilt import ToolNode
+
+
+def create_tool_node(tools: Sequence[BaseTool]) -> dict[str, ToolNode]:
+    """Create individual ToolNode for each tool.
+
+    Args:
+        tools: Sequence of tools to create nodes for.
+
+    Returns:
+        Dict mapping tool.name -> ToolNode([tool]).
+        Each tool gets its own dedicated node for middleware composition.
+
+    Note:
+        handle_tool_errors=False delegates error handling to LangGraph's error boundary.
+    """
+    return {tool.name: ToolNode([tool], handle_tool_errors=False) for tool in tools}

uipath_langchain/agent/tools/utils.py

@@ -0,0 +1,11 @@
+"""Tool-related utility functions."""
+
+import re
+
+
+def sanitize_tool_name(name: str) -> str:
+    """Sanitize tool name for LLM compatibility (alphanumeric, underscore, hyphen only, max 64 chars)."""
+    trim_whitespaces = "_".join(name.split())
+    sanitized_tool_name = re.sub(r"[^a-zA-Z0-9_-]", "", trim_whitespaces)
+    sanitized_tool_name = sanitized_tool_name[:64]
+    return sanitized_tool_name

{uipath_langchain-0.0.143.dist-info → uipath_langchain-0.0.144.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: uipath-langchain
-Version: 0.0.143
+Version: 0.0.144
 Summary: UiPath Langchain
 Project-URL: Homepage, https://uipath.com
 Project-URL: Repository, https://github.com/UiPath/uipath-langchain-python

{uipath_langchain-0.0.143.dist-info → uipath_langchain-0.0.144.dist-info}/RECORD

@@ -10,11 +10,11 @@ uipath_langchain/_cli/cli_new.py,sha256=KKLxCzz7cDQ__rRr_a496IHWlSQXhmrBNgmKHnXA
 uipath_langchain/_cli/cli_run.py,sha256=DIsAKsbQ8gTRz44q9ZV3jBjrbM8bhS6lEQ3dd4joDFU,3712
 uipath_langchain/_cli/_runtime/_context.py,sha256=mjmGEogKiO8tUV878BgV9rFIeA9MCmEH6hgs5W_dm4g,328
 uipath_langchain/_cli/_runtime/_conversation.py,sha256=ayghRqhyLeVUZg1WHnpeOYtPNhRwDOl4z8OSYiJkWSU,11529
-uipath_langchain/_cli/_runtime/_exception.py,sha256=USKkLYkG-dzjX3fEiMMOHnVUpiXJs_xF0OQXCCOvbYM,546
-uipath_langchain/_cli/_runtime/_graph_resolver.py,sha256=5SmYr3KJ_Iy13QtN8XPOOmoSrdysDGlLsgfiebHDXfs,5296
-uipath_langchain/_cli/_runtime/_input.py,sha256=MTupo0p4F1vCTQi_KPZYJ2Um1X3QCmm8GeqC32HZbks,5724
-uipath_langchain/_cli/_runtime/_output.py,sha256=DOIxc9BKYtESOr9sLaBeppskWfUPse8B2PUDOFin0oU,4829
-uipath_langchain/_cli/_runtime/_runtime.py,sha256=ImDBluxga_WbIm9lnljjm7jGl1tZBPy5hUrXYOCcOIE,18262
+uipath_langchain/_cli/_runtime/_exception.py,sha256=xHKeu8njByiMcObbggyZk0cXYXX5BjLLF9PtSJtB4_Q,1358
+uipath_langchain/_cli/_runtime/_graph_resolver.py,sha256=c-JrsX7rx_CflDPfKhz9q-PgBrgI2IOBcYwiffwddh8,5457
+uipath_langchain/_cli/_runtime/_input.py,sha256=HAJUxjNmOg9q7l_ebF1AzIKL5_ysXyjk1bWXHsjhEPI,5761
+uipath_langchain/_cli/_runtime/_output.py,sha256=2VvdW4olv7Vd0c4grtTQazXxfBbcuocgSSP6V2P8uHE,4887
+uipath_langchain/_cli/_runtime/_runtime.py,sha256=HFWU2h864Ifq0gK9-_Jy6sbg0CMxmFExSdSEiUArChE,18548
 uipath_langchain/_cli/_templates/langgraph.json.template,sha256=eeh391Gta_hoRgaNaZ58nW1LNvCVXA7hlAH6l7Veous,107
 uipath_langchain/_cli/_templates/main.py.template,sha256=GpSblGH2hwS9ibqQmX2iB2nsmOA5zDfEEF4ChLiMxbQ,875
 uipath_langchain/_cli/_utils/_graph.py,sha256=nMJWy8FmaD9rqPUY2lHc5uVpUzbXD1RO12uJnhe0kdo,6803
@@ -24,9 +24,27 @@ uipath_langchain/_tracing/__init__.py,sha256=C2dRvQ2ynxCmyICgE-rJHimWKEcFRME_o9g
 uipath_langchain/_tracing/_instrument_traceable.py,sha256=8f9FyAKWE6kH1N8ErbpwqZHAzNjGwbLjQn7jdX5yAgA,4343
 uipath_langchain/_tracing/_utils.py,sha256=r_fiSk3HDDAcePY_UbbEYiSbNqzn5gFeMPYBDvGrFx0,902
 uipath_langchain/_utils/__init__.py,sha256=-w-4TD9ZnJDCpj4VIPXhJciukrmDJJbmnOFnhAkAaEU,81
-uipath_langchain/_utils/_request_mixin.py,sha256=sYvvn3_fUJxtF893xFpVGwJx2YoEbw1m5gp_U_lWjR8,20092
+uipath_langchain/_utils/_request_mixin.py,sha256=_drxHTRpfyVn3g3ppKgn466EBaUWH83qyeGKLY41CGY,20142
 uipath_langchain/_utils/_settings.py,sha256=2fExMQJ88YptfldmzMfZIpsx-m1gfMkeYGf5t6KIe0A,3084
 uipath_langchain/_utils/_sleep_policy.py,sha256=e9pHdjmcCj4CVoFM1jMyZFelH11YatsgWfpyrfXzKBQ,1251
+uipath_langchain/agent/react/__init__.py,sha256=rfVB6PQWUhPHff3J1BnPMBKBMaHfgEkII1gXwjiqUMY,272
+uipath_langchain/agent/react/agent.py,sha256=cU9ZiXi7EfV1pMf9nZBO8LhjYUmRsncyBk9k1pEBRh8,2455
+uipath_langchain/agent/react/constants.py,sha256=B2yqryh242DETslaRYacUPbVdpjvvApjsBira_qhQwk,61
+uipath_langchain/agent/react/exceptions.py,sha256=b3lDhrIIHFljlLK3zXPznT7fYzfMRjSd8JfF4247tbI,226
+uipath_langchain/agent/react/init_node.py,sha256=zfPKgxi_mWsX7nBcK6wpqcDjHx8Q61TSnXFcTPLUd28,389
+uipath_langchain/agent/react/llm_node.py,sha256=jkbfzPNn6rNubgncPlPDQRNuk-sJbj08r95JfWxxWL8,1491
+uipath_langchain/agent/react/router.py,sha256=Ttq5O1_8t-z7pQ9tGhiaMmd_Da7_TWULLcgOED7gw_A,3626
+uipath_langchain/agent/react/state.py,sha256=EnkGXFlmMtJUy7BTZrbYlGBvvAZ70_HwKPW8n6uwjz0,330
+uipath_langchain/agent/react/terminate_node.py,sha256=Uuc-0z4qcPjHB_qZlaEaM2mK1ymCuJJludS7LopyCZg,1898
+uipath_langchain/agent/react/utils.py,sha256=0kZoEkGzddtTZSlGQcqbaPHH5MVtZegq0kBI5_vreGA,1060
+uipath_langchain/agent/react/tools/__init__.py,sha256=LGfG8Dc32ffKdXQyMI2oYzhNnTs1wbzsddXz6eU-0MY,102
+uipath_langchain/agent/react/tools/tools.py,sha256=vFBGnFrGocX__sotKisMJr2lxRRVqA0-uThzzhPADIw,1443
+uipath_langchain/agent/tools/__init__.py,sha256=GqQZLoMxkujjsButdLruxgzmQLX9k0YPtBaBAULSV2o,222
+uipath_langchain/agent/tools/context_tool.py,sha256=Xd2qvc52Ks2eFXF2n-i0d8QDnbHXls_V8jyyNXwdySI,1243
+uipath_langchain/agent/tools/process_tool.py,sha256=3OPxkIAJw_haohDeyDwSo8CIz9300XSvqIz5yjItspk,1715
+uipath_langchain/agent/tools/tool_factory.py,sha256=NfhUU7EWf-zkt4xglkzp8ReOYDvKmoOTiz-OBh3ACWs,1053
+uipath_langchain/agent/tools/tool_node.py,sha256=TnXsjoShvhsoBuV5RoUVoJCc2zYPKSnJYSC9MGJoeOk,707
+uipath_langchain/agent/tools/utils.py,sha256=DsFeZ7kDzFaZ0bGHQN6TlGMJ90wYr7P1Vo1rpHPHWws,401
 uipath_langchain/chat/__init__.py,sha256=WDcvy91ixvZ3Mq7Ae94g5CjyQwXovDBnEv1NlD5SXBE,116
 uipath_langchain/chat/models.py,sha256=PifcbDURqfttqVYKSnzdbOdbSiLiwHfQ6lWgVAtoLj8,16407
 uipath_langchain/embeddings/__init__.py,sha256=QICtYB58ZyqFfDQrEaO8lTEgAU5NuEKlR7iIrS0OBtc,156
@@ -37,8 +55,8 @@ uipath_langchain/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3
 uipath_langchain/tools/preconfigured.py,sha256=SyvrLrM1kezZxVVytgScVO8nBfVYfFGobWjY7erzsYU,7490
 uipath_langchain/vectorstores/__init__.py,sha256=w8qs1P548ud1aIcVA_QhBgf_jZDrRMK5Lono78yA8cs,114
 uipath_langchain/vectorstores/context_grounding_vectorstore.py,sha256=TncIXG-YsUlO0R5ZYzWsM-Dj1SVCZbzmo2LraVxXelc,9559
-uipath_langchain-0.0.143.dist-info/METADATA,sha256=lh7djtB3vKXf2xB6b8BT9IksQGlun2fj2UiNFIver-E,4276
-uipath_langchain-0.0.143.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-uipath_langchain-0.0.143.dist-info/entry_points.txt,sha256=FUtzqGOEntlJKMJIXhQUfT7ZTbQmGhke1iCmDWZaQZI,81
-uipath_langchain-0.0.143.dist-info/licenses/LICENSE,sha256=JDpt-uotAkHFmxpwxi6gwx6HQ25e-lG4U_Gzcvgp7JY,1063
-uipath_langchain-0.0.143.dist-info/RECORD,,
+uipath_langchain-0.0.144.dist-info/METADATA,sha256=fnn1iHs-_Q0lyubeoDFTb6c5LGZaWZbpxDnMytjjbRg,4276
+uipath_langchain-0.0.144.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+uipath_langchain-0.0.144.dist-info/entry_points.txt,sha256=FUtzqGOEntlJKMJIXhQUfT7ZTbQmGhke1iCmDWZaQZI,81
+uipath_langchain-0.0.144.dist-info/licenses/LICENSE,sha256=JDpt-uotAkHFmxpwxi6gwx6HQ25e-lG4U_Gzcvgp7JY,1063
+uipath_langchain-0.0.144.dist-info/RECORD,,