Human-in-the-loop Agent 設計：どの処理で人間の承認が必要か

Feishu（Lark）のメッセージ下書きはできています。タイトル、本文、添付リンクも入っている。残るのは送信だけです。ただしエージェントは send_message の直前で止まり、あなたの確認を待ちます。

メール本文は自動生成できます。しかし顧客へ送る前には、宛先、件名、本文要約、添付を見せる必要があります。CMS フォームも自動で入力できますが、submit_form はポリシーに止められ、owner の承認を待つ。この場面は UI の「確認ボタン」に見えますが、実体は実行状態の停止です。エージェントの RunState を保存し、人間の判断後に実行を再開します。どこで止めるか、誰が承認できるか、拒否やタイムアウトをどう扱うかは、フロントエンドの問題ではありません。ツールシステムの安全境界です。

このガイドでは、リスク分類マトリクス、承認ポイントのチェックリスト、停止と再開の仕組み、監査フィールドのテンプレートをまとめます。「確認ボタンを足す」から「シリアライズでき、再開でき、監査できる状態」に変えるための設計です。

リスク分類マトリクス：どの処理を承認対象にするか

すべての処理を承認対象にする必要はありません。読み取りは自動でよく、削除や支払いは人間を待つべきです。判断には次の 5 つの軸を使います。

軸	分類基準	処理例
外部影響	外部システムやユーザーに影響する	メール送信、フォーム送信、外部 API 呼び出し、Feishu/Slack などの協業システムへの書き込み
可逆性	処理を取り消せるか	レコード削除（不可逆）、下書き保存（可逆）、支払い（一部は補償で対応）、メッセージ送信（不可逆）
データ感度	扱うデータのレベル	公開データの照会（公開）、内部レコードの変更（内部）、ユーザー個人情報のエクスポート（機密）、本番設定の読み取り（機密）
金額/権限しきい値	資金や権限変更を含む	支払い、送金、返金、権限変更、バルク処理、ユーザーデータ削除
自律度	許可する自動化レベル	読み取り照会（完全自動）、下書き作成（完全自動）、外部送信（確認）、削除/支払い（承認）

このマトリクスは、OWASP LLM06 が扱う過剰な機能、過剰な権限、過剰な自律性というリスク分類とよく対応します。そのまま使ってもよいですし、業務に合わせてしきい値を調整してもかまいません。

外部影響：他のシステムや人に届く処理は注意が必要です。メールは送った後に戻せません。フォーム送信は注文を発火するかもしれません。外部 API 呼び出しは相手側のデータを変える可能性があります。

可逆性：レコード削除は不可逆です。下書きはいつでも直せます。支払いは一部戻せても、返金や補償フローが必要です。

データ感度：公開データは比較的自由に読めます。内部データは書き込みを制限し、ユーザー個人情報や本番設定のような機密データは承認対象にします。

金額/権限しきい値：お金や権限変更が絡む処理は止めるべきです。支払い、送金、返金、権限変更、バルク処理は高リスクです。

自律度：読み取りは完全自動でよい。下書きも、まだ下書きなので自動化できます。外部送信は確認が必要で、削除と支払いは承認が必要です。

このマトリクスは一度決めて終わりではありません。たとえば社内通知としての「メッセージ送信」は低リスクなら「確認」に下げられます。一方で実際のお金を動かす「支払い」は、承認 + 2 人レビューのままにします。

3 つの実例で見るリスク分類

ケース 1：Feishu メッセージ下書き

エージェントが Feishu のメッセージ下書きを作るだけなら、自動実行（L0）でかまいません。下書き箱に保存されるだけで、送信されず、可逆で、外部影響も機密データもありません。しかし send_message で顧客へ送る瞬間は承認（L2）が必要です。送信後は不可逆で、外部ユーザーに届き、機密情報や誤解を招く内容を含むかもしれません。MCP tools/call の前に確認する典型例です。

ケース 2：メール送信

メール本文を生成するだけなら自動実行（L0）です。まだ文字列であり、いつでも直せます。しかしメール API で顧客へ送る段階では、宛先、件名、添付を見せる承認（L2）が必要です。承認 UI は「送信を確認」だけでは足りず、要約と証拠を出すべきです。

ケース 3：CMS フォーム送信

フォーム入力は自動実行（L0）でよいです。まだ送信されておらず、データはローカルにあります。しかし CMS API で submit する段階では、ポリシーが止めて owner approve を待つ（L2）。これは「金額がしきい値を超えた」という guardrail でも、「すべての CMS 送信は承認」という静的 policy でも実現できます。

ケース 4：本番データベース削除

本番データベースの照会は自動実行（L0）でよいです。読み取りであり、外部影響もなく、データを変更しません。しかし削除 API を呼ぶなら、強い人間承認 + backup 監査（L3）が必要です。本番 DB の削除は不可逆で、機密データに触れ、ユーザーへ影響します。Guardrail だけに任せず、Policy の強制ルールで制限します。

この 4 例が示すのは、同じタスクでもステップごとにリスクが違うということです。下書きは自動、送信は承認、本番削除は 2 人レビュー。リスク分類は具体的な処理まで分解します。

承認ポイント定義チェックリスト：処理タイプまで具体化する

マトリクスができたら、承認レベルを定義します。よくある処理タイプは次のとおりです。

L0 自動実行：データベース照会、ベクトル検索、設定読み取りなどの読み取り処理。下書き保存、プレビュー生成などの下書き処理。外部影響がなく、可逆で、機密データを扱わない処理です。

L1 確認：メール送信、フォーム送信、外部 API 呼び出しなどの外部送信/データ送信。データエクスポートやバルク照会などのバルク読み取り。外部影響はあるが制御しやすいため、厳密な承認ではなく確認にします。

L2 承認：レコード削除、権限変更、バルク削除などの削除/権限変更。Feishu、Slack、CRM への書き込み。不可逆または外部影響が大きいため、停止して承認を待ちます。

L3 強い承認 + 2 人レビュー：注文支払い、返金などの支払い/送金。ユーザー個人情報のエクスポート、本番設定変更、本番 DB 削除などの機密データ操作。お金や機密データに触れるため、2 人レビューが必要です。

このチェックリストは、OpenAI Agents SDK の needs_approval と MCP Tools の安全推奨に対応します。MCP spec は、ツール呼び出しをユーザーが見られ、拒否でき、機密操作では確認できるべきだとしています。これは L2/L3 に対応します。

業務に合わせて調整できます。

Feishu メッセージ送信が社内通知だけなら L1 確認に下げられます。
レコード削除がユーザーデータに触れるなら L2 承認を維持します。
支払いリスクが高いなら L3 に上げ、2 人レビューと承認理由を必須にします。

このリストも固定ではありません。業務ルールが変われば、「メッセージ送信」を承認リストから外すこともあります。

承認フローの状態機械：停止、状態保存、再開

承認は UI ポップアップではなく、実行状態の停止です。ツール呼び出しが承認を必要とすると、エージェントの RunState を保存し、判断後に再開します。

状態遷移図

承認の状態機械は次の流れです。

request -> pending -> approved/rejected/timeout -> resume/abort/compensate

具体的には次のように進みます。

request：ツール呼び出しが承認リクエストを作り、RunState に tool 名、引数、コンテキストを入れます。
pending：人間の判断を待ちます。状態は checkpoint に保存され、thread_id と関連付けられます。
approved：承認されると checkpoint から再開し、ツールを呼び出します。
rejected：拒否されると abort または convert to draft に進みます。
timeout：タイムアウトすると escalate または auto-reject に進みます。
resume/abort/compensate：実行再開、タスク中断、補償処理を行います。

再開方式

再開方式は 3 つです。

approve：実行を続け、ツールを呼び、次のステップへ進みます。
reject：中断するか下書きに変更し、ツールは呼びません。
edit：メールの宛先や本文など引数を修正し、再度承認して続行します。

checkpoint と thread state は状態保存の技術的な背景です。詳しくは公開済みの LangGraph checkpoint/thread state 記事を参照してください。checkpoint は停止時の状態を保存し、thread state は再開時に実行点へ戻るために使います。

OpenAI Agents SDK HITL コード例

次のコードは OpenAI Agents SDK の承認フローを示す例です。API は変わる可能性があるため、本番コードでは公式ドキュメントを確認してください。

from agents import Agent, Runner, function_tool


@function_tool(needs_approval=True)
def send_email(to: str, subject: str, body: str) -> str:
    return send_email_handler(to=to, subject=subject, body=body)


agent = Agent(
    name="EmailAgent",
    tools=[send_email],
    instructions="メール下書きを作成し、送信前に承認を待つ",
)

result = Runner.run_sync(agent, "顧客向けの返金通知メールを書いてください")

if result.interruptions:
    state = result.to_state()

    for interruption in result.interruptions:
        print(f"承認待ちツール: {interruption.tool_name}")
        print(f"引数: {interruption.arguments}")

        decision = show_approval_ui(interruption)

        if decision == "approve":
            state.approve(interruption)
        elif decision == "reject":
            state.reject(interruption)

    result = Runner.run_sync(agent, state)

要点は次のとおりです。

needs_approval=True でツールに承認必須を付けます。
interruptions に承認待ちのツール呼び出しが入ります。
result.to_state() で停止結果をシリアライズ可能な RunState に変換します。
state.approve() または state.reject() で判断を記録します。
Runner.run_sync(agent, state) で停止点から再開します。

フィールド名は 2026-07 以降に変わる可能性があるため、公式ドキュメントで確認します。

LangGraph interrupt/resume コード例

次のコードは LangGraph の interrupt と Command(resume=...) を示します。

from langgraph.graph import StateGraph, MessagesState
from langgraph.checkpoint.memory import MemorySaver
from langgraph.types import Command, interrupt


def send_email_node(state: MessagesState):
    approved = interrupt({
        "action": "send_email",
        "summary": state["email_summary"],
    })

    if approved != "approved":
        return {"messages": ["メール送信は拒否されました。下書きとして保存しました"]}

    email_result = send_email(state["email_params"])
    return {"messages": [email_result]}


graph = StateGraph(MessagesState)
graph.add_node("send_email", send_email_node)
graph.add_edge("draft_email", "send_email")

checkpointer = MemorySaver()
app = graph.compile(checkpointer=checkpointer)

thread_id = "thread_123"
config = {"configurable": {"thread_id": thread_id}}

result = app.invoke(
    {"messages": ["顧客向けの返金通知を書いてください"]},
    config=config,
)

# graph が停止すると、interrupt payload が呼び出し側へ返ります。
# 承認 UI を表示し、人間の判断を待ちます。
decision = show_approval_ui(result["__interrupt__"])

if decision == "approve":
    app.invoke(Command(resume="approved"), config=config)
elif decision == "reject":
    app.invoke(Command(resume="rejected"), config=config)
elif decision == "edit":
    app.update_state(config, {"email_params": {"to": "new_customer@example.com"}})
    app.invoke(Command(resume="approved"), config=config)

要点は次のとおりです。

interrupt() が graph を停止します。
Command(resume=...) が実行を再開します。
checkpoint + thread_id で状態を一貫させます。
approve/reject/edit の 3 つの再開方式を扱えます。

API は変わる可能性があるため、LangGraph の公式ドキュメントを確認してください。

承認証跡フィールド：何を保存し、どう追跡するか

承認は判断だけではありません。判断を記録する必要があります。最小の監査ログフィールドは次のとおりです。

フィールド	説明	例
tool_name	ツール名 + 操作タイプ	send_email / delete_record
tool_arguments	完全な引数 JSON	{“to”: “customer@example.com”, “subject”: “返金通知”}
invoker_id	呼び出し元の ID（ユーザーまたはシステム）	user@example.com / agent_run_abc123
request_time	承認リクエスト時刻	2026-06-23T09:26:10Z
approver_id	承認者 ID	on-call-engineer@example.com
decision_time	判断時刻	2026-06-23T09:35:12Z
decision	判断結果	approved / rejected / timeout_auto_reject
evidence	承認証跡（スクリーンショットや要約）	“宛先は正しく、本文に機密情報はない”
audit_trail_id	実行ログへ関連付ける ID	run_abc123_step_5_tool_3

これらの項目は MCP Tools の監査推奨と、OpenAI API の mcp_approval_request item に基づきます。承認ログは可観測性の一部です。より広いログ設計は公開済みの Agent monitoring/recovery 記事を参照してください。

RunState をどうシリアライズするか。OpenAI Agents SDK では result.to_state() で停止結果を RunState に変換できます。LangGraph は checkpoint + thread_id を使います。シリアライズした状態を DB やログシステムに保存し、audit_trail_id と関連付けます。

監査ログの主な用途は 3 つです。

インシデント追跡：後でデータ漏えいが見つかったとき、誰がいつどの処理を承認したかを確認できます。
コンプライアンス証跡：企業環境では、高リスク操作に人間の承認があったことを示す証拠になります。
ポリシー改善：承認頻度が高い処理や拒否が多い処理を集計し、承認ポリシーを調整できます。

フィールドは固定ではありません。承認時間、承認チャネル（メール/Slack/Feishu）、2 人レビューの有無などを追加できます。ただし最小セットは残します。

拒否とタイムアウト：承認に失敗した後の処理

承認は必ず通るわけではありません。拒否とタイムアウトの経路を決めないと、タスクが止まったままになります。

拒否後の 3 つの経路

経路 1：continue with fallback。低リスクな処理へ切り替えて続行します。メール送信が拒否されたら下書き保存に変える、といった形です。降格できる処理に向いています。

経路 2：convert to draft。処理を下書き状態へ変えます。CMS 送信が拒否されたら下書きとして保存し、人間が修正してから再送信します。人間の介入が必要な場面に向いています。

経路 3：abort task。タスク全体を止めます。本番 DB 削除が拒否されたら、タスクは停止すべきです。不可逆な高リスク処理に向いています。

選び方は処理タイプで決めます。

可逆な処理：fallback または convert to draft。
不可逆な高リスク処理：abort task。
人間の介入が必要な場面：escalate。

タイムアウト後の 2 つの経路

経路 1：escalate to backup approver。主承認者が 30 分応答しなければ、on-call engineer へ回します。人間の判断が必要な場面に向いています。

経路 2：auto-reject。1 時間などの期限を過ぎたら自動拒否し、タスクを止めます。リスクが比較的低く、時間制約がある処理に向いています。

選び方は文脈で決めます。

高リスク処理：escalate。自動的に実行へ進めない。
時間制約がある処理：auto-reject。タスクをいつまでも止めない。
一般的な場面：escalate。承認者にもう少し時間を与える。

実行済みステップをどう戻すか

拒否後にタスクを止める場合、すでに実行したステップを戻す必要があるかもしれません。たとえば支払い承認が拒否される前に注文を作成していたなら、その注文をキャンセルします。

ロールバック戦略は次のとおりです。

checkpoint rollback：承認前の checkpoint へ戻り、その後のステップを破棄します。
補償トランザクション：注文キャンセルや、可能ならメール送信の取り消し API など補償 API を呼びます。
人間の介入：手動キャンセルなど、人間に処理を依頼します。

ロールバックは常に成功するとは限りません。送信済みメールは戻せません。その場合は監査ログを残し、事後対応します。

4 層の安全境界：Policy、Guardrail、Approval、Audit の組み合わせ

承認は単独の安全機構ではありません。Policy、Guardrail、Approval、Audit の 4 層を組み合わせます。どれも他の層を代替しません。

4 層の責務表

層	責務	例
Policy	静的ルールでツール範囲を制限する	「本番 DB は削除禁止」「支払いツールは sandbox だけ呼ぶ」
Guardrail	入出力の異常を自動チェックして止める	入力検証、出力サニタイズ、機密情報フィルタ、金額しきい値チェック
Approval	高リスク処理を人間が判断する	メール送信前に宛先と本文を表示、レコード削除前に確認、支払い承認
Audit	事後追跡できるように記録する	承認ログ、ツール呼び出しログ、状態変更ログ

4 層は互いに代替できません。

Policy は Guardrail を代替できません。Policy は静的ルールであり、動的な入出力までは検査できません。
Guardrail は Approval を代替できません。Guardrail は自動チェックであり、業務判断が必要な場面は扱えません。
Approval は Audit を代替できません。Approval は判断で、Audit は追跡です。両方必要です。
Audit は前の 3 層を代替できません。Audit は事後の記録であり、リスク発生を止められません。

組み合わせ例です。

支払い：Policy で金額上限を制限し、Guardrail で引数形式を検査し、Approval で 2 人レビューし、Audit で判断を記録します。
メール：Policy で送信先ドメインを制限し、Guardrail で機密内容を検査し、Approval で要約を表示し、Audit で送信ログを残します。

MCP ツールの安全境界

MCP（Model Context Protocol）のツール呼び出しには独自の安全境界があります。spec 2025-06-18 については公開前に再確認してください。

tools/list は利用可能なツールを表示します。ユーザーはエージェントが何を呼べるかを見られ、隠れたリスクを避けられます。
tools/call 前の確認は、機密操作に対する Approval 層です。
inputSchema 検証は Guardrail 層に対応します。
timeout はツール呼び出しが止まり続けることを防ぎます。
audit logging は Audit 層です。

重要な点：MCP approval は OAuth scope や server-side authorization を代替しません。MCP approval はツール呼び出し前の確認です。OAuth scope は API アクセス権限です。server-side authorization は業務ロジック上の権限チェックです。3 つすべてが必要です。

たとえば Feishu MCP server の OAuth が通り、scope に send_message が含まれていても、そのメッセージが安全とは限りません。MCP approval で送信前に内容を確認し、server-side authorization で送信先が許可範囲かを確認します。

外部送信、協業システムへの書き込み、表のバルク変更の承認場面は、計画中の Feishu MCP 調査記事で扱います。

承認 UI の設計ポイント

承認 UI は「承認/拒否」ボタンだけでは不十分です。判断に必要な情報を見せる必要があります。

設計原則です。

ツール名と引数を見せ、エージェントが何をどのパラメータで呼ぶかを承認者が理解できるようにします。
期待される影響を見せます。たとえば「customer@example.com に、件名『返金通知』のメールを送る」。
取り消し可否を見せます。「送信後は取り消せません」「削除後も復元できます」など。
データ感度を見せます。「ユーザー個人情報を含む」「公開データ」など。
「キャンセル」と「拒否」を分けます。キャンセルはこの承認操作をやめること、拒否はツール呼び出しを否定して監査ログに残すことです。

主要要素です。

ツール名 + 操作タイプ
完全な引数（必要なら折りたたみ）
想定される影響の要約
取り消し可否の警告
データ感度ラベル
承認理由の入力欄（任意または必須）
承認 / 拒否 / キャンセルボタン

重要な点：UI は server-side authorization を代替しません。承認 UI は表示であり、server-side authorization はバックエンドの権限チェックです。承認者が確認しても、バックエンドは権限を検査します。

たとえば UI に「record ID=123 を削除」と表示され、承認者が確認したとしても、バックエンドはそのレコードが現在のユーザーに属するか、削除権限があるかを確認します。

HITL は孤立したポップアップではありません。ツールゲートウェイ、ログ、権限システムの中に置くものです。計画中の MCP 本番アーキテクチャ記事で扱います。

OWASP LLM01/LLM06 リスク対応

OWASP LLM Top 10 は LLM とエージェントのセキュリティリスクを定義しています。バージョンや番号は変わる可能性があるため、公開前に確認します。承認設計に直接関係するのは次の 2 つです。

リスク番号	リスク説明	承認での対策
LLM01 Prompt Injection	外部入力が未許可の関数呼び出し、データ漏えい、外部コマンド実行を誘導する	高リスク処理には人間承認を必須にする。prompt ルールだけに頼らず、承認 UI で引数と想定影響を見せる
LLM06 Excessive Agency	過剰な機能、過剰な権限、過剰な自律性がエージェントのツールシステムリスクになる	Policy でツール範囲を制限し、Approval で自動化レベルを制限し、「このセッションでは常に許可」ボタンの範囲を限定する

LLM01 は、prompt injection によりモデルが元の指示から外れ、未許可ツールを呼ぶ可能性を示します。高リスク処理の前で止め、引数と想定影響を見せ、人間が判断できるようにします。

LLM06 は、過剰な自律性がツールシステムのリスクになることを示します。承認は万能ではありません。ツール範囲を絞る Policy と、自動化レベルを絞る Approval を組み合わせます。「このセッションでは常に許可」は範囲を限定しないと、prompt injection に悪用されます。

NIST AI RMF Core への対応

NIST AI RMF Core は、AI システムのリスク管理を 4 段階で整理します。個人開発者や小規模チームなら、企業向けの重いコンプライアンスにせず軽量版で使えます。

段階	承認での責務	例
Govern	役割とリスクルールを定義する	owner/on-call engineer などの承認者ロール、L0〜L3 の承認レベル、拒否とタイムアウト処理を定義する
Map	高リスク場面を特定する	リスクマトリクスで削除、支払い、権限変更を特定し、prompt injection 経路も洗い出す
Measure	承認カバレッジと拒否率を測る	高リスク処理の承認カバレッジ、拒否率、タイムアウト率を集計し、ポリシーを改善する
Manage	インシデント対応と復旧を行う	承認ログで事故を追跡し、実行済みステップを戻し、補償トランザクションを実行する

Govern では承認ルールを定義します。Map では高リスク場面を見つけます。Measure では承認カバレッジ、拒否率、タイムアウト率を測り、ルールを調整します。Manage では事故対応と復旧を扱います。

個人や小規模チームなら、承認レベルの定義、高リスク処理の特定、拒否率の記録、監査ログ保存だけで十分です。企業級のプロセスは不要ですが、最小セットは必要です。

まとめ

承認設計の最初のステップはリスク分類です。すべての処理を承認対象にする必要はありません。読み取りと下書きは自動化でき、削除と支払いは人間を待つべきです。外部影響、可逆性、データ感度、金額/権限しきい値、自律度の 5 軸で判断します。

承認はポップアップではありません。シリアライズでき、再開でき、監査できるシステム状態です。RunState を checkpoint に保存し、停止点から再開し、監査ログに判断と実行チェーンを残します。

4 層の安全境界は役割が違います。Policy はツール範囲を制限し、Guardrail は入出力を自動チェックし、Approval は高リスク処理の人間判断を置き、Audit は追跡可能にします。組み合わせて使う必要があります。

OWASP LLM01 と LLM06 は、prompt injection と過剰な自律性がエージェントのツールシステムで中心的なリスクになることを示しています。承認は Policy と Guardrail と一緒に使うべきで、単独で完結しません。

NIST AI RMF Core はリスク管理の枠組みを提供します。小規模チームなら軽量版で十分です。承認レベルを定義し、高リスク処理を特定し、拒否率を測り、監査ログを残します。

次に読むもの：

公開済みの LangGraph checkpoint/thread state 記事：承認状態を保存する技術的背景。
公開済みの Agent monitoring/recovery 記事：承認ログを可観測性に組み込む方法。
計画中の MCP 本番アーキテクチャ記事：HITL をツールゲートウェイと権限システムに置く理由。
計画中の Feishu MCP 調査記事：外部送信や協業システム書き込みの承認シナリオ。