APM: AI NPM = Agent Package Manager

AI 에이전트를 한두 번 써본 팀과, 실제로 멀티 에이전트 워크플로우를 운영해본 팀의 고민은 꽤 다릅니다.
전자는 “프롬프트를 잘 쓰면 되지 않을까?”에서 시작하지만, 후자는 곧 이런 문제를 만납니다. 누가 어떤 규칙을 쓰는지, 어떤 스킬과 프롬프트가 프로젝트에 묶여 있는지, 새 팀원이 오면 그 환경을 어떻게 똑같이 복제할지, 그리고 그 의존성을 어떻게 버전 관리할지 말입니다. APM은 바로 그 지점을 겨냥해 나온 도구입니다. Microsoft가 오픈소스로 공개한 APM은 AI 에이전트용 컨텍스트, 프롬프트, 스킬, 플러그인, MCP 서버를 apm.yml 하나로 선언하고 설치하는 패키지 매니저입니다. README와 공식 문서가 반복해서 강조하는 비유도 명확합니다. package.json, requirements.txt, Cargo.toml가 코드 의존성을 다루듯, APM은 에이전트 의존성을 다룬다는 것입니다. (GitHub)

지금 시점에서 이 프로젝트는 “아이디어 소개” 수준을 이미 조금 넘었습니다. 저장소에는 CLI, 컴파일러, 의존성 해석기, 런타임 관리자, 보안 스캔, 번들링, GitHub Action까지 한 세트로 들어가 있고, 최신 릴리스는 2026년 3월 20일의 v0.8.3입니다. 다만 문서에서도 일부 기능은 아직 experimental이라고 분명히 적고 있어서, 이걸 곧바로 프로덕션 표준으로 못 박기보다는 “에이전트 운영 인프라를 코드처럼 관리하려는 흐름에서 가장 빨리 움직이는 오픈소스 중 하나”로 보는 게 정확합니다. (GitHub)

 

GitHub - microsoft/apm: Agent Package Manager

 

프로젝트 소개

APM은 한마디로 정리하면 AI 에이전트 설정과 실행 맥락을 패키지처럼 배포하고 재현하는 CLI입니다. 공식 소개에서는 instructions, skills, prompts, agents, hooks, plugins, MCP servers를 하나의 manifest로 선언하고, 프로젝트를 클론한 개발자가 apm install만 실행하면 Copilot, Claude Code, Cursor, OpenCode 같은 도구에 필요한 구성을 재현할 수 있다고 설명합니다. 또한 GitHub뿐 아니라 GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, 셀프호스팅 Git 서버에서도 패키지를 가져올 수 있게 설계돼 있습니다. (Microsoft GitHub)

이 프로젝트는 Microsoft 조직의 오픈소스 저장소로 공개되어 있고, README 기준으로 Daniel Meppiel이 만들고 유지하고 있습니다. 라이선스는 MIT입니다. 구현체는 Python 기반 CLI이며, click, pyyaml, requests, GitPython, rich, llm, llm-github-models 같은 패키지를 사용합니다. 엔트리포인트는 apm = "apm_cli.cli:main"으로 등록되어 있습니다. 즉, 내부 철학은 “에이전트 운영 문제”를 다루지만, 실제 구현은 꽤 전통적인 CLI 아키텍처를 따릅니다. (GitHub)

왜 이 프로젝트가 등장했을까

APM이 풀려는 문제는 사실 매우 현실적입니다. 지금까지의 AI 개발 워크플로우는 대부분 사람 머릿속, 슬랙 스레드, 개별 프롬프트 템플릿, IDE별 설정 파일에 흩어져 있었습니다. 그래서 같은 저장소를 보더라도 개발자마다 AI가 받는 컨텍스트가 달랐고, 결과도 달랐습니다. 공식 문서도 이 문제를 “manual setup”, “nothing is portable nor reproducible”, “no manifest for it”으로 정리합니다. (GitHub)

여기서 APM의 핵심 발상은 단순합니다.
에이전트가 사용하는 규칙과 도구도 결국 의존성이다.
그렇다면 코드를 패키지로 다뤘던 것처럼, 에이전트용 자산도 패키지화하고 버전화하고 잠가야 한다는 겁니다. 이 점에서 APM은 단순한 프롬프트 라이브러리보다 훨씬 인프라 지향적입니다. 프롬프트를 “복붙 가능한 문서”가 아니라 “resolve 가능한 dependency”로 취급하기 때문입니다. 공식 문서가 npm과 pip를 반복적으로 비유하는 이유도 여기에 있습니다. (GitHub)

개발자 관점에서 이게 왜 중요하냐면, 멀티 에이전트 환경에서는 문제가 금방 커지기 때문입니다. 예를 들어 API 설계용 agent, 보안 리뷰용 skill, 릴리즈 체크용 prompt, 사내 MCP 서버 구성이 서로 다른 저장소에 흩어져 있으면, 그것을 조합해 하나의 팀 표준으로 맞추는 일이 곧 운영 문제가 됩니다. APM은 바로 그 운영 문제를 “manifest + resolution + lockfile + install”이라는 익숙한 패턴으로 가져옵니다. (Microsoft GitHub)

핵심 기능

1) apm.yml 하나로 에이전트 의존성 선언

APM의 중심에는 apm.yml이 있습니다. 이 파일 안에 dependencies.apm과 dependencies.mcp를 선언할 수 있고, APM은 이를 읽어 agent primitive 패키지와 MCP 서버 설정을 해석합니다. 공식 schema 문서에 따르면 dependencies는 apm과 mcp라는 두 가지 주요 키를 가지며, 각 항목은 shorthand 문자열 또는 typed object 형태를 지원합니다. (Microsoft GitHub)

예를 들면 이런 식입니다.

name: team-agent-stack
version: 1.0.0

dependencies:
  apm:
    - anthropics/skills/skills/frontend-design
    - github/awesome-copilot/agents/api-architect.agent.md
    - microsoft/apm-sample-package#v1.0.0
  mcp:
    - github

이 구조가 좋은 이유는, 팀이 쓰는 에이전트 환경을 저장소에 같이 넣을 수 있다는 점입니다. 새 팀원이 들어오면 “이 프롬프트 파일 복사해두세요”가 아니라 “클론하고 install 하세요”로 끝납니다. README도 이 온보딩 시나리오를 가장 앞에 둡니다. (GitHub)

2) 전이 의존성과 lockfile

APM은 npm처럼 transitive dependency를 처리합니다. 패키지가 또 다른 패키지에 의존할 수 있고, 설치 후에는 apm.lock.yaml을 생성해 재현 가능한 빌드를 보장합니다. 문서상 동작 방식도 익숙합니다. 첫 설치 때 전체 의존성을 resolve하고 lockfile을 기록하고, 이후 설치에서는 lock된 commit SHA를 기준으로 동일한 결과를 재현합니다. 업데이트가 필요할 때만 apm install --update로 다시 해석합니다. (GitHub)

이건 특히 멀티 에이전트 워크플로우에서 중요합니다. 코드 의존성은 lockfile로 고정해놓고, 정작 에이전트 규칙과 스킬은 최신 main 브랜치를 따라가게 두면 팀 전체의 AI 동작이 매번 달라질 수 있습니다. APM은 이 영역까지 잠그려는 시도라고 보면 됩니다. (Microsoft GitHub)

3) 플러그인 생태계 연결

APM은 자체 포맷만 고집하지 않습니다. plugin.json을 가진 플러그인 저장소도 감지하고, 이를 apm.yml 기반 패키지처럼 취급합니다. 더 흥미로운 건 manifest 위치를 여러 플랫폼 형식에 맞춰 지원한다는 점입니다. 루트의 plugin.json, .github/plugin/plugin.json, .claude-plugin/plugin.json, .cursor-plugin/plugin.json까지 탐색합니다. 그리고 root의 agents/, skills/, commands/, instructions/를 .apm/ 구조로 매핑합니다. (Microsoft GitHub)

즉, APM은 “새로운 포맷을 강요하는 관리자”라기보다, 이미 흩어져 있는 에이전트 자산 형식을 가능한 한 흡수해 하나의 패키징 흐름으로 정리하려는 도구에 가깝습니다.

4) 보안 스캔

APM이 꽤 영리한 포인트는 에이전트가 읽는 텍스트 자체를 공격면으로 본다는 점입니다. 보안 문서에는 숨겨진 Unicode 문자, bidirectional override, zero-width 문자 같은 요소가 룰 파일이나 프롬프트에 섞여 들어갈 수 있다고 설명하고, apm audit와 설치 단계의 사전 검사로 이를 차단한다고 적혀 있습니다. 특히 critical hidden Unicode findings는 배포 전에 막는다고 명시합니다. (Microsoft GitHub)

이건 에이전트 시대에 꽤 중요한 시각입니다. 예전 패키지 매니저가 바이너리나 스크립트 실행만 조심했다면, APM은 “텍스트 지시문”도 공급망 보안 대상으로 취급합니다. AI 에이전트에게는 프롬프트와 instructions도 사실상 실행 입력이기 때문입니다. 이 관점은 앞으로 다른 툴에도 확산될 가능성이 큽니다. (Microsoft GitHub)

5) 번들링과 CI/CD

apm pack은 구성과 primitive를 번들로 만들고, GitHub Action인 microsoft/apm-action은 CI에서 APM 설치, apm.yml 해석, bundle 생성과 복원까지 지원합니다. 액션 문서에는 pack mode, restore mode, cross-job artifact workflow 예시가 포함돼 있어서, “한 번 패킹한 에이전트 구성물을 여러 잡에서 동일하게 재사용”하는 흐름도 염두에 둔 것으로 보입니다. (Microsoft GitHub)

이 지점은 실무에서 꽤 매력적입니다. AI agent 환경을 로컬에서만 쓰는 게 아니라 CI에도 일관되게 심을 수 있다는 뜻이기 때문입니다.

프로젝트 아키텍처 분석

소스 트리를 보면 APM CLI는 매우 분리된 구조를 갖습니다. commands, compilation, registry, runtime, deps, primitives, workflow 같은 디렉터리로 나뉘어 있고, cli.py는 공식 주석 그대로 “thin wiring layer”입니다. 즉, CLI 엔트리포인트는 얇고 실제 로직은 각 모듈로 분산되어 있습니다. (GitHub)

문서의 아키텍처 설명과 소스 트리를 합쳐보면, 내부 구조는 대략 이렇게 이해하면 됩니다.

이 구조의 핵심은 세 가지입니다.

첫째, 패키지 관리자로서의 역할입니다. 원격 Git 저장소에서 패키지를 가져오고, 의존성 트리를 풀고, lockfile로 고정합니다. 문서의 schema와 dependency 가이드는 resolver가 apm.yml을 읽고, 각 dependencies.apm 항목에 대해 저장소를 fetch/clone한 뒤 .apm/ 또는 가상 경로에서 primitive를 추출한다고 설명합니다. (Microsoft GitHub)

둘째, 컨텍스트 컴파일러입니다. 문서의 “How It Works”는 APM이 .apm/ 디렉터리의 context를 받아 AGENTS.md 같은 포터블 표준으로 컴파일한다고 설명합니다. GitHub Copilot와 Claude는 배포된 primitive를 네이티브로 읽고, Cursor와 OpenCode도 특정 디렉터리가 있으면 네이티브 통합을 받으며, 다른 도구는 apm compile이 생성한 AGENTS.md를 소비하는 식입니다. (Microsoft GitHub)

셋째, 런타임 관리자입니다. APM은 단순히 “파일만 깔아주는 툴”이 아닙니다. experimental이긴 하지만 apm runtime setup으로 Copilot CLI, Codex CLI, llm CLI를 설치·설정할 수 있습니다. 즉, 에이전트 컨텍스트뿐 아니라 실행 런타임까지 한 축으로 끌어오려는 설계입니다. (Microsoft GitHub)

실제로 어떻게 쓰이나

가장 현실적인 사용 시나리오는 팀 공용 에이전트 스택을 저장소에 묶는 것입니다.

# 설치
brew install microsoft/apm/apm
# 또는
pip install apm-cli

# 프로젝트에 패키지 추가
apm install microsoft/apm-sample-package
apm install anthropics/skills/skills/frontend-design

# 의존성 트리 확인
apm deps tree

# 보안 검사
apm audit

# 필요 시 업데이트
apm install --update

APM 문서 기준으로 설치는 macOS/Linux, Windows 바이너리와 Homebrew, Scoop, pip를 지원하고, Python 패키지 메타데이터상 CLI 이름은 apm, Python 요구 버전은 >=3.10입니다. (GitHub)

조금 더 팀스러운 예시는 이런 형태가 될 겁니다.

name: vibecoder-workflow
version: 1.0.0

dependencies:
  apm:
    - my-org/agents/backend-architect.agent.md
    - my-org/skills/security-review
    - my-org/prompts/pr-review.prompt.md
    - github/awesome-copilot/plugins/context-engineering#v2.1
  mcp:
    - github

devDependencies:
  apm:
    - my-org/test-helpers

이렇게 해두면 운영용 agent primitive와 개발 보조용 primitive를 나눌 수 있고, dev dependency는 배포 번들에서 제외할 수 있습니다. 공식 dependency 가이드도 이 dev dependency 분리를 지원합니다. (Microsoft GitHub)

플러그인 작성까지 가면 흐름은 더 흥미로워집니다.

apm init my-plugin --plugin
apm install --dev owner/helpers
apm install owner/core-rules
apm pack --format plugin

이 흐름은 apm.yml과 plugin.json을 함께 생성하고, 개발 의존성과 배포 의존성을 나눈 뒤, 마지막에 표준 플러그인 산출물로 export하는 방식입니다. 즉, “에이전트 패키지 관리자”이면서 동시에 “플러그인 빌드 툴체인” 역할도 합니다. (Microsoft GitHub)

APM을 어디서 써볼 만한가

이 도구가 가장 잘 맞는 팀은 아래 성격을 가진 곳입니다.

1) 멀티 에이전트 워크플로우를 이미 굴리고 있는 팀

API 설계용 agent, 문서화용 prompt, 리뷰용 skill, 사내 MCP 서버 설정이 분리돼 있다면 APM의 가치가 바로 보입니다. 이 경우 APM은 “도구 추가”가 아니라 “흩어진 AI 운영 자산을 묶는 계층”이 됩니다. (Microsoft GitHub)

2) 팀 온보딩 비용이 높은 곳

새 개발자가 합류할 때 IDE 규칙, 프롬프트 세트, 사내 지침, MCP 구성을 따로 알려줘야 한다면 APM이 유용합니다. 이 문제를 공식 문서도 핵심 use case로 내세웁니다. (Microsoft GitHub)

3) 에이전트 설정을 CI까지 가져가고 싶은 팀

로컬과 CI의 에이전트 동작이 달라지면 자동화 품질이 무너집니다. APM Action과 bundle/restore 흐름은 이 문제를 줄이는 데 꽤 적합해 보입니다. (GitHub)

아직 조심해서 봐야 하는 부분

반대로 모든 팀에 당장 추천할 도구는 아닙니다.

첫째, 프로젝트는 빠르게 진화 중이고 일부 영역은 아직 experimental입니다. 특히 공식 문서에서 workflow execution과 runtime management는 실험적 기능이라고 분명히 적어둡니다. 따라서 지금 당장은 “에이전트 의존성 관리”에 초점을 맞춰 보고, 런타임 실행 계층은 신중하게 보는 편이 좋습니다. (Microsoft GitHub)

둘째, 개념적으로는 패키지 매니저지만 실제로 관리 대상이 코드가 아니라 에이전트 컨텍스트라는 점이 진입장벽이 될 수 있습니다. npm은 everyone knows인 반면, APM은 조직이 “우리는 어떤 primitive를 표준으로 볼 것인가”부터 정의해야 효과가 납니다. 즉, 툴만 들여와서는 안 되고 운영 규약도 같이 필요합니다. 이건 문서가 말하는 AI-Native Development 프레임워크와도 연결됩니다. (Microsoft GitHub)

셋째, 보안 모델도 만능은 아닙니다. hidden Unicode 같은 특정 공격 벡터를 막는 데는 의미가 크지만, 문서 스스로 plain-text prompt injection, homoglyph substitution, semantic manipulation까지 전부 해결하지는 못한다고 밝힙니다. 그러니 보안 스캔은 유용한 안전망이지, 완전한 검증 시스템은 아닙니다. (Microsoft GitHub)

총평

APM을 보고 가장 먼저 든 생각은 “AI 에이전트 생태계가 드디어 의존성 관리 단계로 들어왔구나”였습니다.

지금까지 AI 개발 도구 대부분은 더 똑똑한 모델, 더 편한 IDE, 더 좋은 프롬프트 템플릿에 집중해 왔습니다. 그런데 팀 단위로 넘어오면 진짜 중요한 건 성능보다 재현성, 공유성, 이식성, 거버넌스입니다. APM은 바로 이 문제를 겨냥합니다. apm.yml, transitive dependencies, apm.lock.yaml, apm audit, apm pack, GitHub Action까지 이어지는 흐름은 “에이전트 운영도 소프트웨어 공급망처럼 다뤄야 한다”는 선언에 가깝습니다. (GitHub)

그래서 이 도구를 한 줄로 평가하면 이렇습니다.

APM은 AI 에이전트용 npm이라기보다, 팀의 에이전트 운영 지식을 패키지화하는 첫 번째 실전형 인프라 시도다.

바이브코딩이나 멀티 에이전트 워크플로우를 이미 손대고 있다면, 이건 충분히 한 번 설치해볼 가치가 있습니다. 다만 지금 단계에서는 “프로덕션 표준”이라기보다 “앞으로 표준이 될 수 있는 방향을 가장 선명하게 보여주는 도구”에 더 가깝습니다. 신규 릴리스가 계속 나오고 있으니, 당분간은 직접 써보면서 lockfile 안정성, 팀 온보딩 경험, CI 통합 품질을 확인해보는 게 가장 좋겠습니다. (GitHub)