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

> 에이전트가 되돌릴 수 없는 작업 전에 멈추고, 승인 버튼이 달린 푸시를 보내 탭 한 번을 기다리게 하세요. 25줄짜리 승인 엔드포인트, Python 헬퍼, 알아둘 한계를 정리했습니다.

*13.10.2026*

<!-- source: https://pocketalert.app/ko/blog/human-in-the-loop-notifications -->

배포, 환불, 삭제, 이메일 발송을 스스로 할 수 있는 에이전트는 잘못 실행하는 순간까지 유용합니다. 해결책은 에이전트를 멈추는 것이 아니라, 실행 전에 묻게 하는 것입니다. 그리고 물어보는 비용을 충분히 낮춰서 실제로 답하게 만드는 것입니다.

휴먼 인 더 루프(Human-in-the-loop)는 말 그대로입니다. 에이전트가 체크포인트에서 멈추고, 사람이 승인하거나 거절하면, 에이전트는 그 답을 받아 다음 작업을 이어갑니다. 어려운 부분은 로직이 아닙니다. 자리에 없을 때 질문을 나에게 전달하고, 노트북 없이도 답을 돌려받는 것입니다.

이 가이드는 **승인** 버튼이 달린 푸시 알림으로 이를 구현합니다. 에이전트가 푸시를 보내고 기다리다가, 버튼이 호출하는 작은 엔드포인트에서 결정을 읽습니다.

## 루프의 동작 방식

구성 요소는 네 가지이고, 모두 간단합니다.

1. 에이전트가 위험한 단계에 도달하면 무작위 ID로 요청을 만듭니다.
2. 해당 ID를 담은 HTTP 요청을 승인 엔드포인트로 보내는 [액션 버튼](https://info.pocketalert.app/features/action-buttons.html) 두 개가 포함된 Pocket Alert 푸시를 보냅니다.
3. 푸시를 탭해 에이전트가 무엇을 하려는지 확인하고 **승인** 또는 **거절**을 누릅니다. 휴대폰이 엔드포인트를 직접 호출합니다.
4. 에이전트는 엔드포인트를 폴링해 결정을 확인하고 계속 진행하거나 멈춥니다.

제한 시간 안에 응답이 없으면 에이전트는 거절로 처리합니다. 기본값이 "예"인 승인 단계는 안전장치가 아니라 그저 알림일 뿐입니다.

## 준비물

- 유료 플랜의 Pocket Alert 계정. 무료 플랜에서는 메시지에서 액션 버튼이 제거되므로 버튼 없이 푸시가 도착합니다. Starter는 월 $6입니다.
- [API 키](/account/apikeys) 페이지에서 발급한 API 키. 가능하면 에이전트 전용 키를 따로 만드세요.
- 휴대폰에서 접근할 수 있는 작은 HTTPS 엔드포인트를 실행할 곳. 예제는 Cloudflare Worker를 사용하며, 이 정도 트래픽은 무료입니다. 어떤 서버든 가능합니다.

## 1단계. 승인 엔드포인트

엔드포인트는 두 가지 일을 합니다. 휴대폰이 호출하면 결정을 기록하고, 에이전트가 물어보면 결정을 알려줍니다. 아래 Worker는 결정을 Workers KV에 1시간 동안 보관합니다.

```js
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 에이전트에서든 동작합니다.

```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
```

그다음 에이전트가 감독 없이 실행하면 안 되는 작업 앞에 두세요.

```python
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 에이전트 알림](/use-cases/ai-agent-alerts) 페이지에서 완료, 실패, 멈춤 상태에 대한 내용을 다룹니다.

## MCP로 처리하기

에이전트가 MCP 클라이언트에서 실행된다면, Python 헬퍼 없이도 같은 푸시를 보낼 수 있습니다. [Pocket Alert MCP 서버](/tools/mcp)는 `create_message` 매개변수가 있는 `actions`를 제공하므로, 두 버튼을 포함해 호출하고 진행 전에 상태 URL을 확인하도록 에이전트에 지시할 수 있습니다.

이 방식도 동작하지만 주의할 점이 있습니다. 이제 기다리는 책임은 에이전트에게 있으며, 승인을 기다리라고 지시받은 모델도 기다리지 않기로 결정할 수 있습니다. 중요한 작업이라면 위의 헬퍼처럼 모델이 건너뛸 수 없는 코드로 체크포인트를 강제하거나, [Claude Code](/blog/claude-code-push-notifications)나 [Codex](/blog/codex-notifications)의 권한 훅을 사용하세요. 질문은 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 키 발급받기](/signup)를 하고 엔드포인트를 배포한 뒤, 에이전트가 행동하기 전에 물어볼 수 있는 방법을 마련하세요.
