Agent Volumes usesDocumentation Index
Fetch the complete documentation index at: https://agentvolumes.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
[dependencies] for Agent Volumes package dependencies and [component-dependencies] for wiring specific components to components exported by those dependencies. Both tables participate in the same single-version resolution graph, so the constraints you write here directly affect how tooling resolves your package’s Agent Volumes dependency tree.
Use [[external-dependencies]] for package dependencies outside the pkg:volume ecosystem. External dependency declarations are audit metadata for review, policy, BOM export, and potential-exposure diagnostics. They are not resolver inputs.
Volume-level dependencies
Declare volume dependencies in the[dependencies] table. Each key is a volume name — either a bare scopeless name or an @scope/name — and each value is a SemVer constraint string.
Supported constraint syntax
The portable v0.1 grammar supports a constrained npm-like SemVer range syntax. All version operands must be full three-component SemVer strings (with optional prerelease identifiers, without build metadata).- Exact version
- Caret range
- Tilde range
- Comparators
Pin to a specific version.
=1.2.3 and 1.2.3 are equivalent.What is not supported
The portable v0.1 grammar intentionally excludes several syntaxes found in other ecosystems: If you need to support multiple incompatible major versions, publish separate volumes or use a meta volume that depends on one.Component-level dependencies
When a component in your volume depends on specific components from another volume — not just the volume itself — declare those relationships in[component-dependencies].
Each key must be the name of a component declared in this manifest’s [[components]] array. Each value is an array of component purl strings whose subpath has the form <type>/<componentName>.
A component-level dependency implies dependency on the containing volume, but versionless
component purls still rely on the parent volume’s
[dependencies] constraint to determine the
resolved version. After resolution, tooling verifies that the referenced components actually exist
in the resolved version of that volume.Omitting versions in authoring
In[component-dependencies], you may omit the version from a component purl when the parent volume’s dependency constraint in [dependencies] determines the resolved version:
External dependency declarations
Declare non-pkg:volume dependencies with [[external-dependencies]]. These records describe external package ecosystem dependencies with Package URL and VERS rather than Agent Volumes SemVer constraints.
purl,constraint, andpurposeare required.purlmust be a valid external Package URL. It must not use thevolumetype, include a version component, or include a subpath.constraintmust be a VERS expression. Do not interpret it as native npm, PyPI, Cargo, or Agent Volumes SemVer range text unless it is also valid VERS.purposeis one of the core purpose values (runtime,build,development,test,optional,peer,source,documentation,other) or a reverse-DNS extension value such asorg.example:codegen.components, when present, scopes the declaration to declared component names and must be non-empty and duplicate-free.
(canonical purl, purpose, scope). Equivalent declarations with the same semantic key are duplicates, and declarations with the same semantic key but different normalized VERS constraints are conflicts. Stable declaration identifiers use av-extdep-v1:sha256:<lowercase-hex> and exclude constraint from the digest input.
Single-version enforcement
The dependency graph for a resolved install must not contain multiple versions of the same volume. If two volumes in the dependency tree require incompatible version constraints for a shared dependency, the resolver rejects the graph rather than allowing version duplication. This rule keeps the resolved install predictable and prevents subtle behavior differences caused by two versions of the same package running side by side.Version lifecycle states in resolution
During ordinary dependency resolution, tooling only selects versions in theavailable state. If the version index or exact release metadata reports a version in one of the other states, the following rules apply:
| 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 |
yanked version can still be installed when it is exactly pinned in a constraint or already present in a lockfile, but tooling must surface a warning before doing so. A blocked version must not be installed even when exactly pinned.