diff --git a/packages/uipath/docs/FAQ.md b/packages/uipath/docs/FAQ.md index c1cd1aec2..602a42196 100644 --- a/packages/uipath/docs/FAQ.md +++ b/packages/uipath/docs/FAQ.md @@ -1,6 +1,6 @@ # Frequently Asked Questions (FAQ) -### Q: Why am I getting a "Failed to prepare environment" error when deploying my python agent to UiPath Cloud Platform? +### Q: Why am I getting a "Failed to prepare environment" error when deploying my Python project to UiPath Cloud Platform? #### Error Message @@ -30,7 +30,7 @@ #### Description -This error might occur when deploying coded-agents to UiPath Cloud Platform, even though the same project might work correctly in your local environment. The issue is often related to how Python packages are discovered and distributed during the cloud deployment process. +This error might occur when deploying coded functions or coded agents to UiPath Cloud Platform, even though the same project might work correctly in your local environment. The issue is often related to how Python packages are discovered and distributed during the cloud deployment process. #### Common Causes @@ -283,7 +283,7 @@ If you encounter SSL certificate errors: //// -### Q: Why are my agent runs hanging on UiPath Cloud Platform? +### Q: Why are my job runs hanging on UiPath Cloud Platform? #### Error Message @@ -298,7 +298,7 @@ You may see errors like these in the logs panel: #### Description -If your Python agent runs are hanging or not completing when deployed to UiPath Cloud Platform's serverless environment, this may be caused by a library incompatibility issue from an outdated version of the UiPath Python library. +If your Python job runs are hanging or not completing when deployed to UiPath Cloud Platform's serverless environment, this may be caused by a library incompatibility issue from an outdated version of the UiPath Python library. #### Solution diff --git a/packages/uipath/docs/cli/index.md b/packages/uipath/docs/cli/index.md index 165c5431a..f1d9e9ef0 100644 --- a/packages/uipath/docs/cli/index.md +++ b/packages/uipath/docs/cli/index.md @@ -1,5 +1,7 @@ # CLI Reference +The following commands apply to both **coded functions** and **coded agents**. The entry point name (`main`, `agent`, or any key you define in `uipath.json`) is the first argument to `run`, `debug`, `eval`, and `invoke`. + ::: mkdocs-click :module: uipath._cli :command: auth @@ -132,7 +134,7 @@ For step-by-step debugging with breakpoints and variable inspection (supported f ```console # Install debugpy package uv pip install debugpy -# Run agent with debugging enabled +# Run with debugging enabled uipath run [ENTRYPOINT] [INPUT] --debug ``` For vscode: @@ -154,19 +156,19 @@ Depending on the shell you are using, it may be necessary to escape the input js /// tab | Bash/ZSH ```console -uipath run agent '{"topic": "UiPath"}' +uipath run main '{"message": "hello"}' ``` /// /// tab | Windows CMD ```console -uipath run agent "{""topic"": ""UiPath""}" +uipath run main "{""message"": ""hello""}" ``` /// /// tab | Windows PowerShell ```console -uipath run agent '{\"topic\":\"uipath\"}' +uipath run main '{\"message\":\"hello\"}' ``` /// @@ -311,7 +313,7 @@ Selected feed: Orchestrator Tenant Processes Feed ```shell -> uipath invoke agent '{"topic": "UiPath"}' +> uipath invoke main '{"message": "hello"}' ⠴ Loading configuration ... ⠴ Starting job ... ✨ Job started successfully! @@ -379,7 +381,7 @@ File 'uipath.json' is up to date :depth: 1 :style: table -Runs your agent under the debug runtime, with a debug bridge attached. Locally, the bridge is the interactive **console** (read commands from stdin, stop at breakpoints). In the cloud, the bridge is **SignalR** (driven by Studio Web / Orchestrator). The `--attach` flag lets you override that default, including `none` for executors that need the debug command's surrounding behavior (bindings fetch, state streaming) but cannot speak the interactive debug protocol. +Runs your project under the debug runtime, with a debug bridge attached. Locally, the bridge is the interactive **console** (read commands from stdin, stop at breakpoints). In the cloud, the bridge is **SignalR** (driven by Studio Web / Orchestrator). The `--attach` flag lets you override that default, including `none` for executors that need the debug command's surrounding behavior (bindings fetch, state streaming) but cannot speak the interactive debug protocol. ### Attach modes @@ -426,7 +428,7 @@ Next: analyze_sentiment :depth: 1 :style: table -Runs an evaluation set against your agent. Entry point and eval set are auto-discovered from the project if not passed explicitly. Evaluations run in parallel (see `--workers`) and, unless `--no-report` is passed, results are reported back to Studio Web when `UIPATH_PROJECT_ID` is set. +Runs an evaluation set against your project. Entry point and eval set are auto-discovered from the project if not passed explicitly. Evaluations run in parallel (see `--workers`) and, unless `--no-report` is passed, results are reported back to Studio Web when `UIPATH_PROJECT_ID` is set. ### Common flags diff --git a/packages/uipath/docs/core/agents.md b/packages/uipath/docs/core/agents.md new file mode 100644 index 000000000..5076d43b6 --- /dev/null +++ b/packages/uipath/docs/core/agents.md @@ -0,0 +1,245 @@ +# Python Coded Agents + +A coded agent is Python code that uses an LLM reasoning loop to make decisions, call tools, and produce a result. You write the agent logic using a framework of your choice — the `uipath` SDK provides the platform layer: authentication, assets, buckets, connections, tracing, and human-in-the-loop. Package it with the CLI and deploy it as an Orchestrator job. + +Use a coded agent when your automation needs multi-step reasoning, dynamic tool selection, or LLM-driven decisions. Use a [coded function](./functions.md) when your logic is deterministic and no LLM is required. + +--- + +## Architecture + +Every coded agent is built from two layers: + +| Layer | Package | Responsibility | +|-------|---------|---------------| +| **Platform** | `uipath` | Auth, assets, buckets, connections, tracing, human-in-the-loop, CLI, packaging | +| **Framework** | one extension (see below) | LLM calls, tool routing, agent loop, memory | + +The `uipath` package is always required. Add one framework extension on top: + +| Framework | Package | Best for | +|-----------|---------|---------| +| LangChain / LangGraph | `uipath-langchain` | Graph-based agents, complex multi-step flows | +| LlamaIndex | `uipath-llamaindex` | RAG-heavy agents, document reasoning | +| OpenAI Agents SDK | `uipath-openai-agents` | OpenAI-native tool use, handoffs | +| PydanticAI | `uipath-pydantic-ai` | Type-safe agents with Pydantic models | +| Google ADK | `uipath-google-adk` | Gemini models, Google ecosystem | +| UiPath Agent Framework | `uipath-agent-framework` | UiPath-native agent primitives | + +--- + +## Quickstart + +The example below uses LangChain. Swap `uipath-langchain` for the framework of your choice. + +//// tab | uv + + + +```shell +> mkdir my-agent && cd my-agent +> uv init . --python 3.11 +> uv add uipath uipath-langchain + +> uipath auth +⠋ Authenticating with UiPath ... +✓ Authentication successful. + +> uipath new agent +✓ Created new agent project. + +> uipath init +⠋ Initializing UiPath project ... +✓ Created 'entry-points.json' file. +✓ Created 'bindings.json' file. + +> uipath run agent '{"message": "hello"}' +``` + +//// + +//// tab | pip + + + +```shell +> mkdir my-agent && cd my-agent +> python -m venv .venv +> source .venv/bin/activate +> pip install uipath uipath-langchain + +> uipath auth +⠋ Authenticating with UiPath ... +✓ Authentication successful. + +> uipath new agent +✓ Created new agent project. + +> uipath init +⠋ Initializing UiPath project ... +✓ Created 'entry-points.json' file. +✓ Created 'bindings.json' file. + +> uipath run agent '{"message": "hello"}' +``` + +//// + +--- + +## Project Structure + +``` +my-agent/ +├── main.py # agent logic +├── pyproject.toml # project metadata and dependencies +├── uipath.json # entry point declarations +├── entry-points.json # generated — I/O JSON Schema +└── bindings.json # generated — resource binding overrides +``` + +### `uipath.json` + +```json +{ + "agents": { + "agent": "main.py:agent" + } +} +``` + +### `pyproject.toml` + +```toml +[project] +name = "my-agent" +version = "0.1.0" +description = "..." +authors = [{ name = "Your Name", email = "you@example.com" }] +requires-python = ">=3.11" +dependencies = ["uipath>=2.0", "uipath-langchain>=2.0"] + +[tool.uipath] +type = "agent" +``` + +`[tool.uipath] type = "agent"` is required — it identifies the project as an agent to the runtime and packaging tools. + +--- + +## Input & Output + +Define `Input` and `Output` as Python dataclasses, the same way as [coded functions](./functions.md#input--output): + +```python +from dataclasses import dataclass + + +@dataclass +class Input: + message: str + + +@dataclass +class Output: + response: str + + +def agent(input: Input) -> Output: + ... +``` + +--- + +## Platform Services + +The `uipath` SDK gives your agent access to Orchestrator resources at runtime — credentials are injected automatically when running as a job. + +```python +from uipath.platform import UiPath + +sdk = UiPath() +``` + +The full set of Orchestrator services is available to agents: + +- **Assets** — read credentials and configuration: [Assets reference](./assets.md) +- **Buckets** — download and upload files: [Buckets reference](./buckets.md) +- **Connections** — Integration Service connections for ERP and SaaS: [Connections reference](./connections.md) +- **Context Grounding** — semantic search over enterprise data: [Context Grounding reference](./context_grounding.md) + +--- + +## Tracing + +Apply `@traced` to custom steps inside your agent to make them visible in the Orchestrator job trace view and Maestro dashboards. Do **not** trace the entry point — the runtime wraps it automatically. + +```python +from uipath.tracing import traced + + +@traced(name="lookup_vendor", run_type="uipath") +def lookup_vendor(vendor_id: str) -> dict: + ... +``` + +See [Tracing](./traced.md) for the full decorator reference. + +--- + +## Framework Guides + +Each framework extension has its own getting started guide and sample agents: + +| Framework | Guide | Samples | +|-----------|-------|---------| +| LangChain / LangGraph | [Get Started](../langchain/quick_start.md) | [Samples](https://github.com/UiPath/uipath-langchain-python/tree/main/samples) | +| LlamaIndex | [Get Started](../llamaindex/quick_start.md) | [Samples](https://github.com/UiPath/uipath-integrations-python/tree/main/packages/uipath-llamaindex/samples) | +| OpenAI Agents SDK | [Get Started](../openai-agents/quick_start.md) | [Samples](https://github.com/UiPath/uipath-integrations-python/tree/main/packages/uipath-openai-agents/samples) | +| PydanticAI | [README](https://github.com/UiPath/uipath-integrations-python/blob/main/packages/uipath-pydantic-ai/README.md) | [Samples](https://github.com/UiPath/uipath-integrations-python/tree/main/packages/uipath-pydantic-ai/samples) | +| Google ADK | [README](https://github.com/UiPath/uipath-integrations-python/blob/main/packages/uipath-google-adk/README.md) | [Samples](https://github.com/UiPath/uipath-integrations-python/tree/main/packages/uipath-google-adk/samples) | +| UiPath Agent Framework | [README](https://github.com/UiPath/uipath-integrations-python/blob/main/packages/uipath-agent-framework/README.md) | [Samples](https://github.com/UiPath/uipath-integrations-python/tree/main/packages/uipath-agent-framework/samples) | + + +--- + +## Pack & Publish + +The same CLI workflow applies as for coded functions: + + + +```shell +> uipath pack +⠋ Packaging project ... +Name : my-agent +Version : 0.1.0 +Description: Add your description here +Authors : Your Name +✓ Project successfully packaged. + +> uipath publish +⠋ Fetching available package feeds... +Select feed number: 0 +✓ Package published successfully! +``` + +After publishing, the agent registers as an Orchestrator Process and can be invoked from Maestro, the Orchestrator API, or the CLI. + +See [CLI Reference](../cli/index.md) for full `pack`, `publish`, and `invoke` options. + +--- + +## Studio Web Integration + +Connect your agent to a Studio Web solution for cloud debugging, evaluation, and solution packaging. + +See [Studio Web Integration](./studio_web.md) for setup and sync details. + +--- + +## Evaluations + +Coded agents support evaluations in Studio Web and locally via `uipath eval`. Evaluators cover LLM output quality, tool call correctness, and trajectory analysis. + +See the [Evaluations documentation](../eval/index.md) for available evaluators and how to define evaluation sets. diff --git a/packages/uipath/docs/core/assets/maestro_execution_trace_light.png b/packages/uipath/docs/core/assets/maestro_execution_trace_light.png new file mode 100644 index 000000000..d3d364168 Binary files /dev/null and b/packages/uipath/docs/core/assets/maestro_execution_trace_light.png differ diff --git a/packages/uipath/docs/core/assets/maestro_service_task_light.png b/packages/uipath/docs/core/assets/maestro_service_task_light.png new file mode 100644 index 000000000..314cb383e Binary files /dev/null and b/packages/uipath/docs/core/assets/maestro_service_task_light.png differ diff --git a/packages/uipath/docs/core/assets/orchestrator_processes_light.png b/packages/uipath/docs/core/assets/orchestrator_processes_light.png new file mode 100644 index 000000000..9b17f72cf Binary files /dev/null and b/packages/uipath/docs/core/assets/orchestrator_processes_light.png differ diff --git a/packages/uipath/docs/core/assets/studio_web_select_function_dark.png b/packages/uipath/docs/core/assets/studio_web_select_function_dark.png new file mode 100644 index 000000000..68a66fc92 Binary files /dev/null and b/packages/uipath/docs/core/assets/studio_web_select_function_dark.png differ diff --git a/packages/uipath/docs/core/assets/studio_web_select_function_light.png b/packages/uipath/docs/core/assets/studio_web_select_function_light.png new file mode 100644 index 000000000..617e30c2f Binary files /dev/null and b/packages/uipath/docs/core/assets/studio_web_select_function_light.png differ diff --git a/packages/uipath/docs/core/environment_variables.md b/packages/uipath/docs/core/environment_variables.md index 6c88d3532..bcf1bcc8b 100644 --- a/packages/uipath/docs/core/environment_variables.md +++ b/packages/uipath/docs/core/environment_variables.md @@ -17,12 +17,12 @@ UIPATH_FOLDER_PATH=/default/path export UIPATH_FOLDER_PATH=/system/path ``` /// warning -When deploying your agent to production, ensure that all required environment variables (such as API keys and custom configurations) are properly configured in your process settings. This step is crucial for the successful operation of your published package. +When deploying your project to production, ensure that all required environment variables (such as API keys and custom configurations) are properly configured in your process settings. This step is crucial for the successful operation of your published package. /// ## Design -Create a `.env` file in your project's root directory to manage environment variables locally. When using the `uipath auth` or `uipath new my-agent` commands, this file is automatically created. +Create a `.env` file in your project's root directory to manage environment variables locally. When using the `uipath auth` or `uipath new` commands, this file is automatically created. The `uipath auth` command automatically populates this file with essential variables: diff --git a/packages/uipath/docs/core/functions.md b/packages/uipath/docs/core/functions.md new file mode 100644 index 000000000..cdcabb594 --- /dev/null +++ b/packages/uipath/docs/core/functions.md @@ -0,0 +1,423 @@ +# Python Coded Functions + +A coded function is Python code with typed input and output that runs as an Orchestrator job. You write plain Python — no agent framework, no LLM required — package it with the CLI, and invoke it from Maestro processes, Coded Apps, or any UiPath job trigger. + +Use coded functions for deterministic compute steps: document extraction, ERP writes, data validation, external API calls. Use a [coded agent](./agents.md) when your logic needs an LLM decision loop or a multi-step reasoning chain. + +--- + +## Quickstart + +//// tab | uv + + + +```shell +> mkdir my-function && cd my-function +> uv init . --python 3.11 +> uv add uipath + +> uipath auth +⠋ Authenticating with UiPath ... +✓ Authentication successful. + +> uipath new my-function +✓ Created 'main.py' file. +✓ Created 'pyproject.toml' file. +✓ Created 'uipath.json' file. + +> uipath init +⠋ Initializing UiPath project ... +✓ Created 'entry-points.json' file. +✓ Created 'bindings.json' file. + +> uipath run main '{"message": "hello"}' +{"message": "hello"} +``` + +//// + +//// tab | pip + + + +```shell +> mkdir my-function && cd my-function +> python -m venv .venv +> source .venv/bin/activate +> pip install uipath + +> uipath auth +⠋ Authenticating with UiPath ... +✓ Authentication successful. + +> uipath new my-function +✓ Created 'main.py' file. +✓ Created 'pyproject.toml' file. +✓ Created 'uipath.json' file. + +> uipath init +⠋ Initializing UiPath project ... +✓ Created 'entry-points.json' file. +✓ Created 'bindings.json' file. + +> uipath run main '{"message": "hello"}' +{"message": "hello"} +``` + +//// + +--- + +## Project Structure + +``` +my-function/ +├── main.py # function logic +├── pyproject.toml # project metadata and dependencies +├── uipath.json # entry point declarations +├── entry-points.json # generated — I/O JSON Schema +└── bindings.json # generated — resource binding overrides +``` + +### `uipath.json` + +Declares which Python functions are callable entry points: + +```json +{ + "functions": { + "main": "main.py:main" + } +} +``` + +The key (`"main"`) is the entry point name used in CLI commands. The value (`"main.py:main"`) is `:`. + +### `pyproject.toml` + +```toml +[project] +name = "my-function" +version = "0.1.0" +description = "..." +authors = [{ name = "Your Name", email = "you@example.com" }] +requires-python = ">=3.11" +dependencies = ["uipath>=2.0"] + +[tool.uipath] +type = "function" +``` + +`[tool.uipath] type = "function"` is required — it identifies the project as a function to the runtime and packaging tools. + +### Generated files + +| File | Purpose | +|------|---------| +| `entry-points.json` | Input/output JSON Schema derived from your dataclasses — used by Maestro for variable binding | +| `bindings.json` | Resource binding overrides (assets, connections, buckets) for local development | + +/// warning +`uipath init` executes `main.py` to derive the I/O schema. Re-run it after every change to your `Input` or `Output` dataclasses. +/// + +--- + +## Input & Output + +Define `Input` and `Output` as Python dataclasses. The runtime validates against these at invocation time and exports them as JSON Schema for Maestro variable binding. + +```python +from dataclasses import dataclass, field +from typing import Any + + +@dataclass +class Input: + document_id: str = "" + amount: float = 0.0 + + +@dataclass +class Output: + result_id: str = "" + status: str = "" + error_type: str = "" + error_message: str = "" + + +def main(input: Input) -> Output: + ... +``` + +### Supported types + +| Python type | Notes | +|-------------|-------| +| `str`, `int`, `float`, `bool` | Primitives | +| `list[str]`, `list[dict]` | Arrays | +| `dict[str, Any]` | Freeform object | +| Nested `@dataclass` | Becomes a nested JSON object | +| `X \| None`, `Optional[X]` | Nullable field | + +### Error output pattern + +Return business errors as typed output fields rather than raising exceptions. This lets Maestro inspect the error reason and route the process accordingly: + +```python +@dataclass +class Output: + bill_id: str = "" + error_type: str = "" # e.g. "VENDOR_NOT_FOUND", "VALIDATION_ERROR" + error_message: str = "" # human-readable detail + + +def main(input: Input) -> Output: + try: + bill_id = create_vendor_bill(input) + return Output(bill_id=bill_id) + except VendorNotFoundError as exc: + return Output(error_type="VENDOR_NOT_FOUND", error_message=str(exc)) + except Exception as exc: + return Output(error_type="FAILED", error_message=str(exc)) +``` + +Reserve `raise` for unrecoverable infrastructure failures (network timeout, authentication error) that should mark the Orchestrator job as faulted. + +--- + +## Platform Services + +`UiPath()` gives your function access to Orchestrator resources at runtime. Credentials are injected automatically when running as a job — no configuration needed. + +```python +from uipath.platform import UiPath + +sdk = UiPath() +``` + +### Assets + +Read credential and configuration values stored in Orchestrator: + +```python +# String asset +asset = sdk.assets.retrieve("API_BASE_URL", folder_path="Shared") +base_url = str(asset.string_value or "") + +# Credential asset +creds = sdk.assets.retrieve("ERP_CREDENTIALS", folder_path="Shared") +username = str(creds.credential_username or "") +password = str(creds.credential_password or "") +``` + +See [Assets](./assets.md) for the full API reference. + +### Buckets + +Download and upload files: + +```python +# Download +sdk.buckets.download( + name="Invoices", + blob_file_path="incoming/acme-001.pdf", + destination_path="/tmp/acme-001.pdf", + folder_path="Shared", +) + +# Upload +sdk.buckets.upload( + name="Processed", + blob_file_path="results/acme-001-result.json", + content_file_path="/tmp/result.json", + folder_path="Shared", +) +``` + +See [Buckets](./buckets.md) for the full API reference. + +### Connections + +Access Integration Service connections for ERP and SaaS systems: + +```python +from uipath.platform.connections.connections import ActivityMetadata, ActivityParameterLocationInfo + +conn = sdk.connections.retrieve("your-connection-id") + +result = sdk.connections.invoke_activity( + activity_metadata=ActivityMetadata( + object_path="/your-endpoint", + method_name="POST", + content_type="application/json", + parameter_location_info=ActivityParameterLocationInfo(body_fields=["query"]), + ), + connection_id="your-connection-id", + activity_input={"query": "SELECT id FROM records LIMIT 10"}, +) +``` + +See [Connections](./connections.md) for the full API reference. + +--- + +## Tracing + +Use `@traced` to make individual steps visible as spans in the Orchestrator job trace view and Maestro dashboards. + +```python +from uipath.tracing import traced + + +@traced(name="fetch_document", run_type="uipath") +def fetch_document(document_id: str) -> bytes: + ... + + +@traced(name="extract_fields", run_type="uipath") +def extract_fields(content: bytes) -> dict: + ... + + +@traced(name="post_to_erp", run_type="uipath") +def post_to_erp(data: dict) -> str: + ... + + +def main(input: Input) -> Output: # entry point — NOT traced + content = fetch_document(input.document_id) + data = extract_fields(content) + result_id = post_to_erp(data) + return Output(result_id=result_id) +``` + +/// warning +Do not apply `@traced` to the entry point function. The Orchestrator runtime wraps the entire job in its own span — adding a second trace on the entry point creates a duplicate outer span. +/// + +Use `hide_input=True` or `hide_output=True` to redact sensitive data from trace storage: + +```python +@traced(name="get_api_token", run_type="uipath", hide_input=True, hide_output=True) +def get_api_token(client_id: str, client_secret: str) -> str: + ... +``` + + + Maestro execution trail showing @traced sub-step spans (assets_retrieve, ixp_digitize, netsuite_get_vendor, etc.) with durations and parent-child nesting under a Service Task + + +See [Tracing](./traced.md) for the full decorator reference. + +--- + +## Multiple Entry Points + +One project can expose several callable functions, each with its own `Input`/`Output`. Define them in `uipath.json`: + +```json +{ + "functions": { + "extract": "main.py:extract_data", + "validate": "main.py:validate_data", + "post_erp": "main.py:post_to_erp" + } +} +``` + +Run `uipath init` after adding new entry points. Each can be invoked independently: + + + +```shell +> uipath run extract '{"document_id": "invoice-001.pdf"}' +> uipath run validate '{"vendor_name": "Acme", "total": 1234.56}' +> uipath run post_erp '{"bill_id": "12345"}' +``` + +Each entry point publishes as a separate invocable function in Orchestrator. + +--- + +## Idempotency + +Functions may be retried by Maestro after a transient failure. Always check for an existing result before writing to an external system: + +```python +@traced(name="find_existing", run_type="uipath") +def find_existing(invoice_number: str) -> str | None: + # query external system by stable business key + ... + + +def main(input: Input) -> Output: + existing_id = find_existing(input.invoice_number) + if existing_id: + return Output(result_id=existing_id, status="Already Processed") + + result_id = create_record(input) + return Output(result_id=result_id, status="Created") +``` + +Use a stable, business-meaningful identifier (invoice number, order ID) as the idempotency key — avoid auto-generated IDs that don't exist before the first write. + +--- + +## Pack & Publish + + + +```shell +> uipath pack +⠋ Packaging project ... +Name : my-function +Version : 0.1.0 +Description: ... +Authors : Your Name +✓ Project successfully packaged. + +> uipath publish +⠋ Fetching available package feeds... +👇 Select package feed: + 0: Orchestrator Tenant Processes Feed + 1: Orchestrator Personal Workspace Feed +Select feed number: 0 +✓ Package published successfully! +``` + +After publishing, the function registers as an **Orchestrator Process**. It can then be: + +- Invoked as a **Maestro Service Task** — Maestro binds typed input/output to process variables automatically from the exported JSON Schema +- Triggered via the **Orchestrator API** (`POST /Jobs/StartJobs`) +- Run from the CLI: `uipath invoke main '{"..."}'` +- Started from a **Studio workflow** using the **Run Job** activity + + + Coded functions published as Function (python) type in the Orchestrator Processes list + + + Coded function wired as a Maestro Service Task with typed input/output variable binding + + +See [CLI Reference](../cli/index.md) for full `pack`, `publish`, and `invoke` options. + +--- + +## Studio Web Integration + +Connect your function to a Studio Web solution for cloud debugging or solution packaging: + + + +```shell +> uipath push +Pushing UiPath project to Studio Web... +Uploading 'main.py' +Uploading 'uipath.json' +Updating 'pyproject.toml' +✓ Project pushed successfully +``` + +See [Studio Web Integration](./studio_web.md) for setup and sync details. diff --git a/packages/uipath/docs/core/getting_started.md b/packages/uipath/docs/core/getting_started.md index 6c00b0089..50da82107 100644 --- a/packages/uipath/docs/core/getting_started.md +++ b/packages/uipath/docs/core/getting_started.md @@ -114,6 +114,10 @@ Upon successful authentication, your project will contain a `.env` file with you ### Writing Your Code +/// tip +This walkthrough creates a **coded function** — plain Python with typed input and output, no LLM required. For a complete reference including platform services, tracing, idempotency, and Maestro integration, see [Python Coded Functions](./functions.md). +/// + Open `main.py` in your code editor. You can start with this example code: ```python from dataclasses import dataclass diff --git a/packages/uipath/docs/core/studio_web.md b/packages/uipath/docs/core/studio_web.md index 762735e48..30bb497df 100644 --- a/packages/uipath/docs/core/studio_web.md +++ b/packages/uipath/docs/core/studio_web.md @@ -1,9 +1,9 @@ # Studio Web Integration -[Studio Web](https://docs.uipath.com/studio-web/automation-cloud/latest/user-guide/overview) is a cloud IDE for building projects such as RPAs, low code agents, and API workflows. It also supports importing coded agents built locally. Bringing your coded agent into Studio Web gives you: +[Studio Web](https://docs.uipath.com/studio-web/automation-cloud/latest/user-guide/overview) is a cloud IDE for building projects such as RPAs, low code agents, and API workflows. It also supports importing coded agents and coded functions built locally. Bringing your project into Studio Web gives you: - Cloud debugging with dynamic breakpoints -- Running and defining evaluations directly in the cloud +- Running and defining evaluations directly in the cloud (coded agents only) - A unified build experience alongside multiple project types - Self contained solution deployment units @@ -16,11 +16,11 @@ /> Coded agent in Studio Web -There are two ways to connect a coded agent to Studio Web: using a [Cloud Workspace](#cloud-workspace) or a [Local Workspace](#local-workspace). +There are two ways to connect your project to Studio Web: using a [Cloud Workspace](#cloud-workspace) or a [Local Workspace](#local-workspace). --- @@ -28,10 +28,14 @@ There are two ways to connect a coded agent to Studio Web: using a [Cloud Worksp In a Cloud Workspace, your project lives in Studio Web and you sync code between your local IDE and the cloud. -### Importing a Coded Agent +### Importing a Coded Agent or Coded Function 1. Open your solution in Studio Web -2. Create a new Agent and select **Coded** +2. Create the project: + + //// tab | Agent + + Create a new Agent and select **Coded**: -3. Choose a sample project to start from, or push an existing local agent + //// -### Pushing an Existing Agent + //// tab | Function -If you already have a coded agent locally, you can sync it to Studio Web: + Use the **Initial setup screen** to get started: -1. Copy the `UIPATH_PROJECT_ID` from Studio Web into your `.env` file - - + + //// + +3. Choose a sample project to start from, or push an existing local project + +### Pushing an Existing Project + +If you already have a project locally, you can sync it to Studio Web: + +1. Copy the `UIPATH_PROJECT_ID` from Studio Web into your `.env` file + + + + + + 2. Push your project: + ```shell > uipath push Pushing UiPath project to Studio Web... @@ -79,7 +104,7 @@ If you already have a coded agent locally, you can sync it to Studio Web: 🔵 Resource import summary: 3 total resources - 1 created, 1 updated, 1 unchanged, 0 not found ``` - Notice the **Resource import summary** at the end. The push command also imports resources defined in `bindings.json` into the Studio Web solution, just like importing resources for a low code agent. This ensures that all required resources are packaged with the solution, so the coded agent works anywhere the solution is deployed. + Notice the **Resource import summary** at the end. The push command also imports resources defined in `bindings.json` into the Studio Web solution, just like importing resources for a low code agent. This ensures that all required resources are packaged with the solution, so the project works anywhere the solution is deployed. See [`uipath push`](../cli/index.md) in the CLI Reference. @@ -88,6 +113,7 @@ If you already have a coded agent locally, you can sync it to Studio Web: To pull the latest version from Studio Web to your local environment: + ```shell > uipath pull Pulling UiPath project from Studio Web... @@ -116,21 +142,24 @@ See [`uipath pull`](../cli/index.md) in the CLI Reference. In a Local Workspace, your project lives on your machine and is linked to a Studio Web solution. See the [Local Workspace documentation](https://docs.uipath.com/studio-web/automation-cloud/latest/user-guide/solutions-in-the-local-workspace) for setup details. -You can either start from a predefined template in Studio Web or set up a new agent from scratch. +You can either start from a predefined template in Studio Web or set up a new project from scratch. ### Starting from a Template -When creating a new Coded agent in Studio Web with a Local Workspace, you can pick one of the predefined templates. This creates the project files directly on your machine. Templates come with sample code and predefined evaluations you can run immediately. +When creating a new coded agent or coded function in Studio Web with a Local Workspace, you can pick one of the predefined templates. This creates the project files directly on your machine. Templates come with sample code and predefined evaluations you can run immediately. -### Setting Up a New Agent +### Setting Up a New Project -You can also create a coded agent from scratch in your local IDE and have it appear in Studio Web. +You can also create a project from scratch in your local IDE and have it appear in Studio Web. + +#### Coded Agent First, install the SDK package for the framework you want to use: //// tab | uv + ```shell # Pick the package that matches your framework: # uipath-langchain - LangChain / LangGraph @@ -149,6 +178,7 @@ Installed 42 packages in 0.8s //// tab | pip + ```shell # Pick the package that matches your framework: # uipath-langchain - LangChain / LangGraph @@ -166,6 +196,7 @@ Successfully installed uipath-langchain Then authenticate, scaffold the agent, and initialize the project: + ```shell > uipath auth ⠋ Authenticating with UiPath ... @@ -187,57 +218,133 @@ Selected tenant: Tenant1 That's it, your agent should now be visible in Studio Web. +#### Coded Function + +A coded function doesn't require an additional framework package. Authenticate, scaffold the project, and initialize it: + + + +```shell +> uipath auth +⠋ Authenticating with UiPath ... +🔗 If a browser window did not open, please open the following URL in your browser: [LINK] +👇 Select tenant: + 0: Tenant1 + 1: Tenant2 +Select tenant number: 0 +Selected tenant: Tenant1 +✓ Authentication successful. + +> uipath new my-function +✓ Created 'main.py' file. +✓ Created 'pyproject.toml' file. +✓ Created 'uipath.json' file. + +> uipath init +⠋ Initializing UiPath project ... +✓ Created 'entry-points.json' file. +``` + +That's it, your coded function should now be visible in Studio Web. + --- ## Publishing -Once your coded agent is in Studio Web, publishing works the same as any other project. Click **Publish** in Studio Web and it will be packaged and deployed through the standard workflow. +Once your project is in Studio Web, publishing works the same as any other project. Click **Publish** in Studio Web and it will be packaged and deployed through the standard workflow. --- ## Running and Debugging -Your agent can be run both in the cloud (via Studio Web) and locally using the CLI. +Your project can be run both in the cloud (via Studio Web) and locally using the CLI. + +The CLI commands below take the entrypoint name as the first argument. For a coded agent, this is the graph name declared in your framework's config (for example, `agent` in `langgraph.json`). For a coded function, this is the key declared in the `functions` map of `uipath.json` (for example, `main`). ### Running Locally +//// tab | Agent + + ```shell > uipath run agent '{"message": "hello"}' ``` +//// + +//// tab | Function + + + +```shell +> uipath run main '{"message": "hello"}' +``` + +//// + See [`uipath run`](../cli/index.md) in the CLI Reference. ### Debugging Locally Use `uipath debug` for an enhanced local debugging experience. Unlike `uipath run`, the debug command: -- Auto polls for trigger responses when the agent suspends (e.g., LangGraph interrupts) +- Auto polls for trigger responses when the project suspends (e.g., LangGraph interrupts) - Fetches binding overwrites from Studio Web (configurable in **Debug > Debug Configuration > Solution resources**) +//// tab | Agent + + ```shell > uipath debug agent '{"message": "hello"}' ``` +//// + +//// tab | Function + + + +```shell +> uipath debug main '{"message": "hello"}' +``` + +//// + See [`uipath debug`](../cli/index.md) in the CLI Reference. ### Evaluating Locally -Run evaluations against your agent using the CLI: +Run evaluations against your project using the CLI: + +//// tab | Agent + ```shell > uipath eval agent .\evaluations\eval-sets\faithfulness-multi-model.json ``` +//// + +//// tab | Function + + + +```shell +> uipath eval main .\evaluations\eval-sets\default.json +``` + +//// + See [`uipath eval`](../cli/index.md) in the CLI Reference and the [Evaluations documentation](../eval/index.md). --- ## Syncing Evaluations -Evaluations can be defined either in Studio Web or locally. They sync automatically when you use `uipath pull` and `uipath push`. +Evaluations can be defined either in Studio Web or locally, and sync automatically when you use `uipath pull` and `uipath push`. Defining and running evaluations in Studio Web is supported for coded agents only; coded functions can still be evaluated locally with `uipath eval`. /// note Custom evaluators must be created locally. See [Custom Evaluators](../eval/custom_evaluators.md) for details. diff --git a/packages/uipath/docs/core/traced.md b/packages/uipath/docs/core/traced.md index da8dbc5dc..195e5751a 100644 --- a/packages/uipath/docs/core/traced.md +++ b/packages/uipath/docs/core/traced.md @@ -71,9 +71,47 @@ def sensitive_operation(secret): - Regular functions (sync/async) - Generator functions (sync/async) -## Example with plain python agents +## Example with coded functions -When used with plain python agents please call `wait_for_tracers()` at the end of the script to ensure all traces are sent, if this is not called the agent could end without sending all the traces. +Apply `@traced` to individual steps inside your function. Do **not** trace the entry point — the Orchestrator runtime wraps the job execution in its own span, so decorating the entry point creates a duplicate outer span. + +```python hl_lines="4 9 14" +from uipath.tracing import traced + + +@traced(name="fetch_document", run_type="uipath") +def fetch_document(document_id: str) -> bytes: + ... + + +@traced(name="extract_fields", run_type="uipath") +def extract_fields(content: bytes) -> dict: + ... + + +@traced(name="post_to_erp", run_type="uipath") +def post_to_erp(data: dict) -> str: + ... + + +def main(input: Input) -> Output: # entry point — NOT traced + content = fetch_document(input.document_id) + data = extract_fields(content) + result_id = post_to_erp(data) + return Output(result_id=result_id) +``` + +Use `hide_input=True` or `hide_output=True` on steps that handle credentials or PII: + +```python hl_lines="1" +@traced(name="get_api_token", run_type="uipath", hide_input=True, hide_output=True) +def get_api_token(client_id: str, client_secret: str) -> str: + ... +``` + +## Example with plain python scripts + +When used outside the Orchestrator runtime (e.g. a standalone script), call `wait_for_tracers()` at the end to ensure all traces are flushed before the process exits. ```python hl_lines="3 8" diff --git a/packages/uipath/docs/index.md b/packages/uipath/docs/index.md index 231add0ca..7ec047397 100644 --- a/packages/uipath/docs/index.md +++ b/packages/uipath/docs/index.md @@ -11,29 +11,32 @@ title: Getting Started [See Details](./core/release_notes.md) +

What do you want to build?

+
-- __UiPath SDK__ +- __Python Coded Functions__ --- - Code with full UiPath context to build custom automations and agents from the ground up. + Deterministic Python automation with typed input/output. No LLM required. Runs as an Orchestrator job, invokable from Maestro, Studio, or the CLI. - [Start Building](./core/getting_started.md) + **Requires:** `uipath` -
+ [Build a Function](./core/functions.md) -
-- __UiPath MCP SDK__ +- __Python Coded Agents__ --- - Build and host Coded MCP Servers within UiPath. + AI-driven automation with LLM reasoning loops. Uses the `uipath` SDK for platform services plus a framework extension of your choice. - [Start Building](./mcp/quick_start.md) + **Requires:** `uipath` + one of the extensions below + + [Build an Agent](./core/agents.md)
-

Extensions

+

Agent Framework Extensions

- __UiPath Langchain SDK__ @@ -60,3 +63,15 @@ title: Getting Started [Get Started](./openai-agents/quick_start.md)
+ +

Other SDKs

+
+- __UiPath MCP SDK__ + + --- + + Build and host Coded MCP Servers within UiPath. + + [Start Building](./mcp/quick_start.md) + +
diff --git a/packages/uipath/mkdocs.yml b/packages/uipath/mkdocs.yml index abffe1161..abb59448d 100644 --- a/packages/uipath/mkdocs.yml +++ b/packages/uipath/mkdocs.yml @@ -56,11 +56,13 @@ nav: - Home: index.md - UiPath SDK: - Getting Started: core/getting_started.md - - Release Notes: core/release_notes.md - - Environment Variables: core/environment_variables.md + - Python Coded Functions: core/functions.md + - Python Coded Agents: core/agents.md - CLI Reference: cli/index.md - Tracing: core/traced.md - Studio Web Integration: core/studio_web.md + - Environment Variables: core/environment_variables.md + - Release Notes: core/release_notes.md - Services: - Assets: core/assets.md - Attachments: core/attachments.md