AI 에이전트에게 API를 읽게 한다면, 과금 전에 무엇을 테스트해 두어야 할까.

Cloudflare가 7월 1일에 웹 페이지나 API, MCP 툴에 대한 액세스마다 과금하는 「Monetization Gateway」를 발표했다. x402로 결제를 다룬다는 이야기는 눈에 띈다. 하지만 내가 오늘 직접 먼저 확인하고 싶었던 것은 결제 처리가 아니라, 미결제 에이전트에게 반환하는 402 Payment Required를 클라이언트가 제대로 읽을 수 있는지였다.

이 부분이 모호하면 나중에 결제 기반을 교체하더라도 문제가 생긴다. 인간 대상이라면 "로그인해 주세요"로 끝나겠지만, 에이전트 대상이라면 payment_url, 금액, 대상 리소스를 기계적으로 추출할 수 없으면 재시도(Retry)나 승인 플로우(Approval Flow)를 구성할 수 없다.

처음에는 http.server로 작은 로컬 API를 세우려고 했다. 그런데 이 환경에서는 대기 시 다음과 같이 오류가 발생했다.

PermissionError: [Errno 1] Operation not permitted

그래서 기사에 실을 코드는 HTTP 서버가 아니라, 응답 규약(Response Contract)만을 검사하는 순수 함수(Pure Function)로 만들었다. x402 구현이 아니다. 과금 게이트를 넣기 전의, 상당히 소박한 스모크 테스트(Smoke Test)다.

# agent_paywall_smoke.py
import json
PAYMENT_URL = "https://pay.example.test/session/abc"
...

실행 결과.

$ python3 agent_paywall_smoke.py
free: 402 payment_required https://pay.example.test/session/abc 0.003
paid: 200 ok rows=2

아래 그림 정도의 입도로 처음에 결정해 두면 나중에 편하다.

보고 있는 것은 세 가지만이다. 미결제라면 402, 본문에 payment_url, 헤더에 결제 링크. 이것만으로도 에이전트 측은 "읽기만 하고 종료한다", "승인을 받으러 간다", "결제 완료로 간주하고 재실행한다"를 구분할 수 있다.

금액을 숫자가 아닌 문자열로 만든 것도 의도적이다. 소수점 반올림으로 인해 0.003이 흔들리면, 로그 비교나 서명 대상에서 짜증 나는 차이가 발생한다. 실제 결제에서는 통화 단위나 서명, 기한, 리플레이 방지(Replay Attack Countermeasure)도 필요하지만, 그 전에 클라이언트가 미결제를 일반적인 에러로 처리하여 뭉개버리고 있지는 않은지 확인하는 것이 우선이라고 생각한다.

에이전트 과금은 결제 프로토콜보다 먼저 에러 규약(Error Contract)이 작용한다. 402를 단순한 실패로 처리하면 자동화 측에서는 다음 수를 선택할 수 없다. 반대로 미결제 응답을 작게 고정하여 테스트에 넣어 두면, x402나 외부 게이트웨이를 나중에 삽입하더라도 어떻게 망가지는지 확인할 수 있다. 우선 한 줄기, 이런 스모크 테스트를 배치하는 것이 현장에서는 가장 비용이 적게 든다.