Skip to main content
This page describes Agent Journal 1.11.0 (1.x). It does not apply to 2.0, the current line on main, which has a different format; see Which Journal do I need?.
This tutorial records one LLM call and one tool call, then persists the run to local JSON and JSONL files.

Requirements

  • Java 17 or later for journal-core
  • Maven 3.9 or the Maven Wrapper

1. Add journal-core

2. Configure local storage

Configure storage before creating a run:
The default backend is InMemoryStorage, so a run is not durable unless you configure storage.

3. Record a run

Run implements AutoCloseable. Normal closure produces FINISHED; call run.fail(exception) to record FAILED explicitly. The capture modules’ RunRecorder behaves differently: it records CRASHED unless finish() was called, so a recording that threw is not mistaken for a complete one.

4. Inspect the files

The example produces this layout:
The first events.jsonl line is a header that names the schema version and the library version that wrote the file. Each following line is one event and carries an @type discriminator.
Use caller-controlled trusted identifiers for experimentId, runId, and artifact names. Version 1.11.0 does not enforce path containment for those values, so do not pass untrusted path fragments or separators.

5. Isolate tests

Use the in-memory backend and reset global state around each test:

Next steps

Core concepts

Learn what is persisted and what is derived.

Analyze runs

Query the generated event files with DuckDB.