콘텐츠 협상을 활용한 AI 에이전트 친화적 웹페이지 만들기
목차
개요
Vercel이 블로그에서 AI 에이전트를 위해 웹페이지 용량을 500KB에서 2KB로 줄인 방법을 공개했다. HTTP 콘텐츠 협상(Content Negotiation) 메커니즘을 활용하여 동일한 URL에서 사람과 AI 에이전트에게 각각 최적화된 콘텐츠를 제공하는 방식이다. 별도의 사이트나 중복 콘텐츠 없이도 에이전트 친화적인 웹페이지를 구현할 수 있다.
문제점: AI 에이전트와 웹 콘텐츠의 불일치
AI 에이전트는 웹 콘텐츠를 사람과는 근본적으로 다르게 처리한다. 에이전트는 CSS, 클라이언트 사이드 JavaScript, 이미지 등의 요소를 활용하지 않는다. 이러한 요소들은 에이전트의 컨텍스트 윈도우를 채우고 토큰을 소비하면서도 유용한 정보를 거의 제공하지 않는다.
기존 방식에서는 사람을 위해 설계된 완전한 HTML 페이지를 에이전트에게도 동일하게 전달했다. 이로 인해 불필요한 리소스 낭비와 토큰 비용 증가 문제가 발생했다.
해결책: HTTP 콘텐츠 협상
HTTP 콘텐츠 협상은 동일한 URL에서 클라이언트의 요청에 따라 서로 다른 형식의 콘텐츠를 제공하는 표준 메커니즘이다. 이를 활용하면 하나의 URL로 다음과 같이 분기할 수 있다.
| 클라이언트 | 제공 형식 |
|---|---|
| 브라우저(사람) | 완전한 HTML + CSS + JavaScript |
| AI 에이전트 | 구조화된 마크다운 |
별도의 API 엔드포인트나 중복 사이트를 만들 필요가 없다는 것이 핵심이다.
기술적 구현
Accept 헤더 기반 라우팅
에이전트는 HTTP 요청 시 Accept 헤더를 통해 선호하는 콘텐츠 형식을 서버에 전달한다. 예를 들어 Claude Code는 다음과 같은 Accept 헤더를 전송한다.
1
Accept: text/markdown, text/html, */*
미들웨어 처리
서버의 미들웨어가 이 Accept 헤더를 감지하고 요청을 적절한 핸들러로 라우팅한다. Next.js 핸들러가 Contentful의 리치 텍스트를 마크다운으로 변환하여 응답한다.
변환 과정에서 다음 요소들은 그대로 유지된다.
| 요소 | 처리 방식 |
|---|---|
| 코드 블록 | 구문 강조 정보 유지 |
| 제목 구조 | 계층적 구조 보존 |
| 링크 | 기능 유지 |
콘텐츠 동기화
마크다운 버전과 HTML 버전의 일관성은 Next.js 16의 리모트 캐시와 공유 URL 슬러그를 통해 보장된다. Contentful에서 콘텐츠가 변경되면 두 버전이 동시에 업데이트된다.
성과
일반적인 블로그 포스트 기준으로 극적인 용량 감소가 확인되었다.
| 항목 | 수치 |
|---|---|
| HTML 버전 | 약 500KB |
| 마크다운 버전 | 약 2KB |
| 감소율 | 99.6% |
이러한 효율성 덕분에 에이전트는 토큰 예산 내에서 더 많은 콘텐츠를 소비할 수 있게 된다.
에이전트 발견 메커니즘
마크다운에 최적화된 사이트맵을 제공하여 에이전트가 사용 가능한 콘텐츠를 탐색할 수 있도록 한다. 사이트맵에는 다음과 같은 정보가 포함된다.
- 발행 날짜
- 콘텐츠 타입
- 형식별 링크
이를 통해 에이전트는 어떤 콘텐츠가 존재하는지 파악하고 원하는 형식을 선택할 수 있다.
결론
HTTP 콘텐츠 협상은 이미 존재하는 웹 표준을 활용한 실용적인 접근법이다. 동일한 URL에서 사람과 에이전트 모두에게 최적화된 경험을 제공할 수 있다. 별도의 에이전트 전용 사이트를 구축할 필요 없이 기존 인프라에 미들웨어를 추가하는 것만으로 구현 가능하다. AI 에이전트의 웹 콘텐츠 소비가 증가하는 현재 시점에서 콘텐츠 협상은 효율적인 에이전트 지원 방법이 될 수 있다.