Agents.md 是什么？2025 年新 AI 编码代理标准的完整指南
- Aisha Washington
- 6月7日
- 讀畢需時 15 分鐘
已更新：6月18日
什么是 Agents.md，以及为什么 2025 AI 编程智能体标准至关重要
Agents.md 是新兴的 2025 年 AI coding agents 开放标准 —— 这是一个机器可读的清单和协议套件，旨在使 AI 编程智能体在不同平台间具备互操作性、可审计性和可移植性。简而言之，Agents.md 是一个规范层，它让独立的模型、运行时、工具适配器和开发者工具能够就智能体的能力、行为方式以及必须执行的安全防护措施使用统一的语言进行交流。
为什么要关注它？因为标准决定了生产环境中的可组合性。如果没有共享协议，开发者将不得不持续为智能体行为构建定制化的脚手架，从而增加碎片化程度、审计难度和安全风险。通过 Agents.md，团队可以获得互操作清单、一致的遥测数据以及能够融入现有合规工具的治理界面。
Microsoft Build 2025 上的发布 —— 启动时刻
Microsoft 将此举定性为行业转型：智能体（agents）将成为软件平台的一等公民，其行为必须是公开、可发现且可治理的。Build 大会的演讲强调了两个主题：开放性（供应商应实现互操作）和责任感（可审计的策略和人工控制）。这一理念使 Agents.md 成为一个共享的起点，而非私有的技术锁定。作为一个共享的起点，而不是私有的技术锁定。发布于 2025 年初 的独立行业分析报告已经呼吁建立这样一个协调点，以遏制碎片化并加速安全采用。
快速概览 —— Agents.md 旨在标准化的内容
在宏观层面，Agents.md 专注于：
声明身份、意图、权限和资源的智能体规则文件与清单（manifests）。
使定义具备可移植性的交换文件格式（JSON/YAML 架构）。
智能体生命周期事件，以及面向规划器（planners）、执行器（executors）和工具适配器（tool adapters）的标准运行时 API 界面。
用于智能体发现和能力广告的发现协议与注册表。
为什么这很重要：标准化使工具链（市场、注册表）、企业治理（策略执行、审计）以及社区构建的适配器成为可能。换句话说，该规范旨在使 AI coding agents 成为可靠的基础设施组件，而非孤立的实验。
Agents.md 规范与核心概念 —— Agents.md 标准定义的内容
Agents.md 围绕一小组可组合的原语构建，旨在覆盖典型的编码智能体需求，同时保持对厂商特定功能的可扩展性。其核心是智能体清单（机器可读的意图与能力声明）、文件格式的交换模式，以及用于生命周期和遥测的标准运行时 API。
智能体清单（Agent manifest）：一个声明式文件，描述智能体的身份、能力、触发器、权限和资源绑定（在首次使用时定义如下）。
设计目标非常明确：互操作性、人类在环（human-in-the-loop）安全钩子，以及稳健的版本控制/兼容性。这些优先级既反映了社区对可移植性的需求，也反映了企业对可审计操作的需求。
核心组件：manifest、格式、API 和执行语义
Agent manifest（规则文件）：声明身份、行为规则、能力接口、资源声明（例如 repo 读/写）以及生命周期策略。
文件格式：规范的 JSON Schema 和可选的 YAML 序列化，带有用于供应商元数据的扩展钩子。
运行时 API：事件化生命周期（创建、规划、批准、执行、完成、审计）、遥测钩子，以及用于工具调用的 action/plan 接口。
执行语义：planner 生成步骤或计划；executor 保证安全操作的原子化应用（在需要时提供沙箱和回滚）。
这些元素旨在使 AI 编程代理便携性：相同的 manifest 应当能被不同的运行时解释，并可由注册表或治理工具进行验证。
设计目标详解
互操作性：Agents.md 的交换模式和运行时 API 刻意保持极简且富有表现力，因此第三方工具适配器可以实现映射层，而无需重新设计核心行为。这与行业报告中描述的、旨在减少碎片化的共享模式社区推动方向一致。
人工在环（Human-in-the-loop）安全钩子：规范强制要求设立检查点事件，以便人工批准或否决操作；它还规定了遥测和签名 manifest，以确保每项决策的可追溯性。
版本控制与兼容性：manifest 包含模式版本控制、向后兼容规则和迁移指南，以便注册表能够安全地管理智能体升级。
核心要点：Agents.md 平衡了简洁性与可扩展性 —— 它定义了实现智能体便携性所需的最小必要界面，同时支持更丰富的供应商扩展。
智能体 manifest 和规则文件 —— 结构与语义
智能体 manifest 是 Agents.md 定义的规范伪像。典型字段包括：
id 和 version — 唯一标识与语义化版本控制。
displayName 和 description — 用户友好的元数据。
capabilities — 声明的功能（例如：code-modify、test-run、dependency-update）。
triggers — 事件源（例如：PR opened、scheduled cron）。
permissions — 资源权限范围（repo read、repo write、CI trigger）。
safetyRules — 策略钩子（humanApproval: required/optional, sandboxMode）。
resources — 所需的外部连接器或机密信息（包含对机密管理器的引用）。
telemetryConfig — 发送什么数据以及发送到哪里。
规则文件（有时与 manifest 分离）用于表达策略约束：例如，“未经人工批准不得直接写入 main 分支”或“仅允许在次要版本更新范围内更新依赖项”。Agents.md 支持嵌入式策略和外部规则引用，默认遵循最小特权原则和沙箱机制。这种设计缩小了爆炸半径，并简化了企业治理。
文件格式与交换 — JSON/YAML 架构和扩展点
Agents.md 建议：
使用单一规范的 JSON Schema 进行机器验证和 CI 检查。
在仓库和人工评审中使用可选的 YAML 以提高可读性。
扩展字段应带有供应商元数据命名空间前缀，以避免冲突（例如 `x-vendor: { ... }`）。
架构演进通过显式的版本字段和兼容性规则来解决；运行时必须在能力协商中声明其支持的架构版本。扩展钩子允许供应商公开特性（例如自定义沙箱模式），同时注册表验证基础合规性。这平衡了人类可读性和机器可验证性，两者对于开发者采用和自动化都至关重要。
代码代理的运行时与 API 表面
该规范定义了一个小型的事件驱动 API 表面：
生命周期事件：onRegister, onPlanRequested, onPlanProduced, onApprovalRequested, onExecuteStart, onExecuteComplete, onAuditLogCreated。
计划/动作接口：plan 对象包含有序步骤、低风险的演练产物（diffs）以及所需的审批。
遥测钩子：针对动作、决策和错误的标准化事件架构。
开发者回调：用于 CI、VCS 和可观测性平台的 webhooks。
Agents.md 正式确定了规划器-执行器（planner-executor）的分离：规划器生成结构化计划（包含人类可读内容及机器验证的 diff），而执行器在沙箱保障下应用这些计划。这防止了规划器在没有执行器强制执行权限和回滚语义的情况下，隐式触发任何系统变更。
规范中内置了安全性、可观测性和审计功能
安全特性包括：
通过签名清单和签名运行记录将身份与操作绑定。
用于事件调查的不可变运行记录和溯源链。
用于对齐不同厂商日志的标准遥测模式。
可观测性和审计是头等公民：每个计划、审批和执行器操作都使用标准模式记录，以便治理工具可以分析跨 agent 的行为。这些控制措施使 Agents.md 对受监管行业和具有风险意识的工程团队极具吸引力。
核心结论： Agents.md 不仅仅是一种清单格式 —— 它是一个具备治理意识的 API 和遥测合约，旨在使智能体（agent）的行为可审计、可移植且安全。
Agents.md 的工作原理 —— 协议、框架与智能体架构
Agents.md 运行在协议定义与运行时模式的交汇处。它规定了在由规划器（planners）、执行器（executors）和工具适配器（tool adapters）组成的智能体架构中，如何发现智能体、与其协商并执行。
智能体发现：宿主找到智能体并评估其适用性的过程。能力协商：确认智能体可以安全执行请求操作的运行时交换。
本节参考了智能体协议的社区指南以及用于 智能体编程工作流 的实用框架。
发现与能力协商
发现通常通过以下方式进行：
本地注册表（仓库级 agent 清单）。
中心化 agent 注册表或市场。
带内能力广告（agent 通过元数据握手宣告运行时能力）。
能力协商使用签名声明和范围受限的 token。Host 必须在移交机密或权限之前，验证 agent 对所请求资源的权利（权利证明）。Agents.md 建议使用短效 token 和加密证明，以便 host 能够基于可验证的声明做出决策。
安全考量是核心：发现过程应获得授权，且能力协商应拒绝请求超出其清单权限的 agent。这减少了自动化过程中的意外过度授权，并防止供应链滥用。
Agents.md 中的 Planner-executor 模式
Agents.md 将 planner-executor 分离进行了规范化：
Planner：一个低权限组件（通常由模型支持），负责摄取 issue 或触发器，查询上下文（测试、代码），并输出结构化计划：步骤列表、diff、要运行的测试、预期的副作用。
Executor：一个受许可的运行时，负责解释计划、与工具适配器（VCS、CI）交互，并执行安全策略（沙箱、审批、回滚）。
Planner 的输出是有意设计的确定性产物（diff 和测试计划），而非不透明的指令。Executor 必须根据 manifest 验证计划并执行最小权限原则。典型的 Planner 输出包括：
有序的步骤列表（例如：创建分支、修改文件、运行测试）。
可以被审查或原子化应用的 Patch/diff 产物。
测试框架调用及预期的成功标准。
这种模式降低了风险：因为 Executor 会进行验证和强制执行，即使 Planner 受到攻击也无法绕过权限。请参阅社区剧本，了解 remio 编码工作流中 Planner-Executor 流水的实际案例。编码工作流。
针对编码智能体的工具适配器和沙箱机制
Agents.md 定义了常见自动化触点的标准适配器接口：
VCS 适配器：创建分支、推送提交、开启 pull requests。
CI 适配器：触发流水线、获取产物、报告状态。
构建与包管理器：运行构建、根据策略发布包。
Secret 管理器：带有审计钩子的作用域内机密检索。
沙箱模式在 manifest 中明确定义：仅 dry-run、受限沙箱（对仓库只读）以及需要人工明确批准的 full-run。沙箱默认降低了供应链风险，并允许在 staging 环境中进行安全评估。工具适配器实现高级计划步骤与特定厂商 API 之间的转换，但必须遵守 manifest 的权限模型。
遥测、故障处理与回滚策略
Agents.md 规定了捕获以下内容的遥测架构：
计划溯源：哪个 agent 制定了计划、哪个模型版本以及使用了哪些数据。
执行追踪：步骤开始/停止时间、成功/失败状态、产出的产物。
审批事件和人工决策。
针对故障，规范建议：
优雅降级：快速失败并将计划标记为已中止，并附上明确原因。
针对部分失败的自动回滚，并在 manifest 中嵌入“安全状态”定义。
针对高风险操作的 Human-in-the-loop 检查点，以便在需要时可以进行人工回滚或缓解。
这些措施实现了可靠的事件分析并促进了合规性报告。它们也非常实用：采用 Agents.md 的团队在早期试点中发现，由于审计追踪加快了根本原因分析，事件解决时间有所缩短。
核心要点： Agents.md 正式化了 discovery、planner、executor 和 adapters 之间的交互，实现了安全、可审计的自动化 coding workflows.
2025 年 Agents.md 的市场采用、趋势与用例
Agents.md 进入了一个已经快速普及 AI agents 的生态系统。Index.dev 和其他聚合平台报告了 2025 年 开发者工具 和 CI 流水线中智能体使用增长的早期信号，务实的分析强调了人们对管理碎片化标准的兴趣正在加速。
定量采用信号（下载量、集成量、活跃智能体）
值得关注的早期关键绩效指标（KPI）：
在公共注册表中发布的智能体清单（manifests）数量。
每个代码库的活跃代理（在过去 30 天内至少执行过一次的代理）。
由代理触发运行的 CI 流水线。
Marketplace 下载量和适配器安装量。
位于 index.dev 的仪表板和务实的社区追踪器显示，2025 年第一季度至第二季度呈上升趋势：代理适配器的下载量增加，启用代理的 PR 增长，以及更多调用代理的 CI 工作流。这些是早期但有意义的采用信号，可为企业决策提供参考。
开发者生产力和工作流改进
Agents.md 提供帮助的常见开发者用例：
自动问题分类：代理根据清单规则和代码库启发式方法对 issue 进行分类和指派。
自动代码生成和 PR 创建：代理生成小型重构 PR（包含测试）并提交以供评审。
测试创建与维护：agent 根据更改的代码或行为生成或更新单元测试。
自动化重构与依赖更新：agent 建议次要版本升级、运行测试并提交 PR。
CI 自动化：agent 对失败的构建进行分类、创建回滚 PR 或触发补丁版本发布。
团队可以预期的具体指标包括缩短 PR 交付周期、加快错误修复速度以及减少手动合并。Index.dev 的报告指出，在试点环境中，启用 agent 的工作流可以显著降低常规 PR 周期时间，尤其是在依赖维护和测试脚手架方面。
洞察：Agent 的生产力提升在重复性、范围明确的任务（依赖升级、测试脚手架）中最为显著。复杂的架构变更仍需要人类架构师。
新兴垂直领域与企业场景
早期垂直领域采用者包括：
平台工程：agent 管理内部库、自动化升级并维护 infra-as-code。
金融科技：在自动化面向客户的代码时，严谨的清单和签名出处使 agent 在满足监管合规方面具有吸引力。
大型开源项目：智能体处理分类、应用规范格式，并管理多个仓库的依赖项健康。
Agents.md 的 注册表和市场模型实现了跨供应商的可移植性：企业可以从供应商中选择智能体、验证清单，并信任通用的遥测模式。这支持了开放的智能体 Web 场景，使独立智能体在保持治理边界的同时跨服务协作。
核心结论： Agents.md 通过标准化清单和遥测加速了开放生态系统的发展，早期信号显示，在处理常规任务时，开发者生产力有了显著提升。
Agents.md 的挑战、标准化辩论和政策
尽管优势明显，Agents.md 的采用也引发了一些棘手问题：碎片化风险、供应链安全和治理。思想领袖和企业指南已经阐述了这些辩论并提出了前进路径。
文件碎片化与格式互操作性
过多的私有清单格式会违背 Agents.md 的初衷。该规范通过规范的 JSON Schema、扩展命名空间和迁移指南来应对这一问题。旧版智能体定义的迁移路径包括自动化转换器和适配器层；注册表可以提供兼容性配置文件以简化采用。尽管如此，社区治理仍然至关重要：一致的验证工具和认证计划将降低碎片化风险。
缓解策略：采用 Agents.md 的规范模式，运行针对非合规清单的自动化扫描，并在 CI 中使用转换工具来规范化旧版格式。
安全、供应链与攻击面
自主代码编写智能体扩大了攻击面。威胁场景包括恶意清单、被篡改的工具适配器，或引入漏洞依赖的智能体。建议的加固步骤包括：
签名清单和签名运行记录，以验证来源和完整性。
针对依赖项和代码更改的来源追踪。
作用域限定的机密信息和短期令牌。
针对不可信智能体或初始评估的仅沙箱模式。
这些措施在企业指南以及IBM analysis关于 AI 智能体预期与现实的分析中已有体现。
治理、可审计性与法律合规
Agents.md 通过清单签名、不可变运行记录和接入现有审计系统的遥测模式来支持治理。对于受监管的环境，团队应当：
对清单强制执行策略配置文件（已批准的能力、允许的资源范围）。
保留已签署的审批和回滚追踪记录。
在审计期间将智能体活动映射到合规控制措施。
然而，法律问题依然存在：谁该为智能体创建的代码负责？Agents.md 通过使操作可审计来提供帮助，但组织必须在其合同和内部政策中明确人类责任和操作员控制。
标准机构、社区治理及后续步骤
可持续的管理至关重要。Agents.md 治理的潜在参与者包括云厂商、开源基金会、标准组织和社区工作组。路线图优先级：
参考实现和经过认证的运行时。
针对受监管垂直行业的合规配置文件。
验证清单合规性的认证计划和智能体注册表。
社区主导的工作组应优先考虑兼容性测试、安全配置文件和公共测试套件。这些具体的交付成果将推动标准的统一并增强对标准的信心。
核心要点：Agents.md 解决了许多治理和安全需求，但其采用必须与认证、注册表和法律明确性相结合，以充分降低风险。
开发者采用清单 —— 在工程工作流中实施 Agents.md
如果您的团队准备采用 Agents.md，请遵循平衡学习与风险控制的实际推广路径。社区指南和从业者报告强调分阶段试点和明确的可观测性基准。
快速启动清单
评估符合 Agents.md 的工具：
选择支持规范 JSON Schema 的运行时和注册表。
选择映射到您的 VCS、CI 和密钥管理器的供应商适配器。
运行受限试点：
选择低风险仓库（文档、基础设施脚本）。
在沙箱或 演练模式。
定义安全策略：
清单签名要求、最低审批门槛和审计保留期。
集成遥测和可观测性：
配置遥测接收器以将代理运行与事件和 CI 事件关联起来。
衡量并迭代：
跟踪成功指标和开发者反馈；在有信心时扩大范围。
可操作：运行 Agents.md 试点，更新文档仓库或在小型服务上升级依赖，作为您的首个真实世界实验。
试点清单 — 如何运行安全、可衡量的试点
定义范围：单一仓库、已定义的代理和明确的成功标准（例如，90% 的自动 PR 通过测试）。
选择低风险仓库：文档、基础设施或实验性服务。
建立遥测基线：PR 前置时间、失败率和误报。
安排人工审查窗口：要求人工批准对受保护分支的写入。
限时运行：4–8 周后评估并调整策略。
来自 从业者的参考建议采用这种有节制 的方法，以减少意外并在更广泛推广前建立信心。
集成 — 关键适配器和自动化触点
从这些适配器开始：
VCS 适配器（分支、PR 创建）。
CI 适配器（触发运行、读取测试结果）。
密钥管理器适配器（仅限范围访问）。
可观测性和事件适配器（将遥测转发到 SIEM 或日志）。
优先集成测试工具和事件警报，以便代理操作对 SRE 和安全团队可见。
组织就绪 — 角色、培训和策略执行
创建以下角色：
代理负责人：负责代理清单和策略对齐。
安全审查员：验证清单权限和沙箱模式。
SRE 集成负责人：确保遥测和事件工作流已连接。
培训主题：
清单审查和威胁建模。
回滚程序和代理操作的事件演练。
监控代理生命周期事件和读取来源轨迹。
要跟踪的关键指标：PR 前置时间、误报变更（人工回滚）、代理成功率和开发者满意度。这些将帮助量化 ROI 并指导安全扩展。
关键要点：从小处着手，全面监控，并定义清晰的所有权以安全扩展 Agents.md 采用。
FAQ — 关于 Agents.md 和 AI 编码代理标准的常见问题
Q: Agents.md 究竟是什么？ A: Agents.md 是 AI 编码代理的标准化清单和协议规范，用于在平台间实现可互操作、可审计的代理行为。
Q: Agents.md 是否绑定到单一供应商或模型？ A: 否 — 该规范有意保持供应商无关，以支持多个 LLM、运行时和工具提供商之间的跨供应商互操作性。行业指南强调这一目标。
Q: Agents.md 会取代现有代理框架吗？ A: 不会 — 它通过提供通用交换和治理层来补充现有框架。现有框架可以采用 Agents.md 清单以与其他工具和注册表互操作。
Q: Agents.md 要求哪些安全功能？ A: 该规范推荐清单签名、标准化遥测、人工审批门槛以及包括仅沙箱选项在内的最小权限运行时模式。这些功能旨在支持可审计性和供应链保护。
Q: 我的团队如何立即开始使用 Agents.md？ A: 从范围限定的试点开始：将合规清单集成到暂存工作流中，启用沙箱/演练模式，并采用遥测和回滚策略。实用指南和试点清单详细说明了这些步骤。
Q: 真实世界案例研究将出现在哪里？ A: 早期案例研究 可能会随着 2025 年采用增长而在平台提供商博客、社区工作组和会议报告中出现。请关注 Microsoft Build 后续和独立景观跟踪器以获取新兴示例。
结论 — 可操作洞见、后续步骤和 Agents.md 的未来
Agents.md 为 2025 年的 AI 编码代理remio 引入了基础互操作层 — 它在开放性与治理之间取得平衡，并使开放代理网络成为现实。它提供清单、运行时契约、遥测标准和安全原语，解决了许多早期采用痛点。
可操作的后续步骤：
在低风险仓库中使用沙箱代理和严格审批门槛运行 Agents.md 试点。
默认采用清单签名、可观测性和回滚策略。
参与标准讨论和工作组，以影响认证、注册表和参考实现。
预计生态系统将在 2025–2026 年通过认证程序、公共代理注册表和基于 Agents.md 构建的更丰富治理工具而成熟。现在启动试点的组织将在运营经验和塑造标准轨迹方面领先一步。
最终要点：Agents.md 不仅仅是一种文件格式 — 它是 AI 代理如何安全且高效地参与软件工程的协调结构。尽早对齐、谨慎试点，并在标准从规范走向主流基础设施的过程中帮助塑造它。
