feat: add entrypoint autodiscover (#1431)

Author: radugheo

packages/uipath/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath"
-version = "2.10.40"
+version = "2.10.41"
 description = "Python SDK and CLI for UiPath Platform, enabling programmatic interaction with automation services, process management, and deployment tools."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath/src/uipath/_cli/_errors.py

@@ -0,0 +1,20 @@
+class EntrypointDiscoveryException(Exception):
+    """Raised when entrypoint auto-discovery fails."""
+
+    def __init__(self, entrypoints: list[str]):
+        self.entrypoints = entrypoints
+
+    def get_usage_help(self) -> list[str]:
+        if self.entrypoints:
+            lines = ["Available entrypoints:"]
+            for name in self.entrypoints:
+                lines.append(f"  - {name}")
+            return lines
+        return [
+            "No entrypoints found.",
+            "",
+            "To configure entrypoints, use one of the following:",
+            "  1. Functions project (uipath.json)",
+            "  2. Framework-specific project (e.g. langgraph.json, llamaindex.json, openai_agents.json)",
+            "  3. MCP project (mcp.json)",
+        ]

packages/uipath/src/uipath/_cli/cli_eval.py

@@ -8,6 +8,7 @@
 
 import click
 
+from uipath._cli._errors import EntrypointDiscoveryException
 from uipath._cli._evals._console_progress_reporter import ConsoleProgressReporter
 from uipath._cli._evals._progress_reporter import StudioWebProgressReporter
 from uipath._cli._evals._telemetry import EvalTelemetrySubscriber
@@ -135,13 +136,35 @@ def _resolve_model_settings_override(
     return override if override else None
 
 
-class _EvalDiscoveryError(Exception):
+class _EvalDiscoveryError(EntrypointDiscoveryException):
     """Raised when auto-discovery of entrypoint or eval set fails."""
 
     def __init__(self, entrypoints: list[str], eval_sets: list[Path]):
-        self.entrypoints = entrypoints
+        super().__init__(entrypoints)
         self.eval_sets = eval_sets
 
+    def get_usage_help(self) -> list[str]:
+        lines = super().get_usage_help()
+
+        if self.eval_sets:
+            lines.append("")
+            lines.append("Available eval sets:")
+            for f in self.eval_sets:
+                lines.append(f"  - {f}")
+        else:
+            lines.append("")
+            lines.append(
+                f"No eval sets found in '{EVAL_SETS_DIRECTORY_NAME}/' directory."
+            )
+
+        lines.append("")
+        lines.append("Usage: uipath eval <entrypoint> <eval_set>")
+        if self.entrypoints and self.eval_sets:
+            lines.append(
+                f"Example: uipath eval {self.entrypoints[0]} {self.eval_sets[0]}"
+            )
+        return lines
+
 
 def _discover_eval_sets() -> list[Path]:
     """Discover available eval set files."""
@@ -151,39 +174,6 @@ def _discover_eval_sets() -> list[Path]:
     return []
 
 
-def _show_eval_usage_help(entrypoints: list[str], eval_set_files: list[Path]) -> None:
-    """Show available entrypoints and eval sets with usage examples."""
-    lines: list[str] = []
-
-    if entrypoints:
-        lines.append("Available entrypoints:")
-        for name in entrypoints:
-            lines.append(f"  - {name}")
-    else:
-        lines.append(
-            "No entrypoints found. "
-            "Add a 'functions' or 'agents' section to your config file "
-            "(e.g. uipath.json, langgraph.json)."
-        )
-
-    if eval_set_files:
-        lines.append("\nAvailable eval sets:")
-        for f in eval_set_files:
-            lines.append(f"  - {f}")
-    else:
-        lines.append(
-            f"\nNo eval sets found in '{EVAL_SETS_DIRECTORY_NAME}/' directory."
-        )
-
-    lines.append("\nUsage: uipath eval <entrypoint> <eval_set>")
-    if entrypoints and eval_set_files:
-        ep_name = entrypoints[0]
-        es_path = eval_set_files[0]
-        lines.append(f"Example: uipath eval {ep_name} {es_path}")
-
-    click.echo("\n".join(lines))
-
-
 @click.command()
 @click.argument("entrypoint", required=False)
 @click.argument("eval_set", required=False)
@@ -475,7 +465,13 @@ async def execute_eval():
             asyncio.run(execute_eval())
 
         except _EvalDiscoveryError as e:
-            _show_eval_usage_help(e.entrypoints, e.eval_sets)
+            click.echo("\n".join(e.get_usage_help()))
+            if not e.entrypoints:
+                click.echo()
+                console.link(
+                    "uipath.json spec:",
+                    "https://github.com/UiPath/uipath-python/blob/main/packages/uipath/specs/uipath.spec.md",
+                )
         except ValueError as e:
             console.error(str(e))
         except Exception as e:

packages/uipath/src/uipath/_cli/cli_run.py

@@ -27,13 +27,29 @@
     LlmOpsHttpExporter,
 )
 
+from ._errors import EntrypointDiscoveryException
 from ._telemetry import track_command
 from ._utils._console import ConsoleLogger
 from .middlewares import Middlewares
 
 console = ConsoleLogger()
 
 
+class _RunDiscoveryError(EntrypointDiscoveryException):
+    """Raised when entrypoint auto-discovery fails."""
+
+    def get_usage_help(self) -> list[str]:
+        lines = super().get_usage_help()
+        lines.append("")
+        lines.append(
+            "Usage: uipath run <entrypoint> <input_arguments>"
+            " [-f <input_json_file_path>]"
+        )
+        if self.entrypoints:
+            lines.append(f"Example: uipath run {self.entrypoints[0]}")
+        return lines
+
+
 @click.command()
 @click.argument("entrypoint", required=False)
 @click.argument("input", required=False, default=None)
@@ -125,11 +141,6 @@ def run(
         return
 
     if result.should_continue:
-        if not entrypoint:
-            console.error("""No entrypoint specified. Please provide the path to the Python function.
-    Usage: `uipath run <entrypoint> <input_arguments> [-f <input_json_file_path>]`""")
-            return
-
         try:
 
             async def execute_runtime(
@@ -187,14 +198,23 @@ async def execute() -> None:
                         factory: UiPathRuntimeFactoryProtocol | None = None
                         try:
                             factory = UiPathRuntimeFactoryRegistry.get(context=ctx)
+
+                            resolved_entrypoint = entrypoint
+                            if not resolved_entrypoint:
+                                available = factory.discover_entrypoints()
+                                if len(available) == 1:
+                                    resolved_entrypoint = available[0]
+                                else:
+                                    raise _RunDiscoveryError(available)
+
                             factory_settings = await factory.get_settings()
                             trace_settings = (
                                 factory_settings.trace_settings
                                 if factory_settings
                                 else None
                             )
                             runtime = await factory.new_runtime(
-                                entrypoint,
+                                resolved_entrypoint,
                                 ctx.conversation_id or ctx.job_id or "default",
                             )
 
@@ -230,6 +250,15 @@ async def execute() -> None:
 
             asyncio.run(execute())
 
+        except _RunDiscoveryError as e:
+            click.echo("\n".join(e.get_usage_help()))
+            if not e.entrypoints:
+                click.echo()
+                console.link(
+                    "uipath.json spec:",
+                    "https://github.com/UiPath/uipath-python/blob/main/packages/uipath/specs/uipath.spec.md",
+                )
+            return
         except UiPathRuntimeError as e:
             console.error(f"{e.error_info.title} - {e.error_info.detail}")
         except Exception as e:

packages/uipath/tests/cli/test_run.py

@@ -1,6 +1,7 @@
 # type: ignore
 import os
-from unittest.mock import patch
+from contextlib import asynccontextmanager
+from unittest.mock import AsyncMock, Mock, patch
 
 import pytest
 from click.testing import CliRunner
@@ -9,6 +10,41 @@
 from uipath._cli.middlewares import MiddlewareResult
 
 
+def _middleware_continue():
+    return MiddlewareResult(
+        should_continue=True,
+        error_message=None,
+        should_include_stacktrace=False,
+    )
+
+
+async def _empty_async_gen(*args, **kwargs):
+    """An async generator that yields nothing (simulates empty runtime.stream)."""
+    if False:  # pragma: no cover
+        yield
+
+
+def _make_mock_factory(entrypoints: list[str]):
+    """Create a mock runtime factory with given entrypoints."""
+    mock_factory = Mock()
+    mock_factory.discover_entrypoints.return_value = entrypoints
+    mock_factory.get_settings = AsyncMock(return_value=None)
+    mock_factory.dispose = AsyncMock()
+
+    mock_runtime = Mock()
+    mock_runtime.execute = AsyncMock(return_value=Mock(status="SUCCESSFUL"))
+    mock_runtime.stream = Mock(side_effect=_empty_async_gen)
+    mock_runtime.dispose = AsyncMock()
+    mock_factory.new_runtime = AsyncMock(return_value=mock_runtime)
+
+    return mock_factory
+
+
+@asynccontextmanager
+async def _mock_resource_overwrites_context(*args, **kwargs):
+    yield
+
+
 @pytest.fixture
 def entrypoint():
     return "main"
@@ -142,14 +178,81 @@ def test_run_input_file_success(
                     assert "Successful execution." in result.output
 
     class TestMiddleware:
-        def test_no_entrypoint(self, runner: CliRunner, temp_dir: str):
+        def test_autodiscover_entrypoint(self, runner: CliRunner, temp_dir: str):
+            """When exactly one entrypoint exists, it is auto-resolved."""
             with runner.isolated_filesystem(temp_dir=temp_dir):
-                result = runner.invoke(cli, ["run"])
-                assert result.exit_code == 1
-                assert (
-                    "No entrypoint specified" in result.output
-                    or "Missing argument" in result.output
+                mock_factory = _make_mock_factory(["my_agent"])
+
+                with (
+                    patch(
+                        "uipath._cli.cli_run.Middlewares.next",
+                        return_value=_middleware_continue(),
+                    ),
+                    patch(
+                        "uipath._cli.cli_run.UiPathRuntimeFactoryRegistry.get",
+                        return_value=mock_factory,
+                    ),
+                    patch(
+                        "uipath._cli.cli_run.ResourceOverwritesContext",
+                        side_effect=_mock_resource_overwrites_context,
+                    ),
+                ):
+                    result = runner.invoke(cli, ["run"])
+
+                assert result.exit_code == 0, (
+                    f"output: {result.output!r}, exception: {result.exception}"
                 )
+                assert "Successful execution." in result.output
+                mock_factory.new_runtime.assert_awaited_once()
+                assert mock_factory.new_runtime.call_args[0][0] == "my_agent"
+
+        def test_no_entrypoint_multiple_available(
+            self, runner: CliRunner, temp_dir: str
+        ):
+            """When multiple entrypoints exist and none specified, show usage help."""
+            with runner.isolated_filesystem(temp_dir=temp_dir):
+                mock_factory = _make_mock_factory(["agent_a", "agent_b"])
+
+                with (
+                    patch(
+                        "uipath._cli.cli_run.Middlewares.next",
+                        return_value=_middleware_continue(),
+                    ),
+                    patch(
+                        "uipath._cli.cli_run.UiPathRuntimeFactoryRegistry.get",
+                        return_value=mock_factory,
+                    ),
+                ):
+                    result = runner.invoke(cli, ["run"])
+
+                assert result.exit_code == 0
+                assert "Available entrypoints:" in result.output
+                assert "agent_a" in result.output
+                assert "agent_b" in result.output
+                assert "Usage: uipath run" in result.output
+                mock_factory.new_runtime.assert_not_awaited()
+
+        def test_no_entrypoint_none_available(self, runner: CliRunner, temp_dir: str):
+            """When no entrypoints exist and none specified, show usage help."""
+            with runner.isolated_filesystem(temp_dir=temp_dir):
+                mock_factory = _make_mock_factory([])
+
+                with (
+                    patch(
+                        "uipath._cli.cli_run.Middlewares.next",
+                        return_value=_middleware_continue(),
+                    ),
+                    patch(
+                        "uipath._cli.cli_run.UiPathRuntimeFactoryRegistry.get",
+                        return_value=mock_factory,
+                    ),
+                ):
+                    result = runner.invoke(cli, ["run"])
+
+                assert result.exit_code == 0
+                assert "No entrypoints found" in result.output
+                assert "Usage: uipath run" in result.output
+                mock_factory.new_runtime.assert_not_awaited()
 
         def test_script_not_found(
             self, runner: CliRunner, temp_dir: str, entrypoint: str