에이전트 친화적인 웹사이트를 만드는 방법 (그리고 거절해야 할 것들)
요약
AI 에이전트가 웹사이트의 정보를 원활하게 탐색하고 활용할 수 있도록 최적화하는 방법론을 다룹니다. isitagentready.com 도구 사용 경험을 바탕으로, MCP 서버, 마크다운 제공, API 카탈로그 등 에이전트 친화적인 웹 구축을 위한 실질적인 기술적 조치들을 제안합니다.
핵심 포인트
- 에이전트 접근을 방해하는 비밀번호 게이트 및 인증 오류 해결 필요
- MCP 서버 및 엔드포인트를 통한 에이전트용 도구 노출
- 에이전트의 효율적 읽기를 위한 마크다운(Markdown) 콘텐츠 협상 구현
- RFC 표준(Link headers, API catalog)을 활용한 리소스 안내
최근에 저는 productize.life를 isitagentready.com이라는 도구를 통해 검사해 보았습니다. 이 도구는 AI 에이전트가 실제로 사용하기에 귀하의 사이트가 얼마나 준비되어 있는지를 스캔하며, 그 결과는 직설적이고 유용했습니다. 에이전트가 사이트가 무엇을 제공하는지 학습하기 위해 확인하는 표준 엔드포인트(endpoints) (/.well-known/... 계열)가 모두 401 오류를 반환했는데, 이는 비밀번호 게이트(password gate) 뒤에 있었기 때문입니다. 쉽게 말해, 사이트를 살펴보는 에이전트에게는 아무것도 보이지 않았던 것입니다.
저는 이를 수정하는 데 몇 시간을 보냈습니다. 하지만 이야기할 가치가 있는 부분은 "모든 항목을 체크했다"는 것이 아닙니다. isitagentready 리스트의 여러 항목 중 일부는 콘텐츠 사이트의 경우 수행해서는 안 되는 것들입니다. 진짜 필요한 것과 가짜인 것을 분류한 결과, 저는 8개를 수행하고, 3개를 거절했으며, 1개를 건너뛰었습니다. 이 포스트는 각 분류 뒤에 숨겨진 논리입니다.
파트 1: 웹사이트의 에이전트 준비도를 점수화하는 도구
먼저, 솔직한 추천을 드리자면: isitagentready.com은 좋은 레이더입니다. 이 도구는 에이전트가 실제로 보내는 종류의 요청을 보내고, 귀하의 사이트에 무엇이 누락되었는지 알려줍니다. 제 사이트의 경우, 홈페이지와 표준 엔드포인트(endpoints)가 비밀번호 게이트 뒤에 숨겨져 있어 에이전트가 아무것도 볼 수 없다는 점을 즉시 잡아냈습니다. 그것은 제가 인지하지 못했던 실제적인 공백이었습니다.
하지만 모든 스캐너는 하나의 습관을 공유합니다. 바로 대규모 SaaS 플랫폼과 개인 블로그를 동일한 잣대로 평가하는 일반적인 체크리스트를 제공한다는 점입니다. 그런 경우, 일부 항목은 귀하의 사이트에 맞지 않습니다. 모든 항목을 체크하는 것이 목표가 아닙니다. 목표는 이 사이트에 실제로 유효한 항목을 수행하고, 어떤 것을 건너뛰어야 할지 아는 것입니다.
파트 2: 내가 수행한 8가지: 하나의 원칙, 실질적인 것에 집중하기
제가 수행한 8가지 사항은 모두 하나의 원칙을 공유합니다: 귀하가 게시하는 모든 것은 사이트에 실제로 존재하는 무언가를 가리켜야 합니다. 이 블로그는 이미 그러한 실질적인 것, 즉 모든 기사가 공개된 상태로 존재합니다:
- 링크 헤더 (Link headers, RFC 8288)는 응답 헤더(response header)에서 에이전트에게 리소스 목록을 읽기 위해 어디로 가야 하는지 알려줍니다.
- MCP 서버 카드 + 엔드포인트 (MCP server card + endpoint)는 이 사이트에 읽기 전용 MCP 서버가 있음을 선언하며, 두 가지 실제 도구를 노출합니다: 기사 목록 나열하기, 그리고 기사를 텍스트로 가져오기.
Agent Skills: 에이전트가 즉시 가져갈 수 있도록 요약본과 함께 전체 기사 목록을 인덱싱합니다.
WebMCP: 브라우저에서 실행되는 에이전트에게 동일한 도구들을 노출합니다.
API catalog (RFC 9727): 실제로 존재하는 MCP 엔드포인트를 가리킵니다.
Web Bot Auth: 다른 사이트가 우리가 서명한 요청을 검증할 수 있도록 실제 공개 키(자체 생성)를 게시합니다.
DNS-AID: 이러한 엔드포인트로 안내하는 DNS 레벨의 레코드를 게시합니다.
Markdown for Agents: 에이전트가 마크다운 (Markdown)을 요청하면 기사를 마크다운으로 제공하고, 브라우저가 방문하면 이전과 같이 HTML을 제공합니다.
마지막 항목에는 유용한 세부 사항이 있습니다. Cloudflare가 이 기능을 제공하지만 유료 플랜에 묶어두었습니다. 그래서 저는 이미 제가 제어하고 있는 코드로 이를 직접 구축했습니다. 이것은 단순한 콘텐츠 협상 (Content Negotiation)입니다. 에이전트가 보내는 헤더를 확인하고, 마크다운을 요청하면 기사를 변환하여 반환하는 방식입니다. 추가 구독료는 필요 없습니다. 무엇을 스스로 무료로 구축할 수 있는지 아는 것도 판단력의 일부입니다.
Part 3: 내가 거절한 3가지: 보유하지 않은 기능은 광고하지 마세요
이것이 핵심입니다. 스캔 결과는 저에게 다음 항목들을 게시하도록 압박했습니다: OAuth/OIDC discovery, OAuth Protected Resource, 그리고 에이전트 등록을 위한 auth.md입니다. 이 세 가지 모두는 에이전트가 등록, 토큰 요청 및 로그인을 할 수 있는 "인증 서버 (Authentication Server)"가 사이트에 있음을 알리는 파일들을 노출할 것을 요구합니다.
하지만 이 블로그에는 그러한 시스템이 없습니다. 제가 노출한 MCP 엔드포인트는 의도적으로 로그인 없이 공개된 읽기 전용 상태입니다. 만약 제가 그 파일들을 게시했다면, 그것을 신뢰하는 에이전트는 존재하지 않는 서버에 인증을 시도하다가 그 자리에서 실패했을 것입니다.
이 지점이 체크리스트가 당신을 가장 쉽게 속이는 부분입니다. 모든 항목에 체크를 하면 더 에이전트 친화적인 것처럼 보이지만, 실제로는 사이트를 덜 에이전트 친화적으로 만듭니다. 왜냐하면 실재하지 않는 기능을 광고하는 것은 당신을 신뢰한 에이전트의 시간을 낭비하게 하고 에이전트를 망가뜨리기 때문입니다. 이 세 가지를 거절하는 것이 사이트를 게으르게 만드는 것이 아니라 정직하게 만드는 길입니다.
Part 4: 내가 의도적으로 건너뛴 1가지
내가 건너뛴 한 가지는 DNSSEC입니다. 리스트에서는 보안을 위해 DNS 존 (DNS zone)에 서명할 것을 권장합니다. 저도 이를 활성화하려고 시도했지만, 정말 큰 벽에 부딪혔습니다. productize.life 도메인은 한 곳에 등록되어 있는 반면, DNS는 다른 곳에서 관리되고 있습니다 (백엔드 전체가 그곳에서 실행되기 때문입니다). 저희 등록 대행업체(registrar)는 자체 네임서버 (name servers)를 사용할 때만 DNSSEC을 지원하므로, 현재 DNS 제공업체를 위한 서명을 게시할 수 없습니다.
이 체크표시를 획득할 수 있는 유일한 방법은 도메인 등록을 완전히 이전하는 것뿐인데, 이는 그 자체로 비용과 번거로움을 수반합니다. DNS-AID 레코드가 이미 잘 작동하고 있는 블로그를 위해, 단지 체크박스 하나를 채우려고 도메인을 옮기는 것은 그만한 가치가 없습니다. 그래서 저는 다른 이유로 도메인을 옮기게 될 때만 다시 검토하겠다고 적어두었습니다. 이것은 영구적인 거부(veto)가 아니라, 재검토 조건이 붙은 "아니오"입니다.
Part 5: 교훈: 배포(deployed)되었다고 해서 라이브(live)인 것은 아니다
진행 과정에서 경고할 만한 함정에 빠졌습니다. 배포했을 때 시스템에는 멋진 초록색 "READY" 메시지가 떴지만, 실제 라이브 페이지는 여전히 이전 버전이었습니다. 이유는 백엔드가 읽어오는 호스트가 11시간 전의 빌드 상태로 고정되어 있었고, 새로운 배포(deploy)는 다른 이름으로 내려받아져 함께 이동하지 않았기 때문입니다.
교훈은 "배포 성공"과 "실제로 라이브 상태임"은 서로 다른 두 가지라는 점입니다. 여러분이 신뢰할 수 있는 것은 실제 사실(ground truth)입니다. 화면의 초록색 상태 표시가 아니라, 실제 URL로 요청을 보내고 돌아오는 바이트(bytes)를 확인하십시오. 나머지는 마크다운(markdown)을 반환하면서, 실제로는 압축되지 않았음에도 압축되었다는 헤더를 그대로 유지하는 것과 같은 사소한 문제들이었습니다. 저는 라이브 상태가 되기 전에 로컬에서 테스트했기에 이를 잡아낼 수 있었습니다.
내일부터 바로 적용하기
-
isitagentready와 같은 스캐너를 레이더처럼 사용하세요. 놓쳤던 실제 격차를 드러내 줍니다.
-
여러분이 게시하는 모든 것은 사이트에 실제로 존재하는 무언가를 가리켜야 합니다.
-
사이트에 존재하지 않는 시스템(인증, 등록 등)을 주장하는 파일을 절대 게시하지 마세요. 가짜 체크표시는 여러분을 에이전트 친화적이지 않게 만듭니다.
-
항목을 건너뛸 때는 영구적인 거부가 아니라, 재검토 조건과 함께 건너뛰세요.
도구의 "성공 (success)" 상태가 아닌, 실제 근거 데이터 (ground truth)로 확인하세요.
사이트를 isitagentready.com에서 테스트하는 것으로 시작할 수 있습니다. 그리고 각 항목을 수행하기 전에 한 가지 질문을 던지세요: "이것이 내가 실제로 보유한 무언가를 가리키는가?" 만약 그렇지 않다면, 건너뛰세요.
실제 업무를 바탕으로 작성되었습니다. 전체 버전(및 태국어 판)은 productize.life에서 확인할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기