Accept: text/markdown은 HTTP Accept 헤더 콘텐츠 협상(content negotiation)을 이용해 한 URL에서 사람용 HTML과 AI 에이전트용 Markdown을 나눠 제공하는 패턴이다. 사이트 본문은 이미 있지만 메뉴·스크립트·광고·레이아웃을 함께 보내는 비용이 큰 퍼블리셔, 문서 사이트, 사내 지식 베이스에 적합하다.
왜 별도 Markdown 변형이 필요한가
에이전트와 RAG 인덱서는 HTML을 가져온 뒤 본문을 추출할 수 있지만, 이 과정은 DOM 잡음과 파싱 비용을 남긴다. 서버가 본문 중심 Markdown을 직접 제공하면 토큰, 검색 신호 대 잡음비, 첫 토큰 지연 시간을 함께 줄일 수 있다. 다만 이는 검색 품질을 자동으로 보장하는 기능이 아니라, 정제된 본문·정확한 캐시·동일한 최신성을 유지해야 효과가 있다.
HTTP 응답 계약
클라이언트가 다음처럼 요청한다.
curl -sI -H "Accept: text/markdown" https://example.com/article서버는 Markdown을 선택했다면 최소한 다음을 반환한다.
Content-Type: text/markdown; charset=utf-8
Vary: AcceptVary: Accept가 없으면 CDN이 HTML 응답을 Markdown 요청에 잘못 재사용할 수 있다. 지원하지 않는 미디어 타입만 요청됐을 때는 406 Not Acceptable을 돌리고, 여러 미디어 타입이 올 때는 q-value 우선순위를 해석한다. HTML과 Markdown은 같은 원문의 표현일 뿐이므로 canonical URL과 수정 시점도 일치하게 관리한다.
도입 전 확인할 것
| 상황 | 권장 |
|---|---|
| 공개 문서·블로그를 에이전트와 검색 시스템이 자주 읽음 | 적용 검토 |
| 인증된 사용자별 개인화 페이지 | 권한·캐시 분리를 먼저 설계 |
| Markdown 본문을 안정적으로 생성·검증할 수 없음 | HTML 추출 파이프라인 유지 |
| 기존 API가 구조화된 JSON을 이미 제공 | Markdown과 JSON의 역할을 분리 |
Markdown 응답도 외부 입력이다. 이를 가져오는 에이전트는 텍스트 안의 지시를 실행 지시로 신뢰하지 말고, 검색 인덱싱과 도구 호출 경계를 별도로 검증해야 한다.
관련 문서
- rag — 외부 문서를 검색해 모델 컨텍스트로 넣는 구조
- crawl4ai — 웹페이지를 Markdown·구조화 데이터로 수집하는 인제스트 도구
- webmcp — 웹 기능을 브라우저 에이전트용 도구로 노출하는 표준
참고 자료
- Accept: text/markdown — acceptmarkdown.com (2026-08-27)