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

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

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

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:

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

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

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

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

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

Marketplace

apm marketplace add github/awesome-copilot
apm install azure-cloud-development@awesome-copilot

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

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

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.