uipath-human-in-the-loop

UiPath Human-in-the-Loop アシスタント

ビジネスプロセスに人の判断が必要な場面があるかを認識し、会話を通じてタスクのスキーマを設計して、HITL ノードをオートメーションに組み込みます。対象は Flow、Maestro、Case Management、Agent です。

コードエージェント： コードエージェント内に HITL を組み込む場合は、uipath-agents スキルを使用してください。詳しくは skills/uipath-agents/references/coded/capabilities/human-in-the-loop.md を参照してください。

このスキルを使用する場面

• ユーザーが承認ゲートについて説明している場合 — 請求書の承認、オファーレターのレビュー、コンプライアンスの承認、PO の承認
• ユーザーが例外のエスカレーションについて説明している場合 — 「信頼度が低い場合は人にエスカレーションする」、不正アラートのレビュー
• ユーザーが書き戻しの検証について説明している場合 — 「エージェントが ServiceNow／SAP／CRM に書き込む前に、人が承認する」
• ユーザーがデータの補完について説明している場合 — オートメーションでは解決できない不足項目を人が入力する
• ユーザーがエージェントの出力レビューについて説明している場合 — 「AI が生成したメール／RCA／要約を、送信前にレビューする」
• ユーザーがIT 変更またはアクセスの承認について説明している場合 — CAB ゲート、ランブックの承認、アクセスプロビジョニングのレビュー
• ユーザーが人事または契約のワークフローについて説明している場合 — オファーレターのレビュー、契約の承認、退職処理の承認
• ユーザーが金融取引の承認について説明している場合 — 支払いのリリース、価格の上書き、上限額を超える経費
• ユーザーが顧客とのコミュニケーションの承認について説明している場合 — エージェントが下書きした返信を、送信前に人が承認する
• ユーザーがHITL ノード、人によるレビューステップ、または Action Center タスクの追加を明示的に求めている場合
• プロセスを続行する前に人が対応する必要があるオートメーションをユーザーが構築している場合
• ユーザーが判断の取得または記録（Decision Ledger への記録を含む）を求めている場合、またはレビュアーが提案を承認または修正する場合：以下のガイド付き判断エクスペリエンスを使用してください

ガイド付き判断エクスペリエンス（オプトイン）。 判断の記録を求める依頼、またはレビュアーが提案を承認もしくは修正するという説明がある場合に限り、Coded Action App のスキーマ、QuickForm、またはドキュメント検証タスクを設計する前に references/decision-capture-action-app-guide.md を読んでください。それ以外の依頼では、このガイドを使用せず、通常の手順で構築します。このガイドでは、依頼内容に基づいて切り替えを行います。ユーザーが判断の記録を求めた場合、またはエージェントやオートメーションの提案をレビュアーが承認もしくは修正する場合にオンにします。オンにすると、作成者自身のフィールドに加えて、固定された判断フィールド一式が追加され、各画面に合わせたシンプルなレイアウトに切り替わります（理由と重み付けメニュー、未選択の状態、判断に沿った最終詳細、理由から作成される根拠、適用範囲を設定できる「次回以降」、折りたたまれた記録）。作成者のフィールド名は変更しません。QuickForm では、1 つの関数を使って、各選択フィールドに任意の「理由」を追加します。これについて、はい／いいえで答える質問をしてはいけません。明示的に求められずにオンにした場合は、その旨を一文で伝えてください。

このスキルを使用しない場面： 実行時に既存の Action Center タスクを管理、再割り当て、エスカレーション、または監視する場合は、uipath-tasks スキルを使用してください。実行時のタスク管理に関する質問に答える際は、管理方法の案内のみを提供してください。遅延やエスカレーションへの言及があっても、追加の提案や推奨として HITL ノード、Flow、またはオートメーションの追加を提案してはいけません。

ビジネスパターンの認識に関する詳しいガイドは、references/hitl-patterns.md を参照してください。

---

重要なルール

1. スキーマの確認を待って作業を止めないでください。 プロンプトと、存在する場合は上流の .flow／caseplan.case データからスキーマを設計してノードを作成し、選択したスキーマを最終レポートに目立つように記載して、ユーザーが後から調整できるようにしてください。ユーザーへの確認は作業を進める前提条件ではありません。ユーザーがその場にいて情報を提供してくれた場合はそれを使用しますが、返答を待たないでください。妥当な推測がどうしてもできないほど依頼が曖昧な場合に限り、作業を中断して未決事項を報告してください。フィールド、結果、出力形式がすでに指定されているプロンプトが、曖昧すぎることはありません。
2. QuickForm のすべての結果について、対応するポートを接続してください。 QuickForm ノードには結果ごとに 1 つの出力ハンドルがあり、名前は outcome-<outcome.id> です。completed ハンドル 1 つだけにすることはできません。outcome-completed は、結果が 0 件のスキーマにのみ存在するプレースホルダーです。既定で提供される Submit を含め、inputs.schema.outcomes に項目が 1 つでも追加されると、すぐに消えます。結果ポートのいずれかが未接続の HITL ノードは、その分岐でフローを永久にブロックします。アプリベース（coded-action-app）ノードは異なり、アプリ独自の結果にかかわらず、ポートは静的な completed のままです。アプリベースノードに inputs.schema ブロックを追加しないでください。追加すると誤って結果由来のポートに切り替わります。どちらのノードタイプでも、output、success、その他の名前は使用しません。
3. 既存のフローにノードを追加する場合は、必ず定義エントリーも追加してください。 ノードを記述する前に、選択したパスに対応する nodeType が workflow.definitions[] にあるか確認してください（QuickForm は "uipath.human-in-the-loop.quick-form"、アプリベースは "uipath.human-in-the-loop.coded-action-app"）。ない場合は、handleConfiguration ブロックを含む定義エントリー全体を追加してください。定義を追加しないと、ノードのハンドルがランタイムに認識されず、配線チェックに失敗します。
4. ノードを追加した後、variables.nodes を再生成してください。 workflow.variables.nodes 配列全体を置き換えてください。追記してはいけません。アルゴリズムについてはリファレンスドキュメントを参照してください。
5. 変更のたびに検証してください。 ノードとエッジを記述した後、uip maestro flow validate <file> --output json を実行してください。uip CLI は --format を受け付けません。これを使用すると error: unknown option '--format' が発生し、終了コード 3 が返されます。
6. 追加する前に、既存の .flow ファイルを読んでください。 すでに存在するノードと、フロー内で HITL チェックポイントを配置すべき場所を把握してください。
7. 定義エントリーは、ノードタイプごとに 1 回だけ追加してください。 workflow.definitions を確認し、一致する nodeType のエントリーがすでにあれば、再度追加しないでください。
8. 新しい ID を生成する前に、既存のノード ID を確認してください。 .flow ファイルから workflow.nodes[*].id を読み取り、次に使用できるサフィックスを選んでください（例：invoiceReview1、次に invoiceReview2）。
9. 検証に失敗した状態で完了を報告しないでください。 uip maestro flow validate がエラーを返した場合は、JSON 出力を基に原因を特定して修正してから、ユーザーに報告してください。
10. 出力フィールドには field.variable ではなく field.id でアクセスしてください。 ランタイムの結果オブジェクトでは、フィールド ID がキーとして使われます（$vars.<nodeId>.output.<fieldId>）。variable プロパティはワークフロー全体で使えるエイリアスを作成するだけで、ノード出力オブジェクト内で使われるキーは変更しません。また、下流スクリプトで値を読み取る方法でもありません。
    • 誤り：$vars.legalApproval — これはグローバルエイリアスのパスであり、スクリプトからのアクセスパスではありません
    • 誤り：$vars.<nodeId>.output.legalApproval — 変数名をキーとして使っています
    • 正しい：$vars.<nodeId>.output.approved — field.id（「approved」）をキーとして使っています すべての下流スクリプトで、<fieldId> にスキーマでフィールドに指定した id を使い、$vars.<nodeId>.output.<fieldId> から値を読み取ってください。variable 名は使わないでください。
11. 入力フィールドのバインディングパスには、HITL フィールド自身の id ではなく、上流の出力キーを使ってください。 これは別のものです。HITL フィールドの id はフォームフィールドを識別し（常に小文字）、バインディングパスのキーは上流スクリプトの return 文で使われる名前です（camelCase を維持します）。スクリプトが { supplierName: "Acme" } を返す場合、正しいバインディングは vars.fetchSupplier.output.supplierName です。フィールドの id である suppliername を記述すると、実行時に存在しないパスになります。フォームフィールドは空欄になりますが、flow validate では検出されません。バインディングキーは、設計中の HITL スキーマではなく、必ず上流スクリプトのソースから特定してください。
12. 下流スクリプトでは $vars.<nodeId>.output にアクセスしてください。 HITL ノードの後に実行されるスクリプトノードは、結果オブジェクトである $vars.<nodeId>.output を読み取る必要があります。$vars.<nodeId>.status だけに依存しないでください。具体例：const output = $vars.reviewNode1.output; const reason = output.reason;。主なルーティングで status を使う場合も、これは必須です。
13. 依頼が判断の記録を求める場合、またはレビュー担当者が提案を承認・修正する場合は、Coded Action App の action-schema.json、QuickForm スキーマ、またはドキュメント検証スキーマを作成する前に、判断ガイドを読んでください。 まず references/decision-capture-action-app-guide.md を開いてください。このガイドでは、依頼内容に応じた判断トグルの設定と、有効な場合に追加するフィールド（proposedOutcome、proposedBy、involvement、nextTimeOptions、conditionOptions、weight を含む reasons、byDecision を含む fields、および出力の rationaleText、decidingReasons、nextTimeScope、changes、record）について説明しています。ガイドを参照せずにスキーマを作成すると、これらのフィールドが抜け落ちます。また、このガイドでは、アプリが満たす必要のある Human Context Capture の原則と、Coded Action App に含める必要がある @uipath/intrinsic-signals のマークアップおよび intrinsicSignals 出力についても説明しています。それ以外の依頼では、このガイドを開かず、判断フィールドのない通常のスキーマとアプリを作成してください。

---

Step 0 — uip バイナリを解決する

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 — サーフェスを検出し、Flow ファイルを見つける

以下のチェックを順番に実行してください。

# 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.case.bpmn carries the same marker; these patterns skip it. Edit caseplan.case.
find . -maxdepth 4 \( -iname "*.json" -o -iname "*.case" \) -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

見つかったもの	サーフェス	HITL の追加方法

| .flow.ts または .flow ファイル | Flow | uipath-maestro-flow スキル（hitl.md）を通じて、<Name>.flow.ts に hitl(...) を記述します。コンパイル済みの .flow にノード JSON を書き込まないでください。compile によって上書きされます |

| caseplan.case（nodes[] の data.parentElement.type: "case-management:root" を持つ任意の *.json または *.case。このマーカーはノードごとにあり、ディスク上に root ノードはありません） | Case | ステージに action タスクを書き込みます。hitl-casetask-action.md を参照してください | | agent.json | Low Code Agent | エスカレーション CLI は現在開発中です。今のところ手動で案内してください | | .bpmn（Maestro） | Maestro | UserTask の XML を直接書き込みます。Step 5 の「サーフェス：Maestro」を参照してください |

Flow サーフェス（.flow.ts、.flow、または新規 Flow）— デフォルト：ここで停止してください。 HITL の依頼を uipath-maestro-flow スキルに渡してください。このスキルは、既存の .flow をまず逆コンパイルしたうえで、<Name>.flow.ts に hitl(...) を記述し、コンパイルします（hitl.md）。コンパイル済みの .flow を読み込んだり、手動で編集したりしないでください。次回の compile で上書きされます。以下の Step 2～6 では、Case、Low-Code Agent、Maestro のサーフェスについて説明します。

**ユーザーが特定のファイルパスを指定した場合は、**そのパスを直接使用してください。

.flow ファイルが存在せず、サーフェスが Flow の場合は、ソリューションを先に作成してスキャフォールドしてください。Flow プロジェクトは必ずソリューション内に配置する必要があります。

# 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

Flow ファイルのパスは <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 へのアップロード、パッケージ化、および後続のツールで失敗します。

---

Step 2 — ビジネスコンテキストを確認する

既存の .flow ファイルを読み、現在のノードとエッジを把握してください。.flow ファイルのパスに対して Read ツールを使用し、次の点を特定してください。

1. どこに人による判断ポイントを配置するか（既存のどのノードの後か）
2. 人に何を見せる必要があるか — 上流のノードが生成したデータ
3. 人から何を受け取る必要があるか — 下流のノードに必要なデータ
4. 実行できるアクション — 名前付きの結果ボタン
5. フォームの種類：QuickForm（インラインスキーマ、ノードタイプ uipath.human-in-the-loop.quick-form）または AppTask（デプロイ済みのコード化アプリ、ノードタイプ uipath.human-in-the-loop.coded-action-app）？

---

ステップ 2b — HITL の積極的な提案

ユーザーが HITL について明示的に言及していない場合は、次に進む前に、ビジネスの説明に以下のシグナルがないか確認してください。

シグナル	パターン	人による確認が重要な理由
外部システムへの「書き込み」「更新」「投稿」を行うエージェント	書き戻しの検証	本番システムへの誤った書き込みを防ぎます
「信頼度が低い場合」「不確かな場合」「エッジケース」	例外のエスカレーション	エージェントだけでは自律的に解決できません
「承認する」「レビューする」「最終承認する」「二人による確認」	承認ゲート	ビジネス上またはコンプライアンス上の要件です
「不足分を補う」「抽出結果を検証する」「修正する」	データの補完	自動化によって不完全なデータが生成されました
「コンプライアンス」「規制」「監査証跡」	コンプライアンス確認	人による承認が義務付けられています

これを理由に処理を止めないでください。 明確なシグナル（承認、レビュー、最終承認の明示的な要件）がある場合は、HITL ステップを追加し、以下の形式で追加したことを伝えてください。

「説明の中に［具体的な箇所を引用］とあることに気付きました。これは［パターン名］に該当します。人がレビューしない場合、［レビューがない場合に生じる影響を簡潔に説明］。［担当者の役割］が、オートメーションの［続行／書き込み／送信］前に［実行する操作］できるよう、Human-in-the-Loop ステップを挿入します。」

これを伝えたら、返答を待たずにスキーマの設計に進んでください。ユーザーが不要だと判断した場合にステップを削除できるよう、最終レポートでこの決定を目立つように記録してください。シグナルが本当に曖昧な場合に限り、ステップの追加を見送って未決事項として報告してください（「HITL について明示的な言及がない」だけでは不十分です。上記のシグナル一覧自体が、曖昧さを判断する基準です）。

例：

ユーザー：「サポートチケットを読み取り、AI で RCA を生成して、ServiceNow のチケットを更新するオートメーションを構築してください。」

エージェント：「このオートメーションは、AI が生成した内容を ServiceNow に直接書き戻すことに気付きました。これは書き戻しの検証パターンです。RCA が間違っていて誰もレビューしなければ、本番のチケットに誤ったデータが記録されます。サポートリードが RCA をレビューし、必要に応じて編集してから更新を適用できるよう、Human-in-the-Loop ステップを挿入します。」

---

ステップ 3 — タスクの種類を選択する

選択肢はサーフェスによって異なります。 ここで処理を止めないでください。サーフェスとビジネスの説明に最も適した選択肢を選び、その選択を伝えて先に進んでください。ユーザーが実際にその場にいて対応可能な場合に限り、質問してください。非対話型の実行では、推測して先に進んでください。

サーフェス：Flow

以下の手がかりから適切なオプションを判断して選択し、選択した内容を伝えてください。最初にレジストリを検索したり、ユーザーが選ぶまで作業を止めたりしないでください。

#	オプション	ノードタイプ	説明
1	QuickForm	uipath.human-in-the-loop.quick-form	インラインの型付きフォーム — ここで設計したスキーマに基づいて、Action Center がフィールドを表示します
2	New Coded Action App	uipath.human-in-the-loop.coded-action-app	ソリューション内に新しい React + TypeScript アプリをひな形から作成します — UI を完全に制御できます
3	Existing Deployed App	uipath.human-in-the-loop.coded-action-app	Orchestrator にすでにデプロイされているアプリを参照します

デフォルト：QuickForm。 リクエストでデプロイ済みアプリ、コード化されたアクションアプリ、またはカスタム UI の要件が明示されていない限り、QuickForm を選択してください。オプション 2 または 3 を選ぶ根拠となるのは、これらの手がかりだけです。選択内容を伝え、質問はしないでください：「QuickForm を使用します。インラインで、デプロイの手順が不要なため、ほとんどの承認やレビューのタスクに適しています。必要であれば、後から Coded Action App または既存のデプロイ済みアプリに切り替えられます。」

選択したオプション	次の手順
ガイド付き意思決定エクスペリエンス（リクエストで意思決定の記録が求められている場合、またはレビュアーが提案を修正する場合）	ガイド付き意思決定エクスペリエンスを読み、意思決定フィールドとガイド付きレイアウトを追加してから、新しい Coded Action App として接続します
QuickForm	QuickForm HITL ノードの記述方法を読み、手順 1～2 を実行してから、手順 4 に進みます
New Coded Action App	新しい Coded Action App のひな形の作成方法を読み、手順 4c の詳細を確認してから、手順 4 に進みます
Existing Deployed App — リクエストでアプリ名がすでに指定されている必要があります	既存のデプロイ済み Action App の接続方法を読み、手順 4b の詳細を確認してから、手順 4 に進みます

フォールバックルール — 以下の理由で作業を止めず、フォールバックして実施内容を伝えてください。

パス	ブロッカー	応答
Existing Deployed App	Orchestrator にアプリが見つからない、またはアプリ名が指定されていない	QuickForm にフォールバックして続行します。次のように伝えます：「デプロイ済みアプリが見つからなかった（またはアプリ名が指定されていなかった）ため、代わりに QuickForm を使用しました。実際のアプリ名を教えていただければ、切り替えます。」
New Coded Action App	ソースパスに dist/ ビルドがない	QuickForm にフォールバックして続行します。次のように伝えます：「ソースフォルダーに dist/ ビルドがまだないため、ひとまず QuickForm を接続しました。ビルドを実行し、準備ができたら Coded Action App への切り替えを依頼してください。」
New Coded Action App	ソースパスが指定されていない	QuickForm にフォールバックして続行します。次のように伝えます：「アプリのソースパスが指定されていなかったため、チェックポイントを接続するために QuickForm を使用しました。アプリのコードを教えていただければ、Coded Action App に置き換えます。」
カスタムアプリ全般	認証の有効期限が切れている（API 呼び出しで 401）	QuickForm にフォールバックして続行します。次のように伝えます：「セッションの有効期限が切れているようだったため、再認証で作業を止めずに QuickForm を使用しました。uip login を実行し、準備ができたらアプリへの切り替えを依頼してください。」

---

サーフェス：ケース

以下の説明から適切なオプションを推定してください。最初にレジストリを取得したり、処理を進める前にユーザーに選択を求めたりしないでください。

#	オプション	判別要素	説明
1	QuickForm（ファイルベースのスキーマ）	独立した<TaskLabel>.hitl.jsonファイル＋アクションタスク内のhitlType: "quick"コンテキストエントリ	.hitl.jsonファイルに構造化フォームフィールドを記述し、caseplan.caseと同じ場所に配置します。Action Centerが実行時にフィールドをレンダリングします。デプロイ済みアプリは不要です。
2	アプリベースのアクションタスク	=bindings.<id>参照としてのdata.nameとdata.folderPath＋data.actionCatalogName	カスタムの入力／出力フィールドを備えた、デプロイ済みのAction Centerアプリを使用します。アプリがOrchestratorに存在している必要があります。

デフォルト：QuickForm。 リクエストでデプロイ済みのAction Centerアプリが明示的に指定されていない限り、QuickFormを選択してください。選択を伝え、質問はしないでください。「QuickFormを使用します。最もすばやく設定でき、構造化フォームフィールドに対応していて、デプロイ済みアプリも必要ありません。カスタムUIレイアウトが必要になった場合は、後からアプリベースのタスクに切り替えられます。」

ビルド時と設計時。 ケース管理のQuickFormは、双方向のラウンドトリップに対応している必要があります。ここで書き込むJSONは、Studio Webのケースデザイナーが読むもの（設計時）であり、uip maestro case validateとAction Centerが実行時にレンダリングするもの（ビルド時）でもあります。書き込み後は必ず検証してください。

選択したオプション	次のステップ
QuickForm（ファイルベースのスキーマ）	references/hitl-casetask-action.md — Path 1を読み、その後ステップ4に進みます
アプリベースのアクションタスク — リクエストでアプリがすでに指定されている必要があります	references/hitl-casetask-action.md — Path 2を読み、その後ステップ4に進みます

フォールバックルール — 以下を理由に処理を止めず、フォールバックして実施内容を伝えてください。

パス	ブロッカー	対応
アプリベース	アプリがレジストリまたはaction-apps-index.jsonに見つからない、またはアプリ名が指定されていない	QuickFormにフォールバックして続行します。次のように伝えてください。「そのアプリが見つからなかった（または指定されていなかった）ため、代わりにQuickFormを使用しました。実在するアプリ名を教えていただければ、そちらに差し替えます。」
QuickForm	検証でスキーマ設計が拒否される（例：フィールドIDの重複、主なアウトカムの不足）	バリデーターのエラーに基づいてスキーマを修正し、再検証します。ステップ4bのチェックを適用します。最終報告で修正内容に触れ、先にスキーマを再提示して確認を待つことはしないでください。
いずれも	認証の有効期限切れ（API呼び出しで401）	QuickFormにフォールバックして続行します。次のように伝えてください。「セッションの有効期限が切れているようだったため、再認証で処理を止めずにQuickFormを使用しました。準備ができたらuip loginを実行し、アプリへの差し替えを依頼してください。」

---

ステップ4 — 共通設定

これらを理由に処理を止めないでください。回答がない場合は指定されたデフォルトを使用してノードに書き込み、最終報告でデフォルト値を伝えて、ユーザーが変更できるようにしてください。

| タイムアウト | デフォルト：24時間。説明に別の期間が記載または示唆されている場合は、その期間を使用します。 | | 優先度 | デフォルト：Low。説明で緊急性（例：「優先度高」「緊急」「時間的制約あり」）が記載または示唆されている場合は、適宜HighまたはMediumを使用します。選択した値をノードのpriorityフィールドに書き込みます。質問するだけでは不十分です。値を必ずノードに反映してください。 |

---

ステップ4b — スキーマ設計の堅牢性（QuickForm — FlowおよびCase）

クリティカルルール1に従い、ユーザーの確認を待たずに、スキーマの設計時、書き込み前に以下のチェックを適用してください。FlowのQuickFormノードとCaseのQuickFormアクションタスクのどちらにも同様に適用されます。どちらも同じfields[]＋outcomes[]の形状で、directionの意味も同じです。

フィールドの方向

人間がフィールドに対して行う操作に基づいて、方向を選択します。

シグナル	方向
「表示できる」、「表示される」、「読み取り専用」、「表示する」、「レビュー担当者向けのコンテキスト」	input
「入力する」、「記入する」、「タイプする」、「選択する」、「必須の判断」、「承認する」	output
「編集できる」、「修正できる」、「事前入力されているが編集可能」、「レビュー担当者が調整できる推奨値」	inOut

inOut は、フィールドに上流ノードから事前に値が入力され、送信前に人間が変更できることを意味します。ランタイムでは出力フィールドと同様に、$vars.<nodeId>.output.<fieldId> の下に公開されます。

フィールドの型

フィールドに適した JS／JSON の型（string、number、boolean、date、file）を使用してください。これらのみが有効な値です。text は使用しないでください。Case では datetime（date とは異なり、日付と時刻の両方を含む値）もサポートされています。Case 固有の型の表については、hitl-casetask-action.md を参照してください。

スキーマの説明が曖昧または不完全な場合

ユーザーが「いくつかフィールドを追加して」や「適切なものを使って」のように指示した場合は、次の手順に従ってください。

1. .flow ファイル（Flow）、または Case の上流タスクにある outputs[] と root.data.uipath.variables（Case）から確認できる上流データと下流のニーズに基づいて、妥当な既定値を推定します。
2. 書き込む前に、提案するスキーマを明示します。「こちらの内容を提案します。変更したい点があればお知らせください。」
3. バインドできる上流データがない場合（トリガーのみの Flow、または最初のタスクとしてこれを使う Case）は、出力方向のフィールドのみを使用し、「データを取得できる上流の値がないため、レビュー担当者がすべてのフィールドを一から入力します。」と伝えます。

空のフィールドラベルは検証を妨げます

inputs.schema.fields の各フィールドには、空でない label が必要です。flow validate は、label が空または空白文字のみの場合、各フィールドについて重大度がエラーの HITL_QUICK_FORM_FIELD_LABEL_REQUIRED を出力します。すべてのラベルが入力されるまで、Debug と Publish はブロックされます。"label": "" を含むフィールドを生成したり、label キーを省略したりしないでください。

---

Step 5 — ノードを直接記述する

サーフェス：Flow — QuickForm（インラインスキーマのみ）

ノード JSON を workflow.nodes に直接記述し、定義を workflow.definitions に（1 回だけ）追加し、エッジを workflow.edges に接続して、workflow.variables.nodes を再生成します。直接 JSON を記述する方法が既定です。

ノード JSON、定義エントリー、エッジ形式、variables.nodes のアルゴリズム、および 4 つの実例については、QuickForm HITL ノードの記述方法 を参照してください。

CLI（オプトイン）： ユーザーが CLI コマンドを明示的に要求した場合：

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 を自動的に更新します。実行後、各 outcome に 1 つずつ outcome-<outcome.id> ポートを接続してください。

書き込み後、次のコマンドで検証します。

uip maestro flow validate <file> --output json

サーフェス：Flow — Coded Action App（新規インライン）

最初に Step 4c を完了します。アプリ名の確認、ソリューションディレクトリの特定、SDK tarball の確認、スキーマの設計と確認が必要です。

プロジェクトディレクトリとすべてのソースファイルを作成し、プロジェクトをソリューションに追加して、ソリューションのリソースファイルを記述します。その後、新しいアプリを参照する inputs.app を指定して、HITL ノード（型 uipath.human-in-the-loop.coded-action-app）を記述します（アプリはまだデプロイされていないため、appSystemName: null とします）。

プロジェクトの完全なテンプレート、UUID の生成方法、ソリューション CLI コマンド、リソースファイルのテンプレート、ノード JSON、および作成後のビルド手順については、新しい Coded Action App の作成方法 を参照してください。

書き込み後、次のコマンドで検証します。

uip maestro flow validate <file> --output json

サーフェス：Flow — AppTask（デプロイ済みのアクションアプリのみ）

最初に Step 4b を完了してください。アプリが解決され、構成が取得されている必要があります。その後：

ソリューションのコンテキスト（.uipx ファイル）を解決し、ソリューションのリソースファイルを書き込み、アプリ参照を登録し、debug_overwrites.json をマージしてから、Step 3b の構成に基づいて inputs.app に値を設定したノード JSON（タイプ uipath.human-in-the-loop.coded-action-app）を書き込みます。

アプリの検索／選択、構成の取得、リソースファイルの書き込み、appInputBindings を含む完全なノード JSON：既存のデプロイ済み Action App の配線方法

書き込み後に検証します：

uip maestro flow validate <file> --output json

サーフェス：Case

上記の検出で見つかったプランファイルを読み込み、対象ステージを特定します。ファイルは caseplan.case、または古い CLI でスキャフォールディングされたプロジェクトの場合は caseplan.json です。そのファイルを編集して検証してください。隣に別のプランを作成しないでください。action タスクを stage.data.tasks[lane][] に直接書き込みます。直接 JSON に書き込む方法のみがサポートされています。uipath-maestro-case スキルには hitl CLI サブコマンドがありません（Flow の uip maestro flow hitl add とは異なります）。

詳細なリファレンス：references/hitl-casetask-action.md — 3 種類のタスク JSON 形式（QuickForm、汎用、アプリベース）、フィールドのリファレンス、担当者の処理、書き込み後の検証、後続処理での出力へのアクセス。

Step 3 で選択したパス	書き込む内容
QuickForm	direction を含む統合された fields[] と outcomes[] を持つ <TaskLabel>.hitl.json スキーマファイルに加えて、data.context[hitlType].value: "quick"、_schemaFileId（UUID のプレースホルダー）、および .hitl.json 内の schemaId と一致する hitlSchemaId を含む caseplan.case のアクションタスクを作成します。data.inputs[] と data.outputs[] は空の配列にします。root.data.uipath.bindings[] のエントリは不要です。書き込み前に Step 4b のスキーマ設計チェックを適用してください。
アプリベース	data.actionCatalogName と、=bindings.<id> 参照としての data.name および data.folderPath を含むアクションタスクを作成します。ルートレベルのバインディングを 2 つ追加してください。

書き込み後に検証します（ビルド時チェック。成功を報告する前に必ず合格する必要があります）：

uip maestro case validate <caseplan.case> --output json

Case サーフェスでこのスキルが使用する uip maestro case CLI は、uip maestro case validate のみです。作成はすべて JSON に直接書き込みます。

---

サーフェス：ローコードエージェント

ローコードエージェントのエスカレーション CLI（uip agent escalation add）は現在開発中です。提供が開始されるまでは、手動で構成してください。

agent.json のエスカレーションエントリ：

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

エージェントのソース（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

サーフェス：Maestro

QuickForm と coded-action-app の HITL ノードは、どちらも Maestro BPMN プロセスでサポートされています。uipath.human-in-the-loop.quick-form と uipath.human-in-the-loop.coded-action-app は、BPMN バリデーターのレジストリショートカット名として登録されています（bpmn-spec.json）。これらはパレット／検出用の識別子であり、XML にそのまま記述するものではありません。Maestro には専用の CLI サブコマンドがありません（Flow の uip maestro flow hitl add とは異なります）。ノードは .bpmn XML に直接書き込んでください。

確認済みのノード形式（QuickForm タスクが正常に動作し、編集可能な実際の Studio Web BPMN プロセスを直接再現して検証済み）：

<bpmn:task id="Activity_InvoiceApproval" name="Invoice Approval">
  <bpmn:extensionElements>
    <uipath:activity version="v1">
      <uipath:type value="Actions.HITL" version="v2" />
      <uipath:context>
        <uipath:input name="hitlType" type="string" value="quick" />
        <uipath:input name="taskTitle" type="string" value="Please review this invoice and approve or reject" />
        <uipath:input name="labels" type="string" />
        <uipath:input name="priority" type="string" value="Medium" />
        <uipath:input name="actionCatalogName" type="string" />
        <uipath:input name="enableActionableNotifications" type="boolean" value="false" />
        <uipath:input name="assignmentCriteria" type="string" />
        <uipath:input name="recipient" type="json" />
        <uipath:input name="_schemaFileId" type="string" value="<see file-id callout below>" />
        <uipath:input name="hitlSchemaId" type="string" value="<matches schemaId in the .hitl.json sidecar>" />
        <uipath:inputSchema type="jsonSchema"><![CDATA[{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"invoiceid":{"type":"string","title":"Invoice ID"},"amount":{"type":"number","title":"Amount"}},"required":[]}]]></uipath:inputSchema>
      </uipath:context>
      <uipath:input name="HitlTaskArguments" type="json" target="bodyField"><![CDATA[{"invoiceid":"INV-1001","amount":500}]]></uipath:input>
      <uipath:output name="Action" type="string" source="=Action" var="invoiceDecision" options="[{&#34;value&#34;:&#34;Approve&#34;,&#34;label&#34;:&#34;Approve&#34;},{&#34;value&#34;:&#34;Reject&#34;,&#34;label&#34;:&#34;Reject&#34;}]" />
    </uipath:activity>
  </bpmn:extensionElements>
  <bpmn:incoming>edge_into_task</bpmn:incoming>
  <bpmn:outgoing>edge_out_of_task</bpmn:outgoing>
</bpmn:task>

間違えやすい点：

• 要素は bpmn:UserTask ではなく bpmn:task です。 bpmn-spec.json の汎用 Actions.HITL XML テンプレートでは bpmn:UserTask と version="v1" が使われています。このテンプレートは、アプリベース／コード化されたアクションアプリの経路向けです（context フィールドは appId、appVersion、actions、key、taskTitle です）。Studio Web からエクスポートされた実際の QuickForm タスクは、uipath:type value="Actions.HITL" version="v2" を持つ通常の bpmn:task です。QuickForm には上記の形式を、アプリベースには仕様のテンプレートを使ってください。
• <uipath:inputSchema>（<uipath:context> の最後の子要素）と <uipath:input name="HitlTaskArguments">（<uipath:context> の内側ではなく、その兄弟要素）は両方必須です。 これらがないと、Studio Web の「スキーマの編集」キャンバスがまったく開きません。これは直接再現して確認済みです。Case サーフェスで data.inputSchema／data.inputs[] が必要なのと同じです。並行する Case の形式と、フィールドごとの詳しい根拠については、hitl-casetask-action.md § Step 3 を参照してください。
• Action の出力には、対応するプロセスレベルの変数宣言が必要です。 プロセスの最上位にある <uipath:variables version="v1"> ブロック内に <uipath:inputOutput id="<varId>" name="Action" type="string" elementId="<taskId>" /> を追加してください。
• 別個の <TaskLabel>.hitl.json サイドカーファイルが必要です。 Case サーフェスと同じ形式（title、direction／任意の colSpan／binding または variable を含む fields[]、action キーを含まない outcomes[]、schemaId）です。正確な形式については、hitl-casetask-action.md § Step 2 を参照してください。両サーフェスで同一です。
• _schemaFileId は、何もない状態から作成できません。これはサーバーが割り当てる外部キーであり、自分で生成する UUID ではありません。 プレースホルダー値を指定すると、「スキーマの編集」はエラーを表示せずに失敗します（Studio Web の内部 FileOperations/File/Rename 呼び出しで 404 が発生することを、直接再現して確認済みです）。現時点でこれを解決する uip CLI コマンドはありません。これを理由に作業を止めないでください。 新しい UUID v4 のプレースホルダーを書き込み、残りのノードを完成させて検証し、先に進んでください。自分でライブ環境との照合を試みたり、確認のために作業を止めたりしないでください。最終報告では、次のように明記してください。「このタスクのスキーマにはプレースホルダーの _schemaFileId が設定されているため、Studio Web の『スキーマの編集』キャンバスはまだ開きません。編集可能にするには、アップロード後に Studio Web が .hitl.json に割り当てる実際のファイル ID（GET /api/Project/{projectId}/FileOperations/Structure）を解決し、その値を対象の単一ファイル更新（PUT /api/Project/{projectId}/FileOperations/File/{fileId}）で反映する必要があります。プロジェクト全体を再アップロードする uip solution upload ではありません。これを使うとすべてのファイルが再プッシュされ、それぞれに新しいランダムなファイル ID が割り当てられて修正が元に戻ってしまいます。Studio Web でスキーマを編集可能にしたい場合は、この照合を行うよう依頼してください。」これは後でユーザーが対処できる、実際の製品／ツールの制約であり、タスクの途中で解決するものではありません。
• コネクター線を描画するには、論理的な bpmn:sequenceFlow がすでに存在していても、ダイアグラム交換形式のエッジが必要です。 すべての bpmn:sequenceFlow に対応する bpmndi:BPMNEdge（2 つの di:waypoint ポイントを持ち、ソース／ターゲットの図形の接続辺に合わせたもの）を bpmndi:BPMNPlane に含めてください。省略すると、ノードは論理的には接続されていても、キャンバス上では視覚的に切り離されます。これは直接再現して確認済みです。

Step 4b に従ってスキーマを設計してください。Critical Rule 1 に従い、ユーザーからの回答を待って作業を止めないでください。その後、ノードを接続しながら uip maestro bpmn validate <file>.bpmn --output json を頻繁に実行して検証し、形状の誤りがデプロイ時ではなく、すぐに表面化するようにしてください。Maestro では、outputs／inOuts のフィールド名が、宣言済みのプロセス変数名と型に完全に一致している必要があります。

---

ステップ 6 — ユーザーへの報告

配線が完了したら、以下を報告します。

1. 挿入した内容 — ノード ID、ラベル、挿入位置
2. スキーマの概要 — 人が確認する内容（input 方向のフィールド）、入力する内容（output／inOut 方向のフィールド）、クリックする内容（結果）。デプロイ済みのアクションアプリの場合は、retrieve-configuration API のレスポンスに含まれる actionSchema をここに示します。
3. 接続したエッジ — 接続したハンドルと接続先のノード。未接続のハンドルがあれば、その内容
4. ランタイム変数 — $vars.<nodeId>.output（オブジェクト）と $vars.<nodeId>.status（文字列）、および後続での参照方法
5. 検証結果 — 合格、または修正が必要なエラー
6. 本番環境への準備状況に関する注記：
   • QuickForm：ソリューションをパッケージ化すれば、デプロイできます。追加のビルド手順はありません。
   • 新規のコードアクションアプリ：HITL タスクを本番環境で使用するには、アプリをビルド（アプリのソース内で npm run build を実行）し、ソリューションをパッケージ化する必要があります。初回デプロイでシステム名が割り当てられるまでは、アプリは appSystemName: null として表示されます。
   • 既存のデプロイ済みアプリ：アプリはすでに稼働しているため、すぐにデプロイできます。
7. 次のステップ — 準備ができたら、uipath-development スキルを使ってパッケージ化し、公開します。

---

参考資料

• QuickForm HITL ノードの作成方法 — ステップ 3 でユーザーが QuickForm を選択した後に読みます。完全なノード JSON、定義エントリー、エッジ接続、variables.nodes の再生成アルゴリズム、および 4 つのスキーマ例を説明しています。
• 既存のデプロイ済み Action App の接続方法 — ステップ 3 でユーザーが既存のデプロイ済みアプリを選択した場合に読みます。Orchestrator API によるアプリ検索、inputs.app のフィールドマッピング、appInputBindings、ソリューションのリソースファイルについて説明しています。
• 新しいコードアクションアプリのスキャフォールディング方法 — ユーザーがソリューション内に新しい React アプリを作成する場合に読みます。プロジェクトの完全なテンプレート、UUID の生成、ソリューションの CLI コマンド、作成後のビルド手順について説明しています。
• ガイド付き意思決定エクスペリエンス — リクエストで意思決定の記録が求められる場合、またはレビュー担当者が提案を修正する場合に限り読みます。リクエストに基づいて、ガイド付き意思決定エクスペリエンスを有効にするかどうかを判断します。切り替え方法、重要度に応じた記録の詳細度の調整、作成者自身の項目に追加される意思決定フィールド、バックエンドでの記録内容、記録レイアウトについて説明しています。
• HITL のビジネスパターン認識 — ステップ 2／ステップ 2b で、プロセスに人間による確認ポイントが必要かどうか、および該当するパターンを特定するために読みます。積極的な推奨の表現と、HITL を推奨すべきでない場合も記載しています。
• Action Center URL のパターン（uipath-tasks スキル内）— Action Center のタスク URL をユーザーに提示する前に読みます。テナントスラッグが欠落するアンチパターンと、API ホストと UI ホストの対応関係について説明しています。
• ケースアクションタスク（HITL） — ケースの画面に関する資料です。アクションタスク JSON、QuickForm とアプリベースの方法、.hitl ファイル形式、コンテキストエントリー、フィールドのバインド、後続処理での出力へのアクセスについて説明しています。