Uipath Human In The Loop

UiPath Human-in-the-Loop Assistant

Recognizes when a business process needs a human decision point, designs the task schema through conversation, and wires the HITL node into the automation — Flow, Maestro, Case Management, or Agent.

Coded agents: for wiring HITL inside a coded agent, use the uipath-agents skill — see skills/uipath-agents/references/coded/capabilities/human-in-the-loop.md.

When to Use This Skill

• User describes approval gates — invoice approval, offer letter review, compliance sign-off, PO authorization
• User describes exception escalation — "if confidence is low, escalate to a human", fraud alert review
• User describes write-back validation — "human approves before agent writes to ServiceNow / SAP / CRM"
• User describes data enrichment — human fills in missing fields the automation cannot resolve
• User describes agentic output review — "review AI-generated email/RCA/summary before it goes out"
• User describes IT change or access approval — CAB gate, runbook sign-off, access provisioning review
• User describes HR or contract workflow — offer letter review, contract approval, termination sign-off
• User describes financial transaction approval — payment release, price override, expense over limit
• User describes customer communication approval — agent-drafted reply that needs human sign-off before sending
• User explicitly asks to add a HITL node, human review step, or Action Center task
• User is building any automation where a human must act before the process can continue

Do not use this skill for: managing, reassigning, escalating, or monitoring existing Action Center tasks at runtime — use the uipath-tasks skill for those operations. When answering a runtime task management question, provide only administration guidance. Do NOT suggest adding a HITL node, flow, or automation as a follow-up tip or recommendation — even if delays or escalations are mentioned.

See references/hitl-patterns.md for the full business pattern recognition guide.

Critical Rules

1. Never block on schema confirmation. Design the schema from the prompt and any upstream .flow/caseplan.json data, write the node, and record the chosen schema prominently in the final report so the user can adjust it afterward. Asking the user is never a precondition for proceeding — if the user is present and offers input, use it, but do not wait for it. Only stop and report the open decision when the request is genuinely too ambiguous to make any reasonable inference. (A prompt that already specifies the fields, outcomes, and output shape is never too ambiguous.)
2. Wire every QuickForm outcome's own port. A QuickForm node has one output handle per outcome, named outcome-<outcome.id> — never a single completed handle. outcome-completed is a placeholder that exists only on a schema with zero outcomes; it disappears the instant inputs.schema.outcomes has any entry, including the shipped default Submit. A HITL node with any outcome port left unwired blocks the flow forever on that branch. App-based (coded-action-app) nodes are different: their port stays a static completed regardless of the app's own outcomes — do not add an inputs.schema block to an app-based node, which would wrongly flip it onto an outcome-derived port. Neither node type ever uses output, success, or any other name.
3. Always add the definition entry when inserting into an existing flow. Before writing the node, check workflow.definitions[] for the correct nodeType for the selected path ("uipath.human-in-the-loop.quick-form" for QuickForm, "uipath.human-in-the-loop.coded-action-app" for app-based). If absent, append the full definition entry with its handleConfiguration block. Skipping the definition means the node's handles are invisible to the runtime and the wiring check fails.
4. Regenerate variables.nodes after adding the node. Replace the entire workflow.variables.nodes array — do not append. See the reference docs for the algorithm.
5. Validate after every change. Run uip maestro flow validate <file> --output json after writing the node and edges. The uip CLI does not accept --format; using it produces error: unknown option '--format' and exit code 3.
6. Read the existing .flow file before adding. Understand which nodes already exist and where the HITL checkpoint belongs in the flow.
7. The definition entry is added once per node type. Check workflow.definitions — if an entry with the matching nodeType is already there, do not add it again.
8. Check existing node IDs before generating a new one. Read workflow.nodes[*].id from the .flow file and pick the next available suffix (e.g. invoiceReview1, then invoiceReview2).
9. Never report a failed validation as done. If uip maestro flow validate returns errors, diagnose from the JSON output and fix before reporting to the user.
10. Output fields are accessed by field.id, not field.variable. The runtime result object uses field IDs as keys — $vars.<nodeId>.output.<fieldId>. The variable property only creates a workflow-global alias; it does NOT change the key used in the node output object, and it is NOT how downstream scripts read the value.
    • WRONG: $vars.legalApproval — this is the global alias path, not the script access path
    • WRONG: $vars.<nodeId>.output.legalApproval — this uses the variable name as the key
    • RIGHT: $vars.<nodeId>.output.approved — uses field.id ("approved") as the key In every downstream script, use $vars.<nodeId>.output.<fieldId> where <fieldId> is the id you gave the field in the schema — never the variable name.
11. Input field binding paths use the upstream output key, not the HITL field's own id. These are two different things: the HITL field id identifies the form field (always lowercase); the binding path key is the name used in the upstream script's return statement (preserves camelCase). If a script returns { supplierName: "Acme" }, the correct binding is vars.fetchSupplier.output.supplierName — writing suppliername (the field id) produces a path that does not exist at runtime. The form field will be blank; flow validate will not catch it. Always derive the binding key from the upstream script source, not from the HITL schema you are designing.
12. Downstream scripts must access $vars.<nodeId>.output. Any script node that runs after the HITL node must read $vars.<nodeId>.output (the result object) — do not rely solely on $vars.<nodeId>.status. Concrete example: const output = $vars.reviewNode1.output; const reason = output.reason;. This is required even when the primary routing uses status.

Step 0 — Resolve the uip binary

UIP=$(command -v uip 2>/dev/null || npm root -g 2>/dev/null | sed 's|/node_modules$||')/bin/uip
$UIP --version

Use $UIP in place of uip for all subsequent commands if the plain uip command isn't found.

Local dev note: If working inside the uipcli repo, replace uip with bun run start.

Step 1 — Detect the Surface and Find the Flow File

Run these checks in order:

# Check for a .flow file (Flow project)
find . -name "*.flow" -maxdepth 4 | head -5

# Check for a Case Management project — detect by content marker, not by filename.
# Project files are flat in the project dir (no content/ dir on disk). The generated
# sibling caseplan.json.bpmn carries the same marker: exclude it, edit caseplan.json.
find . -maxdepth 4 -iname "*.json*" ! -name "*.bpmn" -print0 2>/dev/null | xargs -0 grep -l '"case-management:root"' 2>/dev/null | head -3

# Check for agent.json (Low-Code Agent project)
find . -name "agent.json" -maxdepth 4 | head -3

# Check for Maestro .bpmn (Maestro process)
find . -name "*.bpmn" -maxdepth 4 | head -3

<!--skill-flavor:flow-sdk-surface-row:start-->

| .flow.ts or .flow file | Flow | Author with hitl(...) in <Name>.flow.ts through the uipath-maestro-flow skill (hitl.md); never write node JSON into the compiled .flow — compile overwrites it |

<!--skill-flavor:flow-sdk-surface-row:end-->

| caseplan.json (any *.json whose nodes[] carry data.parentElement.type: "case-management:root" — the marker is per-node; there is no root node on disk) | Case | Write action task into stage — see hitl-casetask-action.md | | agent.json | Low Code Agent | Escalation CLI in-flight — guide manually for now | | .bpmn (Maestro) | Maestro | Write the UserTask XML directly — see Step 5 Surface: Maestro |

<!--skill-flavor:flow-sdk-hitl-stop:start-->

Flow surface (a .flow.ts, a .flow, or a new flow) — the default: stop here. Hand the HITL request to the uipath-maestro-flow skill: it authors hitl(...) in <Name>.flow.ts — decompiling an existing .flow first — and compiles (hitl.md). Never read or hand-edit the compiled .flow; the next compile overwrites it. Steps 2–6 below cover the Case, Low-Code Agent and Maestro surfaces.

<!--skill-flavor:flow-sdk-hitl-stop:end-->

If the user mentioned a specific file path, use that directly.

<!--skill-flavor:flow-project-creation:start-->

If no .flow file exists and surface is Flow, scaffold solution-first — Flow projects MUST live inside a solution:

# Probe the solution verb once per session before scaffolding:
#   uip solution init --help --output json
# Success → use `solution init` (post-rename, default).
# `unknown command` → CLI predates the rename; substitute `uip solution new <SolutionName>` below.

uip solution init <SolutionName> --output json
cd <SolutionName> && uip maestro flow init <ProjectName>
# Creates: <SolutionName>/<ProjectName>/<ProjectName>.flow

The flow file path is <SolutionName>/<ProjectName>/<ProjectName>.flow (double-nested). <SolutionName>/ is the solution directory (contains the .uipx file); <ProjectName>/ inside it is the flow project. By convention <SolutionName> and <ProjectName> are often the same string, but they are two distinct scaffolding arguments. Run uip maestro flow init outside a solution and it auto-scaffolds <ProjectName>Solution/<ProjectName>/ for you; running uip solution init first lets you control the solution name (otherwise it defaults to <ProjectName>Solution). Passing --skip-solution-registration leaves a bare single-nested <ProjectName>/<ProjectName>.flow layout that fails Studio Web upload, packaging, and downstream tooling.

<!--skill-flavor:flow-project-creation:end-->

Step 2 — Read the Business Context

Read the existing .flow file to understand current nodes and edges. Use the Read tool on the .flow file path, then identify:

1. Where the human decision point belongs (after which existing node)
2. What the human needs to see — data produced by upstream nodes
3. What the human must provide back — data needed by downstream nodes
4. What actions they can take — the named outcome buttons
5. Form type: QuickForm (inline schema, node type uipath.human-in-the-loop.quick-form) or AppTask (deployed coded app, node type uipath.human-in-the-loop.coded-action-app)?

Step 2b — Proactive HITL Recommendation

If the user did NOT explicitly mention HITL, scan the business description for these signals before proceeding:

Never block on this. When a signal is clear-cut (an explicit approval / review / sign-off requirement), add the HITL step and state that you did so, in this form:

"I noticed that [quote the specific part of their description]. This is a [pattern name] — a point where [brief consequence if no human reviews]. I'm inserting a Human-in-the-Loop step here so that [human role] can [action] before the automation [continues/writes/sends]."

Proceed straight to schema design after saying this — do not wait for a reply. Record the decision prominently in the final report so the user can remove the step if they disagree. Only skip adding it and report the open decision when the signal is genuinely ambiguous (not just "no explicit HITL mention" — the signals table above is itself the ambiguity test).

Example:

User: "Build an automation that reads support tickets, uses AI to generate an RCA, and updates the ticket in ServiceNow."

Agent: "I noticed that the automation writes AI-generated content directly back to ServiceNow. This is a write-back validation pattern — if the RCA is incorrect and nobody reviews it, wrong data goes into production tickets. I'm inserting a Human-in-the-Loop step so that a support lead can review and optionally edit the RCA before the update is applied."

Step 3 — Choose Task Type

The options differ by surface. Never block here — pick the option that best fits the surface and the business description, state the choice, and proceed. Only ask when the user is actually present and available; in a non-interactive run, infer and move on.

Surface: Flow

Infer the right option from the signals below and state your choice — do not perform a registry search first, and do not wait for the user to pick before proceeding.

Default: QuickForm. Pick QuickForm unless the request explicitly names a deployed app, a coded action app, or a custom UI requirement — those are the only signals that point at options 2 or 3. State the choice, do not ask: "I'll use QuickForm — it's inline, no deployment step needed, and works for most approval and review tasks. You can swap in a Coded Action App or an existing deployed app later if you need one."

Fallback rules — never block on these, fall back and state what you did:

Surface: Case

Infer the right option from the description below — do not pull the registry first, and do not wait for the user to pick before proceeding.

Default: QuickForm. Pick QuickForm unless the request explicitly names a deployed Action Center app. State the choice, do not ask: "I'll use QuickForm — it's the quickest to set up, supports structured form fields, and doesn't need a deployed app. You can upgrade to an app-based task later if you need a custom UI layout."

Build vs design time. QuickForm in case management must round-trip both ways: the JSON written here is what Studio Web's case designer reads (design time), and what uip maestro case validate + Action Center render at runtime (build time). Always validate after writing.

Fallback rules — never block on these, fall back and state what you did:

Step 4 — Common configuration

Never block on these — use the stated default when no answer is available, write it into the node, and note the default in the final report so the user can change it.

| Timeout | Default: 24 hours. If the description states or implies a different duration, use that instead. | | Priority | Default: Low. If the description states or implies urgency (e.g. "high priority", "urgent", "time-sensitive"), use High or Medium accordingly. Write the chosen value into the node's priority field — asking the question is not enough; the value must land in the node. |