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

uipath_langchain/agent/react/llm_node.py

@@ -0,0 +1,43 @@
+"""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 .types 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:
+            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 ..exceptions import AgentNodeRoutingException
+from .constants import MAX_SUCCESSIVE_COMPLETIONS
+from .types 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.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/terminate_node.py

@@ -0,0 +1,82 @@
+"""Termination node for the Agent graph."""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+from langchain_core.messages import AIMessage
+from pydantic import BaseModel
+from uipath.agent.react import END_EXECUTION_TOOL, RAISE_ERROR_TOOL
+from uipath.runtime.errors import UiPathErrorCode
+
+from ..exceptions import (
+    AgentNodeRoutingException,
+    AgentTerminationException,
+)
+from .types import AgentGraphState, AgentTermination
+
+
+def _handle_end_execution(
+    args: dict[str, Any], response_schema: type[BaseModel] | None
+) -> dict[str, Any]:
+    """Handle LLM-initiated termination via END_EXECUTION_TOOL."""
+    output_schema = response_schema or END_EXECUTION_TOOL.args_schema
+    validated = output_schema.model_validate(args)
+    return validated.model_dump()
+
+
+def _handle_raise_error(args: dict[str, Any]) -> NoReturn:
+    """Handle LLM-initiated error via RAISE_ERROR_TOOL."""
+    error_message = args.get("message", "The LLM did not set the error message")
+    detail = args.get("details", "")
+    raise AgentTerminationException(
+        code=UiPathErrorCode.EXECUTION_ERROR,
+        title=error_message,
+        detail=detail,
+    )
+
+
+def _handle_agent_termination(termination: AgentTermination) -> NoReturn:
+    """Handle Command-based termination."""
+    raise AgentTerminationException(
+        code=UiPathErrorCode.EXECUTION_ERROR,
+        title=termination.title,
+        detail=termination.detail,
+    )
+
+
+def create_terminate_node(
+    response_schema: type[BaseModel] | None = None,
+):
+    """Handles Agent Graph termination for multiple sources and output or error propagation to Orchestrator.
+
+    Termination scenarios:
+    1. Command based termination with information in state (e.g: escalation)
+    2. LLM-initiated termination (END_EXECUTION_TOOL)
+    3. LLM-initiated error (RAISE_ERROR_TOOL)
+    """
+
+    def terminate_node(state: AgentGraphState):
+        if state.termination:
+            _handle_agent_termination(state.termination)
+
+        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:
+                return _handle_end_execution(tool_call["args"], response_schema)
+
+            if tool_name == RAISE_ERROR_TOOL.name:
+                _handle_raise_error(tool_call["args"])
+
+        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/types.py

@@ -0,0 +1,39 @@
+from enum import StrEnum
+from typing import Annotated
+
+from langchain_core.messages import AnyMessage
+from langgraph.graph.message import add_messages
+from pydantic import BaseModel, Field
+
+
+class AgentTerminationSource(StrEnum):
+    ESCALATION = "escalation"
+
+
+class AgentTermination(BaseModel):
+    """Agent Graph Termination model."""
+
+    source: AgentTerminationSource
+    title: str
+    detail: str = ""
+
+
+class AgentGraphState(BaseModel):
+    """Agent Graph state for standard loop execution."""
+
+    messages: Annotated[list[AnyMessage], add_messages] = []
+    termination: AgentTermination | None = None
+
+
+class AgentGraphNode(StrEnum):
+    INIT = "init"
+    AGENT = "agent"
+    LLM = "llm"
+    TOOLS = "tools"
+    TERMINATE = "terminate"
+
+
+class AgentGraphConfig(BaseModel):
+    recursion_limit: int = Field(
+        default=50, ge=1, description="Maximum recursion limit for the agent graph"
+    )

uipath_langchain/agent/react/utils.py

@@ -0,0 +1,49 @@
+"""ReAct Agent loop utilities."""
+
+from typing import Any, Sequence
+
+from langchain_core.messages import AIMessage, BaseMessage
+from pydantic import BaseModel
+from uipath.agent.react import END_EXECUTION_TOOL
+from uipath.utils.dynamic_schema import jsonschema_to_pydantic
+
+
+def resolve_input_model(
+    input_schema: dict[str, Any] | None,
+) -> type[BaseModel]:
+    """Resolve the input model from the input schema."""
+    if input_schema:
+        return jsonschema_to_pydantic(input_schema)
+
+    return BaseModel
+
+
+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,17 @@
+"""Tool creation and management for LowCode agents."""
+
+from .context_tool import create_context_tool
+from .integration_tool import create_integration_tool
+from .process_tool import create_process_tool
+from .tool_factory import (
+    create_tools_from_resources,
+)
+from .tool_node import create_tool_node
+
+__all__ = [
+    "create_tools_from_resources",
+    "create_tool_node",
+    "create_context_tool",
+    "create_process_tool",
+    "create_integration_tool",
+]

uipath_langchain/agent/tools/context_tool.py

@@ -0,0 +1,53 @@
+"""Context tool creation for semantic index retrieval."""
+
+from typing import Any
+
+from langchain_core.documents import Document
+from langchain_core.tools import StructuredTool
+from pydantic import BaseModel, Field
+from uipath.agent.models.agent import AgentContextResourceConfig
+from uipath.eval.mocks import mockable
+
+from uipath_langchain.retrievers import ContextGroundingRetriever
+
+from .structured_tool_with_output_type import StructuredToolWithOutputType
+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,
+    )
+
+    class ContextInputSchemaModel(BaseModel):
+        query: str = Field(
+            ..., description="The query to search for in the knowledge base"
+        )
+
+    class ContextOutputSchemaModel(BaseModel):
+        documents: list[Document] = Field(
+            ..., description="List of retrieved documents."
+        )
+
+    input_model = ContextInputSchemaModel
+    output_model = ContextOutputSchemaModel
+
+    @mockable(
+        name=resource.name,
+        description=resource.description,
+        input_schema=input_model.model_json_schema(),
+        output_schema=output_model.model_json_schema(),
+    )
+    async def context_tool_fn(query: str) -> dict[str, Any]:
+        return {"documents": await retriever.ainvoke(query)}
+
+    return StructuredToolWithOutputType(
+        name=tool_name,
+        description=resource.description,
+        args_schema=input_model,
+        coroutine=context_tool_fn,
+        output_type=output_model,
+    )

uipath_langchain/agent/tools/escalation_tool.py

@@ -0,0 +1,111 @@
+"""Escalation tool creation for Action Center integration."""
+
+from enum import Enum
+from typing import Any
+
+from jsonschema_pydantic_converter import transform as create_model
+from langchain.tools import ToolRuntime
+from langchain_core.messages import ToolMessage
+from langchain_core.tools import StructuredTool
+from langgraph.types import Command, interrupt
+from uipath.agent.models.agent import (
+    AgentEscalationChannel,
+    AgentEscalationRecipientType,
+    AgentEscalationResourceConfig,
+)
+from uipath.eval.mocks import mockable
+from uipath.platform.common import CreateEscalation
+
+from ..react.types import AgentGraphNode, AgentTerminationSource
+from .utils import sanitize_tool_name
+
+
+class EscalationAction(str, Enum):
+    """Actions that can be taken after an escalation completes."""
+
+    CONTINUE = "continue"
+    END = "end"
+
+
+def create_escalation_tool(resource: AgentEscalationResourceConfig) -> StructuredTool:
+    """Uses interrupt() for Action Center human-in-the-loop."""
+
+    tool_name: str = f"escalate_{sanitize_tool_name(resource.name)}"
+    channel: AgentEscalationChannel = resource.channels[0]
+
+    input_model: Any = create_model(channel.input_schema)
+    output_model: Any = create_model(channel.output_schema)
+
+    assignee: str | None = (
+        channel.recipients[0].value
+        if channel.recipients
+        and channel.recipients[0].type == AgentEscalationRecipientType.USER_EMAIL
+        else None
+    )
+
+    @mockable(
+        name=resource.name,
+        description=resource.description,
+        input_schema=input_model.model_json_schema(),
+        output_schema=output_model.model_json_schema(),
+    )
+    async def escalation_tool_fn(
+        runtime: ToolRuntime, **kwargs: Any
+    ) -> Command[Any] | Any:
+        task_title = channel.task_title or "Escalation Task"
+
+        result = interrupt(
+            CreateEscalation(
+                title=task_title,
+                data=kwargs,
+                assignee=assignee,
+                app_name=channel.properties.app_name,
+                app_folder_path=channel.properties.folder_name,
+                app_version=channel.properties.app_version,
+                priority=channel.priority,
+                labels=channel.labels,
+                is_actionable_message_enabled=channel.properties.is_actionable_message_enabled,
+                actionable_message_metadata=channel.properties.actionable_message_meta_data,
+            )
+        )
+
+        escalation_action = getattr(result, "action", None)
+        escalation_output = getattr(result, "data", {})
+
+        outcome = (
+            channel.outcome_mapping.get(escalation_action)
+            if channel.outcome_mapping and escalation_action
+            else None
+        )
+
+        if outcome == EscalationAction.END:
+            output_detail = f"Escalation output: {escalation_output}"
+            termination_title = f"Agent run ended based on escalation outcome {outcome} with directive {escalation_action}"
+
+            return Command(
+                update={
+                    "messages": [
+                        ToolMessage(
+                            content=f"{termination_title}. {output_detail}",
+                            tool_call_id=runtime.tool_call_id,
+                        )
+                    ],
+                    "termination": {
+                        "source": AgentTerminationSource.ESCALATION,
+                        "title": termination_title,
+                        "detail": output_detail,
+                    },
+                },
+                goto=AgentGraphNode.TERMINATE,
+            )
+
+        return escalation_output
+
+    tool = StructuredTool(
+        name=tool_name,
+        description=resource.description,
+        args_schema=input_model,
+        coroutine=escalation_tool_fn,
+    )
+
+    return tool