UiPath Runtime Python SDK

Warnings

• breaking Minor version increments for `uipath-runtime` indicate breaking changes for public interfaces not explicitly marked as beta. Always review release notes when upgrading between minor versions (e.g., from 0.x to 0.y).
  Fix: Consult the `uipath-runtime-python` GitHub repository tags and any available release notes for detailed migration guides. Adjust code to new method signatures or interface changes.
• breaking In version `0.3.0`, `UiPathDebugBridgeProtocol` was renamed to `UiPathDebugProtocol`. Methods on `UiPathResumableStorageProtocol` gained a `runtime_id` parameter, and `UiPathResumableRuntime` gained the ability to store arbitrary `(namespace, key, value)` tuples.
  Fix: Update imports and method calls to reflect the new names and signatures: `from uipath.runtime import UiPathDebugProtocol` and include `runtime_id` when calling `UiPathResumableStorageProtocol` methods. Adjust logic for `UiPathResumableRuntime` if using persistent storage.
• gotcha This `uipath-runtime` Python package is distinct from `UiPath.Python.Activities` used within UiPath Studio. While related, `uipath-runtime` focuses on programmatic creation of UiPath runtimes in Python, whereas `UiPath.Python.Activities` facilitates running Python scripts *within* UiPath Studio workflows. The latter may have additional .NET Desktop Runtime dependencies (e.g., .NET 6 or higher) and specific Python version compatibilities that do not directly apply to `uipath-runtime` itself.
  Fix: Ensure you are using the correct package for your use case. If developing custom Python runtimes, focus on `uipath-runtime`. If integrating Python scripts into UiPath Studio workflows, refer to the documentation for `UiPath.Python.Activities`.
• gotcha When building custom runtimes or agents with `uipath-runtime` that rely on external Python libraries, those dependencies must be correctly installed in the Python environment where your runtime will execute. Failure to do so will result in `ModuleNotFoundError` or other runtime exceptions.
  Fix: Manage your Python project dependencies using `pip` or `uv` (e.g., `pip install -r requirements.txt`). Ensure the deployment environment has these dependencies installed. If deploying to UiPath Cloud, follow the specific packaging and deployment guidelines for including Python dependencies (e.g., using `uipath pack` command-line tool which requires `pyproject.toml` with metadata).

Install

• pip install uipath-runtime Install latest stable version

Imports

• UiPathRuntimeProtocol

  from uipath.runtime import UiPathRuntimeProtocol

• UiPathRuntimeResult

  from uipath.runtime import UiPathRuntimeResult

• UiPathRuntimeSchema

  from uipath.runtime import UiPathRuntimeSchema

• UiPathExecuteOptions

  from uipath.runtime import UiPathExecuteOptions

• UiPathRuntimeEvent

  from uipath.runtime.events import UiPathRuntimeEvent

Quickstart

This quickstart demonstrates how to create a basic custom runtime by implementing the `UiPathRuntimeProtocol`. This protocol defines essential methods like `get_schema`, `execute`, `stream`, and `dispose` that all custom UiPath runtimes should follow.

from typing import Any, AsyncGenerator, Optional
from uipath.runtime import (
    UiPathRuntimeResult,
    UiPathRuntimeStatus,
    UiPathRuntimeSchema,
    UiPathRuntimeEvent,
    UiPathExecuteOptions,
    UiPathStreamOptions,
    UiPathRuntimeProtocol
)

class MyRuntime(UiPathRuntimeProtocol):
    """Example runtime implementing the UiPath runtime protocols."""

    async def get_schema(self) -> UiPathRuntimeSchema:
        return UiPathRuntimeSchema(
            name="MyRuntime",
            description="A sample UiPath runtime",
            input_schema={'type': 'object', 'properties': {'name': {'type': 'string'}}},
            output_schema={'type': 'object', 'properties': {'message': {'type': 'string'}}},
        )

    async def execute(
        self, input: Any, options: Optional[UiPathExecuteOptions] = None
    ) -> UiPathRuntimeResult:
        name = input.get('name', 'World')
        message = f"Hello, {name}!"
        return UiPathRuntimeResult(status=UiPathRuntimeStatus.SUCCESS, output={'message': message})

    async def stream(
        self, input: Any, options: Optional[UiPathStreamOptions] = None
    ) -> AsyncGenerator[UiPathRuntimeEvent, None]:
        yield UiPathRuntimeEvent(name='start', payload={'input': input})
        await self.execute(input, options) # Simulate execution
        yield UiPathRuntimeEvent(name='end', payload={'result': 'success'})

    async def dispose(self) -> None:
        # Clean up resources if any
        pass

# To use this runtime (e.g., in a higher-level SDK or framework):
# runtime_instance = MyRuntime()
# schema = await runtime_instance.get_schema()
# print(schema.model_dump_json(indent=2))
# result = await runtime_instance.execute({'name': 'Alice'})
# print(result.model_dump_json(indent=2))