human-gate-designer

Human Gate Designer

DAG ワークフローにおけるヒューマン・イン・ザ・ループのレビューポイントを設計します。提示する内容、フィードバックの収集方法、判断を DAG に戻す方法を定めます。

---

使用する場面

✅ 次の場合に使用：

• DAG のどこにヒューマンゲートを配置するかを決める
• 各ゲートで人間に何を見せるかを設計する
• フィードバックをどのようにルーティングするかを定義する（承認／却下／修正）
• 自動化の速度と人間による監督のバランスを取る

❌ 次の場合には使用しない：

• ヒューマンゲートの実行時処理（dag-runtime と Temporal シグナルを使用してください）
• 一般的な UI／UX の設計（デザインスキルを使用してください）
• チャットボットの会話フロー（異なるパターンです）

---

ゲート配置の判断ツリー

flowchart TD
  A{Is the action irreversible?} -->|Yes| G1[Gate BEFORE the action]
  A -->|No| B{Is output user-facing?}
  B -->|Yes| G2[Gate AFTER generation, BEFORE delivery]
  B -->|No| C{Cost > $0.50 for remaining nodes?}
  C -->|Yes| G3[Gate at the cost threshold]
  C -->|No| D{Confidence score < 0.7?}
  D -->|Yes| G4[Gate on low-confidence outputs]
  D -->|No| N[No gate needed]

ゲートを配置する場所

状況	ゲートの位置	理由
取り消せない操作（デプロイ、メール送信、送信）	操作の前	元に戻せません
ユーザー向けの成果物（レポート、Webサイト、PR）	生成後、提供前	品質を確認します
残りのコストが高い（>$0.50）	コストのかかるフェーズの前	予算を確認します
信頼度の低い出力（<0.7）	不確実なノードの後	専門家の判断が必要です
タスク分解が曖昧	計画後、実行前	計画を検証します
新しいテンプレート DAG の初回実行	各フェーズの後	徐々に信頼を築きます

---

ゲートの提示方法の設計

人間に見せる内容

┌──────────────────────────────────────────────────────┐
│  🔍 Human Review: [Node Name]                        │
│                                                      │
│  Context: [1-2 sentences: what happened so far]      │
│                                                      │
│  Output to Review:                                   │
│  ┌──────────────────────────────────────────────────┐│
│  │ [The node's output, formatted for readability]   ││
│  │ [Key decisions highlighted]                      ││
│  │ [Confidence: 0.82]                               ││
│  └──────────────────────────────────────────────────┘│
│                                                      │
│  Cost so far: $0.08 / $0.50 budget                  │
│  Remaining nodes: 4 (est. $0.12)                    │
│                                                      │
│  [✅ Approve]  [✏️ Modify]  [❌ Reject]              │
│                                                      │
│  If modifying, what should change?                   │
│  ┌──────────────────────────────────────────────────┐│
│  │ [text input for human feedback]                  ││
│  └──────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────┘

提示の原則

1. 出力だけでなく、コンテキストも示す：人間が把握する必要があるのは、現在のノードの結果だけでなく、DAG がこれまでに何を行ったかです。
2. 判断箇所を強調する：エージェントが行った選択を太字にするか、注釈を付けます。人間が実際に確認するのはこれらの選択です。
3. 信頼度を示す：エージェントが確信を持てなかった場合は、そのことを伝えます。信頼度の低い出力には、より慎重な確認が必要です。
4. コストを示す：人間がこれまでに費やした金額と、残りの金額を把握できるようにします。
5. 「修正」を簡単にする：フィードバックを入力でき、その内容が再試行プロンプトに挿入されるテキスト入力欄を用意します。

---

フィードバックのルーティング

flowchart TD
  H[Human decision] --> A{Decision?}
  A -->|Approve| C[Continue to next wave]
  A -->|Modify| M[Re-execute node with human feedback injected]
  M --> V[Validate modified output]
  V --> H
  A -->|Reject| R{Reject scope?}
  R -->|This node only| RN[Re-plan this node with different approach]
  RN --> H
  R -->|Entire phase| RP[Re-plan from last successful phase]
  RP --> H
  R -->|Abort DAG| AB[Stop execution, return partial results]

フィードバックの挿入

人間が「修正」を選択すると、そのテキストは再実行プロンプトの一部になります。

Original task: [same as before]
Previous output: [the output the human rejected]
Human feedback: "[the human's modification text]"

Revise your output to address the human's feedback.
Preserve the parts they didn't comment on.

---

アンチパターン

すべてのノードの後にゲートを置く

誤り：ノードごとに毎回、人間の承認を必須にすること。 正しい方法：取り消せない操作、ユーザー向けの出力、信頼度の低い判断に限ってゲートを設けます。ほとんどの内部ノードにはゲートは不要です。

承認／却下だけの二択にする

誤り：人間が具体的なフィードバックを提供できず、承認するか却下することしかできないこと。 正しい方法：具体的なフィードバックを入力できる欄とともに、「修正」の選択肢を必ず用意します。

ゲートにコンテキストがない

誤り：説明を付けず、生の JSON 出力を人間に見せること。 正しい方法：DAG が何を行っているか、これまでに何が起きたか、この出力が何を意味するか、承認した場合に次に何が起きるかを示します。