diff --git a/CODEOWNERS b/CODEOWNERS index 12944016d2..2a387b7a57 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -28,6 +28,7 @@ /skills/uipath-platform/references/integration-service/ @chandusailella @baishalighosh /skills/uipath-platform/references/data-fabric/ @UiPath/DatafabricCodingAgent /skills/uipath-platform/references/llmgateway/ @denispetre @vstoleru-uipath @dragosvelcea +/skills/uipath-platform/references/guardrails/ @apetraru-uipath @valentinabojan @ctiliescuuipath /tests/tasks/uipath-platform/ @gabrielavaduva @alexenica @andreiopr @vlad-voinea-uipath @emanueldejanu @gcoman @puscasu-ion-daniel @razvalex @aeremencu @alinahornet @DinuDanNicolae @florin-munteanu-uipath @StefanPopaUi @razvanpotcoveanu @vladbucur-8 @busesorin94 @dmorosanu @MarinRzv @vladimir-cozma @UiPath/team-merlot @UiPath/team-orange @UiPath/DatafabricCodingAgent /tests/tasks/uipath-platform/orchestrator/ @gabrielavaduva @alexenica @andreiopr @vlad-voinea-uipath @emanueldejanu @gcoman @puscasu-ion-daniel @razvalex @aeremencu @alinahornet @DinuDanNicolae @florin-munteanu-uipath @StefanPopaUi @razvanpotcoveanu @vladbucur-8 @busesorin94 @dmorosanu @MarinRzv @vladimir-cozma @UiPath/team-merlot @UiPath/team-orange /tests/tasks/uipath-platform/resources/ @gabrielavaduva @alexenica @andreiopr @vlad-voinea-uipath @emanueldejanu @gcoman @puscasu-ion-daniel @razvalex @aeremencu @alinahornet @DinuDanNicolae @florin-munteanu-uipath @StefanPopaUi @razvanpotcoveanu @vladbucur-8 @busesorin94 @dmorosanu @MarinRzv @vladimir-cozma @UiPath/team-merlot @UiPath/team-orange diff --git a/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md b/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md index d23dd64b40..26009d2442 100644 --- a/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md +++ b/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md @@ -54,6 +54,8 @@ uip agent guardrails list --output json Build a lookup of `{ validatorId: status }` from the `Data` array. You will use this to filter recommendations. +> **`Validator` is not unique — key on `(Validator, IsByo)`, not `Validator` alone.** A tenant with a bring-your-own (BYOG) configuration for a validator has two entries sharing the same `Validator` name — one built-in, one BYO (`IsByo: true`, carrying `ByoValidatorName`/`ByoConnectionId`/`ByoConfigurationId`). Collapsing them loses the distinction and can point the discovery/wiring flow at the wrong entry. See [guardrails.md § BYO (bring-your-own) validators](guardrails.md#byo-bring-your-own-validators). + > **Catalog vs. list — the key distinction:** The catalog lists all guardrails that exist on the platform (with rich metadata for reasoning). The guardrails list returns only those accessible to this tenant. Only recommend validators where `Status == "Available"` in the list. ### SDK Documentation (NEVER skipped — Python class names) @@ -115,6 +117,8 @@ For **each entry** in the catalog (`guardrails[]` array from the cached JSON): Do **not** apply predetermined knowledge about which guardrail maps to which schema field. Let the catalog entry's authored fields drive every recommendation decision. +> **Built-in vs. BYO — default to built-in.** When a matched validator has both a built-in entry and one or more `Available` BYO (`IsByo: true`) entries, recommend the standard SDK validator/middleware (built-in) by default, and mention a BYO alternative exists. Only wire in a specific BYO configuration when the user names it or asks for BYO explicitly — see [guardrails.md § BYO (bring-your-own) validators](guardrails.md#byo-bring-your-own-validators) for how that's actually referenced in code. + ### Step 3 — De-duplicate Overlapping Validators Several catalog validators address the same threat. Recommending more than one of them at the same scope and stage is redundant — it doubles latency and cost on every call for marginal benefit (the canonical case is `prompt_injection` and `user_prompt_attacks`: both have `security_category: "adversarial_input"` and both run at LLM · PRE). @@ -235,7 +239,7 @@ For each existing guardrail discovered in the Python file (Step 1 from Recommend ### Correctness Check -From the SDK docs and the catalog, look up the validator class referenced in the code: +From the SDK docs and the catalog, look up the validator class referenced in the code. **If the guardrails list has more than one entry sharing the referenced `Validator` name** (built-in plus BYOG), disambiguate by whether the code wires a BYO validator construct (carrying a `ByoValidatorName`/connection id) or the plain SDK validator/middleware class — match against the corresponding list entry's `IsByo` before reading `Parameters`/scopes for that entry. | Aspect | What to check | |--------|---------------| @@ -295,3 +299,4 @@ python3 -c "import ast; ast.parse(open('graph.py').read())" 13. **Class names and enum names come from the SDK docs** — never invent them. The SDK evolves; relying on memory produces stale code. For **import paths**, use the `langchain/guardrails/` page when the agent is LangChain (paths live in `uipath_langchain.guardrails`); for every other framework use the `core/guardrails/` page (paths live in `uipath.platform.guardrails`). See Rule 8. 14. **Read [guardrails.md](guardrails.md) before writing any Python** — the middleware spread (`*`), decorator placement above `@tool` / factory, factory refactor, and import-source rules are specified there and cannot be safely inferred. 15. **`EscalateAction` is the human-in-the-loop option only when the SDK docs expose it** — recommend it when the user wants a person to review/approve a flagged item rather than hard-block it. It requires a **deployed Action App** declared in `bindings.json` (`app_name` / `app_folder_path`) through the coded-agent bindings sync workflow; if the docs, app, or binding prerequisite is unavailable, fall back to Block/Log and say so — never silently drop the requested escalation. See Step 6 and [guardrails.md § Escalation action (HITL)](guardrails.md#escalation-action-human-in-the-loop). +16. **`Validator` is not unique — disambiguate built-in vs. BYO by `IsByo` before matching on name.** A tenant can have both a built-in and one or more BYOG entries sharing the same `Validator` name. Key any lookup on `(Validator, IsByo)`, and default recommendations/wiring to the built-in SDK validator/middleware unless the user names a BYO configuration or asks for BYO. Never fabricate the BYO validator construct from memory — see [guardrails.md § BYO (bring-your-own) validators](guardrails.md#byo-bring-your-own-validators). diff --git a/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails.md b/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails.md index bf7ea43927..813d235856 100644 --- a/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails.md +++ b/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails.md @@ -57,6 +57,27 @@ If the requested validator has `Status != "Available"` → tell the user and sto --- +## BYO (bring-your-own) validators + +A validator can be fulfilled by a tenant-registered **external** provider (a "BYOG" configuration — e.g. Azure AI Content Safety, Databricks AI Guardrails) instead of UiPath's own built-in implementation. Registration happens Admin-UI-side (Admin → AI Trust Layer → Guardrails Configurations); this section covers wiring an already-registered BYOG configuration into agent code. + +**Same rule as [Step 0](#step-0--fetch-official-documentation): do not hardcode the BYO validator's class name or constructor signature from memory.** Check the same two fetched SDK doc pages (`langchain/guardrails/`, `core/guardrails/`) for BYO validator support before writing any code. If the fetched docs do not expose a BYO validator construct, **stop and report that BYO guardrails are not available in the current SDK docs/runtime** — do not invent the class, import path, or arguments (same posture as `EscalateAction`, Critical Rule 14). + +Discovery steps (in addition to the fetched docs): + +1. Confirm a BYOG configuration exists for the desired validator and get its identifying values: + ```bash + uip agent guardrails list --byo --output json + ``` + Read `ByoValidatorName` and `ByoConnectionId` from the matching entry — these are the values the fetched docs' BYO construct expects as name and connection id. Never guess or fabricate them. +2. Before wiring it in, cross-check the configuration's health on the admin side: + ```bash + uip guardrails byo-configurations list --output json + ``` + Confirm `Enabled: true` and `ValidConnection: true` for the matching `ValidatorName`/`ConnectionId`. A disabled configuration or a broken connection means the guardrail will fail at runtime (or silently fall back, depending on `FallbackOnUiPath`) — tell the user rather than wiring it in anyway. + +--- + ## Step 1 — Style Choice If the user has not specified **middleware** or **decorator**, ask before generating any code. Do not implement both unless explicitly asked. @@ -398,3 +419,4 @@ For non-LangChain frameworks, there is no published adapter yet, so the decorato 15. **`EscalateAction` requires a deployed Action App** referenced by `app_name` + `app_folder_path` and declared as an `app` resource in **`bindings.json`** — discover it with `uip solution resources list --kind App`, resolve duplicate names by folder, pass the literal name/folder in code (not env vars), and sync bindings with [../../lifecycle/bindings-reference.md](../../lifecycle/bindings-reference.md). Route the task with `TaskRecipient` when the user names a reviewer. See [Escalation action (HITL)](#escalation-action-human-in-the-loop). 16. **Verify the escalation app schema when tenant access is available** — the app must expose the guardrail review inputs/outputs/outcomes listed in the prerequisite section. If the schema cannot be verified in a local smoke task, say that runtime readiness is unverified. 17. **A HITL guardrail suspends, it doesn't block.** On violation `EscalateAction` suspends via `interrupt(CreateEscalation(...))`; it terminates **only on Reject** (Approve resumes). Verify by confirming the run suspends + a task is created — never expect a "block" for an escalation guardrail (Rule for the [verification step](#verify-guardrails-are-actually-wired-mandatory-after-writing-for-langchain-ml-guardrails)). +18. **Never fabricate a BYO validator's class name or constructor signature from memory** — get it from the fetched SDK docs (same Step 0 fetch), and get its `ByoValidatorName` / `ByoConnectionId` from `uip agent guardrails list --byo`, never invented. If the fetched docs don't expose BYO validator support, stop and report it's unavailable — do not improvise. Cross-check `Enabled`/`ValidConnection` via `uip guardrails byo-configurations list` before wiring one in. See [BYO (bring-your-own) validators](#byo-bring-your-own-validators). diff --git a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md index 814dc9969f..2470f197a4 100644 --- a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md +++ b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md @@ -47,6 +47,8 @@ uip agent guardrails list --output json Build a lookup of `{ validatorId: status }` from the `Data` array. You will use this in Steps 2 and 5 to filter recommendations. +> **`Validator` is not unique — key the lookup on `(Validator, IsByo)`, not `Validator` alone.** A tenant with a bring-your-own (BYOG) configuration for a validator sees two entries sharing the same `Validator` name — one built-in (`IsByo` absent/false), one BYO (`IsByo: true`, carrying `ByoValidatorName`/`ByoConfigurationId`/etc.). Collapsing them into a single `{ validatorId: status }` key silently picks whichever entry happens to win the collision and can validate against the wrong `Parameters`/`AllowedScopes`. See [guardrails.md § BYO (bring-your-own) guardrails](guardrails.md#byo-bring-your-own-guardrails). + > **Catalog vs. list — the key distinction:** The catalog lists all guardrails that exist on the platform (with rich metadata for reasoning). The guardrails list returns only those accessible to this tenant. Only recommend validators where `Status == "Available"` in the list. --- @@ -114,6 +116,8 @@ For **each entry** in the catalog (`guardrails[]` array from the cached JSON): Do **not** apply predetermined knowledge about which guardrail maps to which schema field. Let the catalog entry's authored fields drive every recommendation decision. +> **Built-in vs. BYO — default to built-in.** When a matched validator has both a built-in entry and one or more `Available` BYO (`IsByo: true`) entries in the guardrails list, recommend the built-in implementation (omit `byoConfigurationId`) by default, and mention that a BYO alternative exists. Only recommend a specific BYO configuration when the user names it or asks for BYO explicitly. + ### Step 3 — De-duplicate Overlapping Validators Several catalog validators address the same threat. Recommending more than one of them at the same scope and stage is redundant — it doubles latency and cost on every call for marginal benefit (the canonical case is `prompt_injection` and `user_prompt_attacks`: both have `security_category: "adversarial_input"` and both run at Llm · PRE). @@ -211,7 +215,7 @@ For each existing guardrail in `agent.json`'s `guardrails[]`: ### Correctness Check -Run `uip agent guardrails list --output json` (from Step 0) and find the matching validator by `Validator` name. The `Parameters` array is the authoritative source for all validation rules: +Run `uip agent guardrails list --output json` (from Step 0) and find the matching validator by `Validator` name. **If more than one entry shares that `Validator` name** (a built-in plus one or more BYOG entries), disambiguate before reading `Parameters`: the guardrail JSON carries `byoConfigurationId` when it targets a specific BYO configuration — match on that against the list entries' `ByoConfigurationId`; if the guardrail JSON has no `byoConfigurationId`, it targets the built-in entry (`IsByo` absent/false). Validating against the wrong entry's `Parameters` produces false correctness findings. The `Parameters` array (of the correctly matched entry) is the authoritative source for all validation rules: | CLI field | What to check | |-----------|---------------| @@ -265,3 +269,4 @@ If the user asks to fix identified issues: apply corrections to `agent.json`, ru 12. **All map-enum keys must exactly match the corresponding enum-list values** — no extra or missing keys. This is the most common correctness error. 13. **Read [guardrails.md](guardrails.md) before writing any JSON** — discriminator fields, PascalCase constraints, and parameter shapes are specified there and cannot be safely inferred. 14. **Do NOT use TaskCreate, TaskUpdate, or other task-tracking tools for guardrail edits.** Edit `agent.json` directly — task management tools add bookkeeping turns without benefit and push runs over their turn budget. +15. **`Validator` is not unique — disambiguate built-in vs. BYO by `IsByo` before matching on name.** A tenant can have both a built-in and one or more BYOG entries sharing the same `Validator` name. Key any lookup on `(Validator, IsByo)`, and when an existing guardrail carries `byoConfigurationId`, match it against `ByoConfigurationId` — not `Validator` alone — before reading `Parameters`/`AllowedScopes` for correctness or recommendation. Default recommendations to the built-in entry unless the user asks for BYO. See [guardrails.md § BYO (bring-your-own) guardrails](guardrails.md#byo-bring-your-own-guardrails). diff --git a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md index d75233adf8..ec80aac3a2 100644 --- a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md +++ b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md @@ -625,9 +625,21 @@ Run `uip agent guardrails list --output json` to get the authoritative list. Onl | `GuardrailStages[scope]` | Valid execution stages for that scope | | `Parameters[].Id` | `validatorParameters[].id` | | `Parameters[].Type` | `validatorParameters[].$parameterType` | +| `IsByo` | Disambiguates a bring-your-own (BYOG) entry from a built-in one — see [BYO (bring-your-own) guardrails](#byo-bring-your-own-guardrails) below. Not itself a JSON field. | +| `ByoConfigurationId` | `byoConfigurationId` value — include this field to pin the guardrail to this exact BYO configuration. Required whenever more than one entry shares this `Validator` name (a built-in plus one or more BYOG configurations). | > **Important:** PII entity names use PascalCase (`"Email"`, not `"email_address"`). Harmful content categories use PascalCase (`"Hate"`, not `"hate"`). Scope values use PascalCase (`"Agent"`, `"Llm"`, `"Tool"`). +## BYO (bring-your-own) guardrails + +A validator can be fulfilled by a tenant-registered **external** provider (a "BYOG" configuration — e.g. Azure AI Content Safety, Databricks AI Guardrails) instead of, or alongside, UiPath's own built-in implementation. A tenant admin registers these at Admin → AI Trust Layer → Guardrails Configurations; see [uipath-platform § BYO Guardrail Configurations](/uipath:uipath-platform) for the admin-side inspection command (`uip guardrails byo-configurations list`). + +- **`Validator` is not unique.** A tenant with a BYOG `harmful_content` configuration sees **two** entries named `harmful_content` in `uip agent guardrails list` output — one built-in, one BYO. Use `IsByo` to tell them apart; never assume a single match. +- **Filter to BYO-only entries** with `uip agent guardrails list --byo --output json` when the user specifically wants to see or target a BYO-backed validator. +- **BYO entries carry extra fields**: `ByoValidatorName`, `ByoConnectionId`, `ByoConfigurationId`, `ByoConnectorName`, `ByoConnectorKey`, `FolderKey` — alongside the same `Parameters`/`AllowedScopes`/`GuardrailStages`/`Status` shape a built-in entry has. +- **To author a guardrail against a specific BYO configuration**, build the `builtInValidator` guardrail exactly as for a built-in validator (same `validatorType`, same `validatorParameters` from that entry's `Parameters`), and add `byoConfigurationId` set to that entry's `ByoConfigurationId`. Omit it to use the built-in implementation. +- **`Status: "Disabled"` on a BYO entry** means the tenant switched that specific configuration off — the entry still shows (it doesn't vanish), so a disabled BYOG configuration is distinguishable from one that was never set up. Do not author a guardrail against a `Disabled` BYO entry; treat it the same as `Unauthorised` (skip, tell the user). + ## Full Examples ### Example 1: Block PII in Agent and Tool Outputs @@ -1030,6 +1042,7 @@ Add the `guardrails` array at the agent.json root level alongside `settings`, `m 18. **Do not attempt OR logic within a single guardrail** — all rules and all fields within a guardrail are combined with AND. OR is not supported. To achieve OR behavior, create separate guardrails — one per condition branch. 19. **Do not generate guardrails targeting unsupported tool types** — `matchNames` can only reference tools of supported types: agent, process, activity, builtInTool, ixpTool, or Integration Service connector. Do not generate guardrails with `matchNames` targeting other tool types. 20. **Do not omit `matchNames` to target "all tools"** — always explicitly list every tool resource name in `matchNames`. Read the agent's `resources/` directory first. If the agent has no tool resources, do not add the guardrail. +21. **Do not assume `Validator` is unique** — a tenant can have both a built-in and one or more bring-your-own (BYOG) entries sharing the same `Validator` name. Always check `IsByo` before treating two same-named entries as a duplicate or conflict, and set `byoConfigurationId` when targeting a specific BYO entry. See [BYO (bring-your-own) guardrails](#byo-bring-your-own-guardrails). ## Walkthrough diff --git a/skills/uipath-platform/SKILL.md b/skills/uipath-platform/SKILL.md index eca7b35533..80418e11a7 100644 --- a/skills/uipath-platform/SKILL.md +++ b/skills/uipath-platform/SKILL.md @@ -1,7 +1,7 @@ --- name: uipath-platform -description: "UiPath platform ops via the uip CLI — use for ANY task hitting UiPath Cloud / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway. Load BEFORE writing code that calls a UiPath API. Covers auth, folders, assets, queues, storage buckets, libraries, webhooks, triggers, processes, jobs, machines, users, roles, sessions, calendars, IS connectors/connections/activities, Data Fabric entities/records/files/choice-sets (`uip df`), BYO LLM product configurations, context grounding, traces (execution traces and spans + trace feedback / annotation), licensing. For 'why did X fail' / root-cause→uipath-troubleshoot. For org/tenant audit trail / audit logs / login history→uipath-admin. For `uip solution` lifecycle→uipath-solution. For PDD/SDD design→uipath-planner. For workflow code (.xaml/.cs)→uipath-rpa, .flow (incl. Data Fabric connector nodes)→uipath-maestro-flow, .bpmn→uipath-maestro-bpmn, agents (.py/agent.json)→uipath-agents, Test Manager→uipath-test." -when_to_use: "User mentions UiPath / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway / 'uip' CLI / asset / queue / bucket / library / webhook / trigger / connector / connection / tenant / folder / robot / package / entity / record / choice set / trace / span / trace feedback / BYO LLM. Also 'upload to UiPath', 'create asset', 'start job', 'list queues', 'deploy a single package to Orchestrator', 'OAuth2 token', 'list trace spans / add trace feedback', 'create entity', 'add field', 'delete field', 'list entities', 'insert record', 'update record', 'delete record', 'query Data Fabric', 'search records', 'show every tagged/where', 'filter records by tag/choice/field', 'count by group', 'unique tag combinations', 'group by field', 'aggregate COUNT/SUM/AVG', 'create choice-set', 'create choiceset', 'add choice set values', 'delete choice set', 'attach file to record', 'upload/download/delete file on entity record', 'swap record attachment', 'import CSV', 'load CSV into entity/list', 'load spreadsheet into entity', 'bulk load records from CSV', 'bulk import from CSV', 'register my own LLM key', 'configure a model substitution', 'my BYO LLM key stopped working / returns errors', 're-probe / audit a BYO configuration', 'uipath.com REST'. For `uip solution` ops or `.uipx` deploys→uipath-solution. For Data Fabric connector nodes inside a `.flow`→uipath-maestro-flow." +description: "UiPath platform ops via the uip CLI — use for ANY task hitting UiPath Cloud / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway. Load BEFORE writing code that calls a UiPath API. Covers auth, folders, assets, queues, storage buckets, libraries, webhooks, triggers, processes, jobs, machines, users, roles, sessions, calendars, IS connectors/connections/activities, Data Fabric entities/records/files/choice-sets (`uip df`), BYO LLM product configurations, BYO guardrail (BYOG) configurations, context grounding, traces (execution traces and spans + trace feedback / annotation), licensing. For 'why did X fail' / root-cause→uipath-troubleshoot. For org/tenant audit trail / audit logs / login history→uipath-admin. For `uip solution` lifecycle→uipath-solution. For PDD/SDD design→uipath-planner. For workflow code (.xaml/.cs)→uipath-rpa, .flow (incl. Data Fabric connector nodes)→uipath-maestro-flow, .bpmn→uipath-maestro-bpmn, agents (.py/agent.json)→uipath-agents, Test Manager→uipath-test." +when_to_use: "User mentions UiPath / Orchestrator / Studio Web / Integration Service / Data Fabric / LLM Gateway / 'uip' CLI / asset / queue / bucket / library / webhook / trigger / connector / connection / tenant / folder / robot / package / entity / record / choice set / trace / span / trace feedback / BYO LLM / BYO guardrail / BYOG. Also 'upload to UiPath', 'create asset', 'start job', 'list queues', 'deploy a single package to Orchestrator', 'OAuth2 token', 'list trace spans / add trace feedback', 'create entity', 'add field', 'delete field', 'list entities', 'insert record', 'update record', 'delete record', 'query Data Fabric', 'search records', 'show every tagged/where', 'filter records by tag/choice/field', 'count by group', 'unique tag combinations', 'group by field', 'aggregate COUNT/SUM/AVG', 'create choice-set', 'create choiceset', 'add choice set values', 'delete choice set', 'attach file to record', 'upload/download/delete file on entity record', 'swap record attachment', 'import CSV', 'load CSV into entity/list', 'load spreadsheet into entity', 'bulk load records from CSV', 'bulk import from CSV', 'register my own LLM key', 'configure a model substitution', 'my BYO LLM key stopped working / returns errors', 're-probe / audit a BYO configuration', 'list bring-your-own guardrail configurations', 'who registered this BYOG guardrail', 'uipath.com REST'. For `uip solution` ops or `.uipx` deploys→uipath-solution. For Data Fabric connector nodes inside a `.flow`→uipath-maestro-flow." allowed-tools: Bash, Read, Write, Glob, Grep, Skill --- @@ -52,6 +52,7 @@ Load this skill BEFORE writing any code that talks to UiPath. Specific triggers: For Query / Create / Update / Delete / GetById connector nodes **inside a `.flow`**, hand off to `uipath-maestro-flow` — that skill owns the in-flow node JSON, `bindings_v2.json`, and connection-resource layout. - **LLM Gateway — BYO product configurations**: `uip llm-configuration byo-connections` (`list / get / create / update / delete / list-product-configs`). Register tenant-owned OpenAI / Azure OpenAI / AWS Bedrock / Google Vertex / Anthropic / OpenAI-compatible keys against UiPath product features (agents, agenthub, jarvis, IXP, agent builder, ECS). Two input shapes: single-mapping (for `AnyModelWithOwnAdditions` features) and repeated `--mapping` (required for `AllModels` / `AnyModel`). Server-side validation is mandatory. - **LLM Gateway — diagnose a failing BYO config**: re-probe the underlying IS connection with `byo-connections get --force-refresh`, force a fresh server-side probe with an idempotent `update`, audit the tenant with `list --include-connection-details` filtered on `connectionState != Enabled`, check catalog drift with `list-product-configs`, and cross-reference trace evidence with `uip traces spans get `. The gateway does **not** expose per-request invocation logs via CLI — diagnosis is current-state + trace evidence only. See [`references/llmgateway/byo-connections.md` § Diagnostics](references/llmgateway/byo-connections.md#diagnostics). For tenant-wide AI Trust Layer policy that may be overriding routing, see [uipath-governance](/uipath:uipath-governance). +- **AI Trust Layer — BYO guardrail (BYOG) configurations**: `uip guardrails byo-configurations list` — read-only view of tenant-registered external guardrail validator providers (e.g. Azure AI Content Safety, Databricks AI Guardrails), each backed by an Integration Service connection. Registration itself is Admin UI only (Admin → AI Trust Layer → Guardrails Configurations) — no `create`/`update`/`delete` CLI verb yet. `ConnectionId` here is the exact value a coded agent passes to `ByoValidator(, connection_id=)`. See [`references/guardrails/byo-configurations.md`](references/guardrails/byo-configurations.md). For authoring a guardrail against one of these configurations (low-code or coded), see [uipath-agents](/uipath:uipath-agents). - **Traces**: `uip traces spans get ` (LLM/agentic execution observability) - **Context grounding**: knowledge indexes for semantic search / RAG — `uip context-grounding` (`list / create` from a bucket or connection `/ ingest / retrieve` to poll ingestion status `/ search / delete`). Agents and flows consume these indexes as tools. See [`references/context-grounding/index-management.md`](references/context-grounding/index-management.md). - **Platform licensing**: tenant license allocations, user/group bundle assignments, consumables reporting (`uip platform tenants licenses`, `users licenses`, `groups rules`, `licenses consumables get` — the only consumables verb; summary/daily/folders are `--mode` values) @@ -173,6 +174,8 @@ Choose the appropriate operation from the Task Navigation table below. For `uip | **Bulk import records from CSV** | [references/data-fabric/bulk-import.md](references/data-fabric/bulk-import.md) | | **Configure BYO LLM keys (OpenAI / Azure OpenAI / Bedrock / Vertex / Anthropic)** | [references/llmgateway/byo-connections.md](references/llmgateway/byo-connections.md) | | **Diagnose / audit / re-probe a BYO LLM configuration** | [references/llmgateway/byo-connections.md#diagnostics](references/llmgateway/byo-connections.md#diagnostics) | +| **List tenant BYO guardrail (BYOG) configurations** | [references/guardrails/byo-configurations.md](references/guardrails/byo-configurations.md) | +| **Diagnose a BYO guardrail (dead connection, disabled config)** | [references/guardrails/byo-configurations.md#diagnostics](references/guardrails/byo-configurations.md#diagnostics) | | **Allocate licenses to tenants** | [references/licensing/tenant-allocations.md](references/licensing/tenant-allocations.md) | | **Assign user/group license bundles** | [references/licensing/user-licenses-allocations.md](references/licensing/user-licenses-allocations.md) | | **Report on license consumption** | [references/licensing/consumables-report.md](references/licensing/consumables-report.md) | @@ -308,6 +311,7 @@ Every `uip` command accepts: - **[Integration Service](references/integration-service/integration-service.md)** — Connectors, connections, activities, resources - **[Data Fabric](references/data-fabric/data-fabric.md)** — Entity schemas, records CRUD, query filters and aggregates, choice sets, file attachments, CSV bulk import, folder scoping - **[LLM Gateway — BYO Connections](references/llmgateway/byo-connections.md)** — Register tenant-owned LLM keys against UiPath products +- **[Guardrails — BYOG Configurations](references/guardrails/byo-configurations.md)** — List tenant-registered bring-your-own guardrail (BYOG) configurations and diagnose their underlying Integration Service connections - **[Licensing](references/licensing/licensing.md)** — Tenant allocations, user/group bundles, consumables reporting - **[Coded Workflows](/uipath:uipath-rpa)** — Building coded automation projects diff --git a/skills/uipath-platform/references/guardrails/byo-configurations.md b/skills/uipath-platform/references/guardrails/byo-configurations.md new file mode 100644 index 0000000000..7b7cf84653 --- /dev/null +++ b/skills/uipath-platform/references/guardrails/byo-configurations.md @@ -0,0 +1,96 @@ +# BYO Guardrail (BYOG) Configurations + +Inspect tenant-registered bring-your-own guardrail configurations via `uip guardrails byo-configurations list`. A BYOG configuration registers an external validator provider (e.g. Databricks AI Guardrails, Azure AI Content Safety) against an Integration Service connection, so an agent's guardrail checks (PII detection, harmful content, etc.) run against that external provider instead of — or as a fallback pair with — UiPath's own built-in implementation. + +> **List-only today.** There is no `create` / `update` / `delete` / `get` verb yet. Registering, editing, or removing a BYOG configuration is **Admin UI only**: Admin → AI Trust Layer → Guardrails Configurations. This command is read visibility, not lifecycle management. + +--- + +## Command + +```bash +uip guardrails byo-configurations list --output json +``` + +**Prerequisites:** +- **Logged in with a user token, not an application (client-credentials) token.** The endpoint requires an org-admin **user** session and rejects application tokens outright. +- The logged-in user must have an org-admin role for AI Trust Layer in the target tenant. Insufficient permissions surface as a `403` with the backend's reason in `Instructions` (e.g. `"User is not a member of the Administrators group"`) — distinct from the `404`/`ByoGuardrailsUnavailable` case below. +- No other setup — this is a read-only listing of whatever the tenant admin has already registered via the Admin UI. + +### Output shape + +```json +{ + "Result": "Success", + "Code": "ByoGuardrailConfigurationsList", + "Data": [ + { + "Id": "e5723bb8-fbc2-4317-c7d7-08de803bc010", + "ConnectionId": "18fb337c-29b7-4162-a9e8-0c05b01cf4df", + "ValidatorName": "my-pii-guardrail", + "ValidatorType": "pii_detection", + "FallbackOnUiPath": true, + "Enabled": true, + "CreatedAt": "2026-07-01T10:00:00Z", + "UpdatedAt": null, + "ConnectorKey": "uipath-azure-contentsafety", + "ConnectorName": "Azure AI Content Safety", + "ConnectionName": "My Content Safety Connection", + "ValidConnection": true + } + ] +} +``` + +| Field | Meaning | +|---|---| +| `Id` | The BYOG configuration's own id — this is the `ByoConfigurationId` a low-code guardrail includes to pin itself to this exact configuration (see [uipath-agents guardrails](/uipath:uipath-agents)). | +| `ConnectionId` | The Integration Service connection GUID backing this configuration. This is the value a **coded agent** passes as `connection_id` in `ByoValidator(, connection_id=)` — the backend does no name→id resolution, so it must be the literal GUID. | +| `ValidatorName` | The tenant-chosen alias for this configuration — the first argument a coded agent passes to `ByoValidator(...)`, and the same value surfaced as `ByoValidatorName` by `uip agent guardrails list --byo`. | +| `ValidatorType` | The raw validator category this configuration implements (e.g. `pii_detection`, `harmful_content`) — matches the built-in `Validator` name for the same category. | +| `FallbackOnUiPath` | Whether a failed call to the external provider falls back to UiPath's own built-in validator logic, or hard-fails the guardrail check. | +| `Enabled` | Whether the tenant has switched this configuration on. A disabled configuration still appears in `uip agent guardrails list --byo` output but with `Status: Disabled`. | +| `ValidConnection` | Whether the underlying Integration Service connection currently resolves and is healthy. `false` means the connection was disabled, revoked, or rotated since registration. | +| `ConnectorKey` / `ConnectorName` / `ConnectionName` | Resolved metadata about the underlying IS connector/connection, for display. | + +Empty `Data: []` is a valid result — it means the tenant has no BYOG configurations registered. + +### Feature not available + +A 404 surfaces as: + +```json +{ + "Result": "Failure", + "Code": "ByoGuardrailsUnavailable", + "Message": "...", + "Instructions": "Contact UiPath support to enable bring-your-own guardrails for this tenant." +} +``` + +This means BYOG is not enabled (feature-flagged off) for the tenant — not a transient error. Report it to the user rather than retrying. + +### Permission errors (distinct from feature-not-available) + +Any other non-2xx status (e.g. `403`) surfaces as `Message: "Failed to list BYO guardrail configurations"` with the backend's response body carried in `Instructions` (truncated to 1000 characters) — e.g. `"403 Forbidden: {\"title\":\"Forbidden\",\"detail\":\"User is not a member of the Administrators group\"}"`. This means the logged-in identity lacks the org-admin role, or is an application token (not a user token) — tell the user to re-authenticate with an admin user account rather than treating it as a feature-availability problem. + +--- + +## How this feeds agent authoring + +This command is the **only CLI way to obtain the `ConnectionId`** a coded agent needs. The agent-authoring side (discovery from an agent-design context, not admin) is `uip agent guardrails list --byo` in `uipath-agents` — see: +- [Low-code guardrails](/uipath:uipath-agents) — `builtInValidator` guardrails authored against a specific BYOG configuration via `byoConfigurationId`. +- [Coded guardrails](/uipath:uipath-agents) — `ByoValidator(, connection_id=)`. + +## Diagnostics + +**`ValidConnection: false`** — the underlying Integration Service connection is broken. Inspect and repair it directly: + +```bash +uip is connections list --output json +uip is connections get --output json +``` + +See [Connections](../integration-service/connections.md) for connection lifecycle. There is no CLI re-probe for a BYOG configuration itself (unlike BYO LLM connections' `get --force-refresh`) — repairing the underlying IS connection is the fix; the BYOG record's `ConnectionId` doesn't change. + +**A guardrail using this configuration behaves unexpectedly at runtime** — check `Enabled` and `FallbackOnUiPath` here first: a disabled configuration or a dead connection with `FallbackOnUiPath: false` fails the guardrail check outright rather than falling back to the built-in validator. See [uipath-troubleshoot § Guardrail Violation](/uipath:uipath-troubleshoot) for full runtime diagnosis via trace spans. diff --git a/skills/uipath-review/references/agents/guardrails/coded-guardrails-review.md b/skills/uipath-review/references/agents/guardrails/coded-guardrails-review.md index beb72a11fe..328b8d9b7d 100644 --- a/skills/uipath-review/references/agents/guardrails/coded-guardrails-review.md +++ b/skills/uipath-review/references/agents/guardrails/coded-guardrails-review.md @@ -94,6 +94,8 @@ uip agent guardrails list --output json Build a `{ validatorId: status }` lookup from the `Data` array (use only `Status == "Available"`). +> **`Validator` is not unique — key on `(Validator, IsByo)`, not `Validator` alone.** A tenant with a bring-your-own (BYOG) configuration for a validator has two entries sharing the same `Validator` name — one built-in, one BYO (`IsByo: true`). If the code wires a BYO validator construct, match it against the `IsByo: true` entry (by its `ByoValidatorName`/connection id), not the built-in one, before reading `Parameters`/scopes. See [uipath-agents coded guardrails.md § BYO (bring-your-own) validators](/uipath:uipath-agents). + ### SDK Docs (required when Step 0 needs Python class names) Coded agents reference guardrails by **Python class name** (`UiPathPIIDetectionMiddleware`, `PIIValidator`), not by @@ -155,6 +157,8 @@ Resolve the entry `.py` (the `langgraph.json` `graphs` value's file, else `main. For each wired guardrail the review CLI did **not** flag, run the checks below. +> **A BYO-backed guardrail's tenant entry showing `Status: "Disabled"` is a configuration switch, not a wiring bug.** It means the tenant admin turned that specific BYOG configuration off (Admin → AI Trust Layer → Guardrails Configurations) — don't re-diagnose the code as a wiring/import defect. If the wired guardrail targets that disabled configuration, it can't protect; treat it like targeting an `Unauthorised` validator and note it in the report. + ### Actionability Check → `CODED_GUARDRAIL_ACTION_INEFFECTIVE` Compare the guardrail's action class against the catalog entry's `when_not_to_use` and its representative diff --git a/skills/uipath-review/references/agents/guardrails/guardrails-review.md b/skills/uipath-review/references/agents/guardrails/guardrails-review.md index 2108b72e44..4d3da6facf 100644 --- a/skills/uipath-review/references/agents/guardrails/guardrails-review.md +++ b/skills/uipath-review/references/agents/guardrails/guardrails-review.md @@ -104,6 +104,8 @@ uip agent guardrails list --output json Build a `{ validatorId: status }` lookup from the `Data` array (use only `Status == "Available"`). +> **`Validator` is not unique — key on `(Validator, IsByo)`, not `Validator` alone.** A tenant with a bring-your-own (BYOG) configuration for a validator has two entries sharing the same `Validator` name — one built-in, one BYO (`IsByo: true`). Collapsing them can point Audit Mode's Correctness/Actionability comparison at the wrong entry's `Parameters`/`AllowedScopes`. When the reviewed guardrail JSON carries `byoConfigurationId`, match it against that entry's `ByoConfigurationId`, not `Validator` alone. See [uipath-agents guardrails.md § BYO (bring-your-own) guardrails](/uipath:uipath-agents). + ### If the catalog is unavailable If the catalog output contains `"Code": "GuardrailCatalogUnavailable"` (or the CLI is unavailable), **do not @@ -123,6 +125,8 @@ guess**: For each guardrail in `agent.json`'s `guardrails[]` that the review CLI did **not** flag format-invalid, read its `validator`, `selector.scopes`, and action `$actionType`, then run two checks. +> **A BYO-backed guardrail's tenant entry showing `Status: "Disabled"` is a configuration switch, not a format problem.** It means the tenant admin turned that specific BYOG configuration off (Admin → AI Trust Layer → Guardrails Configurations) — don't re-diagnose it as a schema/discriminator issue. If the agent's guardrail targets that disabled configuration (via `byoConfigurationId`), it functions the same as targeting an `Unauthorised` validator — treat it as unable to protect and note it in the report. + ### Actionability Check → `LC_GUARDRAIL_ACTION_INEFFECTIVE` A format-valid guardrail's **action** can be ineffective or counterproductive for its **scope**. Compare the diff --git a/skills/uipath-troubleshoot/references/products/agents/playbooks/guardrail-violation.md b/skills/uipath-troubleshoot/references/products/agents/playbooks/guardrail-violation.md index d16dc9157f..f1ab988396 100644 --- a/skills/uipath-troubleshoot/references/products/agents/playbooks/guardrail-violation.md +++ b/skills/uipath-troubleshoot/references/products/agents/playbooks/guardrail-violation.md @@ -29,6 +29,7 @@ What can cause it: - Recent rule tightening or action change from Log/Escalate to Block — behavior change is immediate and silent - Overly broad pattern matches legitimate content (common business terms, structured JSON fields) - OOB validators (PII detection, harmful content, prompt injection, user prompt attacks) at agent or LLM scope — these run automatically when enabled and require no custom rules +- A bring-your-own (BYOG) guardrail whose tenant configuration is disabled, or whose underlying Integration Service connection is broken — behavior depends on `FallbackOnUiPath`: `true` falls back to the built-in validator, `false` fails the guardrail check outright > **Filter and Log do not fault the job.** Filter removes `excludedFields` from the payload; `updatedInput`/`updatedOutput` appear on the evaluation span; execution continues. Agent may behave unexpectedly if required fields are stripped. Log records the match; `severityLevel` appears on the evaluation span; execution continues. Neither produces `TERMINATION_GUARDRAIL_VIOLATION`. @@ -68,6 +69,15 @@ What can cause it: Replace `` with guardrailName value from step 3. + If the matched entry has `"IsByo": true`, cross-check the underlying BYOG configuration's health before assuming the rule/catalog itself is the cause: + + ```bash + uip guardrails byo-configurations list --output json \ + --output-filter "[?ValidatorName == '' || Id == ''].{Enabled: Enabled, ValidConnection: ValidConnection, FallbackOnUiPath: FallbackOnUiPath}" + ``` + + `Enabled: false` or `ValidConnection: false` means the violation traces back to the BYOG configuration itself (disabled or dead connection), not the rule's logic — see Resolution below. + Then fetch catalog entry: ```bash @@ -103,6 +113,8 @@ What can cause it: **Recent rule regression:** Check last-modified date in AgentBuilder or Flow → Guardrails. Restore the prior rule definition or disable the rule temporarily. Document the rollback and review rule scope with the guardrail policy team. +**BYO guardrail connection dead or configuration disabled:** If step 4's BYOG check showed `ValidConnection: false`, the underlying Integration Service connection is broken — repair it directly (`uip is connections get `; see [uipath-platform § BYO Guardrail Configurations § Diagnostics](/uipath:uipath-platform)). If `Enabled: false`, the tenant admin switched the configuration off — confirm with them whether that was intentional before re-enabling it (Admin → AI Trust Layer → Guardrails Configurations; no CLI verb re-enables it). Re-test with the previously blocked input after either fix. + Refresh and validate after any rule or agent change: ```bash