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

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

uipath_langchain/agent/tools/integration_tool.py

@@ -0,0 +1,181 @@
+"""Process tool creation for UiPath process execution."""
+
+import copy
+from typing import Any
+
+from jsonschema_pydantic_converter import transform as create_model
+from langchain.tools import ToolRuntime
+from langchain_core.tools import StructuredTool
+from uipath.agent.models.agent import AgentIntegrationToolResourceConfig
+from uipath.eval.mocks import mockable
+from uipath.platform import UiPath
+from uipath.platform.connections import ActivityMetadata, ActivityParameterLocationInfo
+
+from .static_args import handle_static_args
+from .structured_tool_with_output_type import StructuredToolWithOutputType
+from .utils import sanitize_tool_name
+
+
+def remove_asterisk_from_properties(fields: dict[str, Any]) -> dict[str, Any]:
+    """
+    Fix bug in integration service.
+    """
+    fields = copy.deepcopy(fields)
+
+    def fix_types(props: dict[str, Any]) -> None:
+        type_ = props.get("type", None)
+        if "$ref" in props:
+            props["$ref"] = props["$ref"].replace("[*]", "")
+        if type_ == "object":
+            properties = {}
+            for k, v in props.get("properties", {}).items():
+                # Remove asterisks!
+                k = k.replace("[*]", "")
+                properties[k] = v
+                if isinstance(v, dict):
+                    fix_types(v)
+            if "properties" in props:
+                props["properties"] = properties
+        if type_ == "array":
+            fix_types(props.get("items", {}))
+
+    definitions = {}
+    for k, value in fields.get("$defs", fields.get("definitions", {})).items():
+        k = k.replace("[*]", "")
+        definitions[k] = value
+        fix_types(value)
+    if "definitions" in fields:
+        fields["definitions"] = definitions
+
+    fix_types(fields)
+    return fields
+
+
+def extract_top_level_field(param_name: str) -> str:
+    """Extract the top-level field name from a jsonpath parameter name.
+
+    Examples:
+        metadata.field.test -> metadata
+        attachments[*] -> attachments
+        attachments[0].filename -> attachments
+        simple_field -> simple_field
+    """
+    # Split by '.' to get the first part
+    first_part = param_name.split(".")[0]
+
+    # Remove array notation if present (e.g., "attachments[*]" -> "attachments")
+    if "[" in first_part:
+        first_part = first_part.split("[")[0]
+
+    return first_part
+
+
+def convert_to_activity_metadata(
+    resource: AgentIntegrationToolResourceConfig,
+) -> ActivityMetadata:
+    """Convert AgentIntegrationToolResourceConfig to ActivityMetadata."""
+
+    # normalize HTTP method (GETBYID -> GET)
+    http_method = resource.properties.method
+    if http_method == "GETBYID":
+        http_method = "GET"
+
+    param_location_info = ActivityParameterLocationInfo()
+    # because of nested fields and array notation, use a set to avoid duplicates
+    body_fields_set = set()
+
+    # mapping parameter locations
+    for param in resource.properties.parameters:
+        param_name = param.name
+        field_location = param.field_location
+
+        if field_location == "query":
+            param_location_info.query_params.append(param_name)
+        elif field_location == "path":
+            param_location_info.path_params.append(param_name)
+        elif field_location == "header":
+            param_location_info.header_params.append(param_name)
+        elif field_location in ("multipart", "file"):
+            param_location_info.multipart_params.append(param_name)
+        elif field_location == "body":
+            # extract top-level field from jsonpath parameter name
+            top_level_field = extract_top_level_field(param_name)
+            body_fields_set.add(top_level_field)
+        else:
+            # default to body field - extract top-level field
+            top_level_field = extract_top_level_field(param_name)
+            body_fields_set.add(top_level_field)
+
+    param_location_info.body_fields = list(body_fields_set)
+
+    # determine content type
+    content_type = "application/json"
+    if resource.properties.body_structure is not None:
+        shorthand_type = resource.properties.body_structure.get("contentType", "json")
+        if shorthand_type == "multipart":
+            content_type = "multipart/form-data"
+
+    return ActivityMetadata(
+        object_path=resource.properties.tool_path,
+        method_name=http_method,
+        content_type=content_type,
+        parameter_location_info=param_location_info,
+    )
+
+
+def create_integration_tool(
+    resource: AgentIntegrationToolResourceConfig,
+) -> StructuredTool:
+    """Creates a StructuredTool for invoking an Integration Service connector activity."""
+    tool_name: str = sanitize_tool_name(resource.name)
+    if resource.properties.connection.id is None:
+        raise ValueError("Connection ID cannot be None for integration tool.")
+    connection_id: str = resource.properties.connection.id
+
+    activity_metadata = convert_to_activity_metadata(resource)
+
+    input_model = create_model(resource.input_schema)
+    # note: IS tools output schemas were recently added and are most likely not present in all resources
+    output_model: Any = (
+        create_model(remove_asterisk_from_properties(resource.output_schema))
+        if resource.output_schema
+        else create_model({"type": "object", "properties": {}})
+    )
+
+    sdk = UiPath()
+
+    @mockable(
+        name=resource.name,
+        description=resource.description,
+        input_schema=input_model.model_json_schema(),
+        output_schema=output_model.model_json_schema(),
+    )
+    async def integration_tool_fn(runtime: ToolRuntime, **kwargs: Any):
+        try:
+            # we manually validating here and not passing input_model to StructuredTool
+            # because langchain itself will block their own injected arguments (like runtime) if the model is strict
+            val_args = input_model.model_validate(kwargs)
+            args = handle_static_args(
+                resource=resource,
+                runtime=runtime,
+                input_args=val_args.model_dump(),
+            )
+            result = await sdk.connections.invoke_activity_async(
+                activity_metadata=activity_metadata,
+                connection_id=connection_id,
+                activity_input=args,
+            )
+        except Exception:
+            raise
+
+        return result
+
+    tool = StructuredToolWithOutputType(
+        name=tool_name,
+        description=resource.description,
+        args_schema=resource.input_schema,
+        coroutine=integration_tool_fn,
+        output_type=output_model,
+    )
+
+    return tool

uipath_langchain/agent/tools/process_tool.py

@@ -0,0 +1,49 @@
+"""Process tool creation for UiPath process execution."""
+
+from typing import Any
+
+from jsonschema_pydantic_converter import transform as create_model
+from langchain_core.tools import StructuredTool
+from langgraph.types import interrupt
+from uipath.agent.models.agent import AgentProcessToolResourceConfig
+from uipath.eval.mocks import mockable
+from uipath.platform.common import InvokeProcess
+
+from .structured_tool_with_output_type import StructuredToolWithOutputType
+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: Any = create_model(resource.input_schema)
+    output_model: Any = create_model(resource.output_schema)
+
+    @mockable(
+        name=resource.name,
+        description=resource.description,
+        input_schema=input_model.model_json_schema(),
+        output_schema=output_model.model_json_schema(),
+    )
+    async def process_tool_fn(**kwargs: Any):
+        return interrupt(
+            InvokeProcess(
+                name=process_name,
+                input_arguments=kwargs,
+                process_folder_path=folder_path,
+                process_folder_key=None,
+            )
+        )
+
+    tool = StructuredToolWithOutputType(
+        name=tool_name,
+        description=resource.description,
+        args_schema=input_model,
+        coroutine=process_tool_fn,
+        output_type=output_model,
+    )
+
+    return tool

uipath_langchain/agent/tools/static_args.py

@@ -0,0 +1,138 @@
+"""Handles static arguments for tool calls."""
+
+from typing import Any, Dict, List
+
+from jsonpath_ng import parse  # type: ignore[import-untyped]
+from langchain.tools import ToolRuntime
+from uipath.agent.models.agent import (
+    AgentIntegrationToolParameter,
+    AgentIntegrationToolResourceConfig,
+    BaseAgentResourceConfig,
+)
+
+
+def resolve_static_args(
+    resource: BaseAgentResourceConfig,
+    agent_input: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Resolves static arguments for a given resource with a given input.
+
+    Args:
+        resource: The agent resource configuration.
+        input: Othe input arguments passed to the agent.
+
+    Returns:
+        A dictionary of expanded arguments to be used in the tool call.
+    static_args: Dict[str, Any] = {}
+    """
+
+    if isinstance(resource, AgentIntegrationToolResourceConfig):
+        return resolve_integration_static_args(
+            resource.properties.parameters, agent_input
+        )
+    else:
+        return {}  # to be implemented for other resource types in the future
+
+
+def resolve_integration_static_args(
+    parameters: List[AgentIntegrationToolParameter],
+    agent_input: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Resolves static arguments for an integration tool resource.
+
+    Args:
+        resource: The AgentIntegrationToolResourceConfig instance.
+        input: The input arguments passed to the agent.
+
+    Returns:
+        A dictionary of expanded static arguments for the integration tool.
+    """
+
+    static_args: Dict[str, Any] = {}
+    for param in parameters:
+        value = None
+
+        # static parameter, use the defined static value
+        if param.field_variant == "static":
+            value = param.value
+        # argument parameter, extract value from agent input
+        elif param.field_variant == "argument":
+            if (
+                not isinstance(param.value, str)
+                or not param.value.startswith("{{")
+                or not param.value.endswith("}}")
+            ):
+                raise ValueError(
+                    f"Parameter value must be in the format '{{argument_name}}' when field_variant is 'argument', got {param.value}"
+                )
+            arg_name = param.value[2:-2].strip()
+            # currently only support top-level arguments
+            value = agent_input.get(arg_name)
+
+        if value is not None:
+            static_args[param.name] = value
+
+    return static_args
+
+
+def sanitize_for_serialization(args: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert Pydantic models in args to dicts."""
+    converted_args: Dict[str, Any] = {}
+    for key, value in args.items():
+        # handle Pydantic model
+        if hasattr(value, "model_dump"):
+            converted_args[key] = value.model_dump()
+
+        elif isinstance(value, list):
+            # handle list of Pydantic models
+            converted_list = []
+            for item in value:
+                if hasattr(item, "model_dump"):
+                    converted_list.append(item.model_dump())
+                else:
+                    converted_list.append(item)
+            converted_args[key] = converted_list
+
+        # handle regular value or unexpected type
+        else:
+            converted_args[key] = value
+    return converted_args
+
+
+def apply_static_args(
+    static_args: Dict[str, Any],
+    kwargs: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Applies static arguments to the given input arguments.
+
+    Args:
+        static_args: Dictionary of static arguments {json_path: value} to apply.
+        kwargs: Original input arguments to the tool.
+
+    Returns:
+        Merged input arguments with static arguments applied.
+    """
+
+    sanitized_args = sanitize_for_serialization(kwargs)
+    for json_path, value in static_args.items():
+        expr = parse(json_path)
+        expr.update_or_create(sanitized_args, value)
+
+    return sanitized_args
+
+
+def handle_static_args(
+    resource: BaseAgentResourceConfig, runtime: ToolRuntime, input_args: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Resolves and applies static arguments for a tool call.
+    Args:
+        resource: The agent resource configuration.
+        runtime: The tool runtime providing the current state.
+        input_args: The original input arguments to the tool.
+    Returns:
+        A dictionary of input arguments with static arguments applied.
+    """
+
+    static_args = resolve_static_args(resource, dict(runtime.state))
+    merged_args = apply_static_args(static_args, input_args)
+    return merged_args