Skip to main content
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.
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.toml file at its root
  • Optional components — the actual agent capabilities it exports, unless the volume is a dependency-focused bundle such as role = "meta"
Example purl:
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
Any compliant server can act as a bibliotheca. The Alexandria bibliotheca is the reference implementation maintained by Windlass.
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 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:
The schema field is currently always 1. Tooling rejects manifests with unrecognized schema versions. See the Manifest reference for the full field reference.
Every volume and component has a globally unique identifier expressed as a Package URL (purl) using the volume type. This identifier is used in dependency declarations, supply chain tooling, BOM generation, and trust workflows.Volume identifiers:
Component identifiers use the purl subpath field to address a specific component within a volume:
The subpath format is <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.
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 volume.toml under [[components]] with a type, name, and entrypoint. Component names must be unique within a volume across all component types.
For full semantics and entrypoint format details for each type, see Component Types.
A publisher is an individual or organization that publishes volumes to a bibliotheca. Every volume.toml must include a [publisher] table that identifies the publisher:
A scope is a publisher namespace, written as @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 verification status — whether a publisher’s identity has been cryptographically verified — is managed by the bibliotheca, not declared in the manifest. The 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.
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.
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.
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:
  • Logical identity: the pkg:volume/name@version purl — 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.
The content digest is computed by constructing a normalized file tree from the volume’s contents, sorted canonically, and hashing the result with SHA-256. Any modification to any file — including the manifest — produces a different digest.Example release subject (logical identity + content identity 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.
Every volume declares a role that describes its purpose at the package level. The role appears in the [volume] table and influences how bibliothecas categorize and display the volume.A volume declares one primary role and may add secondary-roles:
The 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:
A publisher publishes a volume to a bibliotheca. The volume contains a 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.