Every volume and every component it exports has a globally unique identifier built on the Package URL (purl) specification. The Agent Volumes identity scheme uses theDocumentation Index
Fetch the complete documentation index at: https://agentvolumes.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
volume purl type, making identifiers compatible with existing supply chain security tooling while precisely addressing the needs of agent component packaging. Understanding these identifiers helps you reference dependencies, target specific components, and work with trust and provenance tooling correctly.
Volume identifiers
Scopeless volumes
When a bibliotheca supports scopeless names, the identifier is simply:Scoped volumes
When a volume belongs to a publisher scope, the scope is encoded as the purl namespace with@ URL-encoded as %40:
%40 encoding is required in canonical purl strings per purl encoding rules. In user-facing contexts — manifests, search results, display — the decoded form @scope/name is used instead (e.g., @acme/research-agent-pack).
Versioned identifiers
Append a SemVer version string after@ to identify a specific release:
sha256:... digest of the release’s normalized file tree.
Component identifiers
Components exported from a volume are addressable via the purl subpath field, which takes the form<type>/<componentName>:
Component types as purl subpath values
The<type> segment in a component purl must be one of these seven values:
| Subpath type | Component kind |
|---|---|
agent | Autonomous runtime actor |
skill | Reusable task capability loaded into agent context |
command | User-invokable slash-command action |
tool | Function or API callable by an agent |
hook | Runtime lifecycle event interceptor |
mcp-server | Model Context Protocol server endpoint |
lsp-server | Language Server Protocol server endpoint |
[component-dependencies] in volume.toml), you may omit the version when the parent volume’s dependency constraint determines the resolved version. For trust, lock-like reproducibility inputs, or exact component identity, include the resolved version.
Naming rules
The same naming policy applies to scopes, volume names, and component names:- Names must consist only of lowercase ASCII letters, digits, and hyphens.
- Names must not start or end with a hyphen.
- Names must not contain consecutive hyphens.
- Scoped names must be unique within their scope.
- Component names must be unique within a volume across all component types.
| Field | Max length | Scope required |
|---|---|---|
scope | 64 characters | Per bibliotheca policy |
name (volume) | 128 characters | Always required |
componentName | 128 characters | Always required |
purl field mapping
The table below shows how Agent Volumes identity maps onto purl fields:| purl field | Agent Volumes mapping |
|---|---|
type | Always volume |
namespace | %40<scope> for scoped volumes; absent for scopeless |
name | Volume name |
version | SemVer version string |
qualifiers | Reserved for future use (e.g., ?repository_url=...) |
subpath | <type>/<componentName> for component references |
Logical identity vs. immutable content identity
Every published release carries two complementary identities that must both be preserved:Logical identity
pkg:volume/...@version — the package-facing release identity. Used for dependency declarations, search, display, and trust attachment subjects.Immutable content identity
sha256:<hex> — the digest of the release’s normalized file tree. Used for integrity verification, trust binding, and supply chain workflows.sha256 digest. A mismatch between the two means the release metadata is inconsistent and the release must be rejected.
Identifier resolution order
When a client needs to resolve a volume identifier to an installable release, it follows this order:Check the lockfile
If a lockfile is present, use the pinned versions and resolved source metadata it contains.
Query configured bibliothecas
Use package-scoped version indexes from configured registries to discover eligible version
candidates.
Registry-priority policy across independently configured bibliothecas is not standardized in v0.1.
Each client applies its own local policy for source selection across multiple registries.
Version lifecycle states
During ordinary dependency resolution, a client must only select versions in theavailable state. The other states affect resolution and installation as follows:
| State | Ordinary resolution | Exact pinned install |
|---|---|---|
available | Allowed | Allowed |
yanked | Excluded | Allowed with warning |
tombstoned | Excluded | Fails |
blocked | Excluded | Fails |
unavailable | Excluded | Fails or reports availability error |