Markdown for Agents: Cloudflare가 공개한, AI 에이전트를 위한 새로운 콘텐츠 요청/응답 방식

9bow · 2월 14, 2026, 9:30오전

Markdown for Agents 소개

Cloudflare가 웹 콘텐츠를 AI 에이전트와 크롤러가 더 효율적으로 소비할 수 있도록 돕는 새로운 기능인 Markdown for Agents를 발표했습니다. 오늘날 웹 트래픽의 상당 부분은 사람이 아닌 AI 에이전트와 크롤러에서 발생하고 있습니다. 하지만 기존 웹은 사람을 위해 설계된 HTML, CSS, JavaScript로 구성되어 있어, AI가 정보를 추출하기에는 불필요한 태그와 스크립트가 많아 비효율적이었습니다. Markdown for Agents는 이러한 문제를 해결하기 위해, 요청 시 실시간으로 웹페이지의 HTML을 Markdown으로 변환하여 제공하는 기능입니다.

이 기술의 핵심은 콘텐츠 협상(Content Negotiation)입니다. AI 에이전트가 웹페이지를 요청할 때 Accept: text/markdown 헤더를 포함하면, Cloudflare 네트워크가 이를 감지하여 원본 서버의 HTML을 가져온 뒤 자동으로 Markdown으로 변환하여 응답합니다. 이를 통해 AI 모델은 복잡한 HTML 파싱 과정 없이 순수한 텍스트와 구조화된 데이터만을 즉시 소비할 수 있게 됩니다.

Markdown for Agents 기능은 AI 모델의 추론 비용과 속도에 직접적인 영향을 미치는 '토큰(Token)' 사용량을 획기적으로 줄여줍니다. 예를 들어, HTML로 구성된 일반적인 블로그 포스트는 약 16,000 토큰을 소모하지만, 이를 Markdown으로 변환하면 약 3,000 토큰으로 줄어들어 약 80%의 절감 효과를 볼 수 있습니다. 이는 AI 에이전트의 컨텍스트 윈도우(Context Window)를 효율적으로 사용하고, 더 정확한 검색 증강 생성(RAG) 결과를 얻는 데 기여합니다.

AI Agent의 HTML vs. Markdown 방식 비교

기존의 웹 접근 방식과 Markdown for Agents를 사용했을 때의 차이점은 다음과 같습니다. 기존 방식(HTML) 은 AI 에이전트가 웹페이지를 스크래핑하면 <div>, <nav>, <script> 등 의미 없는 태그까지 모두 읽어들여야 했습니다. 이는 불필요한 토큰 소모를 유발하고, 핵심 정보를 추출하기 위한 별도의 전처리 과정을 필요로 합니다.

이에 비해, 이번에 Cloudflare가 제시한 새로운 방식(Markdown) 은 AI 에이전트가 Markdown을 요청하면, 불필요한 래퍼(Wrapper)나 스타일 요소가 제거된 '정제된 정보'만 받습니다. Markdown의 명시적인 구조(#, - 등)는 LLM이 문맥을 이해하기에 최적화되어 있어, 처리 속도가 빠르고 비용이 절감됩니다.

Markdown for Agents의 주요 특징

Markdown for Agents 기능은 Cloudflare의 프록시 레벨에서 작동하며, 별도의 복잡한 서버 설정 없이 대시보드에서 활성화하거나 API를 통해 사용할 수 있습니다.

작동 메커니즘 (Content Negotiation)

AI 클라이언트는 HTTP 요청 시 Accept 헤더를 통해 Markdown 형식을 선호한다는 것을 알립니다.

요청 (Request): 클라이언트가 Accept: text/markdown 헤더를 포함하여 요청을 보냅니다.
변환 (Conversion): Cloudflare 엣지 네트워크가 이를 감지하고 원본 HTML을 Markdown으로 변환합니다.
응답 (Response): 변환된 Markdown 텍스트와 함께 메타데이터 헤더를 반환합니다.

사용 예시 (Code Snippets)

Markdown for Agents의 몇 가지 사용 예시를 살펴보겠습니다.

다음은 cURL을 통한 요청 예시입니다:

curl https://blog.cloudflare.com/markdown-for-agents/ \
  -H "Accept: text/markdown"

다음은 JavaScript (Workers)에서의 요청 예시입니다:

const 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();

Markdown for Agents의 주요 응답 헤더

변환된 응답에는 개발자와 AI 에이전트에게 유용한 추가 정보가 포함됩니다.

x-markdown-tokens: 변환된 Markdown 문서의 예상 토큰 수입니다. 이를 통해 에이전트는 컨텍스트 윈도우 용량을 미리 계산하거나 청크(Chunk) 전략을 세울 수 있습니다.
content-signal: 콘텐츠의 사용 허가 범위를 나타냅니다. (예: ai-train=yes, search=yes, ai-input=yes). 이는 콘텐츠 소유자가 자신의 데이터가 AI 학습이나 검색에 사용되는 것을 제어할 수 있는 'Content Signals' 프레임워크의 일부입니다.

기타 변환 도구

Cloudflare 내부망 외부의 문서를 변환하거나 동적 페이지를 처리해야 하는 경우를 위해 추가적인 도구도 제공합니다:

Workers AI: AI.toMarkdown() 기능으로 HTML뿐만 아니라 PDF 등 다양한 문서 형식을 Markdown으로 변환하고 요약할 수 있는 유틸리티입니다.
Browser Rendering API: /markdown REST API를 통해 자바스크립트 실행이 필요한 동적 페이지를 브라우저에서 렌더링한 후 Markdown으로 변환할 수 있습니다.

분석 및 모니터링 (Cloudflare Radar)

Cloudflare Radar는 이제 AI 봇과 크롤러가 요청하는 콘텐츠 유형(MIME type)에 대한 통계를 제공합니다. 이를 통해 웹 운영자는 자신의 사이트가 AI 에이전트에게 어떤 형태로(HTML vs Markdown) 소비되고 있는지 파악할 수 있습니다.

Introducing Markdown for Agents 공식 블로그

Markdown for Agents 기능 관련 개발 문서

Cloudflare Agents 프로젝트 GitHub 저장소

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~