ブログに戻る

プッシュ通知で Human-in-the-loop を実現:スマホから AI エージェントを承認

プッシュ通知で Human-in-the-loop を実現:スマホから AI エージェントを承認

デプロイ、返金、削除、メール送信を自律的に行えるエージェントは、誤った操作をするその瞬間までは便利です。解決策はエージェントの動作を止めることではありません。実行前に必ず確認を求めさせ、その確認に答えるのが面倒にならないようにすることです。

Human-in-the-loop とはまさにそういう仕組みです。エージェントはチェックポイントで停止し、人間が承認するか却下するかを決め、エージェントはその回答を受けて処理を続けます。難しいのはロジックではありません。デスクから離れているときに質問を届け、ノートパソコンがなくても回答を返せるようにすることです。

このガイドでは、Approve ボタン付きのプッシュ通知を使います。エージェントが通知を送り、待機し、ボタンが呼び出す小さなエンドポイントから承認結果を読み取ります。

ループの仕組み

構成要素は 4 つで、どれも小さなものです。

  1. エージェントがリスクのある処理に到達し、ランダムな ID 付きのリクエストを作成します。
  2. Pocket Alert のプッシュ通知を、2 つの アクションボタン 付きで送信します。各ボタンは、その ID を含めて承認エンドポイントへ HTTP リクエストを送ります。
  3. 通知をタップして、エージェントが何をしようとしているかを確認し、Approve または Decline をタップします。スマホがエンドポイントを直接呼び出します。
  4. エージェントはエンドポイントをポーリングして結果を確認し、処理を続行するか停止します。

タイムアウトまでに誰も応答しなければ、エージェントはそれを不承認として扱います。デフォルトが「はい」の承認ステップは、安全装置ではなく単なる通知にすぎません。

必要なもの

  • 有料プランの Pocket Alert アカウント。アクションボタンは無料プランではメッセージから取り除かれるため、ボタンなしで通知が届いてしまいます。Starter は月額 $6 です。
  • API Keys で発行した API キー。エージェント専用に別のキーを用意するのが理想的です。
  • スマホからアクセスできる小さな HTTPS エンドポイントを動かす場所。この例では Cloudflare Worker を使います。この規模なら無料で利用できます。どのサーバーでも構いません。

ステップ 1:承認エンドポイント

エンドポイントは 2 つの役割を担います。スマホから呼び出されたときに判断を記録し、エージェントから問い合わせがあったときに結果を返します。この Worker は判断を Workers KV に 1 時間保存します。

export default {
  async fetch(request, env) {
    if (request.headers.get('X-Approval-Secret') !== env.SECRET) {
      return new Response('forbidden', { status: 403 });
    }

    const [, action, id] = new URL(request.url).pathname.split('/');
    if (!/^[a-f0-9]{32}$/.test(id ?? '')) {
      return new Response('bad id', { status: 400 });
    }

    if (request.method === 'POST' && (action === 'approve' || action === 'decline')) {
      const existing = await env.DECISIONS.get(id);
      if (!existing) await env.DECISIONS.put(id, action, { expirationTtl: 3600 });
      return new Response(existing ?? action);
    }

    if (request.method === 'GET' && action === 'status') {
      return new Response((await env.DECISIONS.get(id)) ?? 'pending');
    }

    return new Response('not found', { status: 404 });
  },
};

KV namespace を DECISIONS としてバインドし、長くランダムな SECRET を Worker のシークレットとして追加してデプロイします。次の 3 点は意図的な設計です。

  • 最初の回答が有効になります。 2 回目のタップや、もう一方のボタンのタップで、すでに記録された判断を覆すことはできません。Pocket Alert は http ボタンの連続タップをブロックしないため、エンドポイント側で防ぐ必要があります。
  • シークレットはヘッダーで送信されます。 ボタン自体に設定されます。スマホとエージェントだけがこの値を持ち、ほかの人は持っていません。
  • 判断には有効期限があります。 昨日の承認で今日何かを実行できてはいけません。

Workers KV は結果整合性なので、タップしてから 60 秒以上たってエージェントが判断を見られないことがあります。承認ステップであればこれで問題ありません。即時性が必要なら、データベースや Durable Object を備えたサーバーでも同じことができます。

ステップ 2:エージェントから確認する

以下のヘルパーは、プッシュ通知を送り、判断をポーリングし、明示的な承認があった場合にのみ True を返します。LangChain のツール、OpenAI Agents SDK の関数、単純なループなど、任意の Python エージェントから使えます。

import json
import os
import time
import uuid

import requests

PUSH_API = "https://api.pocketalert.app/v1/messages"
APPROVALS = "https://approvals.YOUR_SUBDOMAIN.workers.dev"
SECRET = os.environ["APPROVAL_SECRET"]


def ask_human(title: str, details: str, timeout: int = 900) -> bool:
    request_id = uuid.uuid4().hex

    def button(label: str, action: str) -> dict:
        return {
            "type": "http",
            "label": label,
            "value": json.dumps({
                "url": f"{APPROVALS}/{action}/{request_id}",
                "method": "POST",
                "headers": {"X-Approval-Secret": SECRET},
            }),
        }

    requests.post(
        PUSH_API,
        headers={"Token": os.environ["POCKETALERT_API_KEY"]},
        json={
            "title": title,
            "message": details,
            "level": "high",
            "actions": [button("Approve", "approve"), button("Decline", "decline")],
        },
        timeout=10,
    ).raise_for_status()

    deadline = time.time() + timeout
    while time.time() < deadline:
        status = requests.get(
            f"{APPROVALS}/status/{request_id}",
            headers={"X-Approval-Secret": SECRET},
            timeout=10,
        ).text
        if status in ("approve", "decline"):
            return status == "approve"
        time.sleep(5)
    return False

次に、エージェントに無断で実行させたくない処理の前にこれを置きます。

if ask_human("Deploy to production?", "build #482 · 14 files · all checks green"):
    deploy()
else:
    report("Deploy skipped: not approved")

level: "high" を指定すると、プッシュ通知は時間的に重要なものとして送信されるため、iPhone の集中モードでも届き、Android ではヘッドアップ通知として表示されます。1 時間後に気づいた承認は、エージェントが 1 時間待っていた承認になってしまうからです。

スマホでの表示

通知には、エージェントが作成したタイトルと詳細が表示され、通知上に Approve と Decline が並びます。iPhone では長押し、Android では展開してボタンをタップします。アプリを開かなくても、Pocket Alert が閉じている状態でもバックグラウンドでリクエストが送信されます。同じボタンはアプリ内のメッセージにもあり、エンドポイントが返したステータスコードがトーストで表示されます。

この仕組みに頼る前に知っておきたいプラットフォーム上の点が 2 つあります。

  • リクエストが失敗した場合(エンドポイントがエラーを返した、またはスマホがオフラインだった場合)、Retry ボタン付きの新しい通知が表示されます。エンドポイントに届いた可能性のあるリクエストは自動で再送されないため、タップが知らないうちに 2 回承認として処理されることはありません。
  • システム通知のボタンには Pocket Alert アプリ 2.0.1 以降が必要です。 古いバージョンではバナーにボタンが表示されず、メッセージを開くまで待つことになります。両プラットフォームでラベルは指定どおりに表示されます。iOS がカスタムボタンを間に合わせて準備できない場合は、http の汎用ラベル Run が使われますが、ボタン自体は動作します。

チェックポイントの置き場所

確認を頻繁に求めすぎると、内容を読まずに承認するようになってしまいます。適切なチェックポイントは、取り消しが難しい操作や実際にお金がかかる操作です。

  • 本番環境へのデプロイとデータベースマイグレーション
  • メール送信、公開投稿、顧客へのメッセージ送信
  • 返金、購入、決済 API を呼び出す処理全般
  • データの削除、キーのローテーション、DNS や権限の変更
  • 設定したトークンやクラウドの予算を超えて消費する可能性のある実行

それ以外は、事後に通知するだけで十分です。完了、失敗、停止といった側面については AI エージェントのアラート のページで説明しています。

MCP を使う場合

エージェントが MCP クライアントで動作している場合、Python ヘルパーなしで同じプッシュ通知を送信できます。Pocket Alert MCP サーバー は create_message パラメーター付きの actions を提供するので、2 つのボタンを指定して呼び出し、続行する前にステータス URL を確認するようエージェントに指示できます。

これは機能しますが、注意点があります。待機の責任をエージェントが負うことになり、承認を待つよう指示されたモデルでも待たないと判断する可能性があるからです。重要な処理では、上記のヘルパーのように、モデルがスキップできないコードでチェックポイントを強制してください。または Claude Code や Codex の権限フックを使う方法もあります。質問には MCP を、ゲートにはコードを使うのが良い組み合わせです。

バリエーション

  • ボタンを 1 つにする。 Approve だけを送り、応答がないことを不承認とみなします。バナー上で誤タップする要素がなくなり、却下にコストがかかりません。
  • ワークフローツール。 n8n では、Webhook 呼び出しで再開するように設定した Wait ノードが再開用 URL を発行します。それを Approve ボタンに設定すれば、タップ時にワークフローが続行します。
  • 通知にコンテキストを含める。 金額、環境、行数などの数値をメッセージに入れます。テキストだけで判断できるようにしておきましょう。
  • 表示ボタンを追加する。 Decline を view ボタンに置き換えると、差分、請求書、実行結果を開けます。却下は承認しないことで行います。

FAQ

ロック画面から承認できますか?

はい。http ボタンは、Pocket Alert がフォアグラウンド、バックグラウンド、終了のいずれの状態でも、スマホのロックを解除せずにロック画面から実行できます。Android では、ロック画面に通知内容を表示する設定が必要です。内容を隠す設定の場合、ボタンはロック解除後に表示されます。リスクの高い操作に対して簡単すぎると感じる場合は、判断を view ボタンの背後に置いてください。そのボタンはサインインが必要なページを開きます。ページを開く操作では、先にロック解除が求められます。

セキュリティは大丈夫ですか?

ボタンのリクエストはスマホからエンドポイントに直接送られ、Pocket Alert がそれを中継したり、レスポンスを確認したりすることはありません。エンドポイントはシークレットヘッダーで保護し、リクエストごとにランダムな ID を使い、最初の回答だけを受け付け、判断には有効期限を設けてください。ボタンの設定を含むメッセージは、保存時に暗号化されます。

応答しなかった場合はどうなりますか?

タイムアウト(デフォルトは 15 分)後にヘルパーは False を返します。エージェントはこれを却下として扱うべきです。タスクが待てる時間に合わせてタイムアウトを設定してください。

複数の人が承認できますか?

アカウント内のすべてのデバイスにプッシュ通知が届き、最初のタップが有効になります。個人ごとに承認を求める場合は、それぞれに別のリクエスト ID を付けてプッシュ通知を送り、必要な承認数をエンドポイント側で判定してください。

Android と iPhone の両方で使えますか?

はい、両方で使えます。通知上とメッセージ内に、独自のラベルを表示できます。システム通知のボタンにはアプリバージョン 2.0.1 以降が必要です。

API キーを取得してエンドポイントをデプロイし、エージェントが行動する前に確認できる仕組みを用意しましょう。

この記事をシェア