Agents.md 是什么？2025 年新 AI 编码代理标准的完整指南
- Aisha Washington
- 1小时前
- 讀畢需時 13 分鐘
What is Agents.md and why the 2025 AI coding agent standard matters
Agents.md is the emerging 2025 open standard for AI coding agents — a machine-readable manifest and protocol suite designed to make AI coding agents interoperable, auditable, and portable across platforms. In short, Agents.md is the specification layer that lets independent models, runtimes, tool adapters, and developer tooling speak a common language about what an agent can do, how it should behave, and which safeguards must be enforced.
Why should you care? Because standards determine what becomes composable in production. Without a shared protocol, developers will keep building bespoke scaffolding for agent behavior, increasing fragmentation, audit pain, and security risk. With Agents.md, teams can expect interoperable manifests, consistent telemetry, and a governance surface that fits into existing compliance tooling.
The announcement at Microsoft Build 2025 — the launch moment
Microsoft framed the move as an industry pivot: agents will be first-class components of software platforms, and their behavior must be open, discoverable, and governable. The Build presentation emphasized two themes: openness (vendors should interoperate) and responsibility (auditable policies and human control). That messaging anchored Agents.md as a shared starting point rather than a proprietary lock-in. Independent landscape analysis published earlier in 2025 had already called for such a coordination point to curb fragmentation and accelerate safe adoption.
Quick snapshot — what Agents.md aims to standardize
At a high level, Agents.md focuses on:
Agent rules files and manifests that declare identity, intents, permissions, and resources.
Interchange file formats (JSON/YAML schemas) to make definitions portable.
Agent lifecycle events and a standard runtime API surface for planners, executors and tool adapters.
Discovery protocols and registries for agent discovery and capability advertisement.
Why this matters: standardization enables tooling (marketplaces, registries), enterprise governance (policy enforcement, auditing), and community-built adapters. In other words, the spec aims to make AI coding agents reliable infrastructure components rather than isolated experiments.
Agents.md specification and core concepts — What the Agents.md standard defines
Agents.md is built around a small set of composable primitives meant to cover typical coding-agent needs while remaining extensible for vendor-specific features. At its heart are agent manifests (machine-readable declarations of intent and capabilities), an interchange schema for file formats, and a standardized runtime API for lifecycle and telemetry.
Agent manifest: a declarative file that describes an agent’s identity, capabilities, triggers, permissions and resource bindings (defined below at first use).
The design goals are clear: interoperability, human-in-the-loop safety hooks, and robust versioning/compatibility. These priorities reflect both community requests for portability and enterprise needs for auditable operations.
Core components: manifest, formats, APIs, and execution semantics
Agent manifest (rules file): declares identity, behavioral rules, capability interfaces, resource claims (e.g., repo read/write), and lifecycle policies.
File formats: canonical JSON Schema and optional YAML serialization, with extension hooks for vendor metadata.
Runtime API: evented lifecycle (create, plan, approve, execute, complete, audit), telemetry hooks, and action/plan interfaces for tool invocation.
Execution semantics: a planner generates steps or plans; an executor guarantees atomic application of safe actions (with sandboxing and rollback where required).
These elements are designed to make AI coding agents portable: the same manifest should be interpretable by different runtimes and verifiable by registries or governance tooling.
Design goals explained
Interoperability: Agents.md’s interchange schema and runtime API are intentionally minimal yet expressive, so third-party tool adapters can implement mapping layers without reengineering core behavior. This aligns with the community push described in landscape reports for a shared schema to reduce fragmentation.
Human-in-the-loop safety hooks: the spec mandates checkpoint events where humans can approve or veto actions; it also prescribes telemetry and signed manifests to ensure traceability for every decision.
Versioning and compatibility: manifests include schema versioning, backward compatibility rules, and migration guidance so registries can manage agent upgrades safely.
Key takeaway: Agents.md balances simplicity and extensibility — it defines the minimum necessary surface to make agents portable while enabling richer vendor extensions.
Agent manifest and rules files — structure and semantics
An agent manifest is the canonical artifact Agents.md defines. Typical fields include:
id and version — unique identity and semantic versioning.
displayName and description — human-friendly metadata.
capabilities — declared functions (e.g., code-modify, test-run, dependency-update).
triggers — event sources (e.g., PR opened, scheduled cron).
permissions — resource scopes (repo read, repo write, CI trigger).
safetyRules — policy hooks (humanApproval: required/optional, sandboxMode).
resources — external connectors or secrets needed (with references to secret managers).
telemetryConfig — what to emit and where.
Rules files (sometimes separate from manifests) express policy constraints: for example, “no direct write to main branch without human sign-off” or “only update dependencies within minor version bumps.” Agents.md supports both embedded policies and external rule references, favoring least-privilege and sandboxing by default. This design reduces blast radius and eases enterprise governance.
File formats and interchange — JSON/YAML schemas and extension points
Agents.md recommends:
A single canonical JSON Schema for machine verification and CI checks.
Optional YAML for readability in repositories and human review.
Extension fields prefixed with vendor metadata namespaces to avoid collisions (e.g., x-vendor: { ... }).
Schema evolution is addressed by explicit version fields and compatibility rules; runtimes must declare their supported schema versions in capability negotiation. Extension hooks let vendors expose features (e.g., custom sandbox modes) while registries validate base compliance. This balances human-readability and machine-verifiability, which both matter for developer adoption and automation.
Runtime & API surface for coding agents
The spec defines a small, event-driven API surface:
Lifecycle events: onRegister, onPlanRequested, onPlanProduced, onApprovalRequested, onExecuteStart, onExecuteComplete, onAuditLogCreated.
Plan/action interface: plan objects contain ordered steps, low-risk dry-run artifacts (diffs), and required approvals.
Telemetry hooks: standardized event schemas for actions, decisions, and errors.
Developer callbacks: webhooks for CI, VCS, and observability platforms.
Agents.md formalizes the planner-executor split: planners produce structured plans (human-readable plus machine-verified diffs) and executors apply them with sandbox guarantees. This prevents planners from implicitly triggering any system change without the executor's enforcement of permissions and rollback semantics.
Security, observability, and auditing baked into the spec
Security features include:
Signed manifests and signed run records to bind identity to actions.
Immutable run records and provenance chains for incident investigation.
Standard telemetry schemas to align logs across vendors.
Observability and auditing are first-class: every plan, approval, and executor action is recorded using a standard schema so governance tools can analyze behavior across agents. These controls make Agents.md attractive to regulated industries and risk-aware engineering teams.
Key takeaway: Agents.md is not just a manifest format — it’s a governance-aware API and telemetry contract intended to make agent actions auditable, portable and safe.
How Agents.md works — protocols, frameworks and agentic architecture
Agents.md operates at the intersection of protocol definitions and runtime patterns. It prescribes how agents are discovered, negotiated with, and executed inside an agentic architecture composed of planners, executors and tool adapters.
Agent discovery: the process by which hosts find agents and evaluate their suitability. Capability negotiation: runtime exchange confirming an agent can safely perform requested actions.
This section draws on community playbooks for agent protocols and practical frameworks for agentic coding workflows.
Discovery and capability negotiation
Discovery typically happens through:
Local registries (repo-level agent manifests).
Centralized agent registries or marketplaces.
In-band capability advertising (agents announce runtime capabilities via a metadata handshake).
Capability negotiation uses signed claims and scope-limited tokens. Hosts must validate an agent’s rights (proof-of-rights) for requested resources before handing over secrets or permissions. Agents.md recommends short-lived tokens and cryptographic attestations so hosts can make decisions based on verifiable claims.
Security considerations are central: discovery should be permissioned, and capability negotiation should reject agents that request privileges beyond their manifest. This reduces accidental over-privilege during automation and prevents supply-chain abuse.
Planner-executor pattern in Agents.md
Agents.md codifies a planner-executor separation:
Planner: a low-privilege component (often model-backed) that ingests issues or triggers, queries context (tests, code), and emits a structured plan: step list, diffs, tests to run, expected side effects.
Executor: a permissioned runtime that interprets the plan, interacts with tool adapters (VCS, CI), and enforces security policies (sandboxing, approvals, rollback).
Planner outputs are intentionally deterministic artifacts (diffs and test plans), not opaque instructions. Executors must validate the plan against the manifest and enforce least-privilege. Typical planner outputs include:
Ordered step lists (e.g., create branch, modify files, run tests).
Patch/diff artifacts that can be reviewed or applied atomically.
Test harness invocations and expected success criteria.
This pattern reduces risk: because the executor validates and enforces, planners cannot bypass permissions even if compromised. See community playbooks for practical examples of planner-executor pipelines in coding workflows.
Tool adapters and sandboxing for coding agents
Agents.md defines standard adapter interfaces for common automation touchpoints:
VCS adapters: create branches, push commits, open pull requests.
CI adapters: trigger pipelines, fetch artifacts, report statuses.
Build and package managers: run builds, publish packages under policy.
Secret managers: scoped secret retrieval with audit hooks.
Sandboxing modes are explicit in manifests: dry-run only, restricted sandbox (read-only on repos), and full-run with explicit human approval. Sandboxing reduces supply-chain risk by default and allows safe evaluation in staging. Tool adapters implement the translation between high-level plan steps and vendor-specific APIs, but must honor the manifest’s permission model.
Telemetry, fault handling, and rollback strategies
Agents.md prescribes a telemetry schema that captures:
Plan provenance: which agent made the plan, which model version, and what data was used.
Execution traces: step start/stop times, success/failure status, artifacts produced.
Approval events and human decisions.
For faults, the spec recommends:
Graceful degradation: fail fast and mark plans as aborted with clear reasons.
Automatic rollback for partial failures, with a “safe state” definition embedded in manifests.
Human-in-the-loop checkpoints for high-risk operations so rollback or mitigation can be manual if needed.
These measures enable reliable incident analysis and facilitate compliance reporting. They’re also practical: teams adopting Agents.md saw reduced incident time-to-resolution because audit trails made root-cause analysis faster in early pilots.
Key takeaway: Agents.md formalizes the interactions between discovery, planner, executor and adapters, enabling secure, auditable automated coding workflows.
Market adoption, trends and use cases for Agents.md in 2025
Agents.md enters an ecosystem that’s already seeing rapid uptake of AI agents. Index.dev and other aggregators reported early signals of agent usage growth in developer tooling and CI pipelines in 2025, and pragmatic analyses highlight accelerating interest in standards to manage fragmentation.
Quantitative adoption signals (downloads, integrations, active agents)
Early KPIs to watch:
Number of agent manifests published in public registries.
Active agents per repository (agents that executed at least once in the past 30 days).
CI pipelines with agent-triggered runs.
Marketplace downloads and adapter installations.
Dashboards at index.dev and pragmatic community trackers showed upward trends in Q1–Q2 2025: rising downloads for agent adapters, growth in agent-enabled PRs, and more CI workflows invoking agents. These are early but meaningful adoption signals that inform enterprise decisions.
Developer productivity and workflow improvements
Common developer use cases where Agents.md helps:
Automated issue triage: agents classify and assign issues based on manifest rules and repo heuristics.
Automated code generation and PR creation: agents produce small refactor PRs (with tests) and submit them for review.
Test creation and maintenance: agents generate or update unit tests based on changed code or behavior.
Automated refactoring and dependency updates: agents propose minor version upgrades, run tests, and open PRs.
CI automation: agents triage failing builds, create rollback PRs, or trigger patch releases.
Concrete metrics teams can expect include reduced PR lead time, faster bug resolution, and fewer manual merges. Index.dev’s reports indicate agent-enabled workflows can lower routine PR cycle time by measurable margins in pilot environments, especially for dependency maintenance and test scaffolding.
Insight: Agent productivity gains are highest for repetitive, well-scoped tasks (dependency bumps, test scaffolding). Complex architectural changes still need human architects.
Emerging verticals and enterprise scenarios
Early vertical adopters include:
Platform engineering: agents manage internal libraries, automate upgrades, and maintain infra-as-code.
Fintech: careful manifests and signed provenance make agents attractive for regulatory compliance when automating customer-facing code.
Large open-source projects: agents handle triage, apply canonical formatting, and manage dependency hygiene across many repos.
Agents.md’s registry and marketplace model enables cross-vendor portability: enterprises can select agents from vendors, verify manifests, and trust a common telemetry schema. This supports open agentic web scenarios where independent agents cooperate across services while preserving governance boundaries.
Key takeaway: Agents.md accelerates an open ecosystem by standardizing manifests and telemetry, and early signals show measurable developer productivity improvements for routine tasks.
Challenges, standardization debates, and policy for Agents.md
Despite clear benefits, Agents.md adoption raises hard questions: fragmentation risk, supply-chain security, and governance. Thought leaders and enterprise guides have already framed these debates and suggested paths forward.
File fragmentation and format interoperability
Too many proprietary manifest formats would defeat Agents.md’s purpose. The spec counters this with a canonical JSON Schema, extension namespaces and migration guidance. Migration paths for legacy agent definitions include automated converters and adapter shims; registries can provide compatibility profiles to ease adoption. Still, community governance is essential: consistent validation tooling and certification programs will reduce fragmentation risk.
Mitigation strategy: adopt Agents.md’s canonical schema, run automated scans for non-compliant manifests, and use conversion tools in CI to normalize legacy formats.
Safety, supply-chain and attacker surface
Autonomous code-writing agents broaden the attack surface. Threat scenarios include malicious manifests, compromised tool adapters, or agents that introduce vulnerable dependencies. Recommended hardening steps include:
Signed manifests and signed run records to verify origin and integrity.
Provenance tracking for dependencies and code changes.
Scoped secrets and short-lived tokens.
Sandbox-only modes for untrusted agents or initial evaluations.
These measures are already seen in enterprise guidance and the IBM analysis on expectations vs. reality for AI agents.
Governance, auditability and legal compliance
Agents.md supports governance with manifest signing, immutable run records and telemetry schemas that feed into existing audit systems. For regulated environments, teams should:
Enforce policy profiles for manifests (approved capabilities, allowed resource scopes).
Keep signed trails of approvals and rollbacks.
Map agent activities to compliance controls during audits.
However, legal questions remain: who is accountable for agent-created code? Agents.md helps by making actions auditable, but organizations must define human accountability and operator control in their contracts and internal policies.
Standards bodies, community governance, and next steps
Sustainable stewardship is crucial. Likely participants in Agents.md governance include cloud vendors, open-source foundations, standards bodies and community working groups. Roadmap priorities:
Reference implementations and certified runtimes.
Compliance profiles for regulated verticals.
Certification programs and agent registries that verify manifest compliance.
Community-led working groups should prioritize compatibility tests, security profiles and a public test suite. These concrete deliverables will drive convergence and confidence in the standard.
Key takeaway: Agents.md addresses many governance and security needs, but adoption must be coupled with certification, registries, and legal clarity to fully mitigate risk.
Developer adoption checklist — implementing Agents.md in your engineering workflows
If your team is ready to adopt Agents.md, follow a practical rollout path that balances learning with risk control. Community-guides and practitioner reports emphasize staged pilots and clear observability baselines.
Quick-start checklist
评估符合 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 编码代理 引入了基础互操作层 — 它在开放性与治理之间取得平衡，并使开放代理网络成为现实。它提供清单、运行时契约、遥测标准和安全原语，解决了许多早期采用痛点。
可操作的后续步骤：
在低风险仓库中使用沙箱代理和严格审批门槛运行 Agents.md 试点。
默认采用清单签名、可观测性和回滚策略。
参与标准讨论和工作组，以影响认证、注册表和参考实现。
预计生态系统将在 2025–2026 年通过认证程序、公共代理注册表和基于 Agents.md 构建的更丰富治理工具而成熟。现在启动试点的组织将在运营经验和塑造标准轨迹方面领先一步。
最终要点： Agents.md 不仅仅是一种文件格式 — 它是 AI 代理如何安全且高效地参与软件工程的协调结构。尽早对齐、谨慎试点，并在标准从规范走向主流基础设施的过程中帮助塑造它。
