Markdown for Agents（面向 Agent 的 Markdown）

Markdown 已迅速成为 Agent 和 AI 系统的通用语言。该格式的明确结构使其非常适合 AI 处理，最终获得更好的结果，同时最小化 token 浪费。

Cloudflare 的网络支持在源站进行实时内容转换，对于使用内容协商 ↗标头且启用了 Markdown for Agents 的 zone，当 AI 系统从任何使用 Cloudflare 的网站请求页面时，它们可以在请求中表达 text/markdown 偏好，我们的网络会在可能的情况下自动高效地将 HTML 转换为 Markdown。

在我们的博客公告 ↗中阅读更多信息。

要从启用了 Markdown for Agents 的 zone 获取任何页面的 Markdown 版本，客户端需要添加带有 text/markdown 作为选项之一的 Accept 协商标头。Cloudflare 会检测到此请求，从源站获取原始 HTML 版本，并在提供给客户端之前将其转换为 Markdown。

以下是一个带有 Accept 协商标头、从我们的开发者文档请求此页面的 curl 示例：

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

如果您使用 Workers 构建 AI Agent，可以使用 TypeScript：

const r = await fetch(
	`https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/`,
	{
		headers: {
			Accept: "text/markdown",
		},
	},
);
const tokenCount = r.headers.get("x-markdown-tokens");
const originalTokenCount = r.headers.get("x-original-tokens");
const markdown = await r.text();

const r = await fetch(
	`https://developers.cloudflare.com/fundamentals/reference/markdown-for-agents/`,
	{
		headers: {
			Accept: "text/markdown",
		},
	},
);
const tokenCount = r.headers.get("x-markdown-tokens");
const originalTokenCount = r.headers.get("x-original-tokens");
const markdown = await r.text();

此请求的响应现在以 markdown 格式呈现：

HTTP/2 200
date: Wed, 11 Feb 2026 11:44:48 GMT
content-type: text/markdown; charset=utf-8
content-length: 2899
vary: accept
cache-control: public, max-age=3600
strict-transport-security: max-age=63072000; includeSubDomains
x-markdown-tokens: 725
x-original-tokens: 12345
content-signal: ai-train=yes, search=yes, ai-input=yes

---
title: Markdown for Agents · Cloudflare Agents docs
---

## 什么是 Markdown for Agents

Markdown has quickly become the lingua franca for agents and AI systems
as a whole. The format’s explicit structure makes it ideal for AI processing,
ultimately resulting in better results while minimizing token waste.
...

Markdown for Agents 在转换后的响应中保留源站响应的标头，因此与安全性和缓存相关的标头在转换后仍然保留。这包括 Strict-Transport-Security（HSTS）、Content-Security-Policy（CSP）、X-Frame-Options、Set-Cookie、CORS 标头（例如 Access-Control-Allow-Origin）以及缓存标头（Cache-Control、Expires、Age）等标头。

由于正文被替换为转换后的 Markdown，将应用以下更改：

• Content-Type 设置为 text/markdown; charset=utf-8。
• Vary 包含 Accept（保留源站已声明的任何 Vary 维度），以便缓存为 Markdown 和 HTML 存储单独的变体。
• Content-Length 重新计算以匹配 Markdown 响应的大小。
• 描述原始正文的标头被移除，因为它们不再与转换后的响应匹配：Content-Encoding、Content-Range、Transfer-Encoding、ETag 和 Last-Modified。ETag 和 Last-Modified 被丢弃，因为无法对转换后的响应满足条件请求（If-None-Match、If-Modified-Since）。

Markdown for Agents 还会添加下面描述的 token 计数标头。

请注意，我们在转换后的响应中包含 token 计数标头。x-markdown-tokens 表示 Markdown 文档中的估计 token 数，x-original-tokens 表示转换前原始 HTML 文档中的估计 token 数。您可以在流程中使用这些值，例如计算上下文窗口大小、估计 Markdown 转换的 token 节省，或决定分块策略。

Content Signals ↗ 是一个框架，允许任何人在访问内容后表达其内容使用偏好。

如果您的源站已设置 content-signal 标头，Markdown for Agents 会在转换后的响应中保留该值——源站的政策具有权威性。这使您可以通过在源站设置 content-signal 标头来定义自定义 Content Signal 政策。

当源站响应不包含 content-signal 标头时，Markdown for Agents 会添加默认的 Content-Signal: ai-train=yes, search=yes, ai-input=yes，表示内容可用于 AI 训练、搜索结果和 AI 输入（包括 Agent 用途）。

Markdown for Agents 返回具有一致、可预测结构的 Markdown 文档，以便 AI 系统可以依赖它而无需针对每个站点编写解析逻辑。响应始终遵循以下布局：

1. YAML frontmatter（YAML 前置元数据），包含从页面 <meta> 标签提取的元数据。仅当存在至少一个受支持的 meta 标签时才输出。
2. 正文 Markdown，从文档正文转换。非内容元素（如页眉、页脚、导航、脚本和样式）在预处理期间被剥离。有关被移除元素的完整列表，请参阅 Workers AI Markdown Conversion 文档中的 HTML 预处理。
3. JSON-LD 结构化数据，在文档末尾保留为围栏 json 代码块。仅当源 HTML 包含 JSON-LD 时才输出。

当源 HTML 包含受支持的 <meta> 标签时，Markdown for Agents 会在响应前添加 YAML 前置元数据块。该块使用以下字段：

仅输出有值的字段。如果源 HTML 不包含任何受支持的 meta 标签，则完全省略 frontmatter 块。

对于 title 和 description，标准 <meta name="..."> 形式始终优先于 Open Graph <meta property="og:..."> 形式，无论它们在 HTML 中的顺序如何。仅当标准形式缺失时才使用 Open Graph 值作为回退。

示例输出：

---
title: My Page Title
description: A short summary of the page.
image: https://example.com/cover.png
---

# Page heading

...

JSON-LD ↗ 是一种结构化数据格式，搜索引擎和 AI 系统使用它来解读页面的语义内容。Markdown for Agents 通过在转换后的 Markdown 末尾的单个围栏 json 代码块中附加，保留源 HTML 中任何 <script type="application/ld+json"> 块。

如果源 HTML 包含多个 JSON-LD 脚本，它们全部连接在同一代码块内，每个占一行。

JSON-LD 是输出中唯一保留的 <script> 内容——所有其他 <script> 和 <style> 内容在 HTML 预处理期间被剥离。

示例输出：

... main markdown content ...

```json
{
	"@context": "https://schema.org",
	"@type": "Article",
	"headline": "Article Title",
	"author": { "@type": "Person", "name": "Jane Doe" }
}
```

curl -X PATCH 'https://api.cloudflare.com/client/v4/zones/{zone_tag}/settings/content_converter' \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer {api_token}" --data-raw '{"value": "on"}'

curl --request PUT \
  --url "https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_config_settings/entrypoint" \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "rules": [{
      "expression": "http.host eq \"docs.example.com\"",
      "action": "set_config",
      "action_parameters": {
        "content_converter": true
      },
      "description": "Enable Markdown for Agents for docs subdomain"
    }]
  }'

curl --request PATCH \
  --url "https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "custom_metadata": {
      "content_converter": "enabled"
    }
  }'

curl --request PUT \
  --url "https://api.cloudflare.com/client/v4/zones/{zone_id}/rulesets/phases/http_config_settings/entrypoint" \
  --header "Authorization: Bearer {api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "rules": [{
      "expression": "lookup_json_string(cf.hostname.metadata, \"content_converter\") eq \"enabled\"",
      "action": "set_config",
      "action_parameters": {
        "content_converter": true
      },
      "description": "Enable content converter for opted-in custom hostnames"
    }]
  }'

Markdown for Agents 向 Pro、Business 和 Enterprise 计划以及 SSL for SaaS 客户提供，免费使用。

我们已在开发者文档和博客 ↗中启用此功能，邀请所有 AI 爬虫和 Agent 使用 markdown 而非 HTML 消费我们的内容。

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

• 我们仅从 HTML 转换，其他类型的文档可能在未来包含。
• 源站响应不能超过 2 MB（2,097,152 字节）。

如果您正在构建需要在 Cloudflare 外部进行任意文档转换的 AI 系统，或内容源不提供 Markdown for Agents，我们提供其他方式为您的应用将文档转换为 Markdown：

• Workers AI AI.toMarkdown() 支持多种文档类型和摘要。
• Browser Run /markdown 端点支持 markdown 转换，如果您需要在转换前在真实浏览器中渲染动态页面或应用。