원문 보기
Introducing Markdown for Agents
Blog

Introducing Markdown for Agents

@celso
2026.02.13
·Web·by 이호민
#Agents#AI#Cloudflare#Markdown#Web

핵심 포인트

  • 1AI 에이전트가 기존 웹의 HTML 콘텐츠를 처리하는 데 토큰 비효율성과 비구조화된 문제에 직면함에 따라, HTML을 Markdown으로 변환하는 과정이 불필요한 계산 비용을 발생시키고 원래 콘텐츠 제작자의 의도를 반영하지 못할 수 있습니다.
  • 2Cloudflare는 AI 에이전트가 HTTP `Accept: text/markdown` 헤더를 통해 요청할 때 HTML 콘텐츠를 실시간으로 Markdown으로 자동 변환하여 제공하는 'Markdown for Agents' 기능을 도입했습니다.
  • 3이 기능은 AI 시스템의 토큰 사용량을 최대 80%까지 절감하고, 구조화된 데이터를 제공하여 처리 효율성을 높이며, `x-markdown-tokens` 및 `Content-Signal`과 같은 추가 메타데이터를 제공하여 AI 훈련 및 사용에 기여합니다.

이 논문은 온라인에서 콘텐츠와 비즈니스가 발견되는 방식이 변화하고 있으며, 기존 검색 엔진 중심에서 AI 크롤러 및 에이전트 중심으로 전환되고 있음을 설명합니다. 과거의 웹은 인간을 위해 구축된 비정형(unstructured) 데이터인 HTML로 구성되어 있었으나, AI 에이전트는 구조화된(structured) 데이터를 요구합니다.

기존 방식의 문제점은 AI가 원시 HTML을 처리할 때 비효율적이라는 것입니다. 예를 들어, HTML 페이지는 Markdown으로 변환했을 때보다 훨씬 많은 token을 소모합니다(이 블로그 게시물의 경우 HTML은 16,180 token, Markdown은 3,150 token으로 80% 감소). 이는 <div><div> 래퍼, nav bar, 스크립트 태그 등 의미론적 가치가 없는 요소들 때문입니다. Markdown은 명시적인 구조를 가지고 있어 AI 시스템의 lingua franca가 되었으며, token 낭비를 최소화하여 AI 처리에 이상적입니다. 현재 대부분의 AI 파이프라인은 HTML을 Markdown으로 변환하는 단계를 거치지만, 이는 계산 자원 낭비, 비용 증가, 처리 복잡성 추가, 그리고 콘텐츠 제작자의 의도와 다를 수 있다는 문제를 안고 있습니다.

이러한 문제를 해결하기 위해 Cloudflare는 "Markdown for Agents"라는 새로운 접근 방식을 제안합니다. 이 핵심 방법론은 AI 에이전트가 content negotiation headers를 사용하여 소스에서 직접 구조화된 Markdown을 받을 수 있도록 하는 것입니다.

핵심 방법론: Markdown for Agents

  1. 작동 방식:
    • Cloudflare 네트워크에 Markdown for Agents가 활성화된 존(zone)을 사용하는 웹사이트의 경우, AI 시스템 클라이언트가 페이지를 요청할 때 HTTP Accept 헤더에 text/markdown을 옵션 중 하나로 추가합니다.
    • Cloudflare는 이 Accept 헤더를 감지합니다.
    • 감지 후, Cloudflare는 원본 HTML 버전을 오리진 서버에서 가져옵니다.
    • 가져온 HTML을 실시간(on the fly)으로 Markdown으로 변환합니다.
    • 변환된 Markdown 콘텐츠를 클라이언트에 제공합니다.
  1. 기술적 구현:
    • curl 예시:
bashcurl https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/ \ -H "Accept: text/markdown"
  • Workers (TypeScript) 예시:
typescriptconst r = await fetch( `https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/`, { headers: { Accept: "text/markdown, text/html", }, }, ); const tokenCount = r.headers.get("x-markdown-tokens"); const markdown = await r.text();
  • 응답 헤더: 응답은 HTTP/2 200 상태 코드와 함께 content-type: text/markdown을 포함합니다. 특히, x-markdown-tokens 헤더는 변환된 Markdown 문서의 예상 token 수를 제공하여 AI 모델의 context window 계산이나 chunking strategy 결정에 활용할 수 있도록 합니다.

이 방식의 주요 이점은 AI 에이전트가 의도 분석 및 문서 변환의 복잡성을 우회하고, 효율적인 token 사용으로 더 나은 결과를 얻을 수 있다는 점입니다.

추가 기능 및 지원:

  • Content Signals Policy: Cloudflare는 Content Signals라는 프레임워크를 통해 콘텐츠 소유자가 자신의 콘텐츠가 어떻게 사용될 수 있는지 선호도를 표현할 수 있도록 합니다. Markdown for Agents를 통해 변환된 응답에는 Content−Signal:ai−train=yes,search=yes,ai−input=yesContent-Signal: ai-train=yes, search=yes, ai-input=yes 헤더가 포함되어, 해당 콘텐츠가 AI 학습, 검색 결과, 그리고 에이전트 사용을 포함한 AI 입력으로 활용될 수 있음을 명시합니다. 향후에는 사용자 지정 Content Signal 정책을 정의하는 옵션도 제공될 예정입니다.
  • 다른 Markdown 변환 방법: Cloudflare 네트워크 외부의 콘텐츠나 Markdown for Agents를 사용할 수 없는 경우를 위해 다음과 같은 다른 변환 방법도 제공합니다:
    • Workers AI AI.toMarkdown(): HTML 외에도 다양한 문서 유형과 요약 기능을 지원합니다.
    • Browser Rendering /markdown REST API: 동적 페이지나 애플리케이션을 실제 브라우저에서 렌더링한 후 Markdown으로 변환해야 할 때 사용됩니다.
  • Markdown 사용량 추적 (Cloudflare Radar): Cloudflare Radar는 AI 봇 및 크롤러 트래픽에 대한 content_type 인사이트를 제공합니다. 새로운 content_type 차원과 필터를 통해 AI 에이전트에게 반환된 콘텐츠 유형의 분포를 추적하고, 특정 에이전트(예: OAI-Searchbot)에 대한 Markdown 요청을 필터링하여 볼 수 있습니다. 이 데이터는 AI 봇, 크롤러 및 에이전트가 웹 콘텐츠를 소비하는 방식의 진화를 추적하는 데 사용될 것입니다.

Markdown for Agents는 현재 베타 버전으로 Pro, Business, Enterprise 플랜 및 SSL for SaaS 고객에게 추가 비용 없이 제공됩니다. 이 기능을 통해 AI 에이전트가 웹을 보다 효율적으로 탐색하고 적응할 수 있도록 돕는 것을 목표로 합니다.