![[번역] Content Negotiation으로 AI 에이전트 친화적인 웹페이지 만들기](/_next/image?url=%2Fimages%2Fthumbnails%2Fcontent-negotiation-ai%2FthumbnailImage.jpg&w=1920&q=75)
AI 에이전트 시대, 웹페이지는 어떻게 변해야 할까
최근 Claude Code나 다양한 AI 에이전트들이 웹을 탐색하면서 콘텐츠를 수집하는 일이 점점 많아지고 있습니다. 그런데 한 가지 흥미로운 점이 있습니다. AI 에이전트는 우리 사람과는 전혀 다른 방식으로 웹을 '읽는다'는 것이죠.
사람들은 예쁘게 꾸며진 CSS 스타일, 인터랙티브한 자바스크립트, 그리고 이미지들을 보면서 정보를 받아들입니다. 하지만 AI 에이전트에게 이런 요소들은 오히려 방해가 됩니다. 복잡한 HTML 마크업은 에이전트의 컨텍스트 윈도우를 채워버리고, 불필요하게 토큰을 소비하게 만들죠. 에이전트가 정말 필요한 건 깨끗하고 구조화된 텍스트입니다.
그래서 최근 Vercel은 자사의 블로그와 체인지로그 페이지를 흥미로운 방식으로 업데이트했습니다. 사람에게는 여전히 풍부한 HTML과 CSS 경험을 제공하면서도, AI 에이전트에게는 마크다운 형태로 콘텐츠를 제공하는 방식이죠. 이 모든 것이 Content Negotiation이라는 HTTP 메커니즘을 통해 가능합니다.
Content Negotiation이란 무엇인가
Content Negotiation은 서버가 클라이언트의 요청에 따라 같은 콘텐츠를 다른 형식으로 반환할 수 있게 해주는 HTTP의 핵심 기능입니다. 중요한 점은 중복된 콘텐츠를 만들거나 별도의 사이트를 운영할 필요가 없다는 것입니다.
이 방식의 가장 큰 장점은 하나의 URL로 여러 형태의 콘텐츠를 제공할 수 있다는 점입니다. 같은 주소에서 브라우저로 접속하면 HTML을 받고, AI 에이전트로 접속하면 마크다운을 받는 식이죠. SEO 관점에서도 매우 효율적인 접근 방식입니다.
AI 에이전트는 어떻게 원하는 형식을 요청할까
AI 에이전트들은 HTTP의 Accept 헤더를 사용하여 선호하는 콘텐츠 형식을 명시합니다. 예를 들어 Claude Code는 페이지를 가져올 때 다음과 같은 헤더를 보냅니다.
Accept: text/markdown, text/html, */*
여기서 text/markdown을 가장 먼저 나열함으로써, 마크다운이 가능하다면 HTML보다 마크다운을 선호한다는 신호를 보내는 것입니다. 최근 많은 AI 에이전트들이 이런 방식으로 명시적으로 마크다운을 요청하기 시작했습니다.
직접 테스트해보고 싶다면 curl 명령어로 간단히 확인할 수 있습니다.
curl https://vercel.com/blog/self-driving-infrastructure \
-H "accept: text/markdown"
실제로 이 명령어를 실행해보면 HTML이 아닌 깔끔한 마크다운 형태로 콘텐츠가 반환되는 것을 확인할 수 있습니다.
서버에서 Content Negotiation 구현하기
Vercel의 구현 방식을 살펴보면, 미들웨어에서 들어오는 요청의 Accept 헤더를 검사하여 클라이언트의 선호도를 감지합니다. 마크다운이 선호되는 경우, Next.js 라우트 핸들러로 요청을 라우팅하여 Contentful의 rich-text 콘텐츠를 마크다운으로 변환합니다.
이 변환 과정에서 콘텐츠의 구조는 그대로 보존됩니다. 코드 블록은 신택스 하이라이팅 마커를 유지하고, 제목은 계층 구조를 그대로 유지하며, 링크도 정상적으로 작동합니다. AI 에이전트는 HTML 버전과 동일한 정보를 받지만, 토큰 효율성을 위해 최적화된 형식으로 받게 되는 것이죠.
Next.js에서 이를 구현하려면 다음과 같은 방식을 고려할 수 있습니다.
// middleware.ts
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'
export function middleware(request: NextRequest) {
const acceptHeader = request.headers.get('accept') || ''
// 마크다운 선호도 확인
const prefersMarkdown = acceptHeader
.split(',')
.map(type => type.trim().split(';')[0])
.indexOf('text/markdown') <
acceptHeader
.split(',')
.map(type => type.trim().split(';')[0])
.indexOf('text/html')
if (prefersMarkdown) {
// 마크다운 라우트로 리다이렉트
return NextResponse.rewrite(
new URL(`${request.nextUrl.pathname}.md`, request.url)
)
}
return NextResponse.next()
}
놀라운 성능 개선 효과
Content Negotiation을 통한 성능 개선 효과는 정말 놀랍습니다. 일반적인 블로그 포스트는 HTML, CSS, 자바스크립트를 모두 포함하면 약 500KB의 용량을 차지합니다. 하지만 같은 콘텐츠를 마크다운으로 제공하면 단 2KB에 불과합니다. 무려 99.6%의 페이로드 감소 효과가 있는 것이죠.
토큰 제한이 있는 AI 에이전트 입장에서 보면, 작은 페이로드는 요청당 더 많은 콘텐츠를 소비할 수 있다는 의미입니다. 불필요한 마크업 대신 실제 정보에 토큰 예산을 사용할 수 있게 되는 것이죠. 결과적으로 에이전트는 더 빠르게 작동하고, 토큰 제한에 덜 자주 걸리게 됩니다.
Vercel은 Next.js 16의 원격 캐시 기능과 공유 slug를 사용하여 HTML과 마크다운 버전 간의 동기화를 유지합니다. Contentful에서 콘텐츠가 업데이트되면 두 버전 모두 동시에 갱신되는 방식입니다.
AI 에이전트의 콘텐츠 발견 방법
AI 에이전트가 사이트의 콘텐츠를 효율적으로 탐색하려면 어떤 콘텐츠가 있는지 발견할 수 있어야 합니다. Vercel은 이를 위해 마크다운 사이트맵을 구현했습니다.
이 사이트맵은 모든 콘텐츠를 AI 에이전트가 소비하기 최적화된 형태로 나열합니다. 각 콘텐츠의 메타데이터(발행일, 콘텐츠 타입, HTML과 마크다운 버전의 직접 링크 등)를 포함하여, 에이전트가 사용 가능한 정보의 완전한 지도를 제공하고 필요에 맞는 형식을 선택할 수 있게 합니다.
실제로 이 기능을 확인하고 싶다면, Vercel 블로그의 URL 끝에 .md를 추가해보세요. 예를 들어 https://vercel.com/blog/making-agent-friendly-pages-with-content-negotiation.md와 같이 말이죠. 그러면 마크다운 버전의 콘텐츠를 바로 확인할 수 있습니다.
실제 프로젝트에 적용해보기
이 방식을 여러분의 프로젝트에 적용한다면 몇 가지 고려사항이 있습니다.
첫째, 콘텐츠 변환 로직을 잘 구현해야 합니다. HTML을 마크다운으로 변환할 때 구조와 의미를 잃지 않도록 주의해야 합니다. turndown 같은 라이브러리를 활용하면 도움이 됩니다.
둘째, 캐싱 전략을 잘 세워야 합니다. Next.js 16의 원격 캐시 기능처럼, HTML과 마크다운 버전이 항상 동기화되도록 관리하는 것이 중요합니다.
셋째, 사이트맵을 제공하여 AI 에이전트가 콘텐츠를 쉽게 발견할 수 있도록 해야 합니다. 기존의 XML 사이트맵 외에 마크다운 형태의 사이트맵을 추가로 제공하는 것을 고려해보세요.
SEO와 접근성 측면의 이점
Content Negotiation은 SEO 측면에서도 매우 유리합니다. 하나의 URL로 다양한 클라이언트에게 최적화된 콘텐츠를 제공할 수 있기 때문에 중복 콘텐츠 문제가 발생하지 않습니다.
또한 AI 에이전트가 여러분의 콘텐츠를 더 잘 이해하고 처리할 수 있게 되면, 에이전트 기반 검색 결과나 요약에서 더 잘 노출될 가능성이 높아집니다. ChatGPT, Claude, Perplexity 같은 AI 서비스들이 점점 더 많은 사람들의 정보 탐색 도구가 되고 있는 상황에서, 이는 무시할 수 없는 이점입니다.
접근성 측면에서도 긍정적입니다. 마크다운은 스크린 리더나 다른 보조 기술에서도 잘 작동하며, 콘텐츠의 구조를 명확하게 전달합니다.
미래를 위한 준비
AI 에이전트가 웹을 탐색하는 시대가 본격화되고 있습니다. Claude Code처럼 개발자를 돕는 에이전트부터, 사용자의 질문에 답하기 위해 웹을 검색하는 대화형 AI까지, 다양한 형태의 에이전트들이 우리의 콘텐츠를 소비하고 있습니다.
Content Negotiation은 이런 변화에 대응하는 우아한 방법입니다. 기존의 사람 중심 경험을 해치지 않으면서도, 새로운 유형의 클라이언트에게 최적화된 경험을 제공할 수 있으니까요.
여러분의 웹사이트나 블로그가 공개 콘텐츠를 제공한다면, 이제 AI 에이전트 친화적으로 만드는 것을 진지하게 고려해볼 시점입니다. 500KB 대신 2KB로 같은 정보를 전달할 수 있다는 것, 그리고 그것이 단지 몇 줄의 코드로 가능하다는 것은 정말 매력적인 개선 사항이 아닐까요.
참고 자료
