Agent Volumes introduces a precise vocabulary to describe how agent components are packaged, identified, distributed, and verified. Understanding these concepts helps you author correct manifests, reason about package identity, and integrate with the trust model. This page defines each term and shows where it appears in practice.Documentation 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
Volume
A volume is the distribution unit of the Agent Volumes ecosystem. It is a versioned package that usually exports agent components;
role = "meta" volumes can instead act as dependency bundles with no mandatory exported components.A volume is to agent components what an npm package is to JavaScript modules, or what a Python wheel is to Python code. You publish a volume to a bibliotheca, and users install it into their agent runtime.Every volume has:- A name — scopeless (
research-agent-pack) or scoped (@acme/research-agent-pack) - A version — a SemVer string such as
1.4.0 - A manifest — the
volume.tomlfile at its root - Optional components — the actual agent capabilities it exports, unless the volume is a dependency-focused bundle such as
role = "meta"
Bibliotheca
Bibliotheca
A bibliotheca is a registry that indexes, hosts, and serves volumes — the Agent Volumes equivalent of npmjs.com, PyPI, or crates.io.Bibliothecas implement the Agent Volumes Registry API, which covers:
- Publishing and fetching volumes
- Version discovery and search
- Trust metadata upload and retrieval
- Security advisories
- Capability metadata
Bibliothecas define their own policies for scope governance, moderation, and pricing. These
policies are local to each registry and are not standardized by the Agent Volumes specification.
volume.toml
volume.toml
volume.toml is the package manifest file for a volume. Every volume must include a volume.toml at its root — it is the authoritative source for package metadata, component declarations, dependencies, compatibility requirements, and permissions.The format is TOML v1.1.0. The manifest is analogous to package.json for npm or Cargo.toml for Rust.Minimal manifest:schema field is currently always 1. Tooling rejects manifests with unrecognized schema versions. See the Manifest reference for the full field reference.Package identity and purl
Package identity and purl
Every volume and component has a globally unique identifier expressed as a Package URL (purl) using the Component identifiers use the purl subpath field to address a specific component within a volume:The subpath format is
volume type. This identifier is used in dependency declarations, supply chain tooling, BOM generation, and trust workflows.Volume identifiers:<type>/<componentName>, where type is one of the seven component type identifiers.In user-facing contexts such as manifests, search results, and display, the decoded form
@acme/research-agent-pack is used. In portable payloads such as BOM entries and provenance
subjects, the encoded purl form pkg:volume/%40acme/... is used. These two forms are not
byte-for-byte interchangeable.Component
Component
A component is a functional unit exported by a volume and executed by an agent runtime. Every component belongs to one of seven types, each with distinct semantics, an entrypoint format, and an invocation model.
Each component is declared in For full semantics and entrypoint format details for each type, see Component Types.
| Type | Type identifier | Invoked by | Execution model |
|---|---|---|---|
| Agent | agent | Runtime | Autonomous, long-running |
| Skill | skill | Runtime (contextual) | Loaded into context |
| Command | command | User (explicit) | Trigger-based |
| Tool | tool | Agent (programmatic) | Stateless function call |
| Hook | hook | Runtime (event) | Event-driven |
| MCP Server | mcp-server | Runtime or agent | Long-running service |
| LSP Server | lsp-server | Runtime or agent | Long-running service |
volume.toml under [[components]] with a type, name, and entrypoint. Component names must be unique within a volume across all component types.Publisher and scopes
Publisher and scopes
A publisher is an individual or organization that publishes volumes to a bibliotheca. Every A scope is a publisher namespace, written as Publisher verification status — whether a publisher’s identity has been cryptographically verified — is managed by the bibliotheca, not declared in the manifest. The
volume.toml must include a [publisher] table that identifies the publisher:@scope. Scoped volume names follow the pattern @scope/name, for example @acme/research-agent-pack. Scopes let organizations publish groups of related volumes under a single namespace.publisher.id field is a package identity claim, not a verification credential.Scope governance policies (how scopes are created, transferred, and managed) are local to each bibliotheca and are not standardized by this specification.Trust attachments
Trust attachments
A trust attachment is a release-scoped artifact that provides cryptographic evidence about a published volume. Trust attachments are associated with the volume’s release subject — identified by its purl and content digest together.The four categories of trust attachment are:
Trust attachments are uploaded separately from the volume content, typically as part of a CI/CD publish workflow. They are retrieved through the Registry API’s trust endpoints. Security advisories are a separate advisory discovery surface, not a trust attachment category.
| Category | Description |
|---|---|
| BOM | A CycloneDX Bill of Materials listing the volume’s components and their dependencies. |
| Provenance | A SLSA provenance statement linking the release to its source repository and build process. |
| Signature | A Sigstore-family cryptographic signature over the release artifact. |
| Other | A release-scoped trust artifact that does not fit the core categories. |
Bibliothecas may compute derived judgments — verification labels or policy outcomes — based on
the trust attachments they hold. Derived judgments are not canonical trust facts; the raw
attachments are the authoritative record.
Content integrity and immutable content identity
Content integrity and immutable content identity
Agent Volumes uses content integrity to ensure that what you install is exactly what was published. Every published release has two identities that work together:This pair is the subject used in provenance attestations, BOM entries, and signature verification. Clients verify the digest after download before loading or executing any component.
- Logical identity: the
pkg:volume/name@versionpurl — the package-facing identifier you use in dependency declarations and tool calls. - Immutable content identity: a
sha256:...digest of the normalized file tree — a cryptographic anchor that uniquely and permanently identifies the exact byte content of the release.
Package roles
Package roles
Every volume declares a role that describes its purpose at the package level. The role appears in the
A volume declares one primary role and may add The
[volume] table and influences how bibliothecas categorize and display the volume.| Role | Description |
|---|---|
component | A standalone component package — a single skill, tool, command, hook, or server with no broader integration intent. |
plugin | An extension package that adds capabilities to an agent runtime. Most volumes that bundle related components together use this role. |
provider | A package that integrates with an external service or system (e.g., a GitHub integration, a database connector). |
meta | A meta-package used to distribute curated collections. It has no mandatory exported components, and its value is usually in dependencies. |
secondary-roles:providers field lists the external services the volume integrates with. These are discovery-oriented identifiers used for search and filtering — for example, github, slack, postgres, docker, or openai.How the concepts relate
These concepts form the core data model of Agent Volumes:volume.toml manifest and, when it exports components, component entrypoint files. Each exported component within the volume is addressable by its purl subpath. The volume’s release is anchored by its content identity digest. Trust attachments provide cryptographic evidence about the release.
Next steps
Manifest reference
Every field in volume.toml, with types, constraints, and examples.
Implementers guide
Follow a practical path for clients, bibliothecas, validators, exporters, and runtime adapters.
Package identity
The purl scheme in depth: scoped names, encoding rules, and resolution order.
Component types
Entrypoint formats, invocation models, and semantic rules for all seven types.
Supply chain security
The full trust model: content integrity, publisher identity, provenance, and advisories.