Provenance Records for Agent-Produced Artifacts

What a provenance record establishes

A provenance record is a machine-readable account of how a particular artifact was produced. For an artifact created by an agent, it connects the output bytes to the producing agent or builder, the source and inputs used, the relevant toolchain state, the policy decisions made during the run, and the execution identifier needed to investigate it later.

The record is evidence, not a verdict. It can show that named inputs went through a named production process, but it does not by itself show that the output is correct, safe, approved, or fit for use. Those conclusions depend on a consumer checking the evidence against explicit expectations.

The useful model comes from the SLSA v1.2 specification and its provenance model, accessed August 26, 2026. SLSA defines provenance as verifiable information about where, when, and how an artifact was produced. Its build provenance structure separates the definition of the work from the details of one execution: buildDefinition describes the process and inputs, while runDetails identifies the builder and invocation.

That separation applies cleanly to agent-produced artifacts. The agent run is the invocation. The agent runtime, orchestration service, or controlled pipeline is the builder. Prompts, source files, configuration, retrieved material, tool packages, and referenced artifacts are inputs. The produced archive, image, document, executable, patch bundle, or dataset is the subject.

A record must bind to the bytes

Bind the provenance record to the output artifact by digest. The record must carry both the digest algorithm and the digest value for its subject. A consumer recomputes that digest from the artifact it actually received and requires an exact match.

This binding matters because a filename, object key, release label, URL, or database identifier can be reassigned. report-final.pdf, latest, and a mutable download URL identify locations or names, not immutable content. If the record names only one of those references, the same record can later appear beside different bytes without producing an obvious contradiction.

A digest changes the identity rule: the provenance applies to these bytes, not merely to an artifact bearing this name. Replacing or editing the artifact produces a different digest, so the existing record no longer matches. The substitution becomes detectable when verification runs.

The subject binding should be created from the final emitted artifact. If another process compresses, signs, packages, normalizes, or otherwise changes the bytes after the agent run, that result is a different artifact and needs its own digest binding. A record for an unpacked directory does not automatically describe a later archive of that directory. A record for generated source does not automatically describe the executable compiled from it. Each material production boundary needs an explicit subject.

A digest alone is not provenance. It detects that the consumer has different bytes from those named in the record, but it does not identify who produced the record or whether its contents are trustworthy. Conversely, signed provenance without a checked subject digest may be authentic metadata attached to the wrong artifact. Useful verification needs both the record’s integrity and its binding to the artifact.

The practical cost is an extra artifact-handling path: compute the digest after finalization, emit or attach the record, retain both, and make the consumer verify them together. If the distribution system permits an artifact to move without its provenance, or silently selects provenance by filename, the binding is incomplete even when the record contains a digest.

Identify the producer and its trust boundary

Record the producing agent or builder with a stable identity that a consumer can put into policy. A display name such as “release agent” is descriptive but insufficient if several runtimes, configurations, or operators can use it. The identity needs to distinguish production environments with different security properties.

In the SLSA model, builder.id represents the build platform trusted to execute the work and populate the provenance accurately. For an agent workflow, that identity may correspond to the controlled agent service, its orchestrator, or a specific production mode. It should not imply a narrower trust boundary than the system actually has. If a hosted runner and a self-managed runner expose different controls, treating both as one builder identity removes the consumer’s ability to allow one and reject the other.

Keep the producer identity distinct from the signer identity. A signing service can issue records for more than one builder, while a builder may use a signing system operated elsewhere. The consumer therefore needs to approve the signer-builder relationship, not merely accept any record carrying a valid signature.

Record the agent definition or builder version needed to distinguish meaningful production changes. If the agent’s behavior is governed by a versioned prompt or instruction bundle, bind that version as an input rather than leaving only a copied prompt string in logs. The same principle underlies versioning prompts used by agents: a consumer and an investigator need an immutable revision, not a mutable label.

Record the production context

The provenance record needs enough context to answer what ran, what it consumed, and which decisions shaped the output. At minimum, capture the producing agent or builder, source revision, tool versions, resolved inputs, policy decisions, and run identifier.

Treat these as investigation fields as well as admission-control fields. Some values will be compared automatically before use; others will matter when an artifact is questioned weeks later. A field that exists only in an ephemeral execution log does not help if that log expires before the artifact does.

The producing agent or builder identifies the trusted execution boundary. The source revision identifies the code and configuration that defined the run. Tool versions identify executable components that could change behavior independently of the source. Resolved inputs identify the concrete objects actually consumed rather than the names requested before resolution. Policy decisions explain which guarded actions or substitutions were allowed. The run identifier connects the record to execution logs and other evidence.

Use structured fields with declared meanings. A single free-form “context” string is hard to compare with policy and easy to populate inconsistently. A provenance schema should state which fields are required, which party supplies them, which values are covered by the record’s signature, and whether completeness is guaranteed or best effort.

Do not treat absence as a benign value. If the consumer requires a source revision or resolved tool digest, a missing field is not equivalent to an approved revision. The verifier needs an explicit rule for incomplete provenance and should reject the artifact whenever a required expectation cannot be evaluated.

Resolve source, tools, and other inputs

Record the source revision at the immutable revision the producer actually read. A branch name or tag can describe the requested input, but it does not establish which commit supplied the bytes. Preserve both when both matter: the external parameter can carry the requested reference, while a resolved dependency carries the resulting revision or digest.

Agent workflows often have more behavior-bearing inputs than a conventional compile command. The source set may include repository content, workflow configuration, system instructions, prompt templates, tool schemas, policy bundles, and transformation settings. Remote or generated material may also affect the result. Include an input when changing that input could change the artifact or the decision to produce it.

Resolved inputs should identify concrete content. A package range, model alias, moving container tag, unversioned prompt name, or latest-document URL records intent but not resolution. Store the version, revision, or digest selected during the run where that information is available. This is also why pinning dependencies in agent tool runtimes and provenance serve different roles: pinning constrains what may be selected, while provenance records what was selected for this artifact.

Record tool versions at the layer that can affect execution. The agent application version alone does not identify separately updated tool servers, command-line programs, packages, or schemas. Where a tool is itself an artifact, a content digest gives a stronger binding than a human-readable version string. Where only a version is available, record it without implying that it uniquely identifies the bytes.

A tool’s interface is also an input to the agent’s behavior. If a tool schema changes while its name remains constant, the same model and prompt may receive different operations or argument definitions. Bind the applicable schema revision when it affects the run; versioning agent tool schemas covers the release discipline around that input.

Completeness has a real operational cost. Recording every transitive component can produce a large dependency graph, and some inputs may be supplied through systems that do not expose immutable identifiers. State the completeness boundary instead of presenting a partial record as exhaustive. A consumer can then decide whether best-effort dependencies meet the policy for that artifact class.

Sensitive input content does not have to be copied into provenance merely to identify it. A record can use a digest and an authorized location while the protected value remains elsewhere. The schema still needs enough information for an approved investigator or verifier to resolve the evidence when required.

Preserve policy decisions that affected the run

Record policy decisions that changed what the agent could do or what output it produced. Relevant decisions include allowing or denying a tool call, accepting a source or dependency, granting an exception, approving a fallback, or requiring human authorization. The record should identify the policy or rule version, the decision, and the evidence reference needed to understand it.

Do not reduce policy evidence to a final allowed: true. That result cannot explain which policy was evaluated or whether an exception changed the outcome. A useful decision record distinguishes the applicable policy version from the facts evaluated under it and from the resulting action.

The provenance does not need to duplicate the full policy engine log. It can bind to a retained decision artifact by digest and carry the decision fields a consumer must check directly. This keeps the main record verifiable while preserving a route to deeper evidence during investigation.

Policy evidence belongs inside the integrity boundary. If a policy decision can be edited after the provenance is issued without invalidating a signature or digest, it cannot reliably explain why the artifact was admitted. The same applies to human approvals: record an immutable reference to the approval evidence rather than a mutable ticket status.

This is where provenance meets the permission model for agent tools. The permission model states what an agent may do; the provenance record states which policy and decisions governed the run that produced these bytes. Neither replaces the other.

Carry a run identifier into the evidence trail

Record a run identifier that uniquely selects the production invocation. SLSA names the corresponding field invocationId and describes it as useful for finding associated logs or other analysis.

The identifier is a join key, not proof. It should connect the provenance to retained execution logs, approvals, policy decisions, tool traces, and byproducts without being treated as an integrity check. Anyone may be able to copy an identifier; trust comes from the protected provenance record and the systems that resolve the identifier.

Generate the identifier before evidence is emitted and carry it consistently through the run. Retries and resumed work need distinguishable invocation records when they execute independently or can produce different bytes. If several invocations contribute to one final artifact, the final production record should bind to the contributing artifacts or records rather than collapse their histories into one ambiguous identifier.

Retention must be long enough for the identifier to remain useful for the artifact’s investigation period. Keeping an invocation ID after all referenced evidence has expired preserves a label but not an investigation trail.

Protect and retain the record

Protect provenance from alteration and retain it with the release evidence. The NIST Secure Software Development Framework version 1.1, published February 2022, calls for securely archiving release files and supporting data such as integrity-verification and provenance information. It also calls for collecting, safeguarding, maintaining, and sharing provenance data for release components, protecting its integrity, and giving recipients a way to verify that integrity.

A signature over a provenance envelope lets a consumer authenticate the issuer and detect changes to signed fields. The signature must cover the subject digest and the production fields on which policy relies. Storing the artifact and record together is convenient, but their location does not establish their integrity.

Retention policy should cover the artifact, provenance, verification material, and referenced evidence as one investigation set. Deleting the builder’s identity documentation, signing verification material, resolved decision records, or logs can make a retained provenance record impossible to interpret.

Access controls also matter. Producers need a controlled path to issue records, consumers need read access, and investigators need access to the referenced evidence. Write access should not allow an ordinary artifact publisher to rewrite historical provenance without detection.

Verification is the risk control

Provenance only reduces risk when a consumer verifies the artifact digest and compares the recorded builder and inputs with explicit expectations. Collecting records without enforcing those checks produces an archive, not an admission control.

The SLSA v1.2 artifact-verification guidance, accessed August 26, 2026, says verification should authenticate the provenance envelope, confirm that the statement’s subject matches the artifact digest, accept only recognized builder identities, and compare the build type and external parameters with expected values. It also recommends rejecting unrecognized external parameters because an unexpected parameter can introduce behavior that the consumer’s policy never assessed.

For an agent-produced artifact, explicit expectations should cover at least:

• the accepted signer and producing agent or builder identity;
• the allowed source repository and revision rule;
• the agent or workflow type used to interpret the inputs;
• the permitted external parameters;
• required prompt, configuration, policy, tool, and schema revisions;
• required resolved inputs and their accepted digests or origins;
• the policy decisions or approvals required for this artifact class.

The verifier first computes the digest of the artifact under consideration and matches it to the provenance subject. It then authenticates the record and establishes which producer identity issued it. Only then does it compare the production fields with the consumer’s policy. A valid signature does not turn an unapproved builder or source into an approved one.

Expectations must exist outside the untrusted artifact-provenance pair. If the same record can declare both “builder X produced this” and “builder X is trusted,” the check is circular. Keep trusted builder identities, accepted sources, allowed parameters, and decision requirements in verifier configuration or another authenticated policy channel.

Verification should fail closed for missing required fields, unknown producer identities, unrecognized parameters, digest mismatches, and disallowed input revisions. A warning that does not stop installation, publication, or deployment may help investigation, but it does not enforce the expectation.

Verification can occur at publication, download, deployment, or more than one boundary. The important condition is that at least one component able to block use performs the check. A registry-side check does not prove that a later consumer received the same bytes unless the consumer’s path also preserves or rechecks the verified identity.

What provenance does not establish

Provenance does not establish that an agent’s output is factually correct, free of vulnerabilities, policy-complete, or suitable for a particular environment. It states how identified bytes were produced and supports comparison with expectations.

It also cannot make an untrusted producer trustworthy. If the builder can alter the artifact and invent matching provenance, the record faithfully authenticates only the builder’s claim. The consumer still needs a justified root of trust and an understanding of which fields the builder guarantees.

A complete-looking record may still omit an influential input. State which input classes the producer captures and how completeness is enforced. Where capture is best effort, consumers should treat it as such rather than infer a closed, reproducible environment.

Reproducibility and provenance answer different questions. A provenance record describes one run. Reproducing the run may test parts of that description, but identical inputs do not guarantee identical bytes when the process contains nondeterminism. Conversely, inability to reproduce an artifact does not erase the value of authentic, digest-bound evidence about the original invocation.

What to define next

A production design needs a provenance schema or profile, an issuing trust boundary, retention rules, and verifier policy. Define the artifact types covered, when their final digests are computed, which agent and builder identities exist, which inputs are mandatory, how policy decisions are bound, and how invocation evidence is retrieved.

Define expectations per artifact class before accepting records. A generated document, deployable binary, container image, and dataset may require different sources, tools, approvals, and completeness guarantees. Record those differences in policy rather than asking operators to interpret free-form provenance during a release.

Finally, test the full path with deliberate failures: changed artifact bytes, an unknown builder, an unexpected parameter, a disallowed source revision, a missing resolved input, and an expired evidence reference. The provenance system is working only when those conditions are detected before the artifact is used and the retained run identifier still leads an investigator to the evidence behind the decision.