@uipath/skills 1.196.0 → 1.197.0

package/skills/uipath-admin/references/identity-troubleshoot-guide.md

@@ -0,0 +1,251 @@
+# Identity & Authorization Troubleshooting Guide
+
+Common investigation playbooks for identity, access, and security issues. Each starts from a user-reported symptom and resolves to a diagnosis using `uip admin` commands.
+
+> Every command assumes the user has run `uip login`. Every command uses `--output json`.
+
+---
+
+## Playbook 1 — "User can't access resource X"
+
+**Symptom:** "Alice can't publish to the Finance folder" / "Bob gets 403 on the API" / "The new contractor has no access to anything"
+
+**Root causes (most → least common):**
+1. Missing role assignment at the correct scope
+2. Role exists but lacks the specific permission
+3. User not in the expected group
+4. User account disabled or not yet activated
+
+### Step 1 — Resolve the principal
+
+```bash
+uip admin users list --search "<EMAIL_OR_NAME>" --output json
+```
+
+Extract the user's `id` (GUID) and `isActive` status. If `isActive` is `false`, the user is deactivated — that's the diagnosis. Otherwise proceed.
+
+### Step 2 — Check effective access
+
+```bash
+uip admin authorization check-access <USER_GUID> --scope Tenant --output json
+```
+
+Or for folder-level:
+
+```bash
+uip admin authorization check-access <USER_GUID> --scope Folder --folder-id <FOLDER_UUID> --output json
+```
+
+Inspect `Data.roleAssignments[]` — each entry shows `roleName`, `scopeType`, and `securityPrincipalType` (`direct` = assigned to the user; `inherited` or `Group` = inherited from a group). Look for whether the needed permission (e.g., `Publish`) appears anywhere. If absent, that's the gap.
+
+### Step 3 — List current role assignments
+
+```bash
+uip admin authorization roles assignments list --identity-id <USER_GUID> --output json
+```
+
+Compare the user's assignments against what's needed. Check `ownerServiceName` and `scopeType` — a role scoped to `Organization` won't grant folder-level permissions.
+
+### Step 4 — Check group membership
+
+```bash
+uip admin groups list --output json
+```
+
+For each relevant group, check if the user is a member. If the user should inherit permissions via a group but isn't in it, that's the gap:
+
+```bash
+uip admin groups members list <GROUP_ID> --output json
+```
+
+### Step 5 — Diagnose and recommend
+
+Present findings as:
+- **Principal:** `<displayName> (<email>) — <id>`
+- **Current access:** list of roles + scopes
+- **Missing:** specific role or permission needed
+- **Fix:** "Assign role X at scope Y" or "Add user to group Z"
+
+---
+
+## Playbook 2 — "Suspicious login activity"
+
+**Symptom:** "Failed login attempts" / "Account may be compromised" / "Unknown logins from strange locations"
+
+**Scope: `org`.** Login events (User Login, Robot Login, External App Login) are org-level audit events under Identity → Authentication.
+
+### Step 1 — Resolve the user
+
+```bash
+uip admin users list --search "<EMAIL>" --output json
+```
+
+Extract the `id` for `--user-id` filtering.
+
+### Step 2 — Discover login event types
+
+```bash
+uip admin audit org sources --output json > /tmp/sources.json
+```
+
+Extract the User Login type GUID:
+```bash
+jq -r '.Data[] | select(.name == "Identity") | .eventTargets[] | select(.name == "Authentication") | .eventTypes[] | select(.name == "User Login") | .id' /tmp/sources.json
+```
+
+### Step 3 — Query login events
+
+```bash
+uip admin audit org events \
+  --user-id <USER_GUID> \
+  --type    <USER_LOGIN_TYPE_GUID> \
+  --from-date <START_ISO8601> \
+  --to-date   <END_ISO8601> \
+  --limit 100 \
+  --output json
+```
+
+### Step 4 — Analyze
+
+For each event in `Data.auditEvents[]`, check:
+- `status` — `0` = Success, `1` = Failure
+- `clientInfo` — parse JSON string for `ipAddress` and `ipCountry`
+- `createdOn` — timestamp (UTC)
+
+Flag: multiple failures from different IPs, logins from unexpected countries, or logins outside business hours.
+
+---
+
+## Playbook 3 — "Role misconfiguration"
+
+**Symptom:** "Custom role doesn't grant what it should" / "User has a role but still can't do X"
+
+### Step 1 — Inspect the role
+
+```bash
+uip admin authorization roles list --output json
+```
+
+Find the role by name, then:
+
+```bash
+uip admin authorization roles get <ROLE_ID> --output json
+```
+
+Check `actions[]` — these are the permission strings (e.g., `OR.Folders.Create`). Compare against the Permission Catalog:
+
+```bash
+uip admin authorization permissions list --service <SERVICE> --output json
+```
+
+### Step 2 — Verify scope alignment
+
+The role's `scopeType` (Organization / TenantGlobal / Tenant / Project) must match the assignment scope. A role scoped to `Organization` cannot be assigned at `Folder` scope. Check the assignment:
+
+```bash
+uip admin authorization roles assignments list --identity-id <USER_GUID> --output json
+```
+
+Verify `ownerServiceName` matches the scope-path service segment (Rule 17 from SKILL.md).
+
+### Step 3 — Diagnose
+
+Common misconfigurations:
+- **Scope mismatch:** role is `Tenant` but user needs folder-level access → create a `Project`-scoped role or use Orchestrator folder roles instead (`uip or roles`)
+- **Missing actions:** role omits required permissions → `roles update` with the full action set (re-fetch first — Rule 12)
+- **Wrong service:** role's `ownerServiceName` doesn't match the target service
+
+---
+
+## Playbook 4 — "IP restriction lockout"
+
+**Symptom:** "Can't access the platform from new office" / "All users blocked" / "IP restriction locked us out"
+
+### Step 1 — Check enforcement status
+
+```bash
+uip admin ip-restriction enforcement get --output json
+```
+
+If `isEnabled` is `false`, IP restriction is not the cause — look elsewhere.
+
+### Step 2 — Check caller's IP
+
+```bash
+uip admin ip-restriction my-ip --output json
+```
+
+Returns `Data.ipAddress` — the public IP the platform sees for the caller.
+
+### Step 3 — List allowed ranges
+
+```bash
+uip admin ip-restriction ip-ranges list --output json
+```
+
+Compare the caller's IP against every entry's CIDR range. If the IP is not covered by any entry, that's the lockout cause.
+
+### Step 4 — Check bypass rules
+
+```bash
+uip admin ip-restriction bypass-rules list --output json
+```
+
+Bypass rules exempt specific URL patterns from IP restriction. If the affected access is via an API endpoint matching a bypass pattern, the IP restriction should not apply — investigate other causes.
+
+### Step 5 — Resolution options
+
+- **Add the new IP/CIDR:** `ip-ranges create --name "<LOCATION>" --cidr <CIDR> --output json`
+- **Disable enforcement temporarily:** `ip-restriction enforcement disable --output json` (if accessible from an allowed IP)
+- **Platform recovery:** if fully locked out, use the Portal recovery flow (no CLI bypass exists — Rule 32)
+
+---
+
+## Playbook 5 — "PAT or external app not working"
+
+**Symptom:** "API calls return 401" / "PAT stopped working" / "External app can't authenticate"
+
+### Step 1 — List PATs or external apps
+
+For PATs:
+```bash
+uip admin pat list --output json
+```
+
+Check `expiration` — expired PATs return 401 silently. If the token is absent from the list, it was revoked (revocation is a hard delete — no `isRevoked` flag exists).
+
+For external apps:
+```bash
+uip admin external-apps list --output json
+```
+
+### Step 2 — Verify scopes
+
+PATs and external apps are scoped — if the API call requires `OR.Execution` but the token only has `OR.Folders.Read`, the call fails.
+
+For external apps, check the declared scopes against the API endpoint's requirement. For PATs, re-create with the correct `--scope`.
+
+### Step 3 — Check audit for revocation
+
+Query org audit for recent identity events — a PAT or app secret may have been revoked:
+
+```bash
+uip admin audit org sources --output json
+# Find Identity source → PersonalAccessTokens or ExternalApps target
+uip admin audit org events \
+  --source <IDENTITY_SOURCE_GUID> \
+  --from-date <RECENT_WINDOW> \
+  --to-date <NOW> \
+  --limit 50 \
+  --output json
+```
+
+---
+
+## Cross-reference
+
+- Audit event investigation workflows → [audit-workflow-guide.md](audit-workflow-guide.md)
+- Role management (create/update custom roles) → [authorization/role-management.md](authorization/role-management.md)
+- Role assignment scope validation → [authorization/role-assignment-management.md](authorization/role-assignment-management.md)
+- Permission catalog lookup → [authorization/permission-catalog.md](authorization/permission-catalog.md)
+- IP restriction management → [ip-restriction/ip-restriction-commands.md](ip-restriction/ip-restriction-commands.md)

package/skills/uipath-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: uipath-agents
-description: "End-to-end work with UiPath Agents of all types: build, integrate with UiPath Products (e.g., Orchestrator, Flow, Maestro), design with UiPath Tools (e.g., Agent Builder/Studio Web), and deploy. Covers Coded Agents (e.g., LangGraph, LlamaIndex, OpenAI Agents) and Low-Code Agents (`agent.json` / Agent Builder). Excludes coded functions / Functions SDK (separate skill)."
+description: "End-to-end work with UiPath Agents of all types: build, integrate with UiPath Products (e.g., Orchestrator, Flow, Maestro), design with UiPath Tools (e.g., Agent Builder/Studio Web), deploy, and configure/validate. Covers Coded Agents (e.g., LangGraph, LlamaIndex, OpenAI Agents) and Low-Code Agents (`agent.json` / Agent Builder). For deterministic Python Coded Functions (`uip functions`, `uipath.json` functions map, no agent runtime/LLM)→uipath-functions."
 when_to_use: "Must use when user mentions or implies any Agent lifecycle phase - e.g., auth, design, scaffold, Studio Web sync, flow integration, editing, pack/deploy/version bump, eval, debug, tracing, guardrails, memory spaces, bindings, attachments. Example requests: 'create/build a UiPath agent', 'build a low-code / Agent Builder agent', 'add agent memory spaces', 'build a coded / Python agent (LangGraph / LlamaIndex / OpenAI Agents)', 'scaffold an agent project', 'run / debug / evaluate / deploy my agent'."
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, WebFetch
 user-invocable: true
@@ -13,18 +13,21 @@ user-invocable: true
 - Treat "build/create/scaffold/implement a UiPath agent" as the full One-Prompt Flow by default. Do not stop after file creation or local run unless the user explicitly says to stop there.
 - A normal completion point is after smoke eval and the mandatory Delivery fork question. A final build summary before that is premature unless run/eval is blocked or the user opted out.
 - **Probe the `solution` verb once per session before the first scaffold or deploy.** Run `uip solution init --help --output json`. Result `Success` → use `solution init` and `solution deploy run --parent-folder-path` / `--parent-folder-key` (post-rename, default). `unknown command` / non-zero exit → CLI predates the rename; substitute `uip solution new <Name>` and `--folder-path` / `--folder-key` (same arguments otherwise) wherever this skill calls those.
+- **Greenfield coded agents — scaffold with `uip codedagent new`, never hand-author the project.** Building a NEW coded agent from scratch: always create it with `uip codedagent new <name>`, then generate schemas with `uip codedagent init` — never hand-write `pyproject.toml` / `main.py` / `langgraph.json` / `entry-points.json` yourself, even for a trivial agent. Hand-authoring skips required project structure and produces invalid packages. (Existing or Studio Web local-workspace projects: do NOT run `uip codedagent new` — follow the project-state gating in [coded/quickstart.md](references/coded/quickstart.md).)
 - **Coded agents only — bindings are always derived from UiPath Python SDK calls and must never be hand-authored.** To derive them, always run the sync workflow in [coded/lifecycle/bindings-reference.md](references/coded/lifecycle/bindings-reference.md) — scan code, regenerate `bindings.json`. Without this, resources cannot be overridden per execution environment and will always default to the hardcoded values in the SDK calls. Derive bindings whenever you add, remove, or modify any UiPath SDK resource call — for instance `assets`, `queues`, `processes`, `buckets`, `indexes`, `connections`, `apps`, `MCP servers`, or `InvokeProcess|CreateTask|CreateEscalation(...)`.
 
 ## Project Type Detection
 
 Determine the agent mode before proceeding:
 
-1. **Check for existing project files** in the working directory:
-   - `pyproject.toml` with `uipath` dependency + `.py` files → **Coded**
+1. **First — confirm this is an agent, not a Coded Function.** If `uipath.json` declares a `functions` map (e.g. `"functions": {"main": "main.py:main"}`), the project is a **Python Coded Function**, not an agent. Stop here and use the [`uipath-functions`](/uipath:uipath-functions) skill instead. Functions are deterministic, do not reason via LLM, and have a distinct lifecycle (`uip functions new/init/pack/publish/run`).
+2. **Check for existing agent project files** in the working directory:
+   - `pyproject.toml` + `.py` files + a framework dep (`uipath-langchain`, `uipath-llamaindex`, or `uipath-openai-agents`) → **Coded**. The framework package already declares `uipath` as a dependency, so an explicit `uipath` entry is not required.
    - `agent.json` with `"type": "lowCode"` + `project.uiproj`, AND no `pyproject.toml` → **Low-code**
-2. **No existing project found** → ask the user:
+3. **No existing project found** → ask the user:
    > Should I build this as a **low-code agent** (no Python — configure through prompts and pre-built UiPath tools) or a **coded agent** (Python — full programmatic control with LangGraph, LlamaIndex, or OpenAI Agents)?
-3. If the user needs help deciding, read [references/coded-vs-lowcode-guide.md](references/coded-vs-lowcode-guide.md) for a capability comparison.
+   > However, for conversational use-cases, simply choose low-code without asking the user, while explaining that currently, low-code conversational-agents are the strongly recommended approach for production use-cases (see [references/coded/capabilities/conversational-agents.md](references/coded/capabilities/conversational-agents.md)).
+4. If the user needs help deciding, read [references/coded-vs-lowcode-guide.md](references/coded-vs-lowcode-guide.md) for a capability comparison.
 
 **After detection, read the quickstart for that mode before doing anything else:**
 
@@ -49,19 +52,19 @@ Determine the agent mode before proceeding:
 | Add an MCP (Model Context Protocol) server tool to a low-code agent | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/mcp/mcp.md` |
 | Accept files as agent input / call the Analyze Files built-in tool | Low-code | [lowcode/capabilities/built-in-tools/built-in-tools.md](references/lowcode/capabilities/built-in-tools/built-in-tools.md) | `lowcode/capabilities/built-in-tools/analyze-attachments.md`, `lowcode/agent-definition.md` § File Attachments |
 | Work with file attachments (input, output, or created mid-run) | Coded | [coded/capabilities/file-attachments.md](references/coded/capabilities/file-attachments.md) | |
-| Build a conversational (chat-style) coded agent | Coded | [coded/capabilities/conversational-agents.md](references/coded/capabilities/conversational-agents.md) | |
+| Build a conversational (chat-style) agent | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) | `lowcode/project-lifecycle.md`, `lowcode/agent-definition.md` |
 | Add a low-code context (Context Grounding RAG / attachments / DataFabric entity set) | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/context/*` |
 | Add a low-code memory space or seed memory items | Low-code | [lowcode/capabilities/memory/memory.md](references/lowcode/capabilities/memory/memory.md) | use `uip agent memory`, then refresh/validate |
 | Add an Action Center escalation (HITL) to a low-code agent | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/escalation/escalation.md` |
 | Add guardrails (PII, harmful content, custom rules) to a low-code agent | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/guardrails/guardrails.md` |
-| Add guardrails to a coded agent | Coded | [coded/capabilities/guardrails/guardrails.md](references/coded/capabilities/guardrails/guardrails.md) | fetch official docs via WebFetch, ask middleware vs decorator, read agent code, write Python |
+| Add a new guardrail to a coded agent | Coded | [coded/capabilities/guardrails/guardrails.md](references/coded/capabilities/guardrails/guardrails.md) | fetch official docs via WebFetch, ask middleware vs decorator, read agent code, write Python |
 | Add escalation guardrail (escalate action / Action Center app) | Low-code | [lowcode/capabilities/guardrails/guardrails.md](references/lowcode/capabilities/guardrails/guardrails.md) § escalate — Hand Off to Action Center | Run `uip solution resources list --kind App --source remote --output json` to confirm app exists |
 | Recommend guardrails for a low-code agent based on its context | Low-code | [lowcode/capabilities/guardrails/guardrails-recommend.md](references/lowcode/capabilities/guardrails/guardrails-recommend.md) | fetch catalog + list, analyze agent context, apply + validate |
 | Recommend guardrails for a specific scope or tool | Low-code | [lowcode/capabilities/guardrails/guardrails-recommend.md](references/lowcode/capabilities/guardrails/guardrails-recommend.md) § Scoped or Tool-Specific Filtering | filter candidates by scope or tool name after catalog analysis |
 | Validate whether existing guardrails are correctly configured | Low-code | [lowcode/capabilities/guardrails/guardrails-recommend.md](references/lowcode/capabilities/guardrails/guardrails-recommend.md) § Validate Mode | check correctness, actionability, and relevance per guardrail |
 | Recommend guardrails for a coded agent based on its context | Coded | [coded/capabilities/guardrails/guardrails-recommend.md](references/coded/capabilities/guardrails/guardrails-recommend.md) | fetch catalog + list + SDK docs, analyze agent code, apply + verify |
 | Recommend guardrails for a specific scope or tool (coded) | Coded | [coded/capabilities/guardrails/guardrails-recommend.md](references/coded/capabilities/guardrails/guardrails-recommend.md) § Scope and Tool Filtering | filter candidates by `@tool` function or scope after catalog analysis |
-| Validate whether existing coded guardrails are correctly configured | Coded | [coded/capabilities/guardrails/guardrails-recommend.md](references/coded/capabilities/guardrails/guardrails-recommend.md) § Validate Mode | check correctness, actionability, and relevance per guardrail |
+| Check, validate, diagnose, or fix whether an existing coded guardrail is correctly configured (placement / scope) | Coded | [coded/capabilities/guardrails/guardrails-recommend.md](references/coded/capabilities/guardrails/guardrails-recommend.md) § Validate Mode | **fetch SDK docs first (authoritative for scope/placement)**; also fetch catalog + list for relevance/entitlement — then check correctness, actionability, and relevance — fix in place |
 | Embed a low-code agent inline in a flow, or wire a multi-agent solution | Low-code | [lowcode/lowcode.md](references/lowcode/lowcode.md) § Capability Registry | `lowcode/capabilities/inline-in-flow/inline-in-flow.md`, `lowcode/capabilities/process/solution-agent.md` |
 | Run low-code evaluations | Low-code | [lowcode/evaluations/evaluate.md](references/lowcode/evaluations/evaluate.md) | `lowcode/evaluations/evaluators.md`, `lowcode/evaluations/evaluation-sets.md`, `lowcode/evaluations/running-evaluations.md` |
 | Run offline evals for a published Orchestrator package | Low-code | [lowcode/evaluations/orchestrator-eval-run.md](references/lowcode/evaluations/orchestrator-eval-run.md) | Use `uip or eval run-offline-evals` (requires package published to Orchestrator) |
@@ -74,6 +77,7 @@ Determine the agent mode before proceeding:
 | Summarize / research / synthesize over PDF or TXT (DeepRAG, low-code) | Low-code | [context-grounding-patterns.md](references/context-grounding-patterns.md) | [lowcode/capabilities/built-in-tools/deeprag/planning.md](references/lowcode/capabilities/built-in-tools/deeprag/planning.md) |
 | Process CSV rows with LLM per row (BatchTransform, coded) | Coded | [context-grounding-patterns.md](references/context-grounding-patterns.md) | [coded/capabilities/batch-transform/planning.md](references/coded/capabilities/batch-transform/planning.md) |
 | Process CSV rows with LLM per row (BatchTransform, low-code) | Low-code | [context-grounding-patterns.md](references/context-grounding-patterns.md) | [lowcode/capabilities/built-in-tools/batch-transform/planning.md](references/lowcode/capabilities/built-in-tools/batch-transform/planning.md) |
+| Manage context-grounding indexes from the CLI (list / create / ingest / search) | Platform | [`uipath-platform/references/context-grounding/index-management.md`](../uipath-platform/references/context-grounding/index-management.md) | `uip context-grounding` — cross-cutting CLI, owned by `uipath-platform` |
 
 ## Resources
 

package/skills/uipath-agents/references/coded/capabilities/context-grounding.md

@@ -17,6 +17,8 @@ Before using context grounding, you must first create an index in your Orchestra
 
 Once indexed, you can reference the index by name in your agent code.
 
+To create, ingest, poll, search, or delete the index from the CLI instead of the Orchestrator UI, see [uipath-platform/references/context-grounding/index-management.md](../../../../uipath-platform/references/context-grounding/index-management.md).
+
 ## Folder Targeting
 
 Context Grounding indexes live in Orchestrator folders. Pass a folder identifier whenever the index is not in the default folder resolved from your auth context — otherwise the service may return `400 FolderKey required`. `ContextGroundingRetriever` accepts `folder_path` or `folder_key`; `ContextGroundingVectorStore` accepts `folder_path`.

package/skills/uipath-agents/references/coded/capabilities/conversational-agents.md

@@ -1,5 +1,7 @@
 # Conversational Agents
 
+> **Coded conversational agents are currently not intended for production use-cases.** For conversational use-cases, use **low-code conversational agents** by referring to [../../lowcode/lowcode.md](../../lowcode/lowcode.md). Only use coded conversational agents if the user is strongly requesting to use coded agents and the agent will only be tested and ran on a local machine.
+
 Chat-style coded agents where the UiPath runtime feeds **one message per turn** and threads history across turns.
 
 Supported on **LangGraph** and **LlamaIndex**. Coded Function and OpenAI Agents are not conversational.

package/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails-recommend.md

@@ -12,6 +12,8 @@ Both workflows are driven by live data — the catalog (`uip agent guardrails ca
 
 ## Step 0 — Fetch Catalog, Available Validators, and SDK Docs (MANDATORY — do this before any analysis)
 
+> 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).
+
 ### 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.
@@ -160,12 +162,14 @@ Always confirm the chosen scope is in the validator's `allowed_scopes` from the
 
 ### Step 6 — Choose the Action
 
-The action (`BlockAction` vs `LogAction`) is **not** a free choice — default to the `action_type` in the catalog entry's representative `examples[].config`. For security-critical guardrails (`adversarial_input` — prompt injection / user prompt attacks; `content_safety` — harmful content / IP) the catalog examples use **Block**, because a logged-but-allowed violation provides no actual protection.
+The action (`BlockAction` vs `LogAction` vs `EscalateAction`) is **not** a free choice — default to the `action_type` in the catalog entry's representative `examples[].config`. For security-critical guardrails (`adversarial_input` — prompt injection / user prompt attacks; `content_safety` — harmful content / IP) the catalog examples use **Block**, because a logged-but-allowed violation provides no actual protection.
+
+**`EscalateAction` (human-in-the-loop)** is a third option — recommend it when the user wants a **human to review/approve** a flagged item rather than hard-block it (high-stakes or sensitive content where a person should approve or edit before the run proceeds). It **suspends** the run for review and resumes on Approve (terminates on Reject). **Prerequisite:** the fetched SDK docs expose `EscalateAction`, and a deployed Action App is declared in `bindings.json` via the coded-agent bindings sync workflow — see [guardrails.md § Escalation action (HITL)](guardrails.md#escalation-action-human-in-the-loop). If the user asks for escalation but the SDK docs or Action App are unavailable, say so and fall back to Block/Log rather than authoring a guardrail that fails at runtime.
 
 Rules:
 
 1. **Default to the catalog example's `action_type`.** If it is `Block`, generate `BlockAction(...)`. Do not substitute `LogAction` for a security-critical guardrail on your own initiative.
-2. **Never silently downgrade Block → Log.** A guardrail set to log-only when the user expected blocking is the dangerous failure mode — the agent looks protected but isn't. If you use `LogAction` for any guardrail whose catalog default is `Block`, you **must** state it explicitly in the report and give the reason.
+2. **Never silently downgrade Block → Log** (or a requested escalation → Log/Block). A guardrail set to log-only when the user expected blocking is the dangerous failure mode — the agent looks protected but isn't. If you use `LogAction` for any guardrail whose catalog default is `Block`, you **must** state it explicitly in the report and give the reason. If the user asked for **human review** (escalation) but you author Block/Log instead (e.g. no Action App available), say so explicitly — don't quietly drop the human-in-the-loop step.
 3. **Legitimate reasons to use Log instead of Block** (state which applies):
    - The user explicitly asked for observe-only / audit / "log first, block later" rollout.
    - A high false-positive risk where blocking would break normal operation (e.g. PII `PERSON` entity flagging ordinary words) — log so the user can tune thresholds before enforcing.
@@ -188,7 +192,7 @@ Map catalog parameter shapes to Python:
 | `map-enum` (e.g. `entityThresholds`) | Dict from enum member → number (e.g. `{PIIDetectionEntityType.EMAIL: 0.5}`) — keys must exactly match the `enum-list` parameter's values |
 | `number` (e.g. `threshold`) | Plain `float` / `int` constructor argument |
 
-Use `BlockAction(...)`, `LogAction(severity_level=...)`, or other actions exposed by the SDK docs. Never invent action class names.
+Use `BlockAction(...)`, `LogAction(severity_level=...)`, or `EscalateAction(app_name=..., app_folder_path=..., recipient=...)` for human-in-the-loop review — or any other action the SDK docs expose. Never invent action class names. For `EscalateAction`, the fetched SDK docs must expose the class/parameters, and the Action App must be deployed and declared in `bindings.json` using [../../lifecycle/bindings-reference.md](../../lifecycle/bindings-reference.md) (see [guardrails.md § Escalation action (HITL)](guardrails.md#escalation-action-human-in-the-loop)).
 
 > Read [guardrails.md](guardrails.md) before writing any Python. The middleware spread, decorator stacking, and factory refactor rules cannot be safely inferred.
 
@@ -217,7 +221,7 @@ Report to the user:
 
 Use when the agent already has guardrails and the user asks whether they are correctly configured or appropriate.
 
-**Before any validation, run all three Step 0 fetches** (catalog with cache, guardrails list without cache, SDK docs via WebFetch). The SDK docs are the authoritative source for which Python class corresponds to which `validator_id` and which scopes/stages each class supports.
+**Fetch the SDK docs first (WebFetch) — they are the authoritative source** for which Python class corresponds to which `validator_id` and which scopes/stages each class supports; a scope/placement diagnosis is grounded there. Also run the `catalog` and `list` fetches to support the Relevance (`when_not_to_use`) and entitlement checks below — recommended, but not a hard prerequisite once the SDK docs settle the scope question.
 
 For each existing guardrail discovered in the Python file (Step 1 from Recommend Mode):
 
@@ -236,11 +240,11 @@ From the SDK docs and the catalog, look up the validator class referenced in the
 
 ### Actionability Check
 
-1. From the catalog entry, read `allowed_scopes` and the per-scope allowed stages.
+1. Read the validator's allowed scopes and per-scope stages from the **SDK docs** (authoritative for coded); cross-check against the `catalog` entry's `allowed_scopes` when it was fetched.
 2. Confirm the in-code scope is permitted:
    - Middleware — every `GuardrailScope` in the `scopes=[...]` argument is in `allowed_scopes`.
    - Decorator — the function the `@guardrail` decorates matches the implied scope: `@tool` for Tool scope, LLM factory for LLM scope, agent factory for Agent scope.
-3. Confirm the stage is permitted: `GuardrailExecutionStage.PRE` only where catalog allows pre-execution; `POST` only where catalog allows post-execution.
+3. Confirm the stage is permitted. **Middleware takes no `stage=` argument** — the validator fixes its stage (e.g. `intellectual_property` POST, `user_prompt_attacks` PRE), so do not flag a missing stage. The stage check applies only to the **decorator** `stage=`: `GuardrailExecutionStage.PRE` only where catalog allows pre-execution; `POST` only where catalog allows post-execution.
 4. For Tool-scoped middleware: `tools=[...]` must contain the actual `@tool` Python objects discovered in Step 1 — not strings, not undefined names.
 5. For decorator-style LLM/Agent scope: the decorated function must actually return a `UiPathChat(...)` / `create_agent(...)` — decorating an unrelated function silently no-ops.
 
@@ -268,7 +272,7 @@ python3 -c "import ast; ast.parse(open('graph.py').read())"
 
 ## Critical Rules
 
-1. **Always fetch catalog first** (use cache if fresh); **always fetch guardrails list second** (no cache); **always fetch the two SDK doc pages via WebFetch third** (no cache). All three are required before any analysis or code edit.
+1. **Recommend mode / net-new adds:** fetch catalog first (use cache if fresh), guardrails list second (no cache), and the two SDK doc pages via WebFetch third (no cache) — all three required before any analysis or code edit. **Validate mode of an existing guardrail:** the SDK docs are the authoritative, sufficient grounding for a scope/placement fix; still fetch catalog + list for the Relevance and entitlement checks, but they are not a hard prerequisite.
 2. **If `GuardrailCatalogUnavailable`** → surface the message and stop. Do not fall back to guessing or hardcoded recommendations.
 3. **Only recommend `Available` validators**. Mention `Unauthorised` ones to the user so they can contact their administrator.
 4. **Every recommendation must cite** the catalog entry's `when_to_use` or a specific `use_cases` item that matched the agent's context. Do not recommend a guardrail without explaining why it applies.
@@ -282,3 +286,4 @@ python3 -c "import ast; ast.parse(open('graph.py').read())"
 12. **The cache file is `.guardrails-catalog-cache.json`** in the working directory. Add it to `.gitignore` if one exists.
 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).

package/skills/uipath-agents/references/coded/capabilities/guardrails/guardrails.md

@@ -4,6 +4,8 @@ Add guardrails to a Python coded agent (LangChain/LangGraph) in two styles: **mi
 
 > **The user tells you which guardrail to add. You derive the full list of available guardrails and their configuration from the official documentation — fetch it at the start of every task.**
 
+> **Validating or fixing an EXISTING guardrail? Start elsewhere.** If the task is to check / diagnose whether a guardrail is configured correctly, or to fix a misplaced / misconfigured one (even if you will also edit code), follow [guardrails-recommend.md § Validate Mode](guardrails-recommend.md) FIRST — that workflow is mandatory for diagnosis. This page covers adding a **new** guardrail.
+
 ---
 
 ## Step 0 — Fetch Official Documentation
@@ -22,6 +24,15 @@ Add guardrails to a Python coded agent (LangChain/LangGraph) in two styles: **mi
 - Entity type names or their allowed values
 - Import paths
 
+When available, the `langchain/guardrails/` page documents three actions — **`LogAction`**, **`BlockAction`**, and
+**`EscalateAction`** (human-in-the-loop). Treat the fetched page as the source of truth for `EscalateAction`'s
+parameters, supported scopes, and stages; the operational wiring it doesn't cover (the suspend->resume UX, the
+Action-App prerequisite, `bindings.json`, recipient routing) is in [Escalation action (HITL)](#escalation-action-human-in-the-loop) below.
+
+If the fetched SDK docs do **not** expose `EscalateAction` or its constructor parameters, stop and report that the
+installed/published SDK documentation does not currently support HITL guardrail escalation. Do not generate
+`EscalateAction` code from memory or from this operational section alone.
+
 ---
 
 ## Check Tenant Availability (mandatory for built-in AI validators)
@@ -87,13 +98,16 @@ Before writing the import line, identify the framework by reading the agent code
 ```python
 from uipath_langchain.guardrails import (
     guardrail,
-    BlockAction, LogAction,
+    BlockAction, LogAction, EscalateAction,
     PIIValidator, PIIDetectionEntity, PIIDetectionEntityType,
     HarmfulContentValidator, HarmfulContentEntity, HarmfulContentEntityType,
     UserPromptAttacksValidator,
     GuardrailExecutionStage,
     # ...only the names you actually use
 )
+from uipath.core.guardrails import GuardrailScope
+# Only when routing an EscalateAction task to a specific reviewer:
+from uipath.platform.action_center.tasks import TaskRecipient, TaskRecipientType
 ```
 
 ❌ `from uipath.platform.guardrails import guardrail, PIIValidator, ...` in a LangChain agent — type-checks but the LangChain adapter never registers; guardrails silently no-op.
@@ -140,6 +154,49 @@ When the fetched docs show a middleware supports TOOL scope, it requires passing
 ),
 ```
 
+### LLM- / Agent-scoped middleware
+
+Pass `scopes=[GuardrailScope.LLM]` or `[GuardrailScope.AGENT]`. No `tools=`.
+
+```python
+*SomeMiddlewareClass(
+    name="...",
+    scopes=[GuardrailScope.LLM],   # or GuardrailScope.AGENT
+    action=...,
+),
+```
+
+`scopes` is required on most middleware. Exceptions: LLM-only validators (`UiPathUserPromptAttacksMiddleware`, `UiPathPromptInjectionMiddleware`) make `scopes` optional — it defaults to LLM. Passing `scopes=[GuardrailScope.LLM]` and omitting it are equivalent; AGENT/TOOL are rejected.
+
+### Stage is fixed by the validator — no `stage=` on middleware
+
+Middleware classes take **no `stage` argument**. Each validator's stage is fixed: input validators (`user_prompt_attacks`, `prompt_injection`, input PII) run PRE; `intellectual_property` runs POST (output-only). Adding `stage=GuardrailExecutionStage....` to a middleware call raises `TypeError`. Only the **decorator** (`@guardrail`) accepts `stage=`.
+
+### Intellectual property (output-only) middleware
+
+> **`scopes=` is REQUIRED** on `UiPathIntellectualPropertyMiddleware` (and on PII / harmful-content middleware). It has no default — omitting it raises `TypeError: missing 1 required positional argument: 'scopes'`. Always pass `scopes=[GuardrailScope.LLM]` or `[GuardrailScope.AGENT]` (Tool not supported).
+
+```python
+from uipath_langchain.guardrails import (
+    BlockAction,
+    UiPathIntellectualPropertyMiddleware,
+    IntellectualPropertyEntityType,
+)
+from uipath.core.guardrails import GuardrailScope
+
+*UiPathIntellectualPropertyMiddleware(
+    name="Intellectual property",
+    scopes=[GuardrailScope.LLM],   # REQUIRED — LLM or AGENT; Tool not supported
+    action=BlockAction(),
+    entities=[
+        IntellectualPropertyEntityType.TEXT,
+        IntellectualPropertyEntityType.CODE,
+    ],
+),
+```
+
+Runs at POST (checks the LLM's output) — fixed by the validator, not a parameter.
+
 ---
 
 ## Decorator Style — Code Patterns
@@ -203,6 +260,83 @@ If `create_agent()` is called directly at module level (not in a function), wrap
 
 ---
 
+## Escalation action (human-in-the-loop)
+
+`EscalateAction` is a third action (beside `LogAction` / `BlockAction`) that turns a violation into a **human
+review step**: it suspends the run via `interrupt(CreateEscalation(...))`, creates a review task in a UiPath
+**Action App**, and resumes when a human **Approves** (optionally editing the flagged content — the reviewer's
+`ReviewedInputs` at PRE / `ReviewedOutputs` at POST is substituted back) or **Rejects** (raises → terminates,
+like `BlockAction`). Get the exact parameters / supported scopes / stages from the fetched
+`langchain/guardrails/` page; this section is the operational wiring that page doesn't cover.
+
+**The same `EscalateAction` works in both styles** — pass it as the `action`:
+
+```python
+# Middleware (no stage= — fixed by the validator)
+*UiPathPIIDetectionMiddleware(
+    name="PII escalation",
+    scopes=[GuardrailScope.AGENT],
+    action=EscalateAction(
+        app_name="Guardrail.Escalation.Action.App",
+        app_folder_path="Shared",
+        # optional — route the task; default assignment otherwise
+        recipient=TaskRecipient(type=TaskRecipientType.EMAIL, value="reviewer@example.com"),
+    ),
+    entities=[PIIDetectionEntity(PIIDetectionEntityType.EMAIL, 0.5)],
+),
+
+# Decorator — identical action, on a @tool / LLM factory / agent factory
+@guardrail(
+    validator=PIIValidator(entities=[PIIDetectionEntity(PIIDetectionEntityType.EMAIL, 0.5)]),
+    action=EscalateAction(app_name="Guardrail.Escalation.Action.App", app_folder_path="Shared"),
+    name="PII escalation",
+    stage=GuardrailExecutionStage.PRE,
+)
+def create_my_agent(): ...
+```
+
+`EscalateAction` is **action-only** — it works with any validator, including deterministic
+`CustomValidator(...)` rules (no AI-validator / tenant dependency for the validator itself).
+
+### Prerequisite — the Action App must exist and be declared in `bindings.json`
+
+Unlike Block/Log, escalation needs a **deployed Action App** in the tenant, referenced by `app_name` +
+`app_folder_path`. This is the **correct design** (not env vars):
+
+1. Discover the deployed app: `uip solution resources list --kind App --search "<app-name>" --output json`
+   (filter `"Type": "Workflow Action"`); note its `Name` and `Folder`. If it isn't deployed, tell the user — the
+   escalation fails at runtime otherwise. If multiple deployed Workflow Action apps share the same `Name` in
+   different folders, ask which folder to use.
+2. Pass those literal values to `EscalateAction(app_name=..., app_folder_path=...)`.
+3. Verify the app exposes the guardrail escalation action-schema contract before claiming it is runtime-ready:
+   inputs `GuardrailName`, `GuardrailDescription`, `TenantName`, `AgentTrace`, `Tool`, `ExecutionStage`,
+   `ToolInputs`, `ToolOutputs`; outputs `ReviewedInputs`, `ReviewedOutputs`, `Reason`; outcomes `Approve`,
+   `Reject`. If tenant/API access is unavailable in a local smoke task, author the structural code only when the
+   user supplied the exact app name/folder, and report that the deployed app schema was not verified.
+4. Sync the project's **`bindings.json`** with the code using
+   [../../lifecycle/bindings-reference.md](../../lifecycle/bindings-reference.md). Coded-agent bindings are derived
+   from resource-bearing code and must not be hand-authored ad hoc. The result must include a `resource: "app"`
+   entry so Studio/deploy can resolve and override the Action App (locally the literals are used). Canonical
+   examples: `samples/joke-agent/` (middleware) and `samples/joke-agent-decorator/` (decorator) in the
+   uipath-langchain repo — each ships a `bindings.json` with the escalation app and the literal
+   `app_name`/`app_folder_path` in code.
+
+### Escalation Action UX
+
+`EscalateAction` does **not** raise on violation (unlike `BlockAction`) — it **suspends** the run. Under local
+`uip codedagent run` a violation prints a `CreateEscalation` interrupt and the run pauses (no traceback); resume after
+acting on the task in Action Center:
+
+```bash
+uip codedagent run <ENTRYPOINT> --resume
+```
+
+On resume: **Approve** continues (with the reviewer's optional edit applied); **Reject** raises
+`AgentRuntimeError` and terminates the run. This is expected — distinct from `BlockAction` (immediate raise) and
+`LogAction` (logs, no control-flow change).
+
+---
+
 ## Verify Guardrails Are Actually Wired (mandatory after writing)
 
 **Syntactically valid ≠ active.** Because importing from the wrong module bypasses the framework adapter and makes guardrails silently no-op (see [Imports Pattern](#imports-pattern)), `ast.parse` passing tells you nothing about whether a single guardrail will ever fire. After writing, prove the wiring at runtime.
@@ -224,6 +358,8 @@ If either check fails, the most likely cause is importing guardrail symbols from
 For non-LangChain frameworks, there is no published adapter yet, so the decorator/middleware mechanism does not produce a `_Guarded*` wrap. Verify by invoking the validator directly on a known-violating input and confirming it raises / logs.
 
 > A smoke run that deliberately triggers a violation (e.g. feed a PII-bearing input and confirm it blocks) is the strongest verification when the environment is authenticated against the tenant.
+>
+> **For an `EscalateAction` guardrail the outcome differs:** a violating input **suspends** the run with a `CreateEscalation` interrupt — it does not block. Verify by confirming the run suspends and a review task is created, then that `uip codedagent run <ENTRYPOINT> --resume` continues after Approve / terminates after Reject. Don't expect a block/traceback.
 
 ---
 
@@ -248,3 +384,7 @@ For non-LangChain frameworks, there is no published adapter yet, so the decorato
 11. **Deterministic guardrails run locally** — no backend API call, no tenant availability check needed.
 12. **Do not duplicate existing guardrails** — read the agent code first and skip if the same guardrail is already configured.
 13. **Do not delegate the import-source decision (or guardrail authoring) to a subagent.** A dispatched subagent does not carry this skill's context and will report the module where the symbols physically live (`uipath.platform.guardrails`) — the no-op path for LangChain agents (Rule 8). It looks authoritative and silently overrides the correct `uipath_langchain.guardrails` choice. Fetch the docs and write the imports inline, where this skill's import rule still applies.
+14. **`EscalateAction` must come from the fetched SDK docs** — if the docs do not expose the class or constructor parameters, stop and report that HITL guardrail escalation is not available in the current SDK docs/runtime. Never invent the class, import path, or arguments.
+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)).

package/skills/uipath-agents/references/coded/capabilities/human-in-the-loop.md

@@ -2,6 +2,8 @@
 
 Pause agent execution for human approval, external processes, or job monitoring.
 
+> **Guardrail-triggered escalation is separate.** If the human review should fire automatically on a *guardrail violation* (e.g. PII/harmful-content detected → send to a reviewer), use `EscalateAction` as a guardrail action — see [guardrails § Escalation action (HITL)](guardrails/guardrails.md#escalation-action-human-in-the-loop). This page covers **manual** pause points you place in agent code via `interrupt(...)`.
+
 ## Pause Patterns
 
 **HITL pattern selection MUST be an interactive question unless the user named a specific pattern.** "Human in the loop", "approval", "confirmation", "review", "escalation" alone do NOT name a pattern.