From 08399d26f4d7d8ba583d4ff0400c9e0c9bbaad00 Mon Sep 17 00:00:00 2001 From: Andrei Petraru Date: Thu, 23 Jul 2026 15:40:52 +0300 Subject: [PATCH 1/5] fix(guardrails): make Terra trajectory gates explicit --- .../guardrails/guardrails-recommend.md | 5 +++++ .../guardrails/guardrails-recommend.md | 21 +++++++++++++++++++ .../capabilities/guardrails/guardrails.md | 12 ++++++++++- 3 files changed, 37 insertions(+), 1 deletion(-) 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 75654e46d3..d23dd64b40 100644 --- a/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md +++ b/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md @@ -14,6 +14,11 @@ Both workflows are driven by live data — the catalog (`uip agent guardrails ca > Full three-fetch mandate applies to **Recommend mode**. In **Validate mode** of an existing guardrail the SDK docs are the authoritative, sufficient source for a validator's scope/stage — `catalog` (relevance metadata) and `list` (tenant entitlement) are recommended cross-checks, not a hard prerequisite for a scope/placement fix. See [Validate Mode](#validate-mode). +**Required first operation in both modes:** use `WebFetch` on +`https://uipath.github.io/uipath-python/core/guardrails/` before catalog calls, +project inspection, analysis, or edits. A coded guardrail recommendation or +validation is not grounded until this WebFetch has completed. + ### Catalog (cacheable — 30-minute TTL) The catalog is the same for all tenants (authored metadata, rarely changes). Cache it locally for 30 minutes to avoid redundant calls. 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 7598d6d195..dd5e965d66 100644 --- a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md +++ b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md @@ -66,6 +66,27 @@ From `agent.json`, extract: Also read `resources/` to list all tool names (needed for Tool-scope recommendations). +### Exact Named-Tool Deterministic Rules — before catalog ranking + +When the request gives both a named Tool and an exact mechanical predicate on +its input or output (literal word/phrase, regex, number, boolean, or always), +use the custom deterministic recipe below. This decision happens before +built-in catalog candidate ranking: + +1. Read the Tool's `resource.json.name` and use that exact value as the only + entry in `selector.matchNames`. +2. Set `$guardrailType: "custom"` and `selector.scopes: ["Tool"]`. This branch + does not use a `builtInValidator` or `validatorParameters`. +3. For a literal word or phrase, use `$ruleType: "word"`, + `operator: "contains"`, and preserve the exact requested literal as `value`. + Use the matching custom rule type when the user explicitly requests a + regex, number, boolean, or always condition. +4. Use a blocking action when the request says to prevent the Tool operation, + then build the complete object from [guardrails.md](guardrails.md). + +Broad semantic threats without an exact mechanical predicate continue through +the built-in catalog ranking in Step 2. + ### Step 2 — Catalog-Driven Recommendation Analysis For **each entry** in the catalog (`guardrails[]` array from the cached JSON): diff --git a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md index 111c02bea9..772fd06f14 100644 --- a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md +++ b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md @@ -16,6 +16,11 @@ Two types exist: This restriction is enforced as [../../critical-rules/conversational-critical-rules.md](../../critical-rules/conversational-critical-rules.md) Critical Rule 1. +**Required completion gate:** after writing a conversational custom Tool +guardrail, run `uip agent refresh "" --output json`, then execute +`uip agent validate "" --output json`. Do not report the guardrail +task complete before the validation command has been attempted. + ## Guardrail Schema (Base Fields) Every guardrail object in the `guardrails` array shares these base fields: @@ -284,6 +289,12 @@ Example entry: **Step 2 — Verify the app exposes the guardrail action-schema contract** (do this **before** writing the guardrail JSON — an incompatible app must be rejected, not authored). +**Required command gate:** execute +`uip solution resources get "" --output json` for the selected +app before deciding whether it is compatible. The `resources list` row is not +an action schema and cannot replace this command. Do not write or reject the +guardrail until the returned action schema has been checked. + A guardrail escalation app must expose a specific action-schema contract. If verification fails, stop and report to the user: ` does not have the required action schema configuration for tool guardrails.` (replace `` with the app's `Name` from Step 1). Do NOT write the guardrail. `uip solution resources get` returns the app's action schema in one CLI-native call — no auth handling, no Apps API endpoints. Pipe its output into a verifier that confirms every required argument name. The CLI handles authentication, so Claude never touches the auth file or the token. @@ -1113,4 +1124,3 @@ Confirm the guardrails appear in the validated output without errors. Refresh re - [../../critical-rules/critical-rules.md](../../critical-rules/critical-rules.md) — canonical low-code rules and guardrail anti-patterns (discriminators, scope casing, populating `guardrail.policies` on tool resources, UUID reuse) - [../../project-lifecycle.md](../../project-lifecycle.md) § `uip agent guardrails list` — CLI reference for validator discovery - [../../agent-definition.md](../../agent-definition.md) § Guardrails — root-level placement in `agent.json` - From 5565af9f580502514e6dceb23b48867363801a2f Mon Sep 17 00:00:00 2001 From: Andrei Petraru Date: Thu, 23 Jul 2026 23:59:42 +0300 Subject: [PATCH 2/5] test(guardrails): accept portable SDK doc fetches --- .../lowcode/capabilities/guardrails/guardrails.md | 7 +++++++ .../coded/guardrails/recommend_all/recommend_all.yaml | 1 - .../guardrails/recommend_scoped/recommend_scoped.yaml | 1 - .../uipath-agents/coded/guardrails/validate/validate.yaml | 1 - 4 files changed, 7 insertions(+), 3 deletions(-) diff --git a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md index 772fd06f14..d28b635e5a 100644 --- a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md +++ b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md @@ -295,6 +295,13 @@ app before deciding whether it is compatible. The `resources list` row is not an action schema and cannot replace this command. Do not write or reject the guardrail until the returned action schema has been checked. +If Step 1 returns no exact-name row and therefore no key, the command attempt +is still mandatory: execute +`uip solution resources get "" --output json` exactly once +and treat its failure as `GET_ERROR`. A missing catalog row is not permission to +skip `resources get`; this terminal lookup is required before rejecting the +requested escalation app. + A guardrail escalation app must expose a specific action-schema contract. If verification fails, stop and report to the user: ` does not have the required action schema configuration for tool guardrails.` (replace `` with the app's `Name` from Step 1). Do NOT write the guardrail. `uip solution resources get` returns the app's action schema in one CLI-native call — no auth handling, no Apps API endpoints. Pipe its output into a verifier that confirms every required argument name. The CLI handles authentication, so Claude never touches the auth file or the token. diff --git a/tests/tasks/uipath-agents/coded/guardrails/recommend_all/recommend_all.yaml b/tests/tasks/uipath-agents/coded/guardrails/recommend_all/recommend_all.yaml index cc0659a7d7..4b2ee9cb4b 100644 --- a/tests/tasks/uipath-agents/coded/guardrails/recommend_all/recommend_all.yaml +++ b/tests/tasks/uipath-agents/coded/guardrails/recommend_all/recommend_all.yaml @@ -47,7 +47,6 @@ success_criteria: - type: command_executed description: "Agent fetched the UiPath Python SDK guardrail docs" - tool_name: "WebFetch" command_pattern: 'uipath\.github\.io/uipath-python/.*guardrails' min_count: 1 weight: 1.5 diff --git a/tests/tasks/uipath-agents/coded/guardrails/recommend_scoped/recommend_scoped.yaml b/tests/tasks/uipath-agents/coded/guardrails/recommend_scoped/recommend_scoped.yaml index 1c5002ce59..0ab766e5b7 100644 --- a/tests/tasks/uipath-agents/coded/guardrails/recommend_scoped/recommend_scoped.yaml +++ b/tests/tasks/uipath-agents/coded/guardrails/recommend_scoped/recommend_scoped.yaml @@ -47,7 +47,6 @@ success_criteria: - type: command_executed description: "Agent fetched the UiPath Python SDK guardrail docs" - tool_name: "WebFetch" command_pattern: 'uipath\.github\.io/uipath-python/.*guardrails' min_count: 1 weight: 1.5 diff --git a/tests/tasks/uipath-agents/coded/guardrails/validate/validate.yaml b/tests/tasks/uipath-agents/coded/guardrails/validate/validate.yaml index be49e42989..4ef33d1ca5 100644 --- a/tests/tasks/uipath-agents/coded/guardrails/validate/validate.yaml +++ b/tests/tasks/uipath-agents/coded/guardrails/validate/validate.yaml @@ -58,7 +58,6 @@ success_criteria: - type: command_executed description: "Agent fetched the UiPath Python SDK guardrail docs" - tool_name: "WebFetch" command_pattern: 'uipath\.github\.io/uipath-python/.*guardrails' min_count: 1 weight: 1.5 From 0ce84dde797b34be83a6fa42e6220a6b89561362 Mon Sep 17 00:00:00 2001 From: Andrei Petraru Date: Fri, 24 Jul 2026 00:11:32 +0300 Subject: [PATCH 3/5] fix(guardrails): require scaffold before escalation lookup --- .../references/lowcode/capabilities/guardrails/guardrails.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md index d28b635e5a..29373f5286 100644 --- a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md +++ b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md @@ -246,6 +246,11 @@ Prefer `type: 3` (UserEmail) when adding manually — it requires no GUID or ass #### Adding an escalation guardrail — step-by-step +**Scaffolding gate (MANDATORY):** when the request includes creating a solution +or agent, run both `uip solution init` and `uip agent init` before app discovery. +An incompatible or missing escalation app rejects only the guardrail; it does +not cancel the requested local solution and agent scaffolding. + **Step 0 — Discover available validators (MANDATORY — do not skip even when validator type is already known):** ```bash From 340aa6382b6249464ccbab7386a04e654b711d77 Mon Sep 17 00:00:00 2001 From: Andrei Petraru Date: Fri, 24 Jul 2026 08:16:15 +0300 Subject: [PATCH 4/5] fix(guardrails): require schema lookup on missing app --- .../capabilities/guardrails/guardrails.md | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md index 29373f5286..d75233adf8 100644 --- a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md +++ b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails.md @@ -292,6 +292,19 @@ Example entry: > **Important:** Do NOT use `--kind Process` with `Type: "webApp"` to find Action Center apps. Those entries are the code-behind processes — their `Key` values are process release GUIDs, not app deployment IDs. Using them as `app.id` will cause runtime resolution failures. +**Step 1 completion gate — both branches MUST run `resources get`:** + +- Exact app row found: immediately run + `uip solution resources get "" --output json`. +- No exact app row/key found: immediately run + `uip solution resources get "" --output json` once and + treat its failure as `GET_ERROR`. + +Do not edit files, refresh, validate, or respond to the user between +`resources list` and this required `resources get` attempt. A missing catalog +row is not a completed schema check and is never permission to skip the +command. + **Step 2 — Verify the app exposes the guardrail action-schema contract** (do this **before** writing the guardrail JSON — an incompatible app must be rejected, not authored). **Required command gate:** execute @@ -300,13 +313,6 @@ app before deciding whether it is compatible. The `resources list` row is not an action schema and cannot replace this command. Do not write or reject the guardrail until the returned action schema has been checked. -If Step 1 returns no exact-name row and therefore no key, the command attempt -is still mandatory: execute -`uip solution resources get "" --output json` exactly once -and treat its failure as `GET_ERROR`. A missing catalog row is not permission to -skip `resources get`; this terminal lookup is required before rejecting the -requested escalation app. - A guardrail escalation app must expose a specific action-schema contract. If verification fails, stop and report to the user: ` does not have the required action schema configuration for tool guardrails.` (replace `` with the app's `Name` from Step 1). Do NOT write the guardrail. `uip solution resources get` returns the app's action schema in one CLI-native call — no auth handling, no Apps API endpoints. Pipe its output into a verifier that confirms every required argument name. The CLI handles authentication, so Claude never touches the auth file or the token. From 2f9ec36e5ca5fc9b5aac2c4ff162b9f3bbef6aa5 Mon Sep 17 00:00:00 2001 From: Andrei Petraru Date: Fri, 24 Jul 2026 09:04:14 +0300 Subject: [PATCH 5/5] fix(guardrails): preserve literal tool predicates --- .../guardrails/guardrails-recommend.md | 24 +++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) 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 dd5e965d66..814dc9969f 100644 --- a/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md +++ b/skills/uipath-agents/references/lowcode/capabilities/guardrails/guardrails-recommend.md @@ -73,20 +73,29 @@ its input or output (literal word/phrase, regex, number, boolean, or always), use the custom deterministic recipe below. This decision happens before built-in catalog candidate ranking: -1. Read the Tool's `resource.json.name` and use that exact value as the only +1. Treat quoted text and a distinct all-caps token such as `CONFIDENTIAL` as + an exact literal predicate, even when the surrounding request is phrased + semantically (for example, "worried it might publish CONFIDENTIAL content" + or "what guardrails should I add?"). Do not broaden that literal into a + semantic confidentiality classification. +2. Read the Tool's `resource.json.name` and use that exact value as the only entry in `selector.matchNames`. -2. Set `$guardrailType: "custom"` and `selector.scopes: ["Tool"]`. This branch +3. Set `$guardrailType: "custom"` and `selector.scopes: ["Tool"]`. This branch does not use a `builtInValidator` or `validatorParameters`. -3. For a literal word or phrase, use `$ruleType: "word"`, +4. For a literal word or phrase, use `$ruleType: "word"`, `operator: "contains"`, and preserve the exact requested literal as `value`. Use the matching custom rule type when the user explicitly requests a regex, number, boolean, or always condition. -4. Use a blocking action when the request says to prevent the Tool operation, +5. Use a blocking action when the request says to prevent the Tool operation, then build the complete object from [guardrails.md](guardrails.md). Broad semantic threats without an exact mechanical predicate continue through the built-in catalog ranking in Step 2. +Once this deterministic branch matches, the catalog/list calls remain +mandatory discovery steps but cannot replace or override the custom rule with +`llm_as_judge`, PII detection, or any other built-in validator. + ### Step 2 — Catalog-Driven Recommendation Analysis For **each entry** in the catalog (`guardrails[]` array from the cached JSON): @@ -177,6 +186,13 @@ Write the new guardrail blocks to `agent.json`'s `guardrails[]` array. Then run: uip agent validate "" --output json ``` +**Deterministic completion gate:** when the request matched the exact +named-Tool branch, re-read `agent.json` before validation and confirm the +written entry has `$guardrailType: "custom"`, Tool scope, the exact Tool name, +and the requested custom rule type/value. If a built-in validator was written, +replace it with the required custom rule before running validation or +reporting completion. + Report to the user: - What was added (by name) - Why it was recommended (cite the catalog's `when_to_use` or a specific `use_cases` item that matched the agent's context)