AI 에이전트에게 Accept 헤더로 Markdown 서빙하기

Who Should Read

에이전트나 RAG 파이프라인이 자기 사이트 문서를 읽어 가는 상황에서 토큰 낭비와 노이즈를 줄이고 싶은 백엔드·웹 개발자

Core Mechanics

• 같은 URL, 응답은 두 가지
  • 브라우저에는 HTML, Accept: text/markdown을 보낸 클라이언트에는 Markdown을 준다.
  • HTTP 콘텐츠 협상(content negotiation, 요청 헤더로 응답 형식을 고르는 방식)을 쓴다.
• 토큰이 줄어든다는 주장
  • Markdown은 nav, 스타일, 스크립트, 레이아웃 래퍼를 뺀다.
  • 에이전트가 DOM이 아니라 본문에 컨텍스트를 쓰게 된다고 설명한다.
• RAG 노이즈도 줄어든다
  • 광고, 관련 콘텐츠 레일, 모달 오버레이가 없어진다.
  • RAG 파이프라인이 임베딩할 텍스트의 신호 대비 잡음이 좋아진다고 한다.
• 첫 토큰이 빨라진다는 주장
  • 가져오고 파싱하고 컨텍스트에 넣을 양이 줄어든다.
  • 모델이 생각을 시작하기 전 단계가 짧아진다는 설명이다.
• 올바른 구현 체크리스트가 있다
  • Accept: text/markdown에 Markdown을 주는지, Vary: Accept를 설정하는지 본다.
  • 지원 안 하는 타입에 406을 주는지, q-value를 존중하는지도 본다.

Community Reactions

• 캐싱 문제를 지적하는 의견
  • Roy Fielding과 Simon Willison을 인용해 Accept 기반 협상은 캐시에 나쁘다는 의견이 나왔다.
  • Cloudflare CDN 뒤에서는 JSON과 HTML이 서로 뒤바뀌어 캐시될 수 있다는 지적이다.
• 아직 쓰는 에이전트가 없다는 반론
  • 상위 AI 챗봇이 이 헤더를 보내기 전에는 도입할 이유가 없다는 의견이 있었다.
  • 사이트가 얻는 게 없다는 질문도 여럿 나왔다.
• 하네스가 변환해야 한다는 의견
  • 에이전트 쪽 harness(도구 실행 래퍼)가 HTML을 Markdown으로 바꾸면 된다는 주장이 나왔다.
  • 웹 전체를 다시 쓸 일이 아니라는 입장이다.
• 신뢰와 보안 우려
  • 봇이 Markdown 버전이 HTML과 같은 내용이라고 믿기 어렵다는 의견이 있었다.
  • 프롬프트 인젝션이나 LLM에게 가짜 내용을 먹이는 데 악용될 수 있다는 우려도 나왔다.

How to Apply

• 내 사이트에 curl로 헤더 확인하기
  • 오늘 curl -sI -H "Accept: text/markdown" <URL>로 Content-Type과 Vary 헤더를 확인하라.
  • 본문도 curl -s로 받아 HTML이 그대로 오는지 보라.
• Vary: Accept와 406 처리 넣기
  • Markdown 변형을 만들 때 응답에 Vary: Accept를 반드시 붙여라.
  • 지원하지 않는 타입 요청에는 406을 반환하도록 설정하라.
• CDN 캐시 동작 먼저 테스트하기
  • 배포 전에 CDN 뒤에서 Accept별로 응답이 따로 캐시되는지 확인하라.
  • 안 되면 별도 URL(.md 등)로 제공하는 쪽을 택하라.

Try It

# 터미널에 붙여넣기 (내 사이트 URL로 바꿔서)

curl -sI -H "Accept: text/markdown" {{URL}}

# Markdown 본문 받아 보기
curl -s -H "Accept: text/markdown" {{URL}} | head -50

# 일반 HTML 요청과 비교하기
curl -sI -H "Accept: text/html" {{URL}}

Terminology

관련 논문

• Mercury 3: 규모를 키운 diffusion LLM, 초당 1,000토큰 이상

  Diffusion LLM을 40배 키웠더니 속도 4~8배, 품질은 속도 특화 모델 수준

• Timestral: Mistral의 시계열 파운데이션 모델

  209M 파라미터 시계열 모델이 3대 벤치마크 1위, CPU에서도 돌아간다

• DeepSeek V4.1 Flash 1017 (Max) 성능·속도·가격 분석

  DeepSeek V4.1 Flash 1017 Max는 지능 지수 45에 211 tok/s, 입력 $0.30

• LLM 프록시를 직접 안 돌리면 무슨 일이 벌어지는지 어떻게 아나

  자체 LLM 프록시를 세웠더니 키·모델·캐시 미스를 직접 볼 수 있다

• DeepSeek V4.1 Flash 1017: 싼 가격에 1M 컨텍스트를 주는 에이전트용 모델

  DeepSeek V4.1 Flash 1017은 입력 $0.05/M, 1M 컨텍스트의 에이전트용 모델

• DeepSeek-V4.1-Flash-1017 공개: 더 짧게 생각하고 더 빠르게 일하는 에이전트용 모델

  DeepSeek V4.1 Flash 마이너 업데이트로 코딩·에이전트 벤치 점수↑, 실행 시간·출력 길이↓

• Llmspeed: 로컬 LLM 속도를 하드웨어 구매 전에 체감해 보는 시뮬레이터

  GPU·모델을 고르면 로컬 LLM 속도를 미리 체감하게 해 주는 시뮬레이터

Related Resources

• https://acceptmarkdown.com/
• https://dacharycarey.com/2026/02/18/agent-friendly-docs/