feat: add uipath_langchain.agent.deep with optional deepagents extra

Author: radu-mocanu

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-langchain"
-version = "0.10.11"
+version = "0.10.12"
 description = "Python SDK that enables developers to build and deploy LangGraph agents to the UiPath Cloud Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
@@ -53,8 +53,12 @@ bedrock = [
 fireworks = [
     "uipath-langchain-client[fireworks]>=1.10.0,<1.11.0",
 ]
+deep = [
+    "deepagents==0.4.11",
+]
 all = [
     "uipath-langchain-client[all]>=1.10.0,<1.11.0",
+    "deepagents==0.4.11",
 ]
 
 [project.entry-points."uipath.middlewares"]

src/uipath_langchain/agent/deep/__init__.py

@@ -0,0 +1,59 @@
+"""Advanced (deep) agent support, built on the optional `deepagents` package.
+
+Install the optional extra to use this module:
+
+    pip install 'uipath-langchain[deep]'
+
+The `deepagents` types re-exported here (``SubAgent``, ``CompiledSubAgent``,
+``BackendProtocol``, ``BackendFactory``) are loaded lazily so importing this
+package without the extra installed does not crash — only attribute access
+will raise ``ImportError`` with the install hint.
+"""
+
+from .agent import create_advanced_agent, create_advanced_agent_graph
+from .prompts import get_advanced_agent_meta_prompt
+from .types import AdvancedAgentGraphState
+from .utils import create_state_with_input
+
+_INSTALL_HINT = (
+    "deepagents is required for advanced agents. "
+    "Install with: pip install 'uipath-langchain[deep]'"
+)
+
+
+def __getattr__(name: str):
+    if name in ("SubAgent", "CompiledSubAgent"):
+        try:
+            import deepagents
+
+            return getattr(deepagents, name)
+        except ImportError as exc:
+            raise ImportError(_INSTALL_HINT) from exc
+    if name == "BackendProtocol":
+        try:
+            from deepagents.backends import BackendProtocol
+
+            return BackendProtocol
+        except ImportError as exc:
+            raise ImportError(_INSTALL_HINT) from exc
+    if name == "BackendFactory":
+        try:
+            from deepagents.backends.protocol import BackendFactory
+
+            return BackendFactory
+        except ImportError as exc:
+            raise ImportError(_INSTALL_HINT) from exc
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "AdvancedAgentGraphState",
+    "BackendFactory",
+    "BackendProtocol",
+    "CompiledSubAgent",
+    "SubAgent",
+    "create_advanced_agent",
+    "create_advanced_agent_graph",
+    "create_state_with_input",
+    "get_advanced_agent_meta_prompt",
+]

src/uipath_langchain/agent/deep/agent.py

@@ -0,0 +1,159 @@
+"""Advanced (deep) agent builder.
+
+Thin UiPath wrapper around the `deepagents` library. The deepagents dependency
+is optional — install with `pip install 'uipath-langchain[deep]'` to use this
+module.
+"""
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, Any
+
+from langchain.agents.structured_output import ResponseFormat
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import HumanMessage
+from langchain_core.tools import BaseTool
+from langgraph.graph import END, START
+from langgraph.graph.state import CompiledStateGraph, StateGraph
+from pydantic import BaseModel
+
+from .types import AdvancedAgentGraphState
+from .utils import create_state_with_input
+
+if TYPE_CHECKING:
+    from deepagents import CompiledSubAgent, SubAgent
+    from deepagents.backends import BackendProtocol
+    from deepagents.backends.protocol import BackendFactory
+
+
+_INSTALL_HINT = (
+    "deepagents is required for advanced agents. "
+    "Install with: pip install 'uipath-langchain[deep]'"
+)
+
+
+def _import_deepagents() -> Any:
+    try:
+        import deepagents  # noqa: F401
+        from deepagents import create_deep_agent
+
+        return create_deep_agent
+    except ImportError as exc:
+        raise ImportError(_INSTALL_HINT) from exc
+
+
+def create_advanced_agent(
+    model: BaseChatModel,
+    system_prompt: str = "",
+    tools: Sequence[BaseTool] = (),
+    subagents: "Sequence[SubAgent | CompiledSubAgent]" = (),
+    backend: "BackendProtocol | BackendFactory | None" = None,
+    response_format: ResponseFormat[Any] | None = None,
+) -> CompiledStateGraph[Any, Any, Any, Any]:
+    """Create an advanced agent.
+
+    Advanced agents provide built-in capabilities for:
+    - Planning (write_todos, read_todos)
+    - Filesystem operations (read_file, write_file, edit_file, ls, glob, grep)
+    - Sub-agent delegation (task)
+    - Auto-summarization for long conversations
+
+    Args:
+        model: A BaseChatModel instance.
+        system_prompt: Instructions for the agent.
+        tools: Custom tools to provide to the agent.
+        subagents: Optional list of subagent configurations. Each entry is a
+            ``SubAgent`` (name, description, system_prompt, and optional tools/model/middleware)
+            or a ``CompiledSubAgent`` (name, description, and a pre-built runnable).
+        backend: Storage backend for filesystem operations. Can be a
+            ``BackendProtocol`` instance, a factory callable, or ``None``
+            (uses the default in-state backend).
+        response_format: Structured output format for the agent response.
+
+    Returns:
+        Compiled LangGraph agent ready for execution.
+
+    Raises:
+        ImportError: If the ``deepagents`` package is not installed. Install
+            with ``pip install 'uipath-langchain[deep]'``.
+    """
+    create_deep_agent = _import_deepagents()
+    return create_deep_agent(
+        model=model,
+        system_prompt=system_prompt,
+        tools=list(tools),
+        subagents=list(subagents),
+        backend=backend,
+        response_format=response_format,
+    )
+
+
+def create_advanced_agent_graph(
+    model: BaseChatModel,
+    tools: Sequence[BaseTool],
+    system_prompt: str,
+    backend: "BackendProtocol | BackendFactory | None",
+    response_format: ResponseFormat[Any] | None,
+    input_schema: type[BaseModel] | None,
+    output_schema: type[BaseModel],
+    build_user_message: Callable[[dict[str, Any]], str],
+) -> StateGraph[Any, Any, Any, Any]:
+    """Build an advanced agent wrapped in a parent graph that handles I/O transformation.
+
+    The advanced agent only understands messages as input and produces
+    structured_response as output. The wrapper graph bridges the gap:
+
+        START -> transform_input -> advanced_agent -> transform_output -> END
+
+    Args:
+        model: Chat model for the advanced agent.
+        tools: Tools available to the advanced agent.
+        system_prompt: Combined system + meta prompt.
+        backend: Filesystem backend for the advanced agent.
+        response_format: Structured output format.
+        input_schema: Resolved input Pydantic model (or None).
+        output_schema: Resolved output Pydantic model.
+        build_user_message: Callable that converts input arguments dict to a user message string.
+
+    Raises:
+        ImportError: If the ``deepagents`` package is not installed. Install
+            with ``pip install 'uipath-langchain[deep]'``.
+    """
+    inner_graph = create_advanced_agent(
+        model=model,
+        tools=tools,
+        system_prompt=system_prompt,
+        backend=backend,
+        response_format=response_format,
+    )
+
+    wrapper_state = create_state_with_input(input_schema)
+
+    internal_fields = set(AdvancedAgentGraphState.model_fields.keys())
+
+    def transform_input(state: BaseModel) -> dict[str, Any]:
+        state_data = state.model_dump()
+        input_data = {k: v for k, v in state_data.items() if k not in internal_fields}
+        input_args = (
+            input_schema.model_validate(input_data).model_dump()
+            if input_schema is not None
+            else {}
+        )
+        user_text = build_user_message(input_args)
+        return {"messages": [HumanMessage(content=user_text, id="user-input")]}
+
+    def transform_output(state: BaseModel) -> dict[str, Any]:
+        structured = getattr(state, "structured_response", {})
+        return output_schema.model_validate(structured).model_dump()
+
+    wrapper: StateGraph[Any, Any, Any, Any] = StateGraph(
+        wrapper_state, input_schema=input_schema, output_schema=output_schema
+    )
+    wrapper.add_node("transform_input", transform_input)
+    wrapper.add_node("advanced_agent", inner_graph)
+    wrapper.add_node("transform_output", transform_output)
+    wrapper.add_edge(START, "transform_input")
+    wrapper.add_edge("transform_input", "advanced_agent")
+    wrapper.add_edge("advanced_agent", "transform_output")
+    wrapper.add_edge("transform_output", END)
+
+    return wrapper

src/uipath_langchain/agent/deep/prompts.py

@@ -0,0 +1,32 @@
+"""Meta prompt for advanced agent capabilities.
+
+Describes what tools an advanced agent has access to (todos, subagents, filesystem)
+so the model knows how to leverage them. Workflow-specific goals live in agent.json.
+"""
+
+_ADVANCED_AGENT_META_PROMPT_TEMPLATE = """\
+You are an advanced agent with powerful capabilities that standard agents lack. \
+Use them to produce high-quality output efficiently. Break work into parts, delegate, persist, and assemble.
+
+**Planning — `write_todos` / `read_todos`**
+Start by creating a todo list with `write_todos`. Each todo should be a concrete, completable task. \
+Use `read_todos` to check progress and stay on track. Mark todos done as you complete them. \
+Never skip planning.
+
+**Delegation — `task` tool**
+You have subagents. Delegate independent, self-contained tasks using the `task` tool. Each subagent \
+runs independently with its own context and tools. Give subagents specific, detailed \
+instructions including all necessary context, background information, and expected output \
+format — they cannot see your conversation history or files. \
+If work needs context from other subagents (like synthesis or final assembly), do it yourself. \
+Launch multiple subagents in parallel when tasks are independent.
+
+**Filesystem — `write_file` / `edit_file` / `read_file`**
+You have a virtual filesystem (root: `/`). Persist work to files — save results from each \
+task to a dedicated file (e.g., `/task-01.md`). \
+Use `edit_file` to update or append to existing files as work progresses."""
+
+
+def get_advanced_agent_meta_prompt() -> str:
+    """Return the advanced agent capabilities meta prompt."""
+    return _ADVANCED_AGENT_META_PROMPT_TEMPLATE

src/uipath_langchain/agent/deep/types.py

@@ -0,0 +1,14 @@
+"""State types for the advanced (deep) agent wrapper graph."""
+
+from typing import Annotated, Any
+
+from langchain_core.messages import AnyMessage
+from langgraph.graph.message import add_messages
+from pydantic import BaseModel
+
+
+class AdvancedAgentGraphState(BaseModel):
+    """Graph state for the advanced agent wrapper."""
+
+    messages: Annotated[list[AnyMessage], add_messages] = []
+    structured_response: dict[str, Any] = {}

src/uipath_langchain/agent/deep/utils.py

@@ -0,0 +1,26 @@
+"""Utilities for the advanced (deep) agent wrapper graph."""
+
+from typing import cast
+
+from pydantic import BaseModel
+
+from .types import AdvancedAgentGraphState
+
+
+def create_state_with_input(
+    input_schema: type[BaseModel] | None,
+) -> type[AdvancedAgentGraphState]:
+    """Create combined state by merging AdvancedAgentGraphState with the input schema.
+
+    Mirrors the shallow agent's create_state_with_input pattern:
+    dynamic multi-inheritance + model_rebuild() for Pydantic resolution.
+    """
+    if input_schema is None:
+        return AdvancedAgentGraphState
+    CompleteState = type(
+        "CompleteAdvancedAgentGraphState",
+        (AdvancedAgentGraphState, input_schema),
+        {},
+    )
+    cast(type[BaseModel], CompleteState).model_rebuild()
+    return CompleteState

tests/agent/deep/__init__.py

@@ -0,0 +1,38 @@
+"""Smoke test for create_advanced_agent.
+
+Verifies create_advanced_agent forwards its arguments to deepagents.create_deep_agent.
+We don't exercise the deepagents internals (those are tested by the deepagents
+package itself); we only validate UiPath's pass-through.
+"""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+pytest.importorskip("deepagents")
+
+from uipath_langchain.agent.deep import create_advanced_agent  # noqa: E402
+
+
+def test_create_advanced_agent_forwards_to_deepagents() -> None:
+    sentinel_graph = MagicMock(name="compiled_deep_agent")
+    fake_create_deep_agent = MagicMock(return_value=sentinel_graph)
+    model = MagicMock()
+
+    with patch(
+        "uipath_langchain.agent.deep.agent._import_deepagents",
+        return_value=fake_create_deep_agent,
+    ):
+        graph = create_advanced_agent(
+            model=model, system_prompt="sys", tools=[], subagents=[]
+        )
+
+    assert graph is sentinel_graph
+    fake_create_deep_agent.assert_called_once()
+    kwargs = fake_create_deep_agent.call_args.kwargs
+    assert kwargs["model"] is model
+    assert kwargs["system_prompt"] == "sys"
+    assert kwargs["tools"] == []
+    assert kwargs["subagents"] == []
+    assert kwargs["backend"] is None
+    assert kwargs["response_format"] is None