AgentPM™

Package Discovery#

Where the SDK looks for installed tools, skills, knowledge, memory, profiles, loops, and installed agents on disk.

Goal#

Understand the resolution order and on-disk layout so you can control where installed tools, agents, skills, knowledge packages, memory blueprints, instruction profiles, and loops are loaded from.

Resolution order#

The SDK searches for a tool in this order:

  1. AGENTPM_TOOL_DIR (env var) – Highest priority override.
  2. Project-local: ./.agentpm/tools – Typically created by agentpm install.
  3. User-local: ~/.agentpm/tools – Shared across projects for convenience.

You can also override per call:

  • Node: load(spec, { toolDirOverride: "/path/to/tools" })
  • Python: load(spec, tool_dir_override="/path/to/tools")

For installed agent packages, the SDK searches in this order:

  1. AGENTPM_AGENT_DIR (env var) – Highest priority override for installed agents.
  2. Project-local: ./.agentpm/agents
  3. User-local: ~/.agentpm/agents

You can also override per call:

  • Node: loadAgent(spec, { agentDirOverride: "/path/to/agents" })
  • Python: load_agent(spec, agent_dir_override="/path/to/agents")

For installed skill packages, the SDK searches in this order:

  1. AGENTPM_SKILL_DIR (env var) – Highest priority override for installed skills.
  2. Project-local: ./.agentpm/skills
  3. User-local: ~/.agentpm/skills

You can also override per call:

  • Node: loadSkill(spec, { skillDirOverride: "/path/to/skills" })
  • Python: load_skill(spec, skill_dir_override="/path/to/skills")

For installed knowledge packages, the SDK searches in this order:

  1. AGENTPM_KNOWLEDGE_DIR (env var) – Highest priority override for installed knowledge packages.
  2. Project-local: ./.agentpm/knowledge
  3. User-local: ~/.agentpm/knowledge

You can also override per call:

  • Node: loadKnowledge(spec, { knowledgeDirOverride: "/path/to/knowledge" })
  • Python: load_knowledge(spec, knowledge_dir_override="/path/to/knowledge")

For installed memory blueprint packages, the SDK searches in this order:

  1. AGENTPM_MEMORY_DIR (env var) – Highest priority override for installed memory packages.
  2. Project-local: ./.agentpm/memory
  3. User-local: ~/.agentpm/memory

You can also override per call:

  • Node: loadMemory(spec, { memoryDirOverride: "/path/to/memory" })
  • Python: load_memory(spec, memory_dir_override="/path/to/memory")

For installed profile packages, the SDK searches in this order:

  1. AGENTPM_PROFILE_DIR (env var) – Highest priority override for installed profiles.
  2. Project-local: ./.agentpm/profiles
  3. User-local: ~/.agentpm/profiles

You can also override per call:

  • Node: loadProfile(spec, { profileDirOverride: "/path/to/profiles" })
  • Python: load_profile(spec, profile_dir_override="/path/to/profiles")

For installed loop packages, the SDK searches in this order:

  1. AGENTPM_LOOP_DIR (env var) – Highest priority override for installed loops.
  2. Project-local: ./.agentpm/loops
  3. User-local: ~/.agentpm/loops

You can also override per call:

  • Node: loadLoop(spec, { loopDirOverride: "/path/to/loops" })
  • Python: load_loop(spec, loop_dir_override="/path/to/loops")

Directory layout#

Each tool is stored under an namespace/name/version path:

.agentpm/
  tools/
    @zack/summarize/
      0.1.0/
        agent.json
        dist/...
        prompts/...
        (other packaged files…)
  • The SDK reads the agent.json inside the version folder to determine how to execute the tool.
  • Multiple versions can coexist under the same tool directory; the spec you pass to load() picks the version.

Installed registry agent packages live under the parallel agents layout:

.agentpm/
  agents/
    @zack/support-agent/
      0.1.0/
        agent.json
        README.md
  • loadAgent() / load_agent() resolve from the installed agent directory plus the matching root entry in agent.lock.

Installed registry skill packages live under the parallel skills layout:

.agentpm/
  skills/
    @zack/incident-commander/
      0.1.0/
        agent.json
        SKILL.md
        references/...
        scripts/...
  • loadSkill() / load_skill() resolve from the installed skill directory plus the matching root entry in agent.lock.

Installed registry knowledge packages live under the parallel knowledge layout:

.agentpm/
  knowledge/
    @zack/python-docs/
      0.1.0/
        agent.json
        knowledge/...
  • loadKnowledge() / load_knowledge() resolve directly from the installed knowledge directory.
  • loadAgent() / load_agent() surface resolved knowledge relationships from the matching agent.lock root entry.

Installed registry memory blueprint packages live under the parallel memory layout:

.agentpm/
  memory/
    @zack/profile-memory/
      0.1.0/
        agent.json
        memory/
          build.json
          contracts/
  • loadMemory() / load_memory() resolve directly from the installed memory directory.
  • loadAgent() / load_agent() surface resolved memory relationships from the matching agent.lock root entry.

Installed registry profile packages live under the parallel profiles layout:

.agentpm/
  profiles/
    @zack/support-style/
      0.1.0/
        agent.json
        README.md
  • loadProfile() / load_profile() resolve directly from the installed profile directory.
  • loadAgent() / load_agent() surface resolved profile relationships from the matching agent.lock root entry.

Installed registry loop packages live under the parallel loops layout:

.agentpm/
  loops/
    @zack/incident-response-loop/
      1.0.0/
        agent.json
        README.md
  • loadLoop() / load_loop() resolve directly from the installed loop directory.
  • loadAgent() / load_agent() surface singular resolved loop relationships from the matching agent.lock root entry when present.

Not included here#

Templates are not SDK-loadable package artifacts today.

  • The CLI can install and expand Templates through agentpm new.
  • The Node and Python SDKs do not provide loadTemplate() / load_template().
  • This page therefore covers the full installed-package discovery model for the package kinds the SDKs can actually load.
←SDKsPython SDK
→SecurityMFA