uipath-langchain 0.1.34__py3-none-any.whl → 0.3.1__py3-none-any.whl

uipath_langchain/agent/tools/internal_tools/internal_tool_factory.py

@@ -0,0 +1,54 @@
+"""Factory for creating internal agent tools.
+
+This module provides a factory pattern for creating internal tools used by agents.
+Internal tools are built-in tools that provide core functionality for agents, such as
+file analysis, data processing, or other utilities that don't require external integrations.
+
+Supported Internal Tools:
+    - ANALYZE_FILES: Tool for analyzing file contents and extracting information
+
+Example:
+    >>> from uipath.agent.models.agent import AgentInternalToolResourceConfig
+    >>> resource = AgentInternalToolResourceConfig(...)
+    >>> tool = create_internal_tool(resource)
+    >>> # Use the tool in your agent workflow
+"""
+
+from typing import Callable
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import StructuredTool
+from uipath.agent.models.agent import (
+    AgentInternalToolResourceConfig,
+    AgentInternalToolType,
+)
+
+from .analyze_files_tool import create_analyze_file_tool
+
+_INTERNAL_TOOL_HANDLERS: dict[
+    AgentInternalToolType,
+    Callable[[AgentInternalToolResourceConfig, BaseChatModel], StructuredTool],
+] = {
+    AgentInternalToolType.ANALYZE_FILES: create_analyze_file_tool,
+}
+
+
+def create_internal_tool(
+    resource: AgentInternalToolResourceConfig, llm: BaseChatModel
+) -> StructuredTool:
+    """Create an internal tool based on the resource configuration.
+
+    Raises:
+        ValueError: If the tool type is not supported (no handler exists for it).
+
+    """
+    tool_type = resource.properties.tool_type
+
+    handler = _INTERNAL_TOOL_HANDLERS.get(tool_type)
+    if handler is None:
+        raise ValueError(
+            f"Unsupported internal tool type: {tool_type}. "
+            f"Supported types: {list[AgentInternalToolType](_INTERNAL_TOOL_HANDLERS.keys())}"
+        )
+
+    return handler(resource, llm)

uipath_langchain/agent/tools/process_tool.py

@@ -2,13 +2,14 @@
 
 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 uipath_langchain.agent.react.jsonschema_pydantic_converter import create_model
+
 from .structured_tool_with_output_type import StructuredToolWithOutputType
 from .utils import sanitize_tool_name
 
@@ -27,6 +28,7 @@ def create_process_tool(resource: AgentProcessToolResourceConfig) -> StructuredT
         description=resource.description,
         input_schema=input_model.model_json_schema(),
         output_schema=output_model.model_json_schema(),
+        example_calls=resource.properties.example_calls,
     )
     async def process_tool_fn(**kwargs: Any):
         return interrupt(
@@ -44,6 +46,11 @@ def create_process_tool(resource: AgentProcessToolResourceConfig) -> StructuredT
         args_schema=input_model,
         coroutine=process_tool_fn,
         output_type=output_model,
+        metadata={
+            "tool_type": "process",
+            "display_name": process_name,
+            "folder_path": folder_path,
+        },
     )
 
     return tool

uipath_langchain/agent/tools/static_args.py

@@ -1,25 +1,27 @@
 """Handles static arguments for tool calls."""
 
-from typing import Any, Dict, List
+from typing import Any
 
 from jsonpath_ng import parse  # type: ignore[import-untyped]
-from langchain.tools import ToolRuntime
+from pydantic import BaseModel
 from uipath.agent.models.agent import (
     AgentIntegrationToolParameter,
     AgentIntegrationToolResourceConfig,
     BaseAgentResourceConfig,
 )
 
+from .utils import sanitize_dict_for_serialization
+
 
 def resolve_static_args(
     resource: BaseAgentResourceConfig,
-    agent_input: Dict[str, Any],
-) -> Dict[str, Any]:
+    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.
+        input: The input arguments passed to the agent.
 
     Returns:
         A dictionary of expanded arguments to be used in the tool call.
@@ -35,9 +37,9 @@ def resolve_static_args(
 
 
 def resolve_integration_static_args(
-    parameters: List[AgentIntegrationToolParameter],
-    agent_input: Dict[str, Any],
-) -> Dict[str, Any]:
+    parameters: list[AgentIntegrationToolParameter],
+    agent_input: dict[str, Any],
+) -> dict[str, Any]:
     """Resolves static arguments for an integration tool resource.
 
     Args:
@@ -48,7 +50,7 @@ def resolve_integration_static_args(
         A dictionary of expanded static arguments for the integration tool.
     """
 
-    static_args: Dict[str, Any] = {}
+    static_args: dict[str, Any] = {}
     for param in parameters:
         value = None
 
@@ -75,34 +77,10 @@ def resolve_integration_static_args(
     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]:
+    static_args: dict[str, Any],
+    kwargs: dict[str, Any],
+) -> dict[str, Any]:
     """Applies static arguments to the given input arguments.
 
     Args:
@@ -113,7 +91,7 @@ def apply_static_args(
         Merged input arguments with static arguments applied.
     """
 
-    sanitized_args = sanitize_for_serialization(kwargs)
+    sanitized_args = sanitize_dict_for_serialization(kwargs)
     for json_path, value in static_args.items():
         expr = parse(json_path)
         expr.update_or_create(sanitized_args, value)
@@ -122,8 +100,8 @@ def apply_static_args(
 
 
 def handle_static_args(
-    resource: BaseAgentResourceConfig, runtime: ToolRuntime, input_args: Dict[str, Any]
-) -> Dict[str, Any]:
+    resource: BaseAgentResourceConfig, state: BaseModel, input_args: dict[str, Any]
+) -> dict[str, Any]:
     """Resolves and applies static arguments for a tool call.
     Args:
         resource: The agent resource configuration.
@@ -133,6 +111,6 @@ def handle_static_args(
         A dictionary of input arguments with static arguments applied.
     """
 
-    static_args = resolve_static_args(resource, dict(runtime.state))
+    static_args = resolve_static_args(resource, dict(state))
     merged_args = apply_static_args(static_args, input_args)
     return merged_args

uipath_langchain/agent/tools/tool_factory.py

@@ -1,10 +1,12 @@
 """Factory functions for creating tools from agent resources."""
 
-from langchain_core.tools import BaseTool, StructuredTool
+from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
 from uipath.agent.models.agent import (
     AgentContextResourceConfig,
     AgentEscalationResourceConfig,
     AgentIntegrationToolResourceConfig,
+    AgentInternalToolResourceConfig,
     AgentProcessToolResourceConfig,
     BaseAgentResourceConfig,
     LowCodeAgentDefinition,
@@ -13,14 +15,17 @@ from uipath.agent.models.agent import (
 from .context_tool import create_context_tool
 from .escalation_tool import create_escalation_tool
 from .integration_tool import create_integration_tool
+from .internal_tools import create_internal_tool
 from .process_tool import create_process_tool
 
 
-async def create_tools_from_resources(agent: LowCodeAgentDefinition) -> list[BaseTool]:
+async def create_tools_from_resources(
+    agent: LowCodeAgentDefinition, llm: BaseChatModel
+) -> list[BaseTool]:
     tools: list[BaseTool] = []
 
     for resource in agent.resources:
-        tool = await _build_tool_for_resource(resource)
+        tool = await _build_tool_for_resource(resource, llm)
         if tool is not None:
             tools.append(tool)
 
@@ -28,8 +33,8 @@ async def create_tools_from_resources(agent: LowCodeAgentDefinition) -> list[Bas
 
 
 async def _build_tool_for_resource(
-    resource: BaseAgentResourceConfig,
-) -> StructuredTool | None:
+    resource: BaseAgentResourceConfig, llm: BaseChatModel
+) -> BaseTool | None:
     if isinstance(resource, AgentProcessToolResourceConfig):
         return create_process_tool(resource)
 
@@ -42,4 +47,7 @@ async def _build_tool_for_resource(
     elif isinstance(resource, AgentIntegrationToolResourceConfig):
         return create_integration_tool(resource)
 
+    elif isinstance(resource, AgentInternalToolResourceConfig):
+        return create_internal_tool(resource, llm)
+
     return None

uipath_langchain/agent/tools/tool_node.py

@@ -1,22 +1,151 @@
 """Tool node factory wiring directly to LangGraph's ToolNode."""
 
 from collections.abc import Sequence
+from inspect import signature
+from typing import Any, Awaitable, Callable, Literal
 
+from langchain_core.messages.ai import AIMessage
+from langchain_core.messages.tool import ToolCall, ToolMessage
+from langchain_core.runnables.config import RunnableConfig
 from langchain_core.tools import BaseTool
-from langgraph.prebuilt import ToolNode
+from langgraph._internal._runnable import RunnableCallable
+from langgraph.types import Command
+from pydantic import BaseModel
 
+# the type safety can be improved with generics
+ToolWrapperType = Callable[
+    [BaseTool, ToolCall, Any], dict[str, Any] | Command[Any] | None
+]
+AsyncToolWrapperType = Callable[
+    [BaseTool, ToolCall, Any],
+    Awaitable[dict[str, Any] | Command[Any] | None],
+]
+OutputType = dict[Literal["messages"], list[ToolMessage]] | Command[Any] | None
 
-def create_tool_node(tools: Sequence[BaseTool]) -> dict[str, ToolNode]:
+
+class UiPathToolNode(RunnableCallable):
+    """
+    A ToolNode that can be used in a React agent graph.
+    It extracts the tool call from the state messages and invokes the tool.
+    It supports optional synchronous and asynchronous wrappers for custom processing.
+    Generic over the state model.
+    Args:
+        tool: The tool to invoke.
+        wrapper: An optional synchronous wrapper for custom processing.
+        awrapper: An optional asynchronous wrapper for custom processing.
+
+    Returns:
+        A dict with ToolMessage or a Command.
+    """
+
+    def __init__(
+        self,
+        tool: BaseTool,
+        wrapper: ToolWrapperType | None = None,
+        awrapper: AsyncToolWrapperType | None = None,
+    ):
+        super().__init__(func=self._func, afunc=self._afunc, name=tool.name)
+        self.tool = tool
+        self.wrapper = wrapper
+        self.awrapper = awrapper
+
+    def _func(self, state: Any, config: RunnableConfig | None = None) -> OutputType:
+        call = self._extract_tool_call(state)
+        if call is None:
+            return None
+        if self.wrapper:
+            filtered_state = self._filter_state(state, self.wrapper)
+            result = self.wrapper(self.tool, call, filtered_state)
+        else:
+            result = self.tool.invoke(call["args"])
+        return self._process_result(call, result)
+
+    async def _afunc(
+        self, state: Any, config: RunnableConfig | None = None
+    ) -> OutputType:
+        call = self._extract_tool_call(state)
+        if call is None:
+            return None
+        if self.awrapper:
+            filtered_state = self._filter_state(state, self.awrapper)
+            result = await self.awrapper(self.tool, call, filtered_state)
+        else:
+            result = await self.tool.ainvoke(call["args"])
+        return self._process_result(call, result)
+
+    def _extract_tool_call(self, state: Any) -> ToolCall | None:
+        """Extract the tool call from the state messages."""
+
+        if not hasattr(state, "messages"):
+            raise ValueError("State does not have messages key")
+
+        last_message = state.messages[-1]
+        if not isinstance(last_message, AIMessage):
+            raise ValueError("Last message in message stack is not an AIMessage.")
+
+        for tool_call in last_message.tool_calls:
+            if tool_call["name"] == self.tool.name:
+                return tool_call
+        return None
+
+    def _process_result(
+        self, call: ToolCall, result: dict[str, Any] | Command[Any] | None
+    ) -> OutputType:
+        """Process the tool result into a message format or return a Command."""
+        if isinstance(result, Command):
+            return result
+        else:
+            message = ToolMessage(
+                content=str(result), name=call["name"], tool_call_id=call["id"]
+            )
+            return {"messages": [message]}
+
+    def _filter_state(
+        self, state: Any, wrapper: ToolWrapperType | AsyncToolWrapperType
+    ) -> BaseModel:
+        """Filter the state to the expected model type."""
+        model_type = list(signature(wrapper).parameters.values())[2].annotation
+        if not issubclass(model_type, BaseModel):
+            raise ValueError(
+                "Wrapper state parameter must be a pydantic BaseModel subclass."
+            )
+        return model_type.model_validate(state, from_attributes=True)
+
+
+class ToolWrapperMixin:
+    wrapper: ToolWrapperType | None = None
+    awrapper: AsyncToolWrapperType | None = None
+
+    def set_tool_wrappers(
+        self,
+        wrapper: ToolWrapperType | None = None,
+        awrapper: AsyncToolWrapperType | None = None,
+    ) -> None:
+        """Define wrappers for the tool execution."""
+        self.wrapper = wrapper
+        self.awrapper = awrapper
+
+
+def create_tool_node(tools: Sequence[BaseTool]) -> dict[str, UiPathToolNode]:
     """Create individual ToolNode for each tool.
 
     Args:
         tools: Sequence of tools to create nodes for.
+        agentState: The type of the agent state model.
 
     Returns:
-        Dict mapping tool.name -> ToolNode([tool]).
+        Dict mapping tool.name -> ReactToolNode([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}
+    dict_mapping: dict[str, UiPathToolNode] = {}
+    for tool in tools:
+        if isinstance(tool, ToolWrapperMixin):
+            dict_mapping[tool.name] = UiPathToolNode(
+                tool, wrapper=tool.wrapper, awrapper=tool.awrapper
+            )
+        else:
+            dict_mapping[tool.name] = UiPathToolNode(tool, wrapper=None, awrapper=None)
+    return dict_mapping

uipath_langchain/agent/tools/utils.py

@@ -1,6 +1,7 @@
 """Tool-related utility functions."""
 
 import re
+from typing import Any
 
 
 def sanitize_tool_name(name: str) -> str:
@@ -9,3 +10,33 @@ def sanitize_tool_name(name: str) -> str:
     sanitized_tool_name = re.sub(r"[^a-zA-Z0-9_-]", "", trim_whitespaces)
     sanitized_tool_name = sanitized_tool_name[:64]
     return sanitized_tool_name
+
+
+def sanitize_dict_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())
+                elif hasattr(item, "value"):
+                    converted_list.append(item.value)
+                else:
+                    converted_list.append(item)
+            converted_args[key] = converted_list
+
+        # handle enum-like objects with value attribute
+        elif hasattr(value, "value"):
+            converted_args[key] = value.value
+
+        # handle regular value or unexpected type
+        else:
+            converted_args[key] = value
+    return converted_args

uipath_langchain/agent/wrappers/__init__.py

@@ -0,0 +1,6 @@
+"""Wrappers to add behavior to tools while keeping them graph agnostic."""
+
+from .job_attachment_wrapper import get_job_attachment_wrapper
+from .static_args_wrapper import get_static_args_wrapper
+
+__all__ = ["get_static_args_wrapper", "get_job_attachment_wrapper"]

uipath_langchain/agent/wrappers/job_attachment_wrapper.py

@@ -0,0 +1,62 @@
+from typing import Any
+
+from langchain_core.messages.tool import ToolCall
+from langchain_core.tools import BaseTool
+from langgraph.types import Command
+from pydantic import BaseModel
+
+from uipath_langchain.agent.react.job_attachments import (
+    get_job_attachment_paths,
+    replace_job_attachment_ids,
+)
+from uipath_langchain.agent.react.types import AgentGraphState
+from uipath_langchain.agent.tools.tool_node import AsyncToolWrapperType
+
+
+def get_job_attachment_wrapper() -> AsyncToolWrapperType:
+    """Create a tool wrapper that validates and replaces job attachment IDs with full attachment objects.
+
+    This wrapper extracts job attachment paths from the tool's schema, validates that all
+    referenced attachments exist in the agent state, and replaces attachment IDs with complete
+    attachment objects before invoking the tool.
+
+    Args:
+        resource: The agent tool resource configuration
+
+    Returns:
+        An async tool wrapper function that handles job attachment validation and replacement
+    """
+
+    async def job_attachment_wrapper(
+        tool: BaseTool,
+        call: ToolCall,
+        state: AgentGraphState,
+    ) -> dict[str, Any] | Command[Any] | None:
+        """Validate and replace job attachments in tool arguments before invocation.
+
+        Args:
+            tool: The tool to wrap
+            call: The tool call containing arguments
+            state: The agent graph state containing job attachments
+
+        Returns:
+            Tool invocation result, or error dict if attachment validation fails
+        """
+        input_args = call["args"]
+        modified_input_args = input_args
+
+        if isinstance(tool.args_schema, type) and issubclass(
+            tool.args_schema, BaseModel
+        ):
+            errors: list[str] = []
+            paths = get_job_attachment_paths(tool.args_schema)
+            modified_input_args = replace_job_attachment_ids(
+                paths, input_args, state.job_attachments, errors
+            )
+
+            if errors:
+                return {"error": "\n".join(errors)}
+
+        return await tool.ainvoke(modified_input_args)
+
+    return job_attachment_wrapper

uipath_langchain/agent/wrappers/static_args_wrapper.py

@@ -0,0 +1,34 @@
+from typing import Any
+
+from langchain_core.messages.tool import ToolCall
+from langchain_core.tools import BaseTool
+from langgraph.types import Command
+from uipath.agent.models.agent import BaseAgentResourceConfig
+
+from uipath_langchain.agent.react.types import AgentGraphState
+from uipath_langchain.agent.tools.static_args import handle_static_args
+from uipath_langchain.agent.tools.tool_node import AsyncToolWrapperType
+
+
+def get_static_args_wrapper(
+    resource: BaseAgentResourceConfig,
+) -> AsyncToolWrapperType:
+    """Returns an asynchronous tool wrapper that applies static arguments.
+
+    Args:
+        resource: The agent resource configuration.
+
+    Returns:
+        An asynchronous tool wrapper function.
+    """
+
+    async def static_args_wrapper(
+        tool: BaseTool,
+        call: ToolCall,
+        state: AgentGraphState,
+    ) -> dict[str, Any] | Command[Any] | None:
+        input_args = call["args"]
+        merged_args = handle_static_args(resource, state, input_args)
+        return await tool.ainvoke(merged_args)
+
+    return static_args_wrapper