Cloudflare의 "Markdown for Agents"는 AI 시스템을 위해 HTML 페이지를 실시간으로 Markdown 형식으로 변환하여 제공하는 서비스입니다. 이 서비스는 Markdown의 명시적인 구조가 AI 처리에 이상적이며, 토큰 낭비를 최소화하고 더 나은 AI 처리 결과를 도출하는 데 기여한다고 설명합니다.

핵심 방법론 (Core Methodology):
Cloudflare 네트워크는 클라이언트의 요청에 포함된 Accept 콘텐츠 협상 헤더를 사용하여 text/markdown 선호를 감지합니다. 이 선호가 감지되면 Cloudflare는 원본 서버(Origin)로부터 HTML 버전의 콘텐츠를 가져온 후, 이를 즉시(on-the-fly) Markdown으로 변환하여 클라이언트에 제공합니다. 이는 Edge 단에서 이루어지므로 효율적이며, 별도의 변환 로직을 클라이언트 측에 구현할 필요 없이 HTTP 요청의 Accept 헤더 설정만으로 원하는 Markdown 응답을 받을 수 있습니다.

사용 방법:

1. 클라이언트 측 (Client-side):
   • HTTP 요청 시 Accept: text/markdown 헤더를 포함합니다.
   • 예시: curl https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/ -H "Accept: text/markdown"
   • JavaScript 또는 TypeScript fetch API를 사용할 경우, headers 객체에 { Accept: "text/markdown" }를 추가합니다.
   • 응답에는 변환된 Markdown 콘텐츠와 함께, 예상 토큰 수를 나타내는 x-markdown-tokens 헤더 (예: x-markdown-tokens: 725)가 포함됩니다. 이 값은 컨텍스트 윈도우 크기 계산이나 청킹 전략 결정에 활용될 수 있습니다.

2. 서비스 활성화 (Server-side Enablement):
   • 대시보드 (Dashboard): Pro 또는 Business 플랜 사용자는 Cloudflare 대시보드에 로그인하여 특정 Zone의 Quick Actions 섹션에서 "Markdown for Agents" 버튼을 토글하여 활성화할 수 있습니다.
   • API: Cloudflare API를 통해 PATCH 요청을 https://api.cloudflare.com/client/v4/zones/{zone_tag}/settings/content_converter 엔드포인트로 전송하고, 페이로드에 {"value": "on"}을 포함하여 활성화할 수 있습니다. 이를 위해서는 Zone Settings 편집 권한이 있는 API 토큰이 필요합니다.
   • 커스텀 호스트네임 (Custom Hostnames) - Cloudflare for SaaS:
     • 모든 커스텀 호스트네임: SaaS Zone의 대시보드 Quick Actions에서 활성화합니다.
     • 특정 커스텀 호스트네임 (고급 구독 필요):
       • 1단계: API를 통해 커스텀 호스트네임 생성 또는 업데이트 시 custom_metadata 객체에 "content_converter": "enabled"를 설정합니다. 예시: {"custom_metadata": {"content_converter": "enabled"}}
       • 2단계: Configuration Rule을 생성하여 cf.hostname.metadata에서 "content_converter" 값이 "enabled"인 경우 set_config 액션을 통해 content_converter를 true로 설정하는 규칙을 추가합니다. 예시 Rule: {"expression": "lookup_json_string(cf.hostname.metadata, \"content_converter\") eq \"enabled\"", "action": "set_config", "action_parameters": { "content_converter": true }}

콘텐츠 시그널 (Content Signals):
변환된 Markdown 응답에는 기본적으로 $Content-Signal: ai-train=yes, search=yes, ai-input=yes$ 헤더가 포함되어, 해당 콘텐츠가 AI 학습, 검색 결과, AI 입력(에이전트 사용 포함)에 사용될 수 있음을 알립니다. 향후에는 커스텀 Content Signal 정책을 정의하는 옵션도 제공될 예정입니다.

가용성 및 가격 (Availability and Pricing):
Markdown for Agents는 Pro, Business, Enterprise 플랜 및 SSL for SaaS 고객에게 추가 비용 없이 제공됩니다.

제한 사항 (Limitations):

• 원본 응답에 Content-Length 헤더가 없거나, Content-Length가 1MB(1,048,576 bytes)를 초과하는 경우 Markdown 변환이 이루어지지 않고 원본 HTML 응답이 반환됩니다.
• HTML만 변환이 지원되며, 다른 문서 형식은 향후 추가될 수 있습니다.
• 원본 서버에서 압축된 응답은 지원되지 않습니다.
• Zone 레벨 설정이므로, 동일 Zone 내의 하위 도메인별로 다른 설정을 적용하려면 해당 하위 도메인을 별도의 Zone으로 분리해야 합니다.

다른 Markdown 변환 API:
Cloudflare는 Markdown for Agents 외에도 Workers AI의 AI.toMarkdown() (다양한 문서 형식 및 요약 지원) 및 Browser Rendering의 /markdown REST API (동적 페이지 또는 애플리케이션의 실제 브라우저 렌더링 후 변환)와 같은 다른 문서-Markdown 변환 솔루션도 제공합니다.