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.
Arguments
- run
An object accepted by
as_agent_run()(an Agent, a conversation or preset result, a pipeline, an experiment, or anagent_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. IfFALSE, those tables are still written but their free-text columns are replaced by"[OMITTED]", keeping only structure, hashes, and metadata; the records incalls.jsonllikewise omit the request body and reply text (each record keeps its precomputedrequest_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 incalls.jsonl– never to hashes, and never to a request body, which is the call's identity (omit request bodies withinclude_messages = FALSE). Either afunction(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 asrun.rds). Defaults to all three.- overwrite
If
FALSE(default), refuse a non-emptypath. Set toTRUEto 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_"))
} # }