AI 에이전트가 웹을 읽을 때는 사람과 완전히 다릅니다. CSS도, 클라이언트 사이드 자바스크립트도, 이미지도 필요하지 않죠. 이런 요소들은 컨텍스트 윈도우를 채우고 토큰만 소비할 뿐 유용한 정보를 전혀 제공하지 않습니다. 에이전트에게 필요한 건 깔끔하고 구조화된 텍스트뿐입니다.

Vercel이 이 문제를 해결했습니다. 블로그와 체인지로그 페이지를 업데이트해서 사람에게는 완전한 HTML/CSS 경험을, AI 에이전트에게는 마크다운을 제공하는 방식이죠. 핵심은 ‘콘텐츠 협상(content negotiation)’이라는 HTTP 메커니즘입니다. 같은 콘텐츠를 클라이언트가 요청하는 형식에 따라 다르게 반환하는 거예요. 중복 콘텐츠나 별도 사이트 없이 말입니다.

출처: Making agent-friendly pages with content negotiation – Vercel Blog

HTTP Accept 헤더로 포맷 자동 전환

에이전트는 HTTP Accept 헤더를 통해 선호하는 포맷을 명시합니다. 예를 들어 Claude Code는 페이지를 가져올 때 이런 헤더를 보냅니다:

Accept: text/markdown, text/html, */*

text/markdown을 맨 앞에 둬서 HTML보다 마크다운을 선호한다고 신호를 보내는 거죠. 많은 에이전트가 이제 이런 방식으로 마크다운을 명시적으로 요청하기 시작했습니다.

Vercel의 미들웨어는 들어오는 요청의 Accept 헤더를 검사하고 이런 선호도를 감지합니다. 마크다운이 선호되면 요청을 Next.js 라우트 핸들러로 보내서 Contentful의 rich-text 콘텐츠를 마크다운으로 변환하죠. 코드 블록은 문법 강조 마커를 유지하고, 제목은 계층 구조를 보존하며, 링크는 그대로 작동합니다. 에이전트는 HTML 버전과 같은 정보를 받되, 토큰 효율성에 최적화된 포맷으로 받는 겁니다.

99.6% 용량 감소가 가져온 변화

일반적인 블로그 포스트는 HTML, CSS, 자바스크립트를 포함해 500KB입니다. 하지만 같은 콘텐츠를 마크다운으로 제공하면 단 2KB죠. 99.6%의 용량 감소입니다.

토큰 제한 아래서 작동하는 에이전트에게 작은 페이로드는 요청당 더 많은 콘텐츠를 소비할 수 있다는 걸 의미합니다. 마크업 대신 실제 정보에 예산을 쓸 수 있죠. 더 빠르게 작동하고 한계에 덜 부딪힙니다.

Vercel은 Next.js 16의 remote cache와 공유 slug를 사용해 HTML과 마크다운 버전 간 동기화를 유지합니다. Contentful에서 콘텐츠가 업데이트되면 두 버전이 동시에 새로고침됩니다.

마크다운 sitemap으로 콘텐츠 탐색 지원

에이전트는 무엇이 사용 가능한지 알아야 합니다. Vercel은 에이전트 소비에 최적화된 포맷으로 모든 콘텐츠를 나열하는 마크다운 sitemap을 구현했습니다. sitemap에는 각 콘텐츠의 메타데이터가 포함됩니다. 발행 날짜, 콘텐츠 타입, HTML과 마크다운 버전 모두로의 직접 링크 등이죠. 이는 에이전트에게 사용 가능한 정보의 완전한 지도를 제공하고, 필요에 가장 잘 맞는 포맷을 선택할 수 있게 합니다.

AI 에이전트가 웹 콘텐츠를 소비하는 방식은 근본적으로 다릅니다. Vercel의 접근은 이런 차이를 인정하고 각 클라이언트에 최적화된 경험을 제공하는 실용적 해법을 보여줍니다. 사람과 AI 모두를 위한 웹, 그 출발점이 될 수 있겠네요.

참고자료:

• Send Markdown to Agents Demo – 직접 테스트해볼 수 있는 데모 사이트
• How to serve documentation for agents – Vercel 공식 구현 가이드
• Vercel 문서 마크다운 sitemap – 실제 적용 사례