Building Python functions

A Python function has three parts: a typed input, a typed output, and an entry-point function that maps one to the other. This page covers each, plus error handling and exposing multiple functions from one project.

Typed input and output

Define Input and Output as typed Python. Use pydantic.dataclasses.dataclass — what the SDK samples use — so the runtime validates the incoming payload and exports a clean JSON Schema, including for optional, nested, and self-referencing fields. A pydantic BaseModel behaves the same way; a stdlib @dataclass is also accepted and is fine for simple, flat input, but it performs no validation and exports less complete schemas for complex types. Every invocation surface renders that exported schema to bind variables — a Maestro Service Task, an Orchestrator Run Job, or Studio's Run Job activity. The entry point can be a sync def or an async def — both are supported.

from pydantic.dataclasses import dataclass


@dataclass
class Input:
    document_id: str = ""
    amount: float = 0.0


@dataclass
class Output:
    result_id: str = ""
    status: str = ""


def main(input: Input) -> Output:
    # business logic
    return Output(result_id="123", status="success")

Supported types

• Primitives: str, int, float, bool
• Arrays: list[str], list[dict]
• Nested dataclasses or pydantic models
• Nullable fields: Optional[X]

Give fields default values so the schema is generated cleanly and the function is easy to invoke with partial input.

Points d’entrée

The uipath.json file declares which functions are callable:

{
  "functions": {
    "main": "main.py:main"
  }
}

Multiple entry points

A single project can expose several functions. List each one in uipath.json:

{
  "functions": {
    "extract": "main.py:extract_data",
    "validate": "main.py:validate_data",
    "post_erp": "main.py:post_to_erp"
  }
}

Run uipath init after adding entry points to regenerate the input/output schemas.

Gestion des erreurs

A function can signal a business error in two ways. Both are supported — choose based on how the calling process handles failures:

• Return it in the output. Add fields such as a status flag or an error_message to your Output. The job completes successfully, and the caller — for example, a Maestro process — branches on those fields.
• Raise an exception. The job faults with a USER-category error and your exception message is preserved in the fault, so the caller can handle it upstream — for example, with a boundary event in a Maestro process.

To return an error in the output, add the fields you need and populate them on the failure path:

from pydantic.dataclasses import dataclass


@dataclass
class Output:
    result_id: str = ""
    status: str = ""
    error_type: str = ""
    error_message: str = ""


def main(input: Input) -> Output:
    try:
        result = process_data(input)
        return Output(result_id=result, status="success")
    except ValidationError as exc:
        return Output(status="error", error_type="VALIDATION_ERROR", error_message=str(exc))

Catch only the exceptions you can describe meaningfully. Let unexpected errors propagate so the job faults — that surfaces them in Orchestrator job history with the original message intact.

Prochaines étapes

• Access platform services — read assets and files at runtime.
• Tracing and observability — make execution steps visible in traces.