uipath-human-in-the-loop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UiPath Human-in-the-Loop Assistant

UiPath Human-in-the-Loop 助手

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, 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
.

识别业务流程中需要人工决策的节点，通过对话设计任务 schema，并将HITL节点接入自动化流程——支持Flow、Maestro或Agent。

Coded agents： 若要在编码型Agent中接入HITL，请使用
uipath-agents
技能——详见
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.

用户描述审批关卡——发票审批、录用函审核、合规签署、采购订单授权
用户描述异常升级——“当置信度较低时，升级给人工处理”、欺诈警报审核
用户描述回写验证——“在Agent写入ServiceNow/SAP/CRM前，需人工审批”
用户描述数据增强——人工补充自动化无法解析的缺失字段
用户描述Agent输出审核——“AI生成的邮件/根本原因分析/摘要发出前需审核”
用户描述IT变更或权限审批——变更咨询委员会（CAB）关卡、运行手册签署、权限配置审核
用户描述HR或合同工作流——录用函审核、合同审批、离职签署
用户描述财务交易审批——付款放行、价格覆盖、超限额费用审批
用户描述客户沟通内容审批——Agent草拟的回复需人工签署后发送
用户明确要求添加HITL节点、人工审核步骤或Action Center任务
用户正在构建任何需要人工操作后流程才能继续的自动化

请勿将此技能用于： 运行时管理、重新分配、升级或监控现有Action Center任务——此类操作请使用

uipath-tasks

技能。回答运行时任务管理问题时，仅提供管理指导。即使提到延迟或升级情况，也不要建议添加HITL节点、流程或自动化作为后续提示或建议。

完整业务模式识别指南请参阅references/hitl-patterns.md。

Critical Rules

关键规则

Confirm schema with the user before writing anything for quickform type. Show the designed schema and wait for explicit confirmation. Running non-interactively (CI/headless — no user available to answer): do not block — design the schema from the prompt and any upstream
```
.flow
```
data, write the node, and record the chosen schema prominently in the final report. Only stop and report the open decision if the request is too ambiguous to pick a sensible default. (A prompt that already specifies the fields, outcomes, and output shape is never too ambiguous.)
Always wire the
completed
handle. A HITL node with no outgoing edge on
```
completed
```
blocks the flow forever. Only
```
completed
```
is available as an output handle — not
```
output
```
,
```
success
```
, or any other name. This is true even when inserting into an existing flow whose other nodes use
```
"sourcePort": "output"
```
.
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
```
handleConfiguration
```
including the
```
completed
```
handle). Skipping the definition means the
```
completed
```
handle is invisible to the runtime and the wiring check fails.
Regenerate
variables.nodes
after adding the node. Replace the entire
```
workflow.variables.nodes
```
array — do not append. See the reference docs for the algorithm.
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.
Read the existing
.flow
file before adding. Understand which nodes already exist and where the HITL checkpoint belongs in the flow.
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.
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
```
).
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.
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.
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.
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
```
.

编写快速表单类型前，先与用户确认schema。展示设计好的schema并等待用户明确确认。非交互式运行（CI/无头模式——无可用用户响应）： 不要阻塞流程——根据提示和任何上游
```
.flow
```
数据设计schema，编写节点，并在最终报告中突出记录所选schema。仅当请求过于模糊无法选择合理默认值时，才停止并报告未解决的决策。（已明确指定字段、结果和输出格式的请求永远不属于模糊情况。）
务必连接
completed
句柄。未在
```
completed
```
上设置输出边的HITL节点会永久阻塞流程。仅
```
completed
```
可用作输出句柄——不支持
```
output
```
、
```
success
```
或其他任何名称。即使插入到其他节点使用
```
"sourcePort": "output"
```
的现有流程中，此规则依然适用。
插入现有流程时，务必添加定义条目。编写节点前，检查
```
workflow.definitions[]
```
中所选路径对应的正确
```
nodeType
```
（QuickForm对应
```
"uipath.human-in-the-loop.quick-form"
```
，基于应用的对应
```
"uipath.human-in-the-loop.coded-action-app"
```
）。如果不存在，追加完整的定义条目（包含
```
handleConfiguration
```
和
```
completed
```
句柄）。跳过定义会导致
```
completed
```
句柄对运行时不可见，从而导致连接检查失败。
添加节点后重新生成
variables.nodes
。替换整个
```
workflow.variables.nodes
```
数组——不要追加。算法请参阅参考文档。
每次变更后都要验证。编写节点和边后，运行
```
uip maestro flow validate <file> --output json
```
。
```
uip
```
CLI不接受
```
--format
```
选项；使用该选项会产生
```
error: unknown option '--format'
```
错误，退出码为3。
添加前先读取现有
.flow
文件。了解已存在的节点以及HITL检查点在流程中的位置。
每种节点类型仅添加一次定义条目。检查
```
workflow.definitions
```
——如果已存在匹配
```
nodeType
```
的条目，请勿重复添加。
生成新节点ID前检查现有ID。读取
```
.flow
```
文件中的
```
workflow.nodes[*].id
```
，选择下一个可用的后缀（例如
```
invoiceReview1
```
，然后是
```
invoiceReview2
```
）。
永远不要将验证失败的结果报告为已完成。如果
```
uip maestro flow validate
```
返回错误，从JSON输出中诊断问题并修复后再向用户报告。
输出字段通过
field.id
访问，而非
field.variable
。运行时结果对象使用字段ID作为键——
```
$vars.<nodeId>.output.<fieldId>
```
。
```
variable
```
属性仅创建工作流全局别名；它不会更改节点输出对象中使用的键，也不是下游脚本读取值的方式。
- 错误写法：
```
$vars.legalApproval
```
  ——这是全局别名路径，不是脚本访问路径
- 错误写法：
```
$vars.<nodeId>.output.legalApproval
```
  ——使用变量名作为键
- 正确写法：
```
$vars.<nodeId>.output.approved
```
  ——使用
```
field.id
```
  （"approved"）作为键在所有下游脚本中，使用
```
$vars.<nodeId>.output.<fieldId>
```
  ，其中
```
<fieldId>
```
  是你在schema中给字段指定的
```
id
```
  ——永远不要使用
```
variable
```
  名称。
输入字段绑定路径使用上游输出键，而非HITL字段自身的
id
。这是两个不同的概念：HITL字段
```
id
```
标识表单字段（始终为小写）；绑定路径键是上游脚本
```
return
```
语句中使用的名称（保留驼峰命名）。如果脚本返回
```
{ supplierName: "Acme" }
```
，正确的绑定是
```
vars.fetchSupplier.output.supplierName
```
——写成
```
suppliername
```
（字段
```
id
```
）会导致运行时路径不存在。表单字段将为空；
```
flow validate
```
不会捕获此问题。务必从上游脚本源推导绑定键，而非你设计的HITL schema。
下游脚本必须访问
$vars.<nodeId>.output
。HITL节点之后运行的任何脚本节点必须读取
```
$vars.<nodeId>.output
```
（结果对象）——不要仅依赖
```
$vars.<nodeId>.status
```
。具体示例：
```
const output = $vars.reviewNode1.output; const reason = output.reason;
```
。即使主要路由使用
```
status
```
，此要求依然适用。

Step 0 — Resolve the

uip

binary

步骤0 — 解析

uip

二进制文件

bash

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
.

bash

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

如果无法找到普通的

uip

命令，请在后续所有命令中使用

$UIP

替代

uip

。

本地开发注意： 如果在uipcli仓库内工作，请将
uip
替换为
bun run start
。

Step 1 — Detect the Surface and Find the Flow File

步骤1 — 检测平台并查找流程文件

Run these checks in order:

bash

undefined

按顺序运行以下检查：

bash

undefined

Check for a .flow file (Flow project)

检查.flow文件（Flow项目）

find . -name "*.flow" -maxdepth 4 | head -5

Check for agent.json (Low-Code Agent project)

检查agent.json（低代码Agent项目）

find . -name "agent.json" -maxdepth 4 | head -3

Check for Maestro .bpmn (Maestro process)

检查Maestro的.bpmn文件（Maestro流程）

find . -name "*.bpmn" -maxdepth 4 | head -3


| Found | Surface | How HITL is added |
|---|---|---|
| `.flow` file | **Flow** | Write node JSON directly — see reference docs |
| `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 |

**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:

```bash

find . -name "*.bpmn" -maxdepth 4 | head -3


| 找到的文件 | 平台 | HITL添加方式 |
|---|---|---|
| `.flow`文件 | **Flow** | 直接写入节点JSON——详见参考文档 |
| `agent.json` | **低代码Agent** | 升级CLI正在开发中——目前请手动配置 |
| `.bpmn`（Maestro） | **Maestro** | 直接写入`UserTask` XML——详见步骤5 平台：Maestro |

**如果用户提到了特定文件路径**，请直接使用该路径。

<!--skill-flavor:flow-project-creation:start-->
**如果不存在`.flow`文件且平台为Flow**，请先搭建解决方案——Flow项目必须位于解决方案内：

```bash

Probe the solution verb once per session before scaffolding:

搭建前先探测一次solution命令：

uip solution init --help --output json

Success → use

solution init

(post-rename, default).

成功→使用

solution init

（重命名后的默认命令）。

unknown command

→ CLI predates the rename; substitute

uip solution new <SolutionName>

below.

提示

unknown command

→CLI版本早于重命名；将下方的

uip solution init <SolutionName>

替换为

uip solution new <SolutionName>

。

uip solution init <SolutionName> --output json cd <SolutionName> && uip maestro flow init <ProjectName>

Creates: <SolutionName>/<ProjectName>/<ProjectName>.flow

创建：<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-->

---


流程文件路径为`<SolutionName>/<ProjectName>/<ProjectName>.flow`（双重嵌套）。`<SolutionName>/`是解决方案目录（包含`.uipx`文件）；其中的`<ProjectName>/`是Flow项目。按照惯例，`<SolutionName>`和`<ProjectName>`通常是相同的字符串，但它们是两个不同的搭建参数。在解决方案外运行`uip maestro flow init`会自动搭建`<ProjectName>Solution/<ProjectName>/`；先运行`uip solution init`可让你控制解决方案名称（否则默认是`<ProjectName>Solution`）。传递`--skip-solution-registration`会生成单层嵌套的`<ProjectName>/<ProjectName>.flow`结构，这会导致Studio Web上传、打包和下游工具失败。
<!--skill-flavor:flow-project-creation:end-->

---

Step 2 — Read the Business Context

步骤2 — 读取业务上下文

Read the existing

.flow

file to understand current nodes and edges. Use the Read tool on the

.flow

file path, then identify:

Where the human decision point belongs (after which existing node)
What the human needs to see — data produced by upstream nodes
What the human must provide back — data needed by downstream nodes
What actions they can take — the named outcome buttons
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
```
)?

读取现有

.flow

文件以了解当前节点和边。使用读取工具读取

.flow

文件路径，然后确定：

人工决策点的位置（在哪个现有节点之后）
人工需要查看的内容——上游节点生成的数据
人工必须返回的内容——下游节点需要的数据
人工可执行的操作——命名结果按钮
表单类型：QuickForm（内联schema，节点类型
```
uipath.human-in-the-loop.quick-form
```
）还是AppTask（已部署的编码应用，节点类型
```
uipath.human-in-the-loop.coded-action-app
```
）？

Step 2b — Proactive HITL Recommendation

步骤2b — 主动推荐HITL

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

Signal	Pattern	Why a human checkpoint matters
"agent writes to", "updates", "posts to" an external system	Write-back validation	Prevents incorrect writes to production systems
"if confidence is low", "when uncertain", "edge case"	Exception escalation	Agent cannot resolve autonomously
"approves", "reviews", "signs off", "four-eyes"	Approval gate	Business or compliance requirement
"fills in missing", "validates extraction", "corrects"	Data enrichment	Automation produced incomplete data
"compliance", "regulatory", "audit trail"	Compliance checkpoint	Mandated human sign-off

When a signal is found, say this before doing anything else:

"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 recommend inserting a Human-in-the-Loop step here so that [human role] can [action] before the automation [continues/writes/sends]. Should I add it?"

Wait for confirmation. Do not proceed to schema design until the user confirms. Running non-interactively (CI/headless — no user available to answer): treat the recommendation as accepted when the signal is clear-cut (an explicit approval / review / sign-off requirement), add the HITL step, and record that you did so in the final report; only skip it and report the open decision when the signal is ambiguous.

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 recommend inserting a Human-in-the-Loop step so that a support lead can review and optionally edit the RCA before the update is applied. Should I add it?"

如果用户未明确提及HITL，在继续之前扫描业务描述以查找以下信号：

信号	模式	人工检查点的重要性
"agent写入"、"更新"、"发布到"外部系统	回写验证	防止向生产系统写入错误数据
"当置信度较低时"、"不确定时"、"边缘情况"	异常升级	Agent无法自主解决问题
"审批"、"审核"、"签署"、"四眼原则"	审批关卡	业务或合规要求
"补充缺失内容"、"验证提取结果"、"纠正错误"	数据增强	自动化生成的数据不完整
"合规"、"监管"、"审计追踪"	合规检查点	强制要求人工签署

发现信号后，在执行任何操作前先告知用户：

"我注意到[引用用户描述中的具体部分]。这属于[模式名称]——如果没有人工审核，[简要说明后果]。我建议在此处插入Human-in-the-Loop步骤，以便[人工角色]在自动化[继续/写入/发送]前[执行操作]。是否需要添加？"

等待用户确认。在用户确认前不要进行schema设计。非交互式运行（CI/无头模式——无可用用户响应）： 当信号明确时（例如明确要求审批/审核/签署），视为用户接受推荐，添加HITL步骤，并在最终报告中记录；仅当信号模糊时才跳过并报告未解决的决策。

示例：

用户："构建一个自动化流程，读取支持工单，使用AI生成根本原因分析（RCA），并更新ServiceNow中的工单。"

Agent："我注意到自动化会将AI生成的内容直接写回ServiceNow。这属于回写验证模式——如果RCA不正确且无人审核，错误数据会进入生产工单。我建议在此处插入Human-in-the-Loop步骤，以便支持主管在应用更新前审核并可选编辑RCA。是否需要添加？"

Step 3 — Choose Task Type

步骤3 — 选择任务类型

Present the user with three options. Do not choose on their behalf or perform any registry search.

#	Option	Node type	Description
1	QuickForm	`uipath.human-in-the-loop.quick-form`	Inline typed form — fields rendered by Action Center from the schema you design here
2	New Coded Action App	`uipath.human-in-the-loop.coded-action-app`	Scaffold a new React + TypeScript app inside the solution — full UI control
3	Existing Deployed App	`uipath.human-in-the-loop.coded-action-app`	Reference an app already deployed to Orchestrator

If the user's request is purely business-oriented (no mention of a deployed app, coded action app, or custom UI): skip the question and proceed directly with QuickForm. Do not ask. Say: "I'll use QuickForm — it's inline, no deployment step needed, and works for most approval and review tasks."

If the user is unsure or says "just pick one": Default to QuickForm. Say: "I'll use QuickForm — it's the quickest to set up and works for most approval and review tasks. You can always upgrade to a Coded Action App later."

User selects	Next step
QuickForm	Read How to write a QuickForm HITL node for Steps 1–2, then continue with Step 4
New Coded Action App	Read How to scaffold a new Coded Action App for Step 4c details, then continue with Step 4
Existing Deployed App → ask: "What is the name of the deployed action app?"	Read How to wire an existing deployed Action App for Step 4b details, then continue with Step 4

Fallback rules — what to do when the chosen path hits a blocker:

Path	Blocker	Response
Existing Deployed App	App not found in Orchestrator	"I couldn't find an app with that name. Would you like to try a different name, or fall back to QuickForm while you prepare the app?"
New Coded Action App	No `dist/` build present in the source path	"The source folder doesn't have a `dist/` build yet. Run your build first ( `npm run build` or equivalent), then come back. Or I can set up a QuickForm now so the flow is wired and ready — you can swap in the app later."
New Coded Action App	User can't provide a source path	"If you don't have the app code ready yet, I'll use QuickForm to wire the HITL checkpoint. You can replace it with a Coded Action App once it's built."
Any custom app	Auth expired (401 on API call)	"The session looks expired — run `uip login` to refresh your credentials, then retry."

向用户提供三个选项。不要替用户选择或执行任何注册表搜索。

#	选项	节点类型	描述
1	QuickForm	`uipath.human-in-the-loop.quick-form`	内联类型化表单——Action Center根据你在此处设计的schema渲染字段
2	新建编码型Action App	`uipath.human-in-the-loop.coded-action-app`	在解决方案内搭建新的React + TypeScript应用——完全可控UI
3	已部署的现有应用	`uipath.human-in-the-loop.coded-action-app`	引用已部署到Orchestrator的应用

如果用户的请求纯粹是业务导向（未提及已部署应用、编码型Action App或自定义UI）：跳过问题，直接使用QuickForm。不要询问。告知用户："我将使用QuickForm——它是内联式的，无需部署步骤，适用于大多数审批和审核任务。"

如果用户不确定或说"随便选一个"： 默认使用QuickForm。告知用户："我将使用QuickForm——它设置最快，适用于大多数审批和审核任务。你以后随时可以升级为编码型Action App。"

用户选择	下一步
QuickForm	阅读如何编写QuickForm HITL节点中的步骤1–2，然后继续步骤4
新建编码型Action App	阅读如何搭建新的编码型Action App中的步骤4c细节，然后继续步骤4
已部署的现有应用 → 询问："已部署的Action App名称是什么？"	阅读如何接入已部署的现有Action App中的步骤4b细节，然后继续步骤4

回退规则——所选路径遇到阻塞时的处理：

路径	阻塞情况	响应
已部署的现有应用	Orchestrator中未找到该应用	"我无法找到该名称的应用。你想尝试其他名称，还是先回退到QuickForm，待你准备好应用后再替换？"
新建编码型Action App	源路径中不存在 `dist/` 构建产物	"源文件夹中还没有 `dist/` 构建产物。请先运行构建命令（ `npm run build` 或等效命令），然后重试。或者我现在可以设置QuickForm，先完成流程连接，你以后再替换为应用。"
新建编码型Action App	用户无法提供源路径	"如果你还没有准备好应用代码，我将使用QuickForm连接HITL检查点。应用构建完成后，你可以替换它。"
任何自定义应用	授权过期（API调用返回401）	"会话似乎已过期——运行 `uip login` 刷新凭据，然后重试。"

Step 4 — Common configuration

步骤4 — 通用配置

| Timeout | "How long before the task times out if nobody acts? (default: 24 hours)" | | Priority | "What priority should this task have? Options: Low, Medium, High (default: Low)" |

| 超时 | "如果无人操作，任务多久后超时？（默认：24小时）" | | 优先级 | "此任务的优先级应为？选项：低、中、高（默认：低）" |

Step 4b — Schema Design Rules (QuickForm only)

步骤4b — Schema设计规则（仅适用于QuickForm）

Apply these rules unconditionally while designing the schema.

设计schema时无条件应用以下规则。

Field direction

字段方向

Pick direction based on what the human does with the field:

Signal	Direction
"can see", "shown to", "read-only", "displays", "context for reviewer"	`input`
"fills in", "enters", "types", "selects", "required decision", "approves"	`output`
"can edit", "can correct", "pre-filled but editable", "suggested value the reviewer can adjust"	`inOut`

inOut

means the field is pre-populated from an upstream node AND the human can modify it before submitting. The runtime exposes it under

$vars.<nodeId>.output.<fieldId>

the same as an output field.

根据人工对字段的操作选择方向：

信号	方向
"可查看"、"展示给"、"只读"、"显示"、"审核者上下文"	`input`
"填写"、"输入"、"键入"、"选择"、"必填决策"、"审批"	`output`
"可编辑"、"可纠正"、"预填充但可编辑"、"审核者可调整的建议值"	`inOut`

inOut

表示字段由上游节点预填充，且人工提交前可修改。运行时通过

$vars.<nodeId>.output.<fieldId>

访问，与输出字段相同。

Field types

字段类型

Use the JS/JSON type that fits the field:

string

number

boolean

date

, or

file

. These are the only valid values — do not use

text

使用适合字段的JS/JSON类型：

string

、

number

、

boolean

、

date

或

file

。这些是唯一有效值——请勿使用

text

。

Vague or incomplete schema descriptions

模糊或不完整的schema描述

If the user says something like "just add some fields" or "use whatever makes sense":

Infer sensible defaults from the upstream data and downstream needs visible in the
```
.flow
```
file.
If there are no upstream nodes to bind to (flow is just a trigger), use output-direction fields only.

如果用户说“随便加些字段”或“用合理的就行”：

根据
```
.flow
```
文件中可见的上游数据和下游需求推导合理默认值。
如果没有可绑定的上游节点（流程仅包含触发器），仅使用输出方向的字段。

Empty field labels block validation

空字段标签会阻塞验证

Every field in

inputs.schema.fields

must have a non-empty

label

flow validate

emits

HITL_QUICK_FORM_FIELD_LABEL_REQUIRED

(error severity) for each field with an empty or whitespace-only

label

— Debug and Publish are blocked until all labels are filled in. Never generate a field with

"label": ""

or omit the

label

key.

inputs.schema.fields

中的每个字段必须有非空的

label

。

flow validate

会为每个标签为空或仅含空白字符的字段发出

HITL_QUICK_FORM_FIELD_LABEL_REQUIRED

（错误级别）——所有标签填充完成前，调试和发布都会被阻塞。永远不要生成

"label": ""

或省略

label

键的字段。

Step 5 — Write the Node Directly

步骤5 — 直接编写节点

Surface: Flow — QuickForm (inline schema only)

平台：Flow — QuickForm（仅内联schema）

Write the node JSON directly into

workflow.nodes

, add the definition to

workflow.definitions

(once), wire edges into

workflow.edges

, and regenerate

workflow.variables.nodes

. Direct JSON is the default.

Node JSON, definition entry, edge format,

variables.nodes

algorithm, and four worked examples: How to write a QuickForm HITL node

CLI (opt-in): When the user explicitly requests a CLI command:

bash

uip maestro flow hitl add <path/to/file.flow> \
  --label "<TaskLabel>" \
  --priority <Low|Medium|High> \
  --assignee <email-or-group> \
  --schema '<json>' \
  --output json

The CLI writes the node, adds the definition entry, and updates

variables.nodes

automatically. Wire the

completed

port after it returns.

After writing, validate:

bash

uip maestro flow validate <file> --output json

直接将节点JSON写入

workflow.nodes

，将定义添加到

workflow.definitions

（仅添加一次），将边连接到

workflow.edges

，并重新生成

workflow.variables.nodes

。直接写入JSON是默认方式。

节点JSON、定义条目、边格式、

variables.nodes

算法和四个示例：如何编写QuickForm HITL节点

CLI（可选）： 当用户明确要求CLI命令时：

bash

uip maestro flow hitl add <path/to/file.flow> \
  --label "<TaskLabel>" \
  --priority <Low|Medium|High> \
  --assignee <email-or-group> \
  --schema '<json>' \
  --output json

CLI会自动写入节点、添加定义条目并更新

variables.nodes

。返回后连接

completed

端口。

编写完成后验证：

bash

uip maestro flow validate <file> --output json

Surface: Flow — Coded Action App (new inline)

平台：Flow — 编码型Action App（新建内联）

Step 4c must be completed first — app name confirmed, solution directory located, SDK tarball identified, schema designed and confirmed.

Scaffold the project directory and all source files, add the project to the solution, write the solution resource files, then write the HITL node (type

uipath.human-in-the-loop.coded-action-app

) with

inputs.app

referencing the new app (

appSystemName: null

since the app has not been deployed yet).

Full project template, UUID generation, solution CLI commands, resource file templates, node JSON, and post-creation build steps: How to scaffold a new Coded Action App

After writing, validate:

bash

uip maestro flow validate <file> --output json

必须先完成步骤4c——确认应用名称、找到解决方案目录、识别SDK压缩包、设计并确认schema。

搭建项目目录和所有源文件，将项目添加到解决方案，编写解决方案资源文件，然后编写HITL节点（类型

uipath.human-in-the-loop.coded-action-app

），其中

inputs.app

引用新应用（

appSystemName: null

，因为应用尚未部署）。

完整项目模板、UUID生成、解决方案CLI命令、资源文件模板、节点JSON和创建后构建步骤：如何搭建新的编码型Action App

编写完成后验证：

bash

uip maestro flow validate <file> --output json

Surface: Flow — AppTask (deployed action app only)

平台：Flow — AppTask（仅已部署的Action App）

Step 4b must be completed first — app resolved, configuration retrieved. Then:

Resolve the solution context (

.uipx

file), write solution resource files, register the app reference, merge

debug_overwrites.json

, then write the node JSON (type

uipath.human-in-the-loop.coded-action-app

) with

inputs.app

populated from the Step 3b configuration.

App search/selection, retrieve-configuration, resource file writing, complete node JSON with

appInputBindings

: How to wire an existing deployed Action App

After writing, validate:

bash

uip maestro flow validate <file> --output json

必须先完成步骤4b——解析应用、获取配置。然后：

解析解决方案上下文（

.uipx

文件），编写解决方案资源文件，注册应用引用，合并

debug_overwrites.json

，然后编写节点JSON（类型

uipath.human-in-the-loop.coded-action-app

），其中

inputs.app

填充步骤3b中的配置。

应用搜索/选择、配置获取、资源文件编写、包含

appInputBindings

的完整节点JSON：如何接入已部署的现有Action App

编写完成后验证：

bash

uip maestro flow validate <file> --output json

Surface: Low-Code Agent

平台：低代码Agent

The Low-Code Agent escalation CLI (

uip agent escalation add

) is currently in-flight. Until it ships, configure manually:

agent.json
escalation entry:

json

{
  "escalations": [
    {
      "name": "<escalation-name>",
      "inputSchema":  { "inputs": [...], "inOuts": [...] },
      "outputSchema": { "outputs": [...], "outcomes": [...] }
    }
  ]
}

Agent source (Python):

python

from uipath.sdk import interrupt, CreateTask

response = interrupt(CreateTask(
    escalation_name="<escalation-name>",
    data={ "fieldName": value }
))

低代码Agent升级CLI（

uip agent escalation add

）目前正在开发中。在此之前，请手动配置：

agent.json
升级条目：

json

{
  "escalations": [
    {
      "name": "<escalation-name>",
      "inputSchema":  { "inputs": [...], "inOuts": [...] },
      "outputSchema": { "outputs": [...], "outcomes": [...] }
    }
  ]
}

Agent源码（Python）：

python

from uipath.sdk import interrupt, CreateTask

response = interrupt(CreateTask(
    escalation_name="<escalation-name>",
    data={ "fieldName": value }
))

response contains the human's outputs and chosen outcome

response包含人工输出和所选结果

undefined

undefined

Surface: Maestro

平台：Maestro

QuickForm and coded-action-app HITL nodes are both supported on Maestro BPMN processes —

uipath.human-in-the-loop.quick-form

and

uipath.human-in-the-loop.coded-action-app

are registered element types in the BPMN validator (bpmn-spec.json), same node-type strings as the Flow surface. Write the node directly into the

.bpmn

XML as a

bpmn:UserTask

with a

uipath:activity

extension element (see the

Actions.HITL

extension type in the validator spec for the app-based/coded-action-app XML shape and context fields —

appId

appVersion

actions

key

taskTitle

Design the schema per Step 4b, confirm it with the user, then validate frequently (

uip maestro bpmn validate <file>.bpmn --output json

) while wiring the node so any shape mistakes surface immediately rather than at deploy time. In Maestro, field names in

outputs

inOuts

must exactly match declared process variable names and types.

Maestro BPMN流程支持QuickForm和编码型Action App HITL节点——

uipath.human-in-the-loop.quick-form

和

uipath.human-in-the-loop.coded-action-app

是BPMN验证器中的注册元素类型（bpmn-spec.json），节点类型字符串与Flow平台相同。直接将节点写入

.bpmn

XML，作为带有

uipath:activity

扩展元素的

bpmn:UserTask

（基于应用/编码型Action App的XML结构和上下文字段——

appId

、

appVersion

、

actions

、

key

、

taskTitle

，请参阅验证器规范中的

Actions.HITL

扩展类型）。

按照步骤4b设计schema，与用户确认，然后在连接节点时频繁验证（

uip maestro bpmn validate <file>.bpmn --output json

），以便在部署前及时发现任何格式错误。在Maestro中，

outputs

inOuts

中的字段名称必须与声明的流程变量名称和类型完全匹配。

Step 6 — Report to the User

步骤6 — 向用户报告

After completing the wiring:

What was inserted — node ID, label, insertion point
Schema summary — what the human will see (input-direction fields), fill in (output/inOut-direction fields), and click (outcomes). For deployed action app show the actionSchema from the retrieve-configuration api response here.
Edges wired — which handles were connected and to which nodes; any handles left unwired
Runtime variables —
```
$vars.<nodeId>.output
```
(object) and
```
$vars.<nodeId>.status
```
(string) and how to reference them downstream
Validation result — pass or errors to fix
Production readiness note:
- QuickForm: ready to deploy once the solution is packaged. No additional build steps.
- New Coded Action App: the app must be built (
```
npm run build
```
  inside the app source) and the solution packaged before the HITL task can be used in production. The app will appear with
```
appSystemName: null
```
  until first deployment assigns it a system name.
- Existing Deployed App: ready to deploy immediately — the app is already live.
Next step — pack and publish when ready via
```
uipath-development
```
skill

完成连接后：

插入内容——节点ID、标签、插入位置
Schema摘要——人工将看到的内容（输入方向字段）、需要填写的内容（输出/inOut方向字段）以及可点击的按钮（结果）。对于已部署的Action App，此处展示从获取配置API响应中得到的actionSchema。
已连接的边——连接了哪些句柄以及连接到哪些节点；未连接的句柄
运行时变量——
```
$vars.<nodeId>.output
```
（对象）和
```
$vars.<nodeId>.status
```
（字符串），以及下游如何引用它们
验证结果——通过或需要修复的错误
生产就绪说明：
- QuickForm：解决方案打包后即可部署。无需额外构建步骤。
- 新建编码型Action App：必须先构建应用（在应用源码内运行
```
npm run build
```
  ）并打包解决方案，HITL任务才能在生产环境中使用。首次部署分配系统名称前，应用的
```
appSystemName
```
  将显示为
```
null
```
  。
- 已部署的现有应用：可立即部署——应用已上线。
下一步——准备就绪后，通过
```
uipath-development
```
技能打包并发布

References

参考资料

How to write a QuickForm HITL node — Read this after the user confirms QuickForm in Step 3. Covers the complete node JSON, definition entry, edge wiring,
```
variables.nodes
```
regeneration algorithm, and four worked schema examples.
How to wire an existing deployed Action App — Read this when the user selects an existing deployed app in Step 3. Covers app lookup via the Orchestrator API,
```
inputs.app
```
field mapping,
```
appInputBindings
```
, and solution resource files.
How to scaffold a new Coded Action App — Read this when the user wants to build a new React app inside the solution. Covers full project template, UUID generation, solution CLI commands, and post-creation build steps.
HITL business pattern recognition — Read this during Step 2 / Step 2b to identify whether a process needs a human checkpoint and which pattern applies. Includes proactive recommendation language and when NOT to recommend HITL.
Action Center URL patterns (in
```
uipath-tasks
```
skill) — Read this before surfacing any Action Center task URL to the user. Covers the missing-tenant-slug anti-pattern and the API-host vs UI-host mapping.

如何编写QuickForm HITL节点——用户在步骤3中确认使用QuickForm后阅读。涵盖完整节点JSON、定义条目、边连接、
```
variables.nodes
```
重新生成算法和四个schema示例。
如何接入已部署的现有Action App——用户在步骤3中选择已部署的现有应用后阅读。涵盖通过Orchestrator API查找应用、
```
inputs.app
```
字段映射、
```
appInputBindings
```
和解决方案资源文件。
如何搭建新的编码型Action App——用户希望在解决方案内构建新React应用时阅读。涵盖完整项目模板、UUID生成、解决方案CLI命令和创建后构建步骤。
HITL业务模式识别——步骤2/步骤2b期间阅读，以识别流程是否需要人工检查点以及适用哪种模式。包括主动推荐话术和不推荐HITL的情况。
Action Center URL模式（在
```
uipath-tasks
```
技能中）——向用户展示任何Action Center任务URL前阅读。涵盖缺失租户slug的反模式以及API主机与UI主机的映射。

uipath-human-in-the-loop

Original

Translation

UiPath Human-in-the-Loop Assistant

UiPath Human-in-the-Loop 助手

When to Use This Skill

何时使用此技能

Critical Rules

关键规则

Step 0 — Resolve the uip binary

步骤0 — 解析uip二进制文件

Step 1 — Detect the Surface and Find the Flow File

步骤1 — 检测平台并查找流程文件

Check for a .flow file (Flow project)

检查.flow文件（Flow项目）

Check for agent.json (Low-Code Agent project)

检查agent.json（低代码Agent项目）

Check for Maestro .bpmn (Maestro process)

检查Maestro的.bpmn文件（Maestro流程）

Probe the solution verb once per session before scaffolding:

搭建前先探测一次solution命令：

uip solution init --help --output json

uip solution init --help --output json

Success → use solution init (post-rename, default).

成功→使用solution init（重命名后的默认命令）。

unknown command → CLI predates the rename; substitute uip solution new <SolutionName> below.

提示unknown command→CLI版本早于重命名；将下方的uip solution init <SolutionName>替换为uip solution new <SolutionName>。

Creates: <SolutionName>/<ProjectName>/<ProjectName>.flow

创建：<SolutionName>/<ProjectName>/<ProjectName>.flow

Step 2 — Read the Business Context

步骤2 — 读取业务上下文

Step 2b — Proactive HITL Recommendation

步骤2b — 主动推荐HITL

Step 3 — Choose Task Type

步骤3 — 选择任务类型

Step 4 — Common configuration

步骤4 — 通用配置

Step 4b — Schema Design Rules (QuickForm only)

步骤4b — Schema设计规则（仅适用于QuickForm）

Field direction

字段方向

Field types

字段类型

Vague or incomplete schema descriptions

模糊或不完整的schema描述

Empty field labels block validation

空字段标签会阻塞验证

Step 5 — Write the Node Directly

步骤5 — 直接编写节点

Surface: Flow — QuickForm (inline schema only)

平台：Flow — QuickForm（仅内联schema）

Surface: Flow — Coded Action App (new inline)

平台：Flow — 编码型Action App（新建内联）

Surface: Flow — AppTask (deployed action app only)

平台：Flow — AppTask（仅已部署的Action App）

Surface: Low-Code Agent

平台：低代码Agent

response contains the human's outputs and chosen outcome

response包含人工输出和所选结果

Surface: Maestro

平台：Maestro

Step 6 — Report to the User

步骤6 — 向用户报告

References

参考资料

Step 0 — Resolve the
`uip`
binary

步骤0 — 解析
`uip`
二进制文件

Success → use
`solution init`
(post-rename, default).

成功→使用
`solution init`
（重命名后的默认命令）。

`unknown command`
→ CLI predates the rename; substitute
`uip solution new <SolutionName>`
below.

提示
`unknown command`
→CLI版本早于重命名；将下方的
`uip solution init <SolutionName>`
替换为
`uip solution new <SolutionName>`
。