Назад в блог

Human-in-the-loop уведомления: одобряйте действия AI-агента с телефона

Human-in-the-loop уведомления: одобряйте действия AI-агента с телефона

Агент, который сам может развернуть, вернуть деньги, удалить что-то или отправить письмо, полезен ровно до того момента, пока не сделает одно из этих действий неправильно. Решение не в том, чтобы запретить ему действовать. Нужно заставить его сначала спрашивать и сделать вопрос достаточно дешёвым, чтобы вы на него реально отвечали.

Human-in-the-loop именно об этом: агент останавливается на контрольной точке, человек одобряет или отклоняет действие, и агент продолжает работу с учётом ответа. Сложно не сама логика. Сложно доставить вопрос до вас, когда вы не за столом, и получить ответ обратно без ноутбука.

В этом руководстве это делается push-уведомлением с кнопкой Approve. Агент отправляет его, ждёт и читает ваше решение из небольшого эндпоинта, на который отправляет запрос кнопка.

Как работает цикл

Четыре небольших компонента:

  1. Агент доходит до рискованного шага и создаёт запрос со случайным ID.
  2. Он отправляет push-уведомление Pocket Alert с двумя кнопками действий. Каждая кнопка выполняет HTTP-запрос к вашему эндпоинту подтверждения и передаёт этот ID.
  3. Вы нажимаете на push, читаете, что агент собирается сделать, и нажимаете Approve или Decline. Телефон сам вызывает эндпоинт.
  4. Агент опрашивает эндпоинт, видит решение и продолжает работу или останавливается.

Если никто не ответил до истечения таймаута, агент считает это отказом. Шаг подтверждения, который по умолчанию означает «да», — это просто уведомление, а не защита.

Что понадобится

  • Аккаунт Pocket Alert на платном тарифе. Кнопки действий удаляются из сообщений на бесплатном тарифе, поэтому push придёт без них. Starter стоит $6 в месяц.
  • API-ключ из API Keys, желательно отдельный для агента.
  • Место для небольшого 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-namespace как DECISIONS, добавьте длинный случайный SECRET как секрет Worker и разверните его. Три детали здесь неслучайны:

  • Побеждает первый ответ. Повторное нажатие или нажатие на другую кнопку не может изменить уже записанное решение. Pocket Alert не блокирует повторные нажатия на кнопке http, поэтому это должен делать эндпоинт.
  • Секрет передаётся в заголовке, который задаётся внутри самой кнопки. Телефон его отправляет, агент отправляет, больше никто его не знает.
  • Решения истекают. Одобрение вчерашнего дня не должно разрешать что-либо сегодня.

Workers KV работает с отложенной согласованностью, поэтому агент может увидеть решение только через 60 секунд или позже после вашего нажатия. Для шага подтверждения это нормально. Если нужна мгновенность, то же самое сделает любой сервер с базой данных или Durable Object.

Шаг 2. Спрашиваем из агента

Хелпер ниже отправляет push, опрашивает эндпоинт и возвращает 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" отправляет push как срочный, поэтому он пройдёт через Фокусирование на iPhone и появится как всплывающее уведомление на Android. Одобрение, которое вы увидите через час, — это одобрение, которого агент ждал целый час.

Что вы увидите на телефоне

Push приходит с заголовком и описанием, которые написал агент, а Approve и Decline расположены прямо в уведомлении. На iPhone задержите его, на Android разверните и нажмите кнопку: запрос уйдёт в фоне, без открытия приложения, даже если Pocket Alert закрыт. Те же кнопки есть внутри сообщения в приложении, где всплывающая подсказка показывает код ответа вашего эндпоинта.

Перед тем как на это полагаться, стоит знать две особенности платформ:

  • Если запрос не прошёл, потому что эндпоинт вернул ошибку или у телефона не было сети, появляется новое уведомление с кнопкой Retry. Запрос, который мог дойти до эндпоинта, сам по себе никогда не повторяется, поэтому нажатие не может дважды одобрить что-то за вашей спиной.
  • Системные кнопки уведомлений требуют Pocket Alert 2.0.1 или новее. В более старых версиях у баннера нет кнопок, и они ждут внутри сообщения. Ваши подписи отображаются как написаны на обеих платформах. Если iOS не успевает подготовить пользовательские кнопки, для http она использует общую подпись Run, и кнопка всё равно работает.

Где ставить контрольные точки

Если спрашивать слишком часто, вы начнёте одобрять, не читая. Хорошие контрольные точки — действия, которые трудно отменить или которые стоят реальных денег:

  • Деплой и миграции баз данных в production
  • Отправка писем, публикации на публику или сообщения клиентам
  • Возвраты, покупки и всё, что вызывает платёжный API
  • Удаление данных, ротация ключей, изменение DNS или прав доступа
  • Запуски, которые потратят больше заданного бюджета токенов или облачных ресурсов

Всё остальное лучше оформить как обычное уведомление постфактум. Той стороне задачи посвящена страница уведомлений AI-агентов: завершено, сбой, зависание.

Через MCP

Если агент работает в MCP-клиенте, он может отправить тот же push без Python-хелпера. MCP-сервер Pocket Alert предоставляет create_message с параметром actions, поэтому вы можете поручить агенту вызвать его с двумя кнопками, а затем проверить URL статуса перед продолжением.

Это работает, но с оговоркой: теперь именно агент отвечает за ожидание, а модель, которой велели ждать одобрения, всё равно может решить этого не делать. Для всего, что важно, контрольную точку нужно обеспечивать кодом, который модель не может обойти, например хелпером выше или хуком разрешений в Claude Code или Codex. Используйте MCP для вопроса, а код для ворот.

Варианты

  • Одна кнопка. Отправьте только Approve, а молчание считайте отказом. Тогда на баннере нечего перепутать, а отказ ничего вам не стоит.
  • Инструменты для workflow. В n8n нода Wait, которая возобновляется по вызову вебхука, даёт URL для возобновления. Поместите его в кнопку Approve, и workflow продолжится после нажатия.
  • Контекст в push. Указывайте цифры в сообщении: сумму, окружение, количество строк. Решение должно приниматься по тексту, без дополнительных вопросов.
  • Кнопка просмотра. Замените Decline кнопкой view, которая открывает diff, счёт или запуск, а отказ означает просто отсутствие одобрения.

FAQ

Работает ли одобрение с экрана блокировки?

Да. Кнопки http работают с экрана блокировки без разблокировки телефона, открыт ли Pocket Alert, работает ли он в фоне или закрыт. На Android для этого экран блокировки должен показывать содержимое уведомлений. Если содержимое скрыто, кнопки появятся после разблокировки. Если для рискованного действия это слишком просто, спрячьте решение за кнопкой view, которая открывает страницу с обязательным входом в аккаунт: открытие страницы сначала требует разблокировки.

Это безопасно?

Запрос кнопки идёт с вашего телефона прямо на ваш эндпоинт. Pocket Alert не проксирует его и не видит ответ. Защитите эндпоинт секретным заголовком, используйте случайный ID для каждого запроса, принимайте только первый ответ и делайте решения истекающими. Сообщения, включая конфигурацию кнопок, шифруются при хранении.

Что будет, если я так и не отвечу?

Хелпер вернёт False после таймаута, по умолчанию 15 минут, и агент должен воспринимать это как отказ. Выбирайте таймаут, соответствующий тому, сколько разумно может ждать задача.

Могут ли одобрять несколько человек?

Push получают все устройства аккаунта, и побеждает первое нажатие. Если нужны одобрения по каждому человеку, отправляйте каждому свой push с отдельным ID запроса, а в эндпоинте решайте, сколько одобрений требуется.

Работает ли это на Android и iPhone?

Да, на обеих платформах, с вашими подписями на уведомлении и внутри сообщения. Системным кнопкам уведомлений нужна версия приложения 2.0.1 или новее.

Получите API-ключ, разверните эндпоинт и дайте агенту возможность спрашивать, прежде чем действовать.

Поделиться статьёй