What is Microsoft APM (Agent Package Manager)?
Microsoft APM is a dependency manager for AI agent context. How apm.yml, lockfiles and policy work, and what APM leaves to your data layer.
APM, Microsoft’s Agent Package Manager, is an open-source dependency manager for AI agent context. One apm.yml declares the instructions, skills, prompts and MCP servers your repo needs, and apm install deploys them to nine harnesses including GitHub Copilot, Claude Code, Cursor and Codex. It packages the files that configure agents. The half it leaves alone, what your data means and who is allowed to act on it, is the enterprise context layer, where Atlan works.
The distinction matters more than it sounds. APM guarantees that every engineer on your team boots an agent with byte-identical instructions, verified by a content hash in a lockfile. It says nothing about whether those instructions are correct for your business, and Microsoft is unusually direct about that boundary in its own documentation. Teams running agent harnesses at any scale need both halves: reproducible configuration, and a trustworthy account of the data underneath.
- Built by Microsoft, MIT-licensed, and developed in the open at
github.com/microsoft/apm - Manages eight primitive types: instructions, skills, prompts, agents, hooks, commands, plugins and MCP servers
- Borrows the manifest-plus-lockfile model from
npm,pipandcargo - Ships a policy engine,
apm-policy.yml, that organizations enforce at install time - Still pre-1.0 at v0.31.0, releasing roughly weekly
| Field | Value |
|---|---|
| What it is | A build-time dependency manager for the files that configure AI coding agents |
| Built by | Microsoft, open source under the microsoft GitHub org |
| License | MIT |
| Latest version | v0.31.0, released 15 September 2026 |
| Harnesses supported | Nine by default, plus two explicit CLI targets |
| Primitives managed | Instructions, skills, prompts, agents, hooks, commands, plugins, MCP servers |
| Adoption | 3,822 stars, 361 forks on GitHub |
| What Microsoft says it is not | A runtime, an LLM gateway, a fine-tuning tool, or a marketplace |
| What it does not cover | Whether the context it ships is correct about your business |
What does Microsoft’s Agent Package Manager actually do?
APM is a build-time dependency manager for the files that configure AI coding agents, and it does not try to be more than that. You write one manifest listing the context your repo needs, run one command, and every supported agent on every developer machine ends up with the same setup. The official APM documentation (Microsoft, 2026) describes it as “a dependency manager for AI agent context, skills, prompts, instructions, hooks, MCP servers, with a lockfile, a policy engine, and one install gesture across every major harness.”
The problem it was built for is mundane and universally recognized. Four engineers on a team run four different agents. Each hand-copies a coding-standards file into a different directory with a different name. Within a sprint the four files have diverged, nobody knows which is authoritative, and a new joiner gets whichever version they were pointed at. That drift is the same failure agent sprawl produces at the organizational level, expressed one repo at a time.
APM’s answer is the oldest one in software distribution. According to Microsoft’s APM documentation (2026), “APM borrows the manifest-plus-lockfile shape from npm, pip, and cargo” and applies it to agent configuration. Declare, resolve, pin, reproduce. The interesting part is not the mechanism, which is forty years old, but the admission underneath it: the files that tell an agent how to behave have become infrastructure, and infrastructure needs versioning. That is the same conclusion harness engineering reaches from the practitioner side.
Is APM the same as Application Performance Monitoring?
No, and the collision is worth naming early because it wastes a lot of search time. In most of the industry, “APM” means Application Performance Monitoring, the observability category Datadog, New Relic and Dynatrace compete in. It has also meant Atom Package Manager and Advanced Package Manager. Microsoft’s APM shares the acronym and nothing else: one watches production systems, the other installs configuration files. If you arrived here looking for latency traces, you want AI agent observability instead.
How does apm.yml work?
A single manifest declares every agent primitive a repo needs, and apm install resolves it into each harness’s native file layout. The syntax is short enough to read in one pass:
name: your-project
version: 1.0.0
dependencies:
apm:
- anthropics/skills/skills/frontend-design
- github/awesome-copilot/plugins/context-engineering
- microsoft/apm-sample-package#v1.0.0
mcp:
- name: io.github.github/github-mcp-server
transport: httpRun apm install against that file and APM resolves the full dependency tree, including transitive dependencies, then writes each primitive into the directory its target harness expects. Copilot instructions land where Copilot reads them; Claude Code skills land where Claude Code reads them. The developer does not need to know either convention, which is the whole point of context portability.
The reproducibility guarantee lives in apm.lock.yaml. Microsoft’s documentation states that the lockfile “pins every resolved package to an exact source ref and content hash, so two developers running apm install against the same lockfile get byte-identical context.” That is a stronger promise than most teams currently get from their own internal context repository for AI agents, and it makes context versioning for AI agents a solved problem at the file level rather than a convention people try to remember.
The commands you will reach for most are apm install, apm update, apm audit, apm compile, apm publish and apm policy. The CLI is wider than that, with apm init, apm run, apm pack and apm prune alongside them, but those six cover the lifecycle from consumption through authoring to organizational enforcement.
| Primitive | What it is | Where it lands |
|---|---|---|
| Instructions | Repository-scoped guardrails and coding standards | Harness instruction directory |
| Skills | Reusable, model-invocable capabilities | Harness skills directory |
| Prompts | Slash commands and saved prompts | Harness prompt directory |
| Agents | Specialized personas with distinct scope and tools | Harness agent config |
| Hooks | Lifecycle handlers for tool calls | Harness hook config |
| Commands | Custom CLI-style commands in the agent UI | Harness command config |
| Plugins | Bundled collections of the above | Plugin host directory |
| MCP servers | External tools reached over the Model Context Protocol | Harness MCP config |
Eight primitives is a useful inventory in its own right. It is a reasonable checklist of what an AI agent primitive actually is in 2026, arrived at by a team that had to ship a working implementation rather than a taxonomy.
Which harnesses does APM support?
Nine by default: GitHub Copilot, Claude Code, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf and Kiro. Antigravity and Hermes are supported as explicit CLI targets. The breadth is the product; a manifest that only worked with one agent would be a config file, not a package manager. Teams weighing which of these to standardize on should start from agent harness versus agent framework, because the two get conflated constantly and they fail differently.
How does APM handle security and policy?
APM treats agent instruction files as a build-time supply chain and gates them before they reach disk. The reasoning behind that choice is the sharpest sentence in the entire project. According to Microsoft’s APM security model (2026), “There is no ‘execution step.’ File presence IS execution.”
That is not rhetoric. The moment a skill or instruction file lands in a watched directory, an IDE agent may already be reading it and acting on it. There is no compile, no explicit run, no moment where a human approves the content. So APM moves the gate earlier, to install time. Every install scans for hidden Unicode that can steer agent behavior invisibly: tag characters in the U+E0001 to U+E007F range, bidirectional overrides, zero-width joiners and variation selectors. Critical findings block deployment; the package stays cached for inspection, and --force is the only override. Anyone who has looked at prompt injection attacks on AI agents will recognize exactly which class of attack this closes.
Integrity is handled with SHA-256 hashes computed over each package’s sorted file tree and recorded in the lockfile. On reinstall, cached packages are checked against those hashes. If freshly downloaded content fails verification, the install aborts as possible supply-chain tampering rather than warning and continuing.
The MCP trust boundary is the best-designed part of APM, and it is worth copying even if you never adopt the tool. MCP servers declared by your direct dependencies are auto-trusted. MCP servers declared by transitive dependencies are blocked by default, and stay blocked until you either re-declare them yourself or pass --trust-transitive-mcp. A package you installed cannot quietly hand your agent a new tool endpoint. For teams thinking through why MCP matters for AI agents, that is the governance primitive the protocol itself does not provide.
Policy lives in apm-policy.yml, auto-discovered from your organization’s .github-private repository. It merges tighten-only through up to five levels of inheritance, so a team can restrict a parent policy but never relax it, and it is enforced at four points: the install gate, direct MCP preflight, transitive MCP preflight, and apm audit. Findings export to GitHub Code Scanning as SARIF, and apm lock export produces a CycloneDX 1.5 or SPDX 2.3 SBOM. For a platform team trying to standardize AI tooling across business units, that combination is more enterprise-ready than the project’s pre-1.0 version number suggests.
APM vs MCP vs plugin hosts: what is the difference?
These three are stacked layers with different jobs, not competing products, and conflating them is the most common misunderstanding about APM. APM packages MCP server declarations; it is not an MCP registry and not a runtime for the Model Context Protocol. Microsoft states plainly that APM is “not a runtime,” “not an LLM gateway,” “not a fine-tuning tool,” and “not a marketplace.”
Plugin hosts sit underneath rather than opposite. According to Microsoft’s APM plugins guide (2026), every APM package is plugin-compatible by default: apm pack writes a plugin.json at the root of the bundle, so a host like Claude Code loads it natively. APM is a distribution layer above plugins, not a replacement for them.
| Layer | What it moves | What it guarantees | What it does not |
|---|---|---|---|
| APM | Files that configure agents | The same files everywhere, content-hashed | Whether those files are correct |
| Model Context Protocol | A wire protocol for tools and data | A shared calling convention | Which server to trust, or what the data means |
| Plugin hosts | Bundles into one harness | Native loading inside that harness | Portability across harnesses |
| Enterprise context layer | Meaning, trust and rules about your data | That the agent knows what recognized_revenue_q4 is and who may query it |
Which harness a developer happens to run |
Read the table row by row and the division of labor is clean. Protocols move calls, package managers move files, and something else entirely has to move meaning. Teams that get this wrong usually discover it the hard way, which is why when to use MCP versus an API and MCP versus function calling are worth settling before you pick a packaging strategy on top of either.
What APM does not solve
APM guarantees that every engineer’s agent reads the same context, and guarantees nothing about whether that context is true about your business. That boundary is Microsoft’s own, drawn deliberately and documented in its non-goals, so what follows is not a shortfall against a promise APM made. It is the part of the problem a package manager structurally cannot reach, and knowing where the line falls is what tells you what else you need.
Three limits are stated outright in the APM security model and governance guide (Microsoft, 2026):
- “APM does not sign packages… does not inspect what an agent does once it has read your context.”
- “APM does not do LLM-based prompt review, prompt-injection detection, or semantic safety review.”
- Policy cannot govern which model an agent runs against, which harness version is installed locally, or what happens at runtime.
Here is what that leaves open in practice. A data-access skill that tells the agent to “pull ARR from the revenue table” installs perfectly. It hashes cleanly, passes every policy check, and lands in the right directory on nine harnesses. It is also wrong, because three systems in your company define revenue differently: bookings in the CRM, usage revenue in the warehouse, recognized revenue in the finance system. The agent picks one, confidently. A lockfile does not make an answer right; it makes the same wrong answer reproducible on every laptop in the company.
That second layer is a different kind of problem, and it needs different machinery. It answers three questions APM never asks: what data can I trust, what do things mean here, and what am I allowed to do with them. Those are the questions the enterprise context layer exists to answer, and they are solved by a semantic layer for AI agents and a governed account of the data estate, not by a manifest in a repo. The practical work sits in how to give AI agents access to enterprise data and how to structure context for AI agents.
The fair counter-argument deserves stating. APM’s policy engine is considerably more capable than “just a config tool” implies: allow and deny lists, tighten-only inheritance, SARIF audit trails, SBOM export, transitive MCP gating. The limit is scope, not sophistication. APM governs which files land on disk, extremely well. It was never designed to govern what those files claim about your company, and evaluating data quality in AI agent harnesses remains a separate discipline from packaging them.
When should your team adopt APM?
Adopt APM when more than one agent harness is in use across your teams, and wait when there is only one. Everything else is detail on that decision.
| Signal | Adopt now | Wait |
|---|---|---|
| Multiple harnesses across teams | Yes, this is the core use case | |
| Agent instructions already copy-pasted between repos | Yes, the drift is already costing you | |
| You need install-time policy enforcement across business units | Yes, apm-policy.yml is built for this |
|
| One harness, one team, five files | Git is already your package manager | |
| You need runtime governance or model-level control | Wrong layer, APM does not reach there |
Be clear-eyed about maturity. According to the microsoft/apm repository (GitHub, 2026), APM is at v0.31.0 with roughly weekly releases and 144 open issues. That is healthy velocity and an unstable surface at the same time, so pin versions and read release notes. The GitHub Action at microsoft/apm-action (Microsoft, 2026) makes CI enforcement straightforward once you commit, which matters if you intend to test your agent harness rather than assume it works.
One signal is worth reporting honestly because it cuts against the adoption numbers. Four separate submissions of the APM repository to Hacker News (2026) between March and June 2026 drew zero comments between them, peaking at seven points, against 3,822 GitHub stars and 361 forks. Adoption is running well ahead of public discussion, which means almost everything written about APM today is first-party or first-party-adjacent. Evaluate it yourself rather than waiting for a consensus that has not formed. The failure modes worth checking against are catalogued in agent harness failures and anti-patterns, and keeping an AI registry of what you have deployed will tell you whether the drift APM fixes is a problem you actually have.
How Atlan thinks about agent context
Agent context splits into two halves, and only one of them lives in your repo. The half APM handles is the harness: the instructions, skills and tool declarations that configure how an agent works. The other half lives in your data estate, and no package manager can reach it.
The failure this creates is specific. A platform team rolls out APM, every agent across every harness boots identically, the lockfile is clean, and the answers are still wrong, because the agent has no idea which of three revenue definitions the question meant. The context was reproducible. It was never grounded.
Grounding it takes three things working together. AI-ready data and a context graph answer what data can be trusted. Semantics and ontology answer what things mean in this specific business. Enterprise skills answer how work actually gets done and what is allowed. Atlan builds that foundation, which is why context engineering for AI agents and the relationship between the context layer and harness engineering keep turning up in the same architecture conversations.
The convergence is the most interesting thing about APM. Atlan describes skills as a versioned, testable, governed primitive for procedural knowledge. Microsoft reached for a manifest and a lockfile over the same primitive from the opposite end of the stack. When a data platform and a developer-tools team land on package-manager discipline for agent context from different directions, the shape is probably right. The work that follows from it is implementing an enterprise context layer for AI alongside whatever you use to distribute your agent files, and agent context layer design is where that starts.
Package managers solved distribution, not meaning
The industry has now agreed on something it had not agreed on a year ago: agent context is infrastructure, and infrastructure gets a manifest, a lockfile and a policy file. APM is a good implementation of that agreement, and the parts of it worth studying, particularly the transitive MCP trust boundary and install-time policy inheritance, are worth studying whether or not you adopt the tool. What the industry has not settled is who owns the other half. Distribution is solved. Meaning is not, and meaning is where agent answers are actually won or lost.
FAQs
1. Is Microsoft APM the same as Application Performance Monitoring?
No. Application Performance Monitoring is the observability category that Datadog, New Relic and Dynatrace compete in. Microsoft’s APM is the Agent Package Manager, a dependency manager for AI agent configuration files. The two share an acronym and nothing else, and the collision makes searching for either one harder than it should be.
2. Is APM free and open source?
Yes. APM is MIT-licensed and developed in the open under Microsoft’s GitHub organization, with 3,822 stars and 361 forks as of September 2026. Installation is available through Homebrew, a curl script, PowerShell, pip, WinGet and Scoop. There is no paid tier and no telemetry.
3. What is an apm.yml file?
It is the manifest that declares every agent primitive a project needs: APM packages, MCP servers, and the version constraints on each. It plays the same role for agent configuration that package.json plays for a Node project or requirements.txt plays for Python, and it is designed to be committed to the repository.
4. What does apm install actually do?
It reads apm.yml, resolves the full dependency tree including transitive dependencies, scans every file for hidden Unicode, verifies content hashes, applies organizational policy, and writes each primitive into the directory its target harness expects. It then records the exact resolved state in apm.lock.yaml so the next install reproduces it.
5. How is APM different from MCP?
MCP is a wire protocol that defines how an agent calls external tools and data sources. APM is a package manager that distributes configuration files, including the declarations that point an agent at MCP servers. APM packages MCP; it does not replace it, implement it, or run it.
6. Is APM production-ready?
It depends on your tolerance for a pre-1.0 surface. The security and policy design is mature, but the project is at v0.31.0 with roughly weekly releases and over 140 open issues, so the CLI and manifest schema can still change. Pin your versions, read release notes, and treat upgrades as deliberate.
Sources
APM documentation: what is APM, Microsoft APM documentation home, Microsoft APM security model, Microsoft APM governance deep-dive, Microsoft APM plugins guide, Microsoft microsoft/apm repository, GitHub microsoft/apm-action, GitHub Model Context Protocol specification, Anthropic APM discussion thread, Hacker News