n8n AIノードの冪等性、再試行、人による承認ゲート

モデルを呼ぶn8nワークフローは、ハッピーパスが一度動くと完成したように見えます。本番は、同じwebhookの二度目の配信、最初の呼び出しがすでに成功した後に再試行するタイムアウト、承認ステップの所有者がいないために自動送信された下書きで壊れます。

本稿はAIを含むワークフローの堅牢化層です。冪等性、再試行方針、人による承認ゲート、ログを扱います。初めてのn8n AIエージェントとヒューマン・イン・ザ・ループ設計の確認パターンと組み合わせてください。

すでにCRMメモを作成した、メッセージを送った、あるいはメールをキューに入れた可能性のあるノードで再試行を有効にすると、結果が不明な場合に副作用が重複しかねません。プロバイダーの冪等性または突き合わせの挙動が証明されるまで、すべての外部書き込みを「繰り返してはならないもの」として扱ってください。

AIステップに異なる失敗処理が必要な理由

通常のHTTP呼び出しやモデル呼び出しは、ステータスコード、タイムアウト、不正な応答、コミット状態の不明によって失敗しえます。モデルを含むステップには、さらに次のような失敗モードが加わります。

• 遅いローカル推論でのタイムアウト（ローカルOpenAI互換エンドポイント）。
• モデルがJSONではなく散文を返すパース失敗。
• ソフト失敗：JSONとしては妥当だが、内容が誤っている。
• 部分成功：モデルは答えたが、後続のツール書き込みが失敗した。

盲目的な再試行は一部のタイムアウトを直します。しかし、それ以外は増幅します。転送層の再試行（サーバーが処理をコミットしていないなら安全）と業務上の再試行（冪等性キーがあってはじめて安全）を分けてください。

n8nでは、オペレーターが実行履歴から失敗した実行を再試行できます（n8n execution documentation）。このオペレーター向け機能は、副作用を繰り返して安全であることを証明するものではありません。ワークフローには、以下で述べる処理権の確保、突き合わせ、アウトボックスの制御が依然として必要です。

冪等性は処理権のアトミックな確保から始まる

トリガーが許すかぎり早い段階で、安定したキーを選びます。

SELECT keyのあとにINSERT keyを実行する形にしてはいけません。また、スプレッドシートの行をロックとして使わないでください。2つのn8nワーカーが同時に「存在しない」と観測し、どちらも先に進んでしまいます。データベースの一意性制約と、単一のアトミックな文を使ってください。PostgreSQLは、一意制約をキーの一意性を保証する仕組みとして文書化しています（PostgreSQL constraints）。

最小のPostgreSQLの形（型、保持期間、マイグレーションは自分のシステムに合わせてください）：

CREATE TABLE workflow_runs (
  idempotency_key text PRIMARY KEY,
  state text NOT NULL CHECK (state IN (
    'processing', 'awaiting_human', 'approved',
    'completed', 'failed_retryable', 'failed_terminal'
  )),
  payload_hash text NOT NULL,
  lease_owner uuid,
  lease_expires_at timestamptz,
  version bigint NOT NULL DEFAULT 0,
  result jsonb,
  updated_at timestamptz NOT NULL DEFAULT now()
);

n8nの実行ごとに、ランダムなlease_owner UUIDを生成します。新しいキーの処理権の確保、または明示的に再試行可能／期限切れのリースの回収だけを、1つの文で行います。

INSERT INTO workflow_runs (
  idempotency_key, state, payload_hash, lease_owner, lease_expires_at
)
VALUES ($1, 'processing', $2, $3, now() + interval '5 minutes')
ON CONFLICT (idempotency_key) DO UPDATE
SET lease_owner = EXCLUDED.lease_owner,
    lease_expires_at = EXCLUDED.lease_expires_at,
    state = 'processing',
    version = workflow_runs.version + 1,
    updated_at = now()
WHERE workflow_runs.payload_hash = EXCLUDED.payload_hash
  AND (workflow_runs.state = 'failed_retryable'
       OR (workflow_runs.state = 'processing'
           AND workflow_runs.lease_expires_at < now()))
RETURNING idempotency_key, lease_owner, version;

返る行がゼロなら、そのキーは別の実行が保持しているか、その実行がすでに再試行不可の状態に達しています。その場合は状態を取得し、何もしないか、以前の結果を返してください。同じキーが異なるpayload_hashで届いた場合は、調査のために停止してください。変化した業務入力を同じイベントとして黙って扱うことは、上流の破損を覆い隠します。

リースは有効期限を持ち、その所有者だけが更新できなければなりません。状態遷移はすべてコンペア・アンド・セット（CAS）で行います。

UPDATE workflow_runs
SET state = $4, version = version + 1, updated_at = now()
WHERE idempotency_key = $1
  AND lease_owner = $2
  AND version = $3
  AND lease_expires_at > now()
RETURNING version;

行が返らない場合、この実行は所有権を失っており、行動してはいけません。最初のリース長は実測の処理時間から決め、期限前に更新し、リースの総寿命に上限を設け、リースの奪取が繰り返される場合はアラートを上げてください。リースは、放棄された処理が永久にブロックし続けるのを防ぎますが、冪等でない外部送信を安全にするものではありません。

Webhookの配信とワーカーの実行は、通常は「少なくとも一度」です。データベース上で処理権を確保すれば、同時実行時の所有者を一意に決められます。しかし、それはネットワーク境界を越えたメール、決済、CRMの操作を「ちょうど一度」にするものではありません。それには、下流側の冪等性キーか、結果不明の状態を突き合わせられるアウトボックス／ディスパッチャーが必要です。

AIノードの再試行方針

簡潔な対応表を使い、暗黙知ではなくワークフローに組み込んでください。

エージェントノードの最大反復回数は有限に保ってください。すでにツールをループしているエージェントの周りに再試行ラッパーを置くことが、トークン請求と重複したツール呼び出しが爆発する典型的な経路です。

ローカルエンドポイントでは、実測のレイテンシからタイムアウトを決めてください。同期的な顧客向けwebhookに「60秒×3回の再試行」を積み重ねないでください。

副作用を遮断する人による承認ゲート

人による承認ゲートとは、「ご参考まで」と伝えるSlackメッセージではありません。明示的な承認の合図があるまで、顧客に見えるアクションや不可逆なアクションが一切走らない状態のことです。

n8nで機能する3つのパターンがあります。

1. 実行前承認（Approve-before-act）

AIノード → スキーマ検証 → 下書きとキーをストアに書き込む → 単回使用の承認チャレンジを作成 → 認証済みで期限内の承認トランザクションだけが送信をキューに入れられる。

2. 窓付き実行（Act-with-window）

キャンセル窓を設けて後送信をキューに入れます。遅れてのキャンセルが意味を持つ程度にアクションが可逆な場合にのみ使ってください。

3. 例外時承認（Approve-by-exception）

決定的な適格性ルールと、較正された評価の証拠が承認済みのしきい値を満たす、狭く可逆なケースに限って自動実行します。それらも標本抽出して監視し、不確かなときはエスカレートするか判断を控えてください。モデルが自己申告する確信度は、強制力のある制御ではありません。

ゲートの選択は結果の重大さに対応付けてください。ヒューマン・イン・ザ・ループ設計と同じ判断モデルです。顧客向けメール、返金、アカウントやCRMの変更、通常の業務上の金銭的アクションは、実測の根拠と方針が別の扱いを認めるまで、実行前承認のままにします。医療的な治療、法的助言、規制対象の金融助言、児童の安全に関わる判断、構造・建築に関わる判断は、有資格の専門家による確認が必要です。自動化は記録の準備や振り分けはできますが、その確認を置き換えてはなりません。

承認カード上のゲートチェックリストの例：

• 冪等性キー
• ソースレコードへのリンク
• モデル出力（下書き／ラベル／スコア）
• 検証エラー（あれば）
• ログに残す承認者の身元
• 保留状態の有効期限

承認リンクはベアラー資格情報である

https://n8n.example/webhook/approve?id=ticket-42&action=approveのようなURLを送ってはいけません。推測、転送、スキャン、再送のいずれかができる者は誰でも行動できてしまいます。暗号学的に安全な乱数で少なくとも256ビットのトークン材料を生成し、不透明なトークンはHTTPS経由でのみ送り、保存するのはそのSHA-256ハッシュだけにしたうえで、次を併せて保持してください。

• 実行キーと許可された決定内容
• 想定する承認者・対象範囲、またはSSO方針
• 絶対的な有効期限
• consumed_at、決定内容、承認者の身元
• 単回使用の制約

GETは確認ページを表示するだけにし、状態を変更してはいけません。決定は、認証とCSRF対策を経たPOSTで送信してください。複雑さの低いケースでは、現行のn8nノードが処理を一時停止して承認を求めることができます。n8n自身は、より複雑な承認にはWaitノードを推奨しています（n8n Gmail approval operation）。実際にデプロイするノードとバージョンについて、認証、有効期限、転送、監査のセマンティクスを検証してください。メールのボタンが、決済や法務の承認に自動的に適するわけではありません。

不変の業務上の冪等性キーにひもづけた承認レコードを作ります。

CREATE TABLE approvals (
  approval_id uuid PRIMARY KEY,
  idempotency_key text NOT NULL REFERENCES workflow_runs(idempotency_key),
  token_hash bytea NOT NULL UNIQUE,
  allowed_decisions text[] NOT NULL,
  expires_at timestamptz NOT NULL,
  consumed_at timestamptz,
  decision text,
  approver_subject text,
  created_at timestamptz NOT NULL DEFAULT now()
);

生のトークンはアプリケーション側でハッシュ化し、ダイジェストだけを$1として渡します。消費はアトミックに行います。

UPDATE approvals
SET consumed_at = now(), decision = $2, approver_subject = $3
WHERE token_hash = $1
  AND consumed_at IS NULL
  AND expires_at > now()
  AND $2 = ANY (allowed_decisions)
RETURNING idempotency_key;

返る行がゼロなら、期限切れ、無効、使用済み、または許可されていない決定です。送信しないでください。この文は、続いて対応するworkflow_runsの行をロックし、まだawaiting_humanであることを確認し、approvedに更新し、一意なアウトボックス行を挿入する、1つのトランザクションの中で実行してください。いずれかのステップが失敗したら、トランザクション全体をロールバックします。結果の重大なアクションでは、ログイン済みのSSOに加えて役割と職務分離のチェックを必須にしてください。メールのリンクを持っているだけでは不十分です。

モデルにauto_replyを選ばせ、ワークフローで強制するしきい値なしにその選択をそのまま尊重させないでください。プロンプトは提案し、ノードが強制します。

外部操作のためのトランザクショナル・アウトボックス

承認の消費、実行状態の変更、意図した外部操作の記録は、1つのデータベーストランザクションの中で行うべきです。承認webhookの内側から送信しないでください。最小のアウトボックスの制約は次のとおりです。

CREATE TABLE effect_outbox (
  effect_id uuid PRIMARY KEY,
  idempotency_key text NOT NULL REFERENCES workflow_runs(idempotency_key),
  effect_type text NOT NULL,
  target text NOT NULL,
  payload jsonb NOT NULL,
  state text NOT NULL CHECK (state IN ('pending', 'sending', 'completed', 'unknown', 'failed')),
  lease_owner uuid,
  lease_expires_at timestamptz,
  provider_id text,
  created_at timestamptz NOT NULL DEFAULT now(),
  UNIQUE (idempotency_key, effect_type, target)
);

アウトボックスのワーカーは、期限付きのリースでpending状態の行の処理権を確保し（PostgreSQLのFOR UPDATE SKIP LOCKEDはキューのような消費者のために設計されています。locking clause documentationを参照）、対応している場合は同じ冪等性キーでプロバイダーを呼び、プロバイダーの外部IDを保存し、その後CASで行を完了としてマークします。

冪等でないアクションをプロバイダーが受け付けた可能性がある状態でワーカーがタイムアウトした場合は、その外部操作をunknownとマークし、再試行の前にプロバイダーと突き合わせてください。たとえばSMTPの送信は、ローカルのデータベーストランザクションによって「ちょうど一度」にすることはできません。結果不明のあとの自動再送こそが、顧客宛メールの重複が起きる経路です。

インシデント後にも役立つログ

n8nの実行履歴は出発点です。それ自体はコンプライアンスのアーカイブではありません。AIステップでは、キーごとに構造化イベントをログしてください。

• タイムスタンプとワークフローの版／コミットID（ワークフローをバージョン管理する場合）
• 冪等性キーとトリガーの送信元
• 機密情報を除いた入力ハッシュまたは許可されたフィールド（生のシークレットは含めない）
• 承認されたプロバイダー／エンドポイントの区分と、モデルおよびリビジョンの識別情報。広くアクセスできるログに内部ホストや資格情報を露出させないこと
• 承認され、最小化されたモデル出力のフィールド、または管理されたポインター。生の出力を保存する場合は、その目的、アクセス、保持について別途判断が必要
• 検証結果
• ゲートの決定と行為者
• 外部ID付きの下流書き込み
• エラークラスと再試行回数

「デバッグのため」と称して、非公開の思考連鎖のダンプを共有チャネルに保存しないでください。監査に出しても構わない判断の要約とツール引数を保存してください。

実行ログは、チケットやメール由来の個人データを含むことがよくあります。本番のAIノードで詳細ログを有効にする前に、保持、アクセス、機密情報を除く方法を定義してください。ローカルモデルを使っていても、個人データを処理するならGDPR型の説明責任を免れるわけではありません。

何かがおかしくなったとき、次に答えられる必要があります。このキーを処理したか。送信したか。誰が承認したか。どのモデル版が下書きしたか。

リードまたはチケット経路の参照シーケンス

1. Webhookがペイロードを受信 → スキーマ検証（初めてのn8n AIエージェント方式のゲート）。
2. キーとペイロードハッシュを計算 → 期限付きのprocessingリースをアトミックに確保。
3. 構造化出力の契約付きでAIノード／エージェントを呼ぶ。
4. JSONを検証（列挙値、必須フィールド、最大長）。
5. 限定的な修復のあとも無効なら → failed_terminal＋人へのアラート。
6. 有効かつ高リスクなアクションなら → CASでawaiting_humanへ。ハッシュ化され、期限があり、単回使用の承認チャレンジを作成。
7. 認証済みの承認POSTを受けたら → チャレンジをアトミックに消費し、状態を更新し、一意なアウトボックス効果を挿入。
8. ディスパッチャーがアウトボックス行をリースし、対応していれば同じキーでプロバイダーを呼び、プロバイダーIDを保存し、効果と実行の両方をCASで完了としてマーク。
9. 却下されたら → 理由付きで終端状態としてマークし、キューに入れない。
10. 重複配信を受けたら → 以前の結果を返すか現在の状態を報告する。モデル呼び出しや送信の経路を黙って繰り返してはならない。

任意：判断の比重が大きい下書きは、HermesのBearer認証APIサーバーへ渡せます。また、イベント入口と設定済み宛先への配信という契約がワークフローに合う場合は、独立したwebhookアダプターを意図的に選ぶこともできます。どちらの場合も、永続的なキー、確認ゲート、コネクターはn8nまたは業務システムが保持します。構成例であるn8n → Hermes webhook引き継ぎを参照してください。

冪等性を壊さずに強制再実行する

オペレーターはn8nのUIから失敗した実行を再実行します。それ自体は健全です。ただし、部分成功のせいでキーがcompletedのままになっており、再実行が2つ目のCRMメモを黙って作る場合や、そもそもキーが書かれていなかったためにメールが再送される場合は別です。

明示的な再実行プロトコルを定義してください。

1. 再試行による回収： 上で示したアトミックな処理権の確保によって回収できるのは、failed_retryableか、期限切れのprocessingリースだけです。業務上のキーは同じものを保持します。
2. 終端状態や完了済みの再実行は禁止： failed_terminal、awaiting_human、approved、completedのキーは、以前または現在の状態を返すだけで、再び開始しません。
3. 意図的な訂正または置換： 上流が発行する独自の冪等性キーを持つ新しい業務イベントを作り、元のキーと外部の結果にリンクし、オペレーターと理由を記録し、新しい承認・アウトボックス経路を通してください。場当たりの接尾辞を付けたり、元の実行をその場で書き換えたりしないでください。

夜勤のオペレーターが圧力の下で方針を即興しないよう、このプロトコルを承認カードに表示してください。

追跡する価値のある運用指標

初日から完全な可観測性プラットフォームは不要です。週次で次の指標を追跡してください。

• 重複webhook率（同じキーが二度観測される）
• ゲートの待ち時間（p50／p95。自分の測定値としてラベルを付ける）
• AIノード後の検証失敗率
• 自動実行と人による承認の比率
• 再試行上限に達した回数

検証失敗のスパイクは、モデル、プロンプト、スキーマ、入力分布、または連携の変更を調査すべき理由になります。重複のスパイクは、上流の再配信、処理権の確保の失敗、再送、またはプロバイダー側の結果のあいまいさを調査すべき理由になります。指標だけで原因が特定できるわけではありません。

キルスイッチと所有権

キルスイッチは、最初のワークフローノードだけでなく、副作用の境界かディスパッチャーで、既定拒否として強制してください。AI_ACTIONS_ENABLED=falseは、実行が途中から再開した場合や、前段の分岐を迂回した場合でも、あらゆる外部送信を止めなければなりません。キューに入っている効果と実行中の効果の両方に対して無効状態をテストし、何をログに残し続けるかを定義し、この制御を操作・検証できる権限を持つ所有者を指名してください。

さらに次も定義してください。

• 誰が承認してよいか
• 誰が強制再実行してよいか。また、場当たり的な接尾辞を使わず、置換イベントに上流発行の新しいキーを与え、元のキーとどう関連付けるか
• ゲートが待機中のとき、サポートのSLA上「完了」が何を意味するか

出荷チェックリスト

• 冪等性キーを選び、AI呼び出しの前に永続化している
• 同じキーの同時配信10件から、有効なリースがちょうど1つだけ生まれる
• 期限切れリースの回収と、古い所有者によるCASの拒否をテスト済み
• 失敗クラスごとの再試行規則を文書化している
• 承認トークンのハッシュ、有効期限、SSO／役割、POST／CSRF、単回使用の再送をテスト済み
• 人による承認ゲートはアウトボックス行を挿入する。送信ノードを直接呼べない
• プロバイダーが受理した可能性のあるタイムアウトはunknownに入り、自動再送しない
• 構造化ログにキー、検証、承認者、外部IDが含まれる
• キルスイッチをテスト済み
• ログのプライバシー保持期間を設定済み

AIノードは、失敗したときに退屈であってはじめて価値を持ちます。冪等性は再試行が嘘をつかないようにします。人による承認ゲートは、誤った出力が顧客にとっての事実になるのを防ぎます。ログは、その両方の主張を点検可能にします。