휴먼 인 더 루프 알림: 휴대폰으로 AI 에이전트 승인하기

배포, 환불, 삭제, 이메일 발송을 스스로 할 수 있는 에이전트는 잘못 실행하는 순간까지 유용합니다. 해결책은 에이전트를 멈추는 것이 아니라, 실행 전에 묻게 하는 것입니다. 그리고 물어보는 비용을 충분히 낮춰서 실제로 답하게 만드는 것입니다.
휴먼 인 더 루프(Human-in-the-loop)는 말 그대로입니다. 에이전트가 체크포인트에서 멈추고, 사람이 승인하거나 거절하면, 에이전트는 그 답을 받아 다음 작업을 이어갑니다. 어려운 부분은 로직이 아닙니다. 자리에 없을 때 질문을 나에게 전달하고, 노트북 없이도 답을 돌려받는 것입니다.
이 가이드는 승인 버튼이 달린 푸시 알림으로 이를 구현합니다. 에이전트가 푸시를 보내고 기다리다가, 버튼이 호출하는 작은 엔드포인트에서 결정을 읽습니다.
루프의 동작 방식
구성 요소는 네 가지이고, 모두 간단합니다.
- 에이전트가 위험한 단계에 도달하면 무작위 ID로 요청을 만듭니다.
- 해당 ID를 담은 HTTP 요청을 승인 엔드포인트로 보내는 액션 버튼 두 개가 포함된 Pocket Alert 푸시를 보냅니다.
- 푸시를 탭해 에이전트가 무엇을 하려는지 확인하고 승인 또는 거절을 누릅니다. 휴대폰이 엔드포인트를 직접 호출합니다.
- 에이전트는 엔드포인트를 폴링해 결정을 확인하고 계속 진행하거나 멈춥니다.
제한 시간 안에 응답이 없으면 에이전트는 거절로 처리합니다. 기본값이 "예"인 승인 단계는 안전장치가 아니라 그저 알림일 뿐입니다.
준비물
- 유료 플랜의 Pocket Alert 계정. 무료 플랜에서는 메시지에서 액션 버튼이 제거되므로 버튼 없이 푸시가 도착합니다. Starter는 월 $6입니다.
- API 키 페이지에서 발급한 API 키. 가능하면 에이전트 전용 키를 따로 만드세요.
- 휴대폰에서 접근할 수 있는 작은 HTTPS 엔드포인트를 실행할 곳. 예제는 Cloudflare Worker를 사용하며, 이 정도 트래픽은 무료입니다. 어떤 서버든 가능합니다.
1단계. 승인 엔드포인트
엔드포인트는 두 가지 일을 합니다. 휴대폰이 호출하면 결정을 기록하고, 에이전트가 물어보면 결정을 알려줍니다. 아래 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 네임스페이스를 DECISIONS라는 이름으로 바인딩하고, 길고 무작위인 SECRET을 Worker 시크릿으로 추가한 뒤 배포하세요. 세 가지 세부 사항은 의도된 설계입니다.
- 첫 번째 응답이 유효합니다. 두 번째 탭이나 다른 버튼을 눌러도 이미 기록된 결정을 뒤집을 수 없습니다. 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에서는 헤즈업 알림으로 표시됩니다. 한 시간 뒤에 보는 승인은, 에이전트가 한 시간 동안 기다린 승인이라는 뜻입니다.
휴대폰에서 보이는 모습
푸시에는 에이전트가 작성한 제목과 세부 내용이 표시되며, 승인과 거절 버튼이 알림에 바로 나타납니다. iPhone에서 길게 누르거나 Android에서 알림을 펼쳐 버튼 하나를 누르면, Pocket Alert가 닫혀 있어도 앱을 열지 않고 백그라운드에서 요청이 전송됩니다. 같은 버튼은 앱 안의 메시지에도 있으며, 엔드포인트가 반환한 상태 코드가 토스트로 표시됩니다.
이 방식에 의존하기 전에 알아둘 플랫폼 세부 사항이 두 가지 있습니다.
- 요청이 실패하면, 엔드포인트가 오류를 반환했거나 휴대폰에 네트워크가 없어서 실패한 경우, 재시도 버튼이 있는 새 알림이 나타납니다. 엔드포인트에 도달했을 수도 있는 요청은 자동으로 재시도되지 않으므로, 탭 한 번으로 몰래 두 번 승인되는 일은 없습니다.
- 시스템 알림 버튼은 Pocket Alert 앱 2.0.1 이상이 필요합니다. 이전 버전에서는 배너에 버튼이 없고, 메시지를 열어야 버튼이 나타납니다. 두 플랫폼 모두 작성한 라벨이 그대로 표시됩니다. iOS가 시간 안에 커스텀 버튼을 준비하지 못하면,
http버튼은 일반 실행 라벨로 대체되지만 버튼은 여전히 동작합니다.
체크포인트를 어디에 둘까
너무 자주 물어보면 내용을 읽지 않고 승인하게 됩니다. 좋은 체크포인트는 되돌리기 어렵거나 실제 비용이 드는 작업입니다.
- 프로덕션 배포와 데이터베이스 마이그레이션
- 이메일 발송, 공개 게시, 고객 메시지 전송
- 환불, 구매, 결제 API를 호출하는 모든 작업
- 데이터 삭제, 키 교체, DNS 또는 권한 변경
- 설정된 토큰 또는 클라우드 예산을 초과할 수 있는 실행
그 외의 작업은 사후에 단순 알림으로 받는 편이 낫습니다. AI 에이전트 알림 페이지에서 완료, 실패, 멈춤 상태에 대한 내용을 다룹니다.
MCP로 처리하기
에이전트가 MCP 클라이언트에서 실행된다면, Python 헬퍼 없이도 같은 푸시를 보낼 수 있습니다. Pocket Alert MCP 서버는 create_message 매개변수가 있는 actions를 제공하므로, 두 버튼을 포함해 호출하고 진행 전에 상태 URL을 확인하도록 에이전트에 지시할 수 있습니다.
이 방식도 동작하지만 주의할 점이 있습니다. 이제 기다리는 책임은 에이전트에게 있으며, 승인을 기다리라고 지시받은 모델도 기다리지 않기로 결정할 수 있습니다. 중요한 작업이라면 위의 헬퍼처럼 모델이 건너뛸 수 없는 코드로 체크포인트를 강제하거나, Claude Code나 Codex의 권한 훅을 사용하세요. 질문은 MCP로, 게이트는 코드로 처리하는 것이 좋습니다.
변형 방법
- 버튼 하나만 사용. 승인만 보내고, 응답이 없으면 거절로 간주하세요. 배너에서 잘못 누를 버튼이 없고, 거절에 따른 비용도 없습니다.
- 워크플로 도구. n8n에서는 웹훅 호출로 재개되도록 설정한 Wait 노드가 재개 URL을 제공합니다. 이 URL을 승인 버튼에 넣으면 탭할 때 워크플로가 계속 진행됩니다.
- 푸시에 맥락 담기. 금액, 환경, 행 수 같은 수치를 메시지에 넣으세요. 텍스트만 보고도 결정할 수 있어야 합니다.
- 보기 버튼. 거절 버튼 대신 diff, 청구서, 실행 기록을 여는
view버튼을 두고, 승인하지 않는 것으로 거절하세요.
FAQ
잠금 화면에서도 승인할 수 있나요?
네. http 버튼은 Pocket Alert가 열려 있든, 백그라운드에 있든, 닫혀 있든 휴대폰 잠금을 풀지 않고 잠금 화면에서 실행됩니다. Android에서는 알림 내용을 표시하도록 잠금 화면이 설정되어 있어야 합니다. 내용을 숨기도록 설정되어 있으면 잠금을 푼 뒤에 버튼이 나타납니다. 위험한 작업에 이 방식이 너무 쉽다면, 결정을 view 버튼 뒤에 두고 로그인해야 하는 페이지를 열도록 하세요. 페이지를 열 때는 먼저 잠금 해제를 요구합니다.
보안은 괜찮은가요?
버튼 요청은 휴대폰에서 엔드포인트로 직접 전달됩니다. Pocket Alert는 이를 중계하지 않으며 응답도 보지 않습니다. 시크릿 헤더로 엔드포인트를 보호하고, 요청마다 무작위 ID를 사용하고, 첫 응답만 인정하고, 결정을 만료시키세요. 버튼 설정을 포함한 메시지는 저장 시 암호화됩니다.
아무도 응답하지 않으면 어떻게 되나요?
헬퍼는 제한 시간(기본 15분)이 지나면 False를 반환하며, 에이전트는 이를 거절로 처리해야 합니다. 작업이 합리적으로 기다릴 수 있는 시간에 맞춰 제한 시간을 정하세요.
여러 사람이 승인할 수 있나요?
계정의 모든 기기가 푸시를 받으며, 먼저 탭한 응답이 적용됩니다. 사람별로 승인을 받으려면, 각자에게 별도의 요청 ID로 푸시를 보내고, 엔드포인트에서 필요한 승인 수를 판단하세요.
Android와 iPhone 모두에서 동작하나요?
네, 둘 다 동작합니다. 알림과 메시지 안에 원하는 라벨을 표시할 수 있습니다. 시스템 알림 버튼은 앱 버전 2.0.1 이상이 필요합니다.
API 키 발급받기를 하고 엔드포인트를 배포한 뒤, 에이전트가 행동하기 전에 물어볼 수 있는 방법을 마련하세요.