콘텐츠 협상으로 에이전트 친화적인 페이지 만들기

에이전트도 웹을 탐색하지만, 사람과 읽는 방식이 다릅니다. CSS, 클라이언트 사이드 JavaScript, 이미지 같은 요소는 에이전트에게 불필요합니다. 이런 마크업은 컨텍스트 윈도우만 차지하고 토큰을 소모할 뿐, 유용한 정보를 제공하지 않습니다. 에이전트에게 필요한 건 깔끔하게 구조화된 텍스트입니다.

그래서 저희는 블로그와 체인지로그 페이지를 업데이트하여, 사람에게는 기존과 동일한 HTML·CSS 경험을 제공하면서도 에이전트에게는 마크다운을 전달할 수 있도록 했습니다. 이 방식의 핵심은 콘텐츠 협상(Content Negotiation)입니다. 클라이언트가 요청하는 형식에 따라 서버가 동일한 콘텐츠를 다른 포맷으로 반환하는 HTTP 메커니즘으로, 콘텐츠를 복제하거나 별도 사이트를 운영할 필요가 없습니다.

에이전트의 콘텐츠 요청 방식

에이전트는 HTTP Accept 헤더를 통해 선호하는 포맷을 지정합니다. 예를 들어 Claude Code는 페이지를 가져올 때 다음과 같은 헤더를 전송합니다:

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

text/markdown을 가장 먼저 나열함으로써, 에이전트는 HTML보다 마크다운을 우선적으로 원한다는 신호를 보냅니다. 최근 많은 에이전트가 이런 방식으로 마크다운 선호를 명시적으로 표현하기 시작했습니다.

curl 요청으로 직접 확인해 보세요:

curl https://vercel.com/blog/self-driving-infrastructure -H "accept: text/markdown"

저희 미들웨어는 들어오는 요청의 Accept 헤더를 분석하여 클라이언트의 포맷 선호도를 감지합니다. 마크다운이 선호되는 경우, 요청을 Next.js 라우트 핸들러로 전달하여 Contentful의 리치 텍스트 콘텐츠를 마크다운으로 변환합니다.

이 변환 과정에서 콘텐츠의 구조는 그대로 유지됩니다. 코드 블록의 구문 강조 마커, 제목의 계층 구조, 링크의 기능 모두 보존됩니다. 에이전트는 HTML 버전과 동일한 정보를 받되, 토큰 효율에 최적화된 포맷으로 전달받는 것입니다.

성능상의 이점

일반적인 블로그 글 하나의 용량은 HTML, CSS, JavaScript를 모두 포함하면 약 500KB에 달합니다. 하지만 동일한 콘텐츠를 마크다운으로 제공하면 단 2KB로, 페이로드 크기가 99.6% 줄어듭니다.

토큰 제한 내에서 동작하는 에이전트 입장에서, 페이로드가 작아지면 한 번의 요청으로 더 많은 콘텐츠를 처리할 수 있고 마크업이 아닌 실제 정보에 토큰 예산을 집중할 수 있습니다. 처리 속도는 빨라지고, 제한에 걸리는 빈도도 줄어듭니다.

HTML 버전과 마크다운 버전 간의 동기화는 Next.js 16 리모트 캐시와 공유 슬러그를 활용하여 유지합니다. Contentful에서 콘텐츠가 업데이트되면 두 버전이 동시에 갱신됩니다.

에이전트의 콘텐츠 탐색 방식

에이전트는 어떤 콘텐츠가 있는지 파악할 수 있어야 합니다. 저희는 에이전트 소비에 최적화된 형식으로 모든 콘텐츠를 나열하는 마크다운 사이트맵을 구현했습니다. 이 사이트맵에는 발행일, 콘텐츠 유형, HTML·마크다운 양쪽 버전의 직접 링크 등 각 콘텐츠의 메타데이터가 포함되어 있어, 에이전트가 활용 가능한 정보의 전체 지도를 확인하고 목적에 맞는 포맷을 선택할 수 있습니다.

직접 확인해 보고 싶다면, 이 페이지 URL 끝에 .md을 추가하여 마크다운 버전을 확인해 보세요.