面向 AI Agents 的 Link Headers
HTTP Link header 可以使用已注册 relation 暴露 API catalog、机器可读服务描述、人工文档和元数据。本文说明标准边界、响应语法、部署检查与常见误用。
面向 AI Agents 的 Link Headers
Link headers 是 HTTP 响应里的链接字段，可以在 agent 解析页面正文前，先告诉它相关资源在哪里。对 AI agents 来说，它可以作为 API catalog、机器可读服务描述、人工文档和服务元数据的轻量发现层。
它不能替代可见导航或 HTML 链接，但可以补充一个协议层信号，让 crawler 或 agent 不必只靠抓页面模板来猜资源位置。
为什么重要
AI agents 经常从一个 URL 开始，然后需要判断：
- 有没有 API 描述文件？
- 有没有人工文档或服务状态页？
- 有没有注册在 IANA 的 relation 能准确表达这种关系？
HTTP Link header 可以直接暴露这些资源。
常见发现目标
rel="api-catalog"：指向发布方的 API 目录；RFC 9727 同时定义/.well-known/api-catalogrel="service-desc"：指向主要供机器使用的 API 或服务描述，例如 OpenAPI 文件rel="service-doc"：指向主要供人阅读的服务文档rel="service-meta"：指向其他机器可读服务元数据rel="status"：指向服务状态资源rel="alternate"：指向当前资源的替代表示；必须结合媒体类型和具体使用场景解释
relation 应以 IANA Link Relation Registry为准。不要随意创造一个看起来合理的 relation 并假设客户端认识它。sitemap 目前不是该注册表中的标准 relation；面向搜索引擎提交 sitemap 时，应继续使用 robots.txt、Search Console 和搜索引擎明确支持的方式。
响应示例
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Link: </.well-known/api-catalog>; rel="api-catalog"; type="application/linkset+json"
Link: </openapi.yaml>; rel="service-desc"; type="application/yaml"
Link: </docs/api/>; rel="service-doc"; type="text/html"
一个响应可以包含多个 Link 字段，也可以在一个字段中用逗号组合多个链接。部署时要检查 CDN、反向代理和 Pages/Workers 规则是否保留了全部字段，避免后写入的值覆盖前一个。
SEO 建议
把 Link headers 当成支撑基础设施，而不是内容替代品。核心页面仍然需要可抓取 HTML、canonical、内部链接、结构化数据和清晰正文。
适合 Agent SEO 的模式是：
- 重要资源保留 HTML 链接
- 为机器发现补充 HTTP Link headers
- 让 header 指向稳定资源
- 测试原始 HTTP 响应，不只看渲染页面
发布审计清单
- 使用
curl -I或等价工具检查生产响应，而不是只看源码。 - 确认目标 URL 返回预期状态码、媒体类型和 CORS 策略。
- 验证 relation 已注册，且语义与目标资源一致。
- 同时保留人类可发现的 HTML 导航，不把 Link header 当成唯一入口。
- 对私有 API catalog、认证元数据和内部服务描述执行访问控制，不能因为“机器可读”就默认公开。
- 记录 relation、目标格式、版本和负责人，避免协议文件长期失效。
Link header 是发现机制，不是搜索排名保证，也不代表 agent 获得调用或付款授权。客户端仍需决定是否支持该 relation，并继续执行认证、策略与安全检查。