返回博客

人机协同推送通知:用手机批准 AI 智能体的操作

人机协同推送通知:用手机批准 AI 智能体的操作

一个能够自行部署、退款、删除或发送邮件的智能体,在它做错其中某件事之前都很有用。解决办法不是阻止它执行操作,而是让它先提问,并且让提问的成本足够低,使你真的会去回答。

人机协同(Human-in-the-loop)正是这个意思:智能体在检查点停下,由人批准或拒绝,然后智能体根据答复继续执行。难点不在逻辑,而在于你不在电脑前时,如何把问题送到你手上,并且在没有笔记本电脑的情况下把你的答复传回去。

本指南用一条带有 Approve 按钮的手机推送通知来实现。智能体发送通知,然后等待,并从按钮调用的一个小端点读取你的决定。

循环如何运作

四个部分,都很简单:

  1. 智能体遇到有风险的步骤,用随机 ID 创建一个请求。
  2. 它发送一条带有两个操作按钮的 Pocket Alert 推送。每个按钮都是一个发往你的审批端点的 HTTP 请求,并携带该 ID。
  3. 你点开推送,查看智能体想做什么,然后点击 Approve 或 Decline。你的手机直接调用该端点。
  4. 智能体轮询该端点,看到决定后继续执行或停止。

如果超时前没有人回应,智能体会把它视为拒绝。默认为“同意”的审批步骤只是一条通知,而不是安全保障。

你需要准备

  • 一个付费套餐的 Pocket Alert 账户。免费套餐会去掉消息中的操作按钮,推送到达时将不带按钮。Starter 套餐每月 6 美元。
  • 来自 API 密钥页面的 API 密钥,最好为智能体单独创建一个。
  • 一个你的手机可以访问的 HTTPS 端点。示例使用 Cloudflare Worker,在这个用量下是免费的;任何服务器都可以。

第 1 步:审批端点

端点做两件事:手机调用时记录决定,智能体询问时返回决定。这个 Worker 会将决定保存在 Workers KV 中,保留一小时:

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 命名空间绑定为 DECISIONS,添加一个较长的随机 SECRET 作为 Worker 密钥,然后部署。其中三个细节是刻意设计的:

  • 先到的答复生效。 第二次点击,或点击另一个按钮,都无法更改已经记录的决定。Pocket Alert 不会阻止 http 按钮的重复点击,因此端点必须自己处理。
  • 密钥通过请求头传递,在按钮自身中设置。手机发送它,智能体也发送它,其他人都无从获得。
  • 决定会过期。 昨天的批准不应该解锁今天的任何操作。

Workers KV 是最终一致的,因此智能体可能要等到你点击后 60 秒甚至更久才看到决定。对于审批步骤,这没有问题;如果你需要即时生效,任何带数据库或 Durable Object 的服务器都能完成同样的工作。

第 2 步:从智能体发起询问

下面的辅助函数会发送推送,轮询决定,并且只在明确批准时返回 True。它适用于任何 Python 智能体:LangChain 工具、OpenAI Agents SDK 函数,或普通循环。

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 上以悬浮通知的形式显示。如果你一小时后才看到审批请求,那么智能体就得等了一小时。

手机上会看到什么

推送会显示智能体编写的标题和详情,Approve 和 Decline 直接位于通知上。在 iPhone 上长按或在 Android 上展开,然后点击其中一个:请求会在后台发出,无需打开应用,即使 Pocket Alert 已关闭也一样。相同的按钮也位于应用内的消息中,那里的提示会显示你的端点返回的状态码。

在依赖这一功能之前,有两个平台细节值得了解:

  • 如果请求失败,例如端点返回错误或手机没有网络,会出现一条带有 Retry 按钮的新通知。可能已经到达端点的请求不会被自动重试,因此一次点击不会在你背后被批准两次。
  • 系统通知按钮需要 Pocket Alert 2.0.1 或更高版本。 在旧版本中,横幅没有按钮,它们会在消息内等待。两个平台都会按你写的标签显示;如果 iOS 无法及时准备自定义按钮,http 按钮会退回为通用的 Run 标签,但按钮仍然有效。

检查点应该放在哪里

询问过于频繁,你就会开始不看内容直接批准。好的检查点是那些难以撤销或会产生真实费用的操作:

  • 生产环境的部署和数据库迁移
  • 发送邮件、公开发帖或联系客户
  • 退款、购买,以及任何调用支付 API 的操作
  • 删除数据、轮换密钥、修改 DNS 或权限
  • 将消耗超过设定 Token 或云预算的运行

其他情况更适合事后以普通通知的形式告知。AI 智能体告警页面介绍了这一方面:完成、失败、卡住。

通过 MCP 实现

如果智能体运行在 MCP 客户端中,它无需 Python 辅助函数也能发送同样的推送。Pocket Alert MCP 服务器提供了带有 create_message 参数的 actions,因此你可以指示智能体用两个按钮调用它,然后在继续之前检查状态 URL。

这种方式可行,但有一点需要注意:现在由智能体负责等待,而被告知要等待审批的模型仍然可能选择不等。对于重要的操作,应在模型无法跳过的代码中强制执行检查点,例如上面的辅助函数,或 Claude Code 与 Codex 中的权限钩子。用 MCP 路线来提问,用代码来设置关卡。

变体

  • 单按钮。 只发送 Approve,让沉默意味着否定。这样横幅上就没有可能误触的按钮,而拒绝也不会让你付出任何代价。
  • 工作流工具。 在 n8n 中,将 Wait 节点设置为通过 Webhook 调用恢复,即可得到一个恢复 URL;把它放进 Approve 按钮,点击后工作流就会继续。
  • 在推送中提供上下文。 把关键数字写进消息:金额、环境、行数。你应该仅凭文字就能做出决定。
  • 查看按钮。 用 view 按钮替代 Decline,它会打开差异、发票或运行记录,而拒绝则通过不批准来实现。

常见问题

在锁屏上也能批准吗?

可以。http 按钮可以直接在锁屏上运行,无需解锁手机,无论 Pocket Alert 是在前台、后台还是已关闭。在 Android 上,这需要锁屏设置为显示通知内容;如果锁屏隐藏了内容,按钮会在你解锁后才出现。如果对于有风险的操作来说这样太容易了,可以把决定放在一个 view 按钮后面,它会打开一个需要你登录的页面;打开页面时会先要求解锁。

安全吗?

按钮的请求直接从你的手机发送到你的端点;Pocket Alert 不会代理它,也看不到响应。请使用密钥请求头保护端点,每个请求使用随机 ID,只接受先到的答复,并让决定过期。消息(包括按钮配置)在静态存储时均经过加密。

如果我一直不回应会怎样?

超时后辅助函数会返回 False,默认为 15 分钟,智能体应将其视为拒绝。请选择与任务合理等待时长相匹配的超时时间。

多人可以批准吗?

账户上的每台设备都会收到推送,先点击的人生效。如果需要按人分别审批,请为每个人发送单独的推送,并使用各自的请求 ID,然后在端点中决定需要多少个批准。

在 Android 和 iPhone 上都能用吗?

可以,两个平台都支持,通知和消息内都可以使用你自己设置的标签。系统通知按钮需要应用版本 2.0.1 或更高。

获取 API 密钥,部署端点,并让你的智能体在行动之前有办法先询问你。

分享这篇文章