Use audit reports to hand the activity recorded for an aidb database to an auditor, or to keep a copy outside Agent Governance. An audit report is a CSV file. When Agent Governance produces one, it keeps a record of the export with the SHA-256 hash of the finished file, so you can verify the file later.
Audit reports are available for aidb databases only. Hybrid Manager and Loki sources don't offer them.
Exporting an audit report
Sign in as an Administrator. Other users don't see the Export Audit Report button.
Open the cluster and go to the Activity page. Set the filters to the activity you want in the report: date range, agents, identifier, activity type, and decision status.
To export a single session, connection, conversation, or trace, open it instead and use the button on the session page.
Select Export Audit Report. Review the selection summary in the dialog. To change the selection, close the dialog and adjust the filters. The summary shows:
- Instance and Date, always.
- Agents, when any are selected.
- Identifier, Activity Type, and Status, when those filters are set.
- Activity, when you export a single activity from its page.
Leave Include Sensitive Content off unless the auditor needs the recorded content itself:
- SQL text
- User inputs and model outputs
- Tool call inputs and outputs
- Log record bodies
- Free-text denial reasons
When Include Sensitive Content is off, the columns for those values stay in the file but their cells are empty. The
excluded_fieldscolumn in each row names the values that were left out on purpose.Select Export Audit Report in the dialog. The button reads Exporting Audit Report... while the file is being built.
The browser then downloads the file, and a notice confirms Audit report exported successfully with a Verify this report link.
Note
Keep the file as downloaded. Opening it in a spreadsheet and saving it again changes the bytes, and verification then fails.
Understanding what the selection covers
Filters select whole sessions, not individual rows. When a filter matches a session, the report includes every step of that session, including steps by agents the filter didn't name, so the auditor sees the whole conversation. Each row says which it is: the trace_scope column is matching_trace for rows the filters selected and session_context for rows included as context of a matching session.
Export limits
One export runs at a time per application. An export stops with an error when it would exceed 100,000 records or 50 MB, or when building it takes longer than 45 seconds. The messages are This export is too large and The export took too long, both ending with Choose fewer activities or a shorter date range. To export a long period, split it into several exports.
Understanding the audit report file
The file is UTF-8 CSV with a byte order mark. Read columns by name, not by position. The set and order of columns can change between versions, and some columns are dropped when the viewer runs with governance decisions turned off.
The first row holds the column names. Every following row has a record_type:
record_type | Position | Contents |
|---|---|---|
metadata | Second row | The export record. It identifies the export: export_id, exported_at, instance_id and instance_name, who exported it (exported_by, exported_by_name, exported_by_email), the selection (selection_from, selection_to_exclusive, selection_agents, selection_identifier, selection_types, selection_statuses, selection_activity), sensitive_content_included, the retention settings of the source database at export time, the range of recorded activity the database held, and the telemetry source scope with a provenance_note (see the aidb 7.9.0 item in Prerequisites). It also carries verification_url and verification_instructions for the recipient. |
span | Step rows | One recorded agent action. One session produces many rows. |
log | Step rows | One recorded log record. |
warning | After the step rows | Records the export couldn't read or had to leave out. |
summary | Last row | export_record_count, report_content_status, omitted_decision_records, the sections and fields that have any data, the producer versions seen, and the checksum. |
Use the verification_url only if it matches the address of your own Agent Governance installation, because a tampered file could carry a tampered address.
In the summary row:
export_record_countcounts only thespanandlogrows. It doesn't count the column names, the export record, warnings, or the summary itself.report_content_statusisrecords_present,no_matching_records, orcoverage_incomplete. The last one means some records couldn't be read or the log table wasn't available.checksum_sha256, the last column, is the SHA-256 of the file computed with that cell filled with zeros (checksum_scopeissha256_csv_zeroed_checksum_v1).
Understanding empty cells
An empty cell in a step row can mean four different things. Four columns explain which:
excluded_fieldslists values left out because sensitive content was off.not_recorded_fieldslists values the source never recorded.unresolved_fieldslists values that couldn't be determined.not_applicable_fieldslists values that have no meaning for that kind of row.
Read these columns before you treat an empty cell as evidence that nothing happened.
Understanding how verification works
The checksum_sha256 value lets you check that a file is internally consistent, but not that it's the export Agent Governance produced: whoever edits the file can recompute it. Only the application's own record proves that, because it stores the hash of the finished file, with the checksum already written in. The two hashes differ by design.
The application stores two records for every export, one when it starts and one when the file is ready or the export fails. Each holds the export identifier, the instance, who exported it and when, the selection filters, the outcome, and, for completed exports, the record count, file size, and hash. It doesn't keep a copy of the report.
Verifying an audit report
Sign in with any role. Any signed-in user can verify a report.
Open the cluster menu in the header and select Verify audit report, or follow the Verify this report link after an export. The page is also at
/verify.Drop the CSV file on the page or select it. The file must be a CSV of at most 50 MB. A larger file is rejected in the browser with Choose a CSV file no larger than 50 MB.
Review the result on the page.
Reading a File Verified result
File Verified means the hash of the uploaded file matches the application's record of that export. The page shows:
- Timestamp and Record Count, from the application's record. Record Count counts the step rows only, as in the file's summary row.
- Exported By, Scope & Filters, and Sensitive Content, read from the uploaded file itself, which is trustworthy now that the file is known to be unaltered. Exported By shows the name, email, and sign-in identity that the file holds and skips any of them the file doesn't have.
Compare the details with what you expected the report to cover.
Resolving a Verification Failed result
Use this table to resolve the reasons the page shows with Verification Failed:
| Reason | Cause | Fix |
|---|---|---|
| The file's hash does not match the original record | The file was altered, re-saved, truncated, or is a different export than the record describes. | Obtain the file as originally downloaded and verify it again. |
| No trusted audit record was found for this export | The application has no record of this export_id. | Use the Agent Governance installation that created the report. Records aren't shared between installations. |
| Choose an original Governance CSV audit report | The file isn't an audit report from this application, or its export record is incomplete. | Upload the CSV exactly as downloaded from the export. |
| The file exceeds the upload size limit, The upload could not be completed, Verification is busy, or Verification is unavailable | The upload or the verification service failed. | Try again, with a smaller export or later. |
Interpreting a File Verified result
A matching hash proves that the file is exactly what the application produced. It doesn't prove that the report is complete. Check the summary row for anything the report deliberately or unavoidably left out:
report_content_statusother thanrecords_present- Any
warningrows - A non-zero
omitted_decision_records
Verification compares the whole file, so it can't tell which rows changed, only that the file differs.
Next steps
- Review the activity you plan to export on the Activity page.
- Inspect a single session, connection, conversation, or trace before you export it on the session page.
- Review how Agent Governance handles credentials and recorded data in Securing access and handling credentials.