DEV Community

Cover image for Agent Package Manager (APM): gerenciando contexto de agentes de IA como dependências
Fazedor de Codigo profile image Emerson Delatorre
Emerson Delatorre for Fazedor de Codigo

Posted on

Agent Package Manager (APM): gerenciando contexto de agentes de IA como dependências

#apm #microsoft #agents #ai

1. O que é o Agent Package Manager?

O Agent Package Manager (APM) é um dependency manager open-source e community-driven para AI agents. A analogia mais direta é com package.json, requirements.txt ou Cargo.toml — só que aplicado à configuração de agentes de IA, não a bibliotecas de aplicação.

Na prática, o APM gerencia o contexto que os agentes precisam para ser úteis: skills, prompts, instructions, hooks e MCP servers. Ele faz isso com um manifest (apm.yml), um lockfile (apm.lock.yaml), um policy engine e um gesto de install que configura múltiplos harnesses.

Atenção ao escopo: este APM não é Application Insights nem Azure Monitor Application Performance Monitoring. O assunto deste artigo é o repositório microsoft/apm — Agent Package Manager.

Versões de referência (verificadas em 2026-09-30):

  • Release GitHub estável: v0.32.0 (publicado em 2026-09-25)
  • Pacote PyPI: apm-cli 0.32.0 (requires-python = ">=3.10")
  • Licença: MIT
  • Docs: https://microsoft.github.io/apm/

O projeto se apoia em padrões abertos: AGENTS.md, Agent Skills e MCP.

2. O problema: setup manual e “file presence = execution”

AI coding agents precisam de contexto — standards, prompts, skills, plugins — para serem úteis. Hoje, cada developer costuma configurar isso manualmente. O resultado é previsível:

  • nada é portátil entre máquinas ou times;
  • nada é reproduzível de forma confiável;
  • não há um manifest que declare “o que este repo espera dos agentes”.

O APM ataca exatamente isso: você declara as dependências em apm.yml e apm install configura o ambiente. Com o manifest no repositório, o fluxo vira:

git clone <org/repo> && cd <repo>
apm install    # every agent is configured
Enter fullscreen mode Exit fullscreen mode

Há ainda um detalhe de threat model que muda o jogo em relação a gestores de pacotes clássicos. Em npm, existe um gap entre install e start: instalar um pacote não executa o código da aplicação. No contexto de agentes, a presença do arquivo no diretório do harness pode ser ingerida imediatamente — “file presence IS execution”. Por isso o APM trata o deploy de pacotes como um pre-deployment gate: escaneia primeiro e só então faz o deploy se estiver limpo.

3. As três promises

O APM se compromete publicamente com três pilares:

  1. Portable by manifest
  2. Secure by default
  3. Governed by policy

Portable by manifest

Um único apm.yml descreve primitives (instructions, skills, prompts, agents, hooks, plugins, MCP) e apm install reproduz o setup. O apm.lock.yaml pina a árvore resolvida.

Harnesses default documentados: Copilot, Claude, Grok Build, Cursor, OpenCode, Codex, Gemini, Windsurf e Kiro. Antigravity e Hermes estão disponíveis como targets explícitos via CLI.

Dependências podem vir de GitHub, GitLab, Bitbucket, Azure DevOps, GitHub Enterprise, Gitea, Gogs ou qualquer git host — com resolução de dependências transitivas.

Secure by default

Contexto de agente é executável em efeito: um prompt é um programa para um LLM. Por isso:

  • todo apm install escaneia Unicode oculto antes de os agentes lerem o conteúdo;
  • o lockfile pina integrity hashes;
  • MCP servers transitivos exigem consentimento explícito (trust prompts).

Após apm install ou apm compile, o processo do APM sai: não há runtime footprint, sem phone-home, sem execução arbitrária por default e sem telemetria.

Governed by policy

Com apm-policy.yml, um time de segurança pode declarar as únicas sources, scopes e primitives permitidas na organização. A política é enforced em todo apm install, com herança tighten-only (enterprise → org → repo). Em CI, apm audit --ci encaixa em branch protection.

Importante: apm-policy.yml governa o que é instalado; o harness governa o que roda. Os dois planos não se sobrepõem.

4. Conceitos essenciais

Primitives

Uma primitive é uma unidade de contexto de agente que o APM consegue gerenciar. O conjunto documentado inclui:

  • Instructions
  • Skills
  • Prompts
  • Agents
  • Hooks
  • Commands
  • Plugins
  • MCP servers
  • Canvas (experimental, Copilot-only)

Harnesses (targets)

São os ambientes/agentes onde o contexto é materializado no disco (Copilot, Claude, Cursor, etc.). Você pode deixar o APM detectar markers do harness ou informar --target / targets no manifest — útil em multi-harness e em CI sem markers locais.

Manifest (apm.yml)

Declara o projeto e as dependências. Exemplo oficial:

name: your-project
version: 1.0.0
dependencies:
  apm:
    - anthropics/skills/skills/frontend-design
    - github/awesome-copilot/plugins/context-engineering
    - github/awesome-copilot/agents/api-architect.agent.md
    - microsoft/apm-sample-package#v1.0.0
  mcp:
    - name: io.github.github/github-mcp-server
      transport: http
Enter fullscreen mode Exit fullscreen mode

Opcionalmente o manifest pode incluir targets, includes e scripts.

Lockfile (apm.lock.yaml)

Pina a árvore resolvida (commits + content hashes). É o equivalente semântico a um lockfile de npm: commitado no repo, base de apm install --frozen em CI.

Policy (apm-policy.yml)

Allow-list organizacional de sources/scopes/primitives. Complementa — e não substitui — o sandbox/runtime do harness.

Verbos no estilo npm

A semântica dos comandos é intencionalmente alinhada ao npm:

APM Analogia npm
apm install npm install
apm update npm update
apm install --frozen npm ci
apm prune npm prune

Quem já usa npx skills add encontra um caminho drop-in: apm install vercel-labs/agent-skills (ou com --skill), ganhando manifest, lockfile e reprodutibilidade.

5. Hands-on: instalar, inicializar e commitar

5.1 Instalar o CLI

Métodos oficiais documentados:

# macOS (Homebrew)
brew install apm
# atualizar: brew upgrade apm  (não use apm self-update no Homebrew)

# Linux / macOS (installer)
curl -sSL https://aka.ms/apm-unix | sh

# Windows (PowerShell)
irm https://aka.ms/apm-windows | iex

# pip (Python 3.10+)
pip install apm-cli
# ou: python3 -m pip install apm-cli

# WinGet
winget install --id Microsoft.APM --exact --source winget

# Scoop: bucket microsoft/scoop-apm + scoop install apm
Enter fullscreen mode Exit fullscreen mode

Requisitos gerais: macOS, Linux ou Windows (x86_64 ou ARM64) e git. Python 3.10+ é necessário apenas para instalação via pip ou from-source.

Verifique:

apm --version
Enter fullscreen mode Exit fullscreen mode

Em builds standalone (não Homebrew), a atualização documentada é apm self-update.

5.2 Projeto novo (consumer, ~5 minutos) 

apm init my-agent && cd my-agent
apm install microsoft/apm-sample-package#v1.0.0 --target copilot
Enter fullscreen mode Exit fullscreen mode

O apm init cria o apm.yml. Você pode editar o manifest (por exemplo, descomentar targets) antes ou depois do install. Se o harness já tiver markers no disco, o --target pode ser omitido.

5.3 O que revisar e o que commitar

Após o install, espere ver:

  • apm.yml — manifest
  • apm.lock.yaml — lockfile
  • apm_modules/ — cache local (não commit; gitignore)
  • diretórios deployados pelo harness, por exemplo .github/, .agents/, etc.

Commitar: manifest + lockfile + dirs deployados.

Não commitar: apm_modules/.

5.4 Repo já existente com apm.yml 

git clone <repo> && cd <repo>
apm install
# em CI:
apm install --frozen
Enter fullscreen mode Exit fullscreen mode

Em seguida, abra o harness (Copilot, Claude, Cursor, …): as primitives já estarão no disco.

Há também uma GitHub Action oficial para CI/CD: microsoft/apm-action.

6. Exemplos práticos

Skills (compatível com o fluxo de npx skills add) 

apm install vercel-labs/agent-skills
apm install vercel-labs/agent-skills --skill deploy-to-vercel
Enter fullscreen mode Exit fullscreen mode

Marketplace 

apm marketplace add github/awesome-copilot
apm install azure-cloud-development@awesome-copilot
Enter fullscreen mode Exit fullscreen mode

Marketplaces ajudam no discovery; qualquer repositório git continua sendo um package APM válido.

MCP server 

apm install --mcp io.github.github/github-mcp-server --transport http
Enter fullscreen mode Exit fullscreen mode

Esse fluxo documentado faz o wire em Copilot, Claude, Cursor, Codex, OpenCode, Gemini, Windsurf e Kiro.

Compile zero-config para GitHub Copilot 

apm compile -t copilot
Enter fullscreen mode Exit fullscreen mode

Escreve .github/copilot-instructions.md, lido pelo VS Code / GitHub Copilot.

Autoria de plugins

O APM é descrito como a primeira ferramenta que permite author plugins com um dependency manager real e export de pacotes plugin.json padrão; apm pack gera zip ou plugin standalone.

Complemento: agentrc

O projeto microsoft/agentrc gera instructions a partir do codebase. O formato .instructions.md é compartilhado com o APM — sem conversão.

7. Boas práticas para extrair o máximo

  1. Pin de versões — use tags (#v1.0.0) e confie no lockfile para reprodutibilidade.
  2. Sempre commit o lockfile — apm.lock.yaml carrega commits e content hashes.
  3. Policy de org/cloud — mantenha apm-policy.yml e rode apm audit --ci na proteção de branch.
  4. MCP transitivo com cuidado — não use --trust-transitive-mcp às cegas; prefira promover o servidor a dependência direta quando fizer sentido.
  5. Unicode / conteúdo oculto — confie no scan do apm install; use apm audit e, se necessário, opções como --strip documentadas.
  6. Targets explícitos — especialmente em multi-harness ou CI sem markers locais.
  7. Pacotes privados — tokens só via ambiente: GitHub GITHUB_APM_PAT → GITHUB_TOKEN → GH_TOKEN; Azure DevOps ADO_APM_PAT. Nunca em arquivos YAML.
  8. Compile Copilot — apm compile -t copilot para instructions agregadas.
  9. Marketplaces para discovery — sem abandonar o modelo “qualquer git repo é package”.
  10. Não misture os planos — APM cuida de install/integridade; sandbox e runtime ficam com o harness.

Princípios de produto relevantes (P1–P7) reforçam: sem frontmatter inventado apm-*, multi-harness com traction gating, vendor neutrality, UX floor em init/install/run, portabilidade, reliability over magic e community over feature count. O manifesto AI-Native soma: portability over vendor lock-in; natural language over code complexity; reusability; reliability over magic; DX over AI sophistication; collaboration over isolation.

8. Enterprise (visão curta)

Para times com requisitos de governança:

  • apm-policy.yml — allow-list de sources, scopes e primitives; herança tighten-only enterprise → org → repo.
  • apm audit / apm audit --ci — reconstrói o contexto em scratch e faz diff com o working tree (detecta hand-edits / drift); o modo CI encaixa em branch protection.
  • SBOM — apm lock export --format cyclonedx|spdx emite inventário a partir do lockfile. Trata-se de export de inventário, não de attestation/SLSA.
  • CI — apm install --frozen + Action oficial microsoft/apm-action.
  • Auth privada — PATs somente em variáveis de ambiente (nunca em YAML).

Lembrete de fronteira: a policy do APM decide o que entra no disco; o harness decide o que executa.

9. O que o APM não faz

Para evitar expectativas erradas:

  • Não é runtime de agente.
  • Não é LLM gateway.
  • Não é ferramenta de fine-tuning.
  • Não é marketplace obrigatório — qualquer repositório git é um package APM válido.
  • Não deixa footprint de runtime após install/compile; não coleta telemetria.
  • Não governa a execução dentro do harness (isso permanece no plano do agente).

O APM resolve git repos, faz deploy de arquivos estáticos, gera output compilado (por exemplo AGENTS.md / instructions) e grava o lockfile. O ciclo de vida termina quando o comando sai.

Top comments (0)