Skip to contents

Writes a self-contained, hash-sealed archive of a run: the study agent_manifest() (manifest.json), the transcript (transcript.csv), the event / call / tool / state views, the per-call provenance (calls.jsonl: this run's records from the LLMR audit log, copied verbatim, when one was kept), any artifacts, a drafted methods note (README-methods.md), and a hashes.sha256 manifest over every file written. The archive is the supplementary material a paper can ship: it carries the declared specification and the calls' provenance, not just the prose.

Usage

archive_agent_study(
  run,
  path,
  include_messages = TRUE,
  redact = NULL,
  formats = c("csv", "jsonl", "rds"),
  overwrite = FALSE
)

# S3 method for class 'agent_archive'
print(x, ...)

Arguments

run

An object accepted by as_agent_run() (an Agent, a conversation or preset result, a pipeline, an experiment, or an agent_run).

path

Directory to write into; created (recursively) if absent.

include_messages

If TRUE (default), write the transcript and the free-text columns of the tool and state tables. If FALSE, those tables are still written but their free-text columns are replaced by "[OMITTED]", keeping only structure, hashes, and metadata; the records in calls.jsonl likewise omit the request body and reply text (each record keeps its precomputed request_hash, so the join invariant holds).

redact

Optional redaction applied to the free-text columns of the written transcript, tool, and state tables (text, content, arguments, result, response_text) and to the reply text of the records in calls.jsonl – never to hashes, and never to a request body, which is the call's identity (omit request bodies with include_messages = FALSE). Either a function(text) -> text, or a character vector of regular expressions, each of which is replaced by "[REDACTED]". Redaction is applied to the on-disk copy after hashing, so the join invariant holds.

formats

Which optional formats to write, any of "csv" (the tabular views), "jsonl" (events and calls; always written), and "rds" (the privacy-filtered, data-only run snapshot as run.rds). Defaults to all three.

overwrite

If FALSE (default), refuse a non-empty path. Set to TRUE to replace archive files in an existing directory; other files in it are left alone.

x

An agent_archive.

...

Unused.

Value

Invisibly, an object of class agent_archive: a list with path, files (relative paths written), manifest_hash (NA when the manifest could not be built), n_calls (NA when the call records could not be read), calls_source (where calls.jsonl came from, or "none"), llm_log_compatible (whether calls.jsonl is an LLMR audit log), and write_failures (a tibble with columns file and error, with no rows when every file was written). Print lists what was written and whether it was sealed.

Details

The archive is privacy-preserving at its serialization boundary: run.rds is a data-only snapshot of the same projected levels written to the text formats. Live agents, callers, tool functions, model configurations, and configuration secrets are never serialized into the archive. Message omission and redaction apply to this snapshot as well as the text files. They do not reach the manifest, artifacts, or error messages.

Hashes are identity, not outcome. The request_hash in calls.jsonl is computed over the original request, so a call read back from the archive still matches the same call issued live. Redaction therefore never touches a hash or a request body, and when an LLMR audit log is present this run's records are copied byte-for-byte rather than reserialized – unless a privacy lever is engaged: with include_messages = FALSE each copied record's request body and reply text are removed (its precomputed request_hash is kept, so the join survives), and with redact the copied records' reply text is scrubbed.

A record is this run's when its request hash matches one of the run's calls and, where both carry one, so does its response id, which keeps an earlier identical request out. When a response id is missing on either side, or more records match than the run made calls, the function warns that an earlier identical request can be among the copied records. The rest of the log is never copied. When the log cannot be read, or the run's calls carry no request hashes, calls.jsonl is rendered from the run's own call records instead, with a warning. When a privacy lever cannot be applied, the copied records are removed and calls.jsonl is not written.

Each file is written in its own step. A file that cannot be produced is removed, recorded in write_failures, and reported in one warning at the end; the rest of the archive is still written. A level of the run that cannot be read is not written as an empty table (a level that is readable and empty is), run.rds is omitted when any of its levels cannot be read, and no manifest.json is written when the manifest cannot be built. The seal is written last, over the final bytes of every other listed file, and is listed only when it was written; the methods note lists it only then. A partial archive is still sealed. A checksum identifies bytes; it does not establish that the run's record is complete. A destination directory that cannot be created, or a failed file that cannot be removed, is an error.

Examples

a <- agent("Aria", LLMR::llm_config("groq", "openai/gpt-oss-20b"), quiet = TRUE)
a$memory$add("user", "Hello")
dir <- file.path(tempdir(), "aria-study")
arch <- archive_agent_study(a, dir, include_messages = FALSE)
arch
arch$write_failures
unlink(dir, recursive = TRUE)

if (FALSE) { # \dontrun{
a$chat("Hello")
archive_agent_study(a, tempfile("study_"))
} # }