Capability Packaging, Versioning, and Dependency Resolution
Make agent capabilities reproducible, composable, and safely replaceable.
A rapid review of the chapter’s existing Quick Read, principles, definitions, lessons, and review material.
The chapter in one pass.
- Purpose: Make agent capabilities reproducible, composable, and safely replaceable.
- Best for: Engineers building agent definitions, skills, tools, prompts, adapters, and factory manifests.
- Prerequisites: Capability Supply Chain and Registries.
- Reading time: 12 minutes.
- You will learn: How to package capabilities, version behavioral contracts, resolve dependency graphs, and qualify combinations.
- Keep three ideas: version behavior, not filenames; lock complete graphs for execution; and prove compatibility with conformance tests.
Reconstruct and defend this chapter’s architecture.
Reconstruct the architecture, name each boundary, and defend the tradeoffs.
Open the source exercise
Design resolution for a repository-review agent with two alternative model routes and a tool available only in one environment. Add a critical tool revocation during an active Attempt. Separate behavior for the active Attempt, queued work, and historical replay.
3. Enduring Principle
Package the smallest independently governed unit
A capability package contains a manifest, source or content, schemas, tests, evaluation references, provenance, and signature. The package should be immutable after publication. A correction creates a new version.
The manifest separates:
- identity: canonical name, type, owner, source, digest;
- behavioral contract: purpose, inputs, outputs, side effects, failure modes;
- operating contract: runtime, harness, model, environment, network, storage;
- authority requirements: scopes, credentials, approvals, data classes;
- quality contract: required tests, evaluations, thresholds, limitations; and
- lifecycle contract: support window, deprecation, migration, revocation.
Version on material behavior
A major change breaks consumers or widens authority. A minor change adds backward-compatible behavior or eligibility. A patch corrects behavior without changing the declared contract. Because prompts and models are behavioral dependencies, even a seemingly small text or provider change may require new evaluation and a new package digest.
Resolve before execution
Resolution converts ranges, aliases, policies, and environment constraints into an immutable graph. The lock must include transitive dependencies and the reason each version was selected. Execution receives the lock; it does not discover a materially different graph mid-Attempt.
Requested capability
-> policy and tenant eligibility
-> version constraints
-> transitive dependency graph
-> compatibility matrix
-> vulnerability and revocation checks
-> immutable resolution lock
-> Factory Version and Execution Manifest
Test combinations, not labels
Conformance suites should exercise tool discovery, schema validation, permission denial, cancellation, timeout, streaming, artifact capture, structured completion, and teardown. A compatibility declaration without a passing suite is an assertion, not evidence.
8. Notes and lessons learned
Reproducibility is a graph property. Pinning the model while leaving tools, prompt fragments, skills, or runtime images mutable produces a precise-looking identifier for an imprecise system.
9. Interview and discussion questions
- Which changes require a new capability version?
- When is a provider fallback compatible, and when is it a new experiment?
- What belongs in a resolution lock?
- How should deprecation differ from revocation?
- Why are compatibility matrices insufficient without conformance tests?
Review this chapter.
Challenge a claim, boundary, missing failure mode, unclear term, or unsupported evidence statement.
- Claim
- Boundary
- Failure
- Evidence