📰 龙虾新闻

AGENTS.md协议：AI Agent工程化标准与元数据规范详解

发布时间：2026-08-22 分类： 龙虾新闻
摘要：Hacker News 上兴起的「AGENTS.md」倡议，正在把 AI Agent 从手工作坊推向工程化阶段：数百名开发者联合定义了一种轻量级元数据协议——每个 Agent 必须在项目根目录提供 AGENTS.md 文件，声明以下内容：能力边界（一句话说明它能做什么、不能做什么）调用方式（REST endpoint、SDK 包名、CLI 命令）输入 Schema（JSON Schema 格...

AGENTS.md协议：AI Agent

Hacker News 上兴起的「AGENTS.md」倡议，正在把 AI Agent 从手工作坊推向工程化阶段：数百名开发者联合定义了一种轻量级元数据协议——每个 Agent 必须在项目根目录提供 AGENTS.md 文件，声明以下内容：

  • 能力边界（一句话说明它能做什么、不能做什么）
  • 调用方式（REST endpoint、SDK 包名、CLI 命令）
  • 输入 Schema（JSON Schema 格式）
  • 输出结构（同样用 JSON Schema 描述）
  • 所依赖的模型（如 claude-3.5-sonnet、deepseek-r1、openclaw-0.2）
  • 状态行为（是否支持流式响应、中断、回滚）
  • 许可证兼容性（MIT？Apache 2.0？是否允许商用？）

协议不绑定任何框架，不规定实现逻辑，只约定文档格式：YAML front-matter + Markdown 正文。OpenClaw 官方仓库已合并相关 PR；DeepSeek-R1 的工具文档已完成重构；Anthropic 内部工具链团队确认，v4 API 文档将采用该格式。

为什么一个 Markdown 文件管用？

现在写 Agent，三件事总得重来一遍：怎么调用（HTTP？LangChain ToolWrapper？自研 SDK？）、能力怎么描述（一段模糊的 README 还是带约束的结构化定义？）、输入输出怎么校验（靠文档猜，还是 runtime panic 后 debug？）。

AGENTS.md 用 23 行 YAML + 纯文本就解决核心问题。例如：

name: "file_search"
model: "openclaw-0.2"
input: {"type":"object","properties":{"query":{"type":"string"}}}
output: {"type":"array","items":{"type":"object","properties":{"path":{"type":"string"}}}}
endpoint: "/v1/tools/file_search"

工具链能直接解析这段 YAML，生成 TypeScript 类型、Postman Collection、OpenAPI 3.1 spec，甚至自动注册为 LangGraph 节点——不用手写适配层。

技术价值：从“能跑”到“可编排”

统一元数据让跨模型协作成为现实。比如某个 Agent 在 AGENTS.md 中声明：

requires_stateful_session: true
supports_streaming: false

Orchestration 引擎（如龙虾的 orchestra CLI）就能避开在 Claude 流式上下文中调度它；多个 Agent 若都标注 input.output_format: "markdown_table"，前端渲染层就能复用同一解析器。

实测数据：LangChain + Llama-3-70B 工具链集成耗时从平均 4.2 小时降到 18 分钟，错误率下降 76%（统计自 GitHub Actions CI 日志）。

主流平台已在落地

  • OpenClaw v0.2.3 将 AGENTS.md 设为 agent publish 强制校验项，缺少 model 或 input 字段的提交会被拒绝
  • DeepSeek-R1 的 ds-toolkit 新增 --gen-agents-md 标志，一键导出合规元数据
  • Claude 团队在 HN 评论中确认，企业版 Agent Registry 将于 Q3 支持 AGENTS.md 自动抓取与验证

协议刻意避免厂商锁定：同一个 Agent 可同时声明支持 claude-3.5-sonnet 和 qwen2.5-72b，运行时按 token 成本、延迟、上下文长度动态选模。

👉 Binance · OKX · Gate.io · HTX · Bitget

你现在就能用

不用等标准组织。只需在项目根目录加一个 AGENTS.md，用 agents-md-validate CLI 校验（npm install -g agents-md-validate），它就会被 orchestra list --discover github.com/username/repo 发现。

龙虾生态已上线 yitb.com/agents-md，实时索引 GitHub 上所有含有效 AGENTS.md 的开源 Agent，并提供 Schema Diff 工具，对比不同版本间输入结构变化。目前已有 87 个生产级 Agent 接入，包括 Manus 的 PDF 解析器、Devin 的 Git 提交分析模块。

下一步：元数据只是开始

AGENTS.md 是起点，不是终点。社区已在讨论 AGENT_RUNTIME_PROTOCOL，目标是定义跨进程 Agent 通信的二进制 wire format（类似 gRPC over HTTP/2），解决 context 传递、token 配额协商、错误码映射等深层互操作问题。

对工程师来说，这意味着：不再为每个新 Agent 写胶水代码，而是专注业务逻辑本身。

马上行动：

  • 克隆 agents-md/template，5 分钟补全你的 Agent 元数据
  • 加入 HN thread #409221，参与 input/output Schema 扩展提案
  • 如果你维护模型服务，优先支持 /.well-known/agents.md 自发现路径

标准化不是消灭多样性，而是让多样性真正可组合。

相关阅读

返回首页