요약 (TL;DR)

AI 쇼핑 에이전트가 귀하의 사이트에서 구매를 수행하기를 원한다면, 에이전트가 무엇인가를 클릭하기 전에 세 가지 질문에 대한 답이 필요합니다: 무엇을 판매하는지, 결제(checkout) 프로세스가 어떻게 작동하는지, 그리고 계정이 필요한지 여부입니다. 세 가지 정적(static) 파일이 이 세 가지 질문에 모두 답하며, 이 중 어떤 파일도 결제 코드를 수정할 필요가 없습니다. 이 포스트에서는 각 파일에 무엇이 포함되어 있는지, 어디에 위치하는지, 그리고 에이전트가 이 파일들을 발견했을 때 어떤 일이 일어나는지 살펴봅니다.

왜 하나가 아니라 세 개의 파일인가

가입(signup) 설명이 없는 결제 설명은 절반의 답변에 불과합니다. /.well-known/agent-checkout.json에 접속하여 POST 엔드포인트(endpoint)를 확인한 에이전트는 먼저 로그인을 해야 하는지, 아니면 게스트 구매가 허용되는지 알 수 없습니다. 결제 설명이 없는 가입 설명은 더 나쁩니다. 에이전트는 계정 모델은 알지만 가격, 이행 경로(fulfillment path), 또는 환불 기간은 알지 못합니다.

이러한 분리는 의도적입니다. 결제(Checkout)는 트랜잭션(transactional) 중심입니다. 가입(Signup)은 신원(identity) 중심입니다. 이들은 서로 다른 주기(clocks)로 변경되며, 서로 다른 팀에 속해 있고, 이를 하나의 JSON으로 혼합하는 것은 어느 팀도 소유하고 싶어 하지 않는 스키마(schema)를 강제하게 됩니다.

세 번째 파일인 llms-pay.md는 인간과 기계를 위한 서사(narrative)입니다. 에이전트는 JSON을 파싱(parse)하지만, LLM(Large Language Models)은 귀하가 무엇을 판매하는지 평이한 언어로 설명해 달라는 요청을 받았을 때 마크다운(markdown)을 읽습니다. 두 인터페이스 모두 사실 관계에 대해 일치해야 합니다.

파일 1: /.well-known/agent-checkout.json

사이트 루트의 .well-known 접두사 아래에 위치하며, Content-Type: application/json으로 제공됩니다. 이는 인간 사용자가 "나를 위해 프로 플랜을 구매해줘"라고 말할 때 에이전트가 가장 먼저 찾는 곳입니다.

선언 내용:

• products[] - 각 제품은 id, name, description, 그리고 amount, currency, recurrence (one_time 또는 monthly)를 포함하는 price 객체를 가집니다. 일회성 결제와 정기 결제가 결합된 티어(tier)의 경우, starts_after가 포함된 subscription 블록을 추가합니다.
• checkout_flow - 에이전트가 수행하는 정확한 HTTP 호출입니다. method, endpoint, 그리고 에이전트가 채워야 할 필드 이름이 포함된 body_schema를 포함합니다. 만약 결제 전 단계(예: 스캔 전용 패키지를 구매하기 전 대상 도메인을 스캔하는 것)가 필요하다면, 해당 내용은 자체 스키마를 가진 prereq에 작성합니다.
• fulfillment - 에이전트가 주문이 완료되었음을 인지하는 방법입니다. 보통 poll_endpoint와 terminal_status로 구성됩니다. delivery 필드는 구매자가 실제로 받게 되는 것(서명된 URL, 라이선스 키, 대시보드 액세스 권한 등)을 설명합니다.
• payment_providers[] - role (primary, fallback, planned), 지원되는 modes (live, sandbox), 그리고 카드 네트워크와 함께 목록을 나열합니다.
• test_mode - 매우 중요합니다. 실제 돈을 움직이지 않고도 흐름을 스모크 테스트 (smoke-test) 할 수 있도록 에이전트에게 명시적인 경로를 제공하십시오. 샌드박스 (Sandbox) 호스트, 판매자 계정 요구 사항, 또는 문서화된 드라이 런 (dry-run) 브랜치 등이 해당됩니다.

실제 예시는 agentfix.pro/.well-known/agent-checkout.json에서 확인할 수 있습니다. 두 개의 제품, 세 개의 제공업체, 한 개의 선행 단계 (결제 전 스캔), 한 개의 폴링 엔드포인트 (poll endpoint)로 구성되어 있습니다.

파일 2: /.well-known/agent-signup.json

동일한 디렉토리에 위치하며, Content-Type: application/json 형식을 가집니다. 이 파일은 회원가입 기능이 없는 경우에도 존재해야 하며, 그럴 경우 signup_required: false라고 선언하고 게스트 모델을 설명합니다.

선언 내용:

• signup_required - boolean (불리언). 기본값 false는 에이전트에게 계정 생성 로직 없이 진행할 수 있다는 강력한 신호를 보냅니다.
• signup_model - guest_first, pre_purchase_signup, post_purchase_activation, 또는 hybrid 중 하나입니다. 에이전트에게 신원 확인(identity)이 필요한 시점을 알려줍니다.
• authentication_methods[] - SSO 제공업체, 패스키 (passkey), 이메일 링크 (email-link), 비밀번호 (password). 빈 배열도 유효한 답변입니다.
• post_purchase_activation - 결제 후 팩 (pack), 라이선스 (license), 또는 구독 (subscription)에 별도의 활성화 단계가 필요한 경우, 트리거(trigger), 전달 채널 (delivery channel), 그리고 엔드포인트 (endpoints)를 설명합니다. 이를 설명하지 않으면, 결제 웹훅 (webhook)은 완료되었으나 즉시 다운로드가 나타나지 않을 때 즉각적인 전달을 예상하는 에이전트들이 혼란을 겪을 수 있습니다.
• identity_privacy - 수집되는 개인정보 (PII), 보유 기간 (retention days), 비밀번호 저장 여부 (password storage boolean), 교차 사이트 추적 여부 (cross-site tracking boolean). 개인정보 보호를 중시하는 사용자에게 답변하는 에이전트들은 이 항목들을 가장 먼저 확인합니다.

실제 예시: agentfix.pro/.well-known/agent-signup.json. 이 파일은 guest-first, 계정 불필요, 라이선스 키를 통한 결제 후 활성화 (post-purchase activation)를 선언하고 있습니다.

파일 3: /llms-pay.md

사이트 루트(root)에 위치한 마크다운 (Markdown) 파일입니다. 이 파일은 이중 목적을 가집니다. 에이전트는 JSON 파일에서 의사결정 근거를 찾을 수 없을 때 폴백 (fallback) 용도로 이를 파싱(parse)합니다. 사람 개발자와 LLM 기반 어시스턴트는 대화형 답변이 필요할 때 이 파일을 읽습니다.

효과적인 구조:

1. 맨 상단의 한 줄 요약 (> AI 쇼핑 에이전트를 위한 탐색 레이어...).
2. JSON 파일로 다시 연결되는 링크를 포함하여, 에이전트가 두 가지 인터페이스가 모두 존재함을 알 수 있게 합니다.
3. 판매 품목 - 제품당 하나의 불렛 포인트(bullet point)를 사용하며, 가격은 표 안에 숨기지 않고 문장 안에 포함합니다.
4. 프로그래밍 방식으로 구매하는 방법 - JSON의 checkout_flow를 반영하되 산문(prose) 형태로 작성된 번호 매기기 단계.
5. 테스트 모드 - JSON의 샌드박스 (sandbox) 경로를 반복하되, 그것이 왜 존재하는지 설명합니다.
6. 결제 제공업체, 환불, 연락처 - JSON 필드들을 사람이 읽을 수 있는 버전으로 제공합니다.

실제 예시: agentfix.pro/llms-pay.md.

경험적인 원칙(rule of thumb): JSON은 에이전트가 실행하는 것이고, 마크다운(markdown)은 에이전트가 설명을 요청받았을 때 인용하는 것입니다. 둘 중 어느 것도 서로 모순되어서는 안 됩니다.

에이전트가 실제로 이를 사용하는 방법

자율 쇼핑 에이전트의 현실적인 작업 순서는 다음과 같습니다:

1. 에이전트가 사이트 루트(root)에 접속하여, AI 대응 매니페스트(manifest)를 확인하기 위해 robots.txt와 llms.txt를 읽습니다.
2. llms.txt는 Commerce 섹션 아래에 세 가지 커머스 파일(commerce files)을 나열해야 합니다. 만약 이 파일들이 링크되어 있지 않다면, 에이전트는 이를 완전히 건너뛸 수 있습니다. 많은 에이전트들이 명시적으로 공지되지 않은 .well-known/ 경로를 추측하는 것을 거부하기 때문입니다.
3. 에이전트는 먼저 agent-signup.json을 파싱(parse)합니다. 만약 signup_required: true인데 에이전트가 지원하는 authentication_methods(인증 방법)가 없다면, 에이전트는 동작을 중단합니다.
4. 에이전트는 agent-checkout.json을 파싱하여 사용자의 의도(intent)에 맞는 제품을 매칭하고, checkout_flow(결제 흐름)를 고정합니다.
5. 샌드박스(sandbox) 모드를 사용할 수 있고 에이전트가 드라이 런(dry-run) 상태라면, test_mode 브랜치를 사용합니다.
6. 에이전트는 흐름을 실행하고, 이행(fulfillment) 상태를 폴링(poll)하며, 배송 결과물(delivery artifact)을 사용자에게 전달합니다.

2단계는 대부분의 사이트가 실패하는 지점입니다. llms.txt에 공지되지 않았다는 이유로 에이전트가 전혀 찾지 못하는, 완벽하게 잘 만들어진 탐색 파일(discovery files)들이 버려지게 됩니다.

데이터가 누락되었을 때 작성해야 할 내용

존재하지 않는 제품 카탈로그, 결제 엔드포인트(endpoint), 또는 가입 흐름을 지어내지 마십시오. 에이전트는 당신이 선언한 무엇이든 호출할 것이며, 404를 반환하는 조작된 엔드포인트는 아예 선언하지 않는 것보다 더 나쁩니다.

안전한 패턴: 공백을 설명하는 명시적인 notes 필드를 포함하여 파일을 발행하십시오. signup_required: false와 notes: "no signup layer configured; guest checkout only"(가입 레이어 미설정; 게스트 결제만 가능)가 포함된 agent-signup.json은 유효하고 유용한 답변입니다. notes: "product catalog pending; contact support@example.com for programmatic buying"(제품 카탈로그 준비 중; 프로그래밍 방식 구매를 위해 support@example.com으로 문의)와 함께 비어 있는 products[] 역시 유효하고 유용한 답변입니다.

침묵은 진실된 공백보다 더 나쁩니다.

에이전트가 경로를 따라올 수 있도록 하는 상호 링크(Cross-linking)

이 파일들 각각은 나머지 두 파일을 참조해야 합니다. agent-checkout.json에는 llms-pay.md를 가리키는 docs 필드가 포함되어 있습니다. agent-signup.json에는 agent-checkout.json을 가리키는 checkout_reference 필드가 포함되어 있습니다. llms-pay.md는 상단에서 두 .well-known 파일을 모두 링크합니다.

그 후 사이트 루트(root)에 있는 llms.txt에는 이 세 가지를 모두 나열하는 커머스(Commerce) 섹션이 있습니다. 그것이 바로 출발점(trailhead)입니다. 이것이 없다면 다른 모든 것은 도달할 수 없습니다.

실제로 이 경로가 어떻게 구성되어 있는지 보고 싶다면, 이 레이어를 제공하는 사이트를 스캔하거나, 귀하의 커머스 자산을 직접 실행하여 9가지 커머스 체크 항목 중 몇 개가 통과되는지 확인해 보십시오. 저희는 여기서 다룬 9가지 커머스 항목을 포함하여 52가지 시그널(signals)을 점검하는 오픈 스캐너를 agentfix.pro에서 제공하고 있습니다.

핵심 요약 (Key takeaways)

• 세 개의 파일은 세 가지 별개의 질문, 즉 무엇을(what), 어떻게(how), 누가(who)에 답합니다.
• llms.txt에서 출발점(trailhead)을 찾지 못하는 에이전트는 탐색을 시도하지 않을 것입니다.
• 커머스 데이터를 절대 임의로 만들어내지 마십시오. 조작된 엔드포인트(endpoint)보다 진실된 notes 필드가 훨씬 낫습니다.
• 에이전트가 경로를 추측하지 않고 그래프(graph)를 따라 이동할 수 있도록 세 파일 모두 상호 링크(cross-link)하십시오.
• JSON은 에이전트가 실행하는 것이고, 마크다운(markdown)은 에이전트가 인용하는 것입니다. 이 둘은 반드시 일치해야 합니다.

원문 게시 위치: agentfix.pro/blog/three-commerce-discovery-files.