Microsoft Agent Package Manager (APM) Explained

If you have used npm, pip, or nuget, Microsoft Agent Package Manager (APM) will feel familiar.

APM helps you manage dependencies for AI agents the same way package managers help you manage code dependencies.

In simple terms:

  • package.json is for app dependencies
  • requirements.txt is for Python dependencies
  • apm.yml is for AI agent dependencies (skills, prompts, instructions, MCP servers, plugins)

Why APM Is Useful

Without APM, agent setup is usually manual:

  • Copy prompts from one repo
  • Add instructions in different places
  • Configure MCP servers by hand
  • Hope everyone on the team has the same setup

With APM, you define everything once in apm.yml, commit it, and anyone can reproduce the same agent setup with one command.

That means:

  1. Faster onboarding
  2. Consistent behavior across developers
  3. Better traceability through lock files

Core Files You Should Know

APM usually works with these files:

  1. apm.yml - your manifest (what to install)
  2. apm.lock.yaml - resolved and pinned dependencies
  3. Optional policy files - guardrails for allowed sources and primitives

Think of apm.lock.yaml like package-lock.json: it helps keep installs reproducible.

Install APM (Windows)

irm https://aka.ms/apm-windows | iex

After installation, verify:

apm --version

Example 1: Install a Shared Agent Package

Let us say your team maintains a reusable package with instructions and skills.

Install it:

apm install microsoft/apm-sample-package#v1.0.0

What happens:

  1. APM resolves dependencies
  2. Downloads required agent assets
  3. Updates your lock file for reproducibility

This is the equivalent of adding a library dependency in traditional development.

Example 2: Add an MCP Server Dependency

If your agent needs external tools, you can install an MCP server as a dependency.

apm install --mcp io.github.github/github-mcp-server --transport http

This tells APM to include that MCP server in your agent setup so supported clients can use it.

Example 3: Generate Copilot Instructions

If you use GitHub Copilot, APM can compile the resolved setup into a Copilot-readable instructions file.

apm compile -t copilot

This writes the instructions into:

.github/copilot-instructions.md

Now your repository has a reproducible path from manifest -> resolved dependencies -> generated instructions.

Minimal apm.yml Example

name: my-blog-agent-setup
version: 1.0.0
dependencies:
  apm:
    - microsoft/apm-sample-package#v1.0.0
  mcp:
    - name: io.github.github/github-mcp-server
      transport: http

Keep this file in source control so your team gets the same agent context everywhere.

A Simple Workflow For Teams

  1. Define dependencies in apm.yml
  2. Run apm install
  3. Commit both apm.yml and apm.lock.yaml
  4. Run apm compile -t copilot if you use Copilot instructions
  5. In CI, run audit checks to catch drift or policy violations

Common Beginner Mistakes

  1. Not committing lock file Without apm.lock.yaml, teammates may resolve different versions.

  2. Manual edits after install Manual edits can create drift. Prefer updating manifest and reinstalling.

  3. Confusing APM with app dependency managers APM manages agent context, not your application runtime libraries.

Final Thoughts

Microsoft APM brings a clean software-engineering mindset to AI agent setup: declarative config, reproducibility, and governance.

If your team uses multiple AI coding clients and wants a consistent setup, APM is worth trying.

References

AI  Copilot  MCP  Agent