Human-in-the-loop notifications: setujui agen AI dari ponsel Anda

Agen yang bisa men-deploy, mengembalikan dana, menghapus, atau mengirim email secara mandiri sangat berguna, sampai ia salah melakukan salah satu dari hal itu. Solusinya bukan melarangnya bertindak. Yang perlu dilakukan adalah membuatnya bertanya lebih dulu, dan membuat pertanyaan itu cukup ringan sehingga Anda benar-benar menjawabnya.
Human-in-the-loop berarti persis itu: agen berhenti di sebuah titik pemeriksaan, seseorang menyetujui atau menolak, lalu agen melanjutkan sesuai jawaban tersebut. Bagian yang sulit bukan logikanya. Yang sulit adalah membuat pertanyaan itu sampai ke Anda saat Anda tidak di depan meja kerja, dan menerima jawaban Anda tanpa laptop.
Panduan ini melakukannya dengan push notification yang memuat tombol Approve. Agen mengirimkannya, menunggu, dan membaca keputusan Anda dari endpoint kecil yang dipanggil oleh tombol tersebut.
Cara kerja loop-nya
Ada empat bagian, semuanya kecil:
- Agen mencapai langkah berisiko dan membuat permintaan dengan ID acak.
- Agen mengirim push Pocket Alert dengan dua tombol aksi. Setiap tombol adalah permintaan HTTP ke endpoint persetujuan Anda, dengan membawa ID tersebut.
- Anda mengetuk push, membaca apa yang ingin dilakukan agen, lalu mengetuk Approve atau Decline. Ponsel Anda memanggil endpoint secara langsung.
- Agen melakukan polling ke endpoint, melihat keputusannya, lalu melanjutkan atau berhenti.
Jika tidak ada yang menjawab sebelum batas waktu habis, agen menganggapnya sebagai penolakan. Langkah persetujuan yang default-nya "ya" hanyalah notifikasi, bukan pengaman.
Yang Anda butuhkan
- Akun Pocket Alert dengan paket berbayar. Tombol aksi dihapus dari pesan di paket gratis, sehingga push akan tiba tanpa tombol. Starter berharga $6 per bulan.
- Kunci API dari API Keys, sebaiknya kunci terpisah untuk agen.
- Tempat untuk menjalankan endpoint HTTPS kecil yang bisa dijangkau ponsel Anda. Contohnya menggunakan Cloudflare Worker, yang gratis pada volume ini; server apa pun juga bisa.
Langkah 1. Endpoint persetujuan
Endpoint ini melakukan dua hal: mencatat keputusan saat ponsel memanggilnya, dan melaporkannya saat agen bertanya. Worker ini menyimpan keputusan di Workers KV selama satu jam:
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 });
},
};
Ikat namespace KV sebagai DECISIONS, tambahkan SECRET acak yang panjang sebagai secret Worker, lalu deploy. Tiga detail ini disengaja:
- Jawaban pertama yang menang. Ketukan kedua, atau ketukan pada tombol lainnya, tidak bisa membalik keputusan yang sudah tercatat. Pocket Alert tidak memblokir ketukan berulang pada tombol
http, jadi endpoint harus melakukannya. - Secret dikirim lewat header, diatur di dalam tombol itu sendiri. Ponsel mengirimnya, agen mengirimnya, dan tidak ada pihak lain yang memilikinya.
- Keputusan kedaluwarsa. Persetujuan dari kemarin tidak boleh membuka apa pun hari ini.
Workers KV bersifat eventually consistent, jadi agen mungkin tidak melihat keputusan hingga 60 detik atau lebih setelah Anda mengetuk. Untuk langkah persetujuan, itu tidak masalah; jika Anda membutuhkannya seketika, server apa pun dengan database atau Durable Object melakukan tugas yang sama.
Langkah 2. Bertanya dari agen
Helper di bawah ini mengirim push, melakukan polling untuk keputusan, dan hanya mengembalikan True jika ada persetujuan eksplisit. Ia bisa dipakai dari agen Python mana pun: sebagai tool LangChain, fungsi OpenAI Agents SDK, atau loop biasa.
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
Lalu letakkan di depan apa pun yang tidak ingin Anda biarkan dilakukan agen tanpa pengawasan:
if ask_human("Deploy to production?", "build #482 · 14 files · all checks green"):
deploy()
else:
report("Deploy skipped: not approved")
level: "high" mengirim push sebagai time-sensitive, sehingga tetap lolos Fokus di iPhone dan muncul sebagai heads-up notification di Android. Persetujuan yang baru Anda lihat satu jam kemudian adalah persetujuan yang sudah ditunggu agen selama satu jam.
Yang Anda lihat di ponsel
Push tiba dengan judul dan detail yang ditulis agen, serta Approve dan Decline langsung pada notifikasi. Tekan lama di iPhone atau perluas di Android, lalu ketuk salah satunya: permintaan dikirim di latar belakang tanpa membuka aplikasi, bahkan jika Pocket Alert sudah ditutup. Tombol yang sama juga ada di dalam pesan di aplikasi, tempat toast menampilkan kode status yang dikembalikan endpoint Anda.
Dua detail platform perlu diketahui sebelum Anda mengandalkannya:
- Jika permintaan gagal, karena endpoint Anda mengembalikan error atau ponsel tidak punya jaringan, notifikasi baru muncul dengan tombol Retry. Permintaan yang mungkin sudah sampai ke endpoint Anda tidak pernah dicoba ulang secara otomatis, sehingga satu ketukan tidak bisa menyetujui dua kali di belakang Anda.
- Tombol notifikasi sistem memerlukan Pocket Alert app 2.0.1 atau yang lebih baru. Pada versi lama, banner tidak memiliki tombol dan tombol menunggu di dalam pesan. Label Anda ditampilkan sesuai penulisan di kedua platform; jika iOS tidak sempat menyiapkan tombol kustom, ia akan menggunakan label umum Run untuk
http, dan tombolnya tetap berfungsi.
Di mana meletakkan titik pemeriksaan
Jika Anda terlalu sering bertanya, Anda akan mulai menyetujui tanpa membaca. Titik pemeriksaan yang baik adalah aksi yang sulit dibatalkan atau berbiaya nyata:
- Deploy dan migrasi database di production
- Mengirim email, memposting secara publik, atau menghubungi pelanggan
- Pengembalian dana, pembelian, dan apa pun yang memanggil API pembayaran
- Menghapus data, merotasi kunci, mengubah DNS atau izin
- Eksekusi yang akan menghabiskan token atau anggaran cloud melebihi batas tertentu
Selebihnya lebih baik berupa notifikasi biasa setelah kejadian. Halaman AI agent alerts membahas sisi itu: selesai, gagal, macet.
Melalui MCP
Jika agen berjalan di klien MCP, ia bisa mengirim push yang sama tanpa helper Python. Server MCP Pocket Alert menyediakan create_message dengan parameter actions, sehingga Anda bisa menginstruksikan agen untuk memanggilnya dengan dua tombol lalu memeriksa URL status sebelum melanjutkan.
Cara ini berfungsi, dengan satu catatan: agen kini bertanggung jawab untuk menunggu, dan model yang diminta menunggu persetujuan tetap bisa memutuskan untuk tidak menunggu. Untuk hal yang penting, terapkan titik pemeriksaan dalam kode yang tidak bisa dilewati model, seperti helper di atas atau hook izin di Claude Code atau Codex. Gunakan rute MCP untuk pertanyaannya, dan kode untuk gerbangnya.
Variasi
- Satu tombol. Kirim hanya Approve dan biarkan diam berarti tidak. Dengan begitu tidak ada yang bisa salah ketuk pada banner, dan menolak tidak membebani Anda.
- Tool workflow. Di n8n, node Wait yang dilanjutkan oleh panggilan webhook memberi Anda URL resume; letakkan di tombol Approve dan workflow berlanjut saat Anda mengetuk.
- Konteks di push. Cantumkan angkanya di pesan: jumlahnya, lingkungannya, jumlah barisnya. Anda seharusnya bisa memutuskan hanya dari teksnya.
- Tombol lihat. Ganti Decline dengan tombol
viewyang membuka diff, faktur, atau run, dan tolak dengan tidak menyetujui.
FAQ
Apakah persetujuan bisa dilakukan dari layar kunci?
Bisa. Tombol http berjalan dari layar kunci tanpa membuka kunci ponsel, baik Pocket Alert sedang terbuka, di latar belakang, maupun tertutup. Di Android, itu memerlukan layar kunci yang menampilkan isi notifikasi; jika isinya disembunyikan, tombol muncul setelah Anda membuka kunci. Jika itu terlalu mudah untuk aksi berisiko, letakkan keputusan di balik tombol view yang membuka halaman yang harus Anda masuki; membuka halaman akan meminta buka kunci terlebih dahulu.
Apakah ini aman?
Permintaan dari tombol dikirim langsung dari ponsel Anda ke endpoint Anda; Pocket Alert tidak meneruskannya atau melihat responsnya. Lindungi endpoint dengan header secret, gunakan ID acak untuk setiap permintaan, terima hanya jawaban pertama, dan kedaluwarsakan keputusan. Pesan, termasuk konfigurasi tombol, dienkripsi saat disimpan.
Apa yang terjadi jika saya tidak pernah menjawab?
Helper mengembalikan False setelah batas waktu, secara default 15 menit, dan agen sebaiknya memperlakukannya sebagai penolakan. Pilih batas waktu yang sesuai dengan lamanya tugas itu masuk akal untuk menunggu.
Bisakah beberapa orang menyetujui?
Setiap perangkat di akun menerima push, dan ketukan pertama yang menang. Untuk persetujuan per orang, kirim push tersendiri ke setiap orang dengan ID permintaan yang terpisah, lalu tentukan di endpoint berapa banyak persetujuan yang Anda butuhkan.
Apakah ini berfungsi di Android dan iPhone?
Ya, keduanya, dengan label Anda sendiri pada notifikasi maupun di dalam pesan. Tombol notifikasi sistem memerlukan aplikasi versi 2.0.1 atau yang lebih baru.
Dapatkan kunci API, deploy endpoint, dan berikan agen Anda cara untuk bertanya sebelum bertindak.