Agent report
Give your agent a run as compact JSON instead of an HTML report. The agent report names the failure, the steps and the evidence each one kept, and one step can be inspected on its own.
Try it autonom agent export --bundle <dir> --out agent.json
Needs a flow run
How it works
agent export writes one autonom.agent-report/v1 file. agent inspect prints a single step, with the run's attempt and only that step's attachments. Both read the same report, from one of two sources:
A report bundle, with
--bundle. Autonom verifies every file of the bundle against its digest before it reads anything, so an edited bundle is refused instead of reported on.A run of a session, with
--run, from the current session or the one--sessionnames. A stopped session works too. With no--run, the session's latest run is read.
Both commands only read. They change nothing in the bundle or the session, and need no device; agent export writes only its --out file. A run records a secret's name, not its value, in the flow, the command line and the steps' arguments. Evidence of the screen is kept as it was, though: a typed secret that the screen shows is in the screen trees, the screenshots and the steps' target text, and so in the bundle and the report.
agent inspect --step takes the step's runtime index, such as 6, or its stable step id, such as src_4d88cd3b8ce7.1. The stable id is the safer choice for anything your agent stores, because it names the same step after a flow gains a conditional branch.
Examples
Every output here comes from Autonom's test emulator showing a PIN screen, so you can rerun it without a device. The run types a PIN from the APP_PIN secret, taps Continue, then waits for a Welcome screen that never comes, so step 6 fails. Reproduce these outputs, at the end of this section, has the exact commands.
Export the report of a failed run
Goal: hand your agent the failure and its evidence in one file.
- Export the report from the run's bundle.
autonom report bundle --run ID --out DIRwrote the bundle when the run ended.autonom agent export --bundle bundle --out agent.json - Read it.
The file is compact JSON;
python3 -m json.toolindents it.python3 -m json.tool agent.json
You should see where the file went, then the report: the failure, the steps and a summary.
What to look at. failure gives the code, the file and the line, so your agent can branch on flow_assertion_timeout without parsing text. summary.first_causal_failure is the stable id of the step to inspect next. The failing step lists the attachments it kept, a screenshot and a screen tree, by id.
Inspect the failing step
Goal: read one step in full, with only the evidence it kept.
- Inspect it by its index.
autonom agent inspect --bundle bundle --step 6 - Inspect it by its stable id.
The answer is byte for byte the same.
autonom agent inspect --bundle bundle --step src_4d88cd3b8ce7.1
You should see the run's attempt, the step and its two attachments.
What to look at. execution_command is the command that made the run; the secret appears only as --secret APP_PIN. reproduction is how to rebuild it, with Replay. To open an attachment from a bundle, join the bundle directory and its blob, such as bundle/blobs/sha256/da/da41…. path is where the file was in the session's directory, flows/ or shots/ under the session, and the bundle has no such folder. A report read from a session with --run has no blob; there, path is relative to the session's directory.
Check that nothing changed and nothing leaked
Goal: confirm the report left the bundle as it was, and that the PIN was not recorded.
- Verify the bundle again.
autonom report verify bundle - Search the bundle and the report for the PIN.
grep -rl 271828 bundle agent.json
You should see the bundle verified, and no file holding the secret, because the PIN field of this screen never shows what was typed.
What to look at. Every file still matches its digest after the export and both inspections. The second line comes from the script: grep found no file. The run kept only the name APP_PIN; the next example shows what changes when the screen shows the value.
Know that screen evidence keeps what the screen showed
Goal: see where a secret goes when the app displays it, before you share a bundle or a report.
- Run the flow again on a screen that shows the PIN.
The script now shows
271828in the PIN field, as a plain text field shows what was typed into it. It runs the flow, bundles the run intoshownand exports its report toshown-agent.json.autonom flow run pin.yaml --secret APP_PIN - Search the new bundle and report for the PIN.
grep -rl 271828 shown shown-agent.json
You should see the PIN in the report, in the bundle's screen trees and event stream, and in the files built from them.
What to look at. The three blobs are the two screen trees and the event stream; the step file is step 2, whose target text is the field's text. report verify still passes, because nothing was changed after the run: the value was recorded as screen content, not as the secret. On a real device the screenshots show it too. Treat a bundle or an agent report as sensitive when a secret can appear on screen: have the app mask the field, use a test credential, and do not publish such a bundle as a public artifact.
Read the refusals
Goal: tell why a report was not produced, from the error code alone.
Each refusal is one error object on stderr, with exit code 2.
What to look at. flow_replay_step_not_reached means the step index or id is not in this run. no_active_session asks for a source: pass --bundle, or name the stopped session with --session and its run with --run, as the script does after session stop. report_integrity_failed lists each file whose digest no longer matches; nothing is read from that bundle.
Reproduce these outputs
From the root of an Autonom checkout at tag v0.36.1 (commit ca2a280), in bash or zsh. The autonom function runs that checkout against its test emulator, and the script writes the PIN screen it shows, then a copy whose PIN field shows the PIN. Run ids, attempt ids, attachment ids, session ids, times and sizes differ on every run, and ids are shortened to … on the page; step, case and history ids stay the same, because the flow has an id. On macOS the paths inside the report start with /private/tmp.
Good to know
Branch on codes, not on messages.
failure.error_codeand each step'serror.codeare stable codes; the messages are for people.Start from
first_causal_failure. The summary names the first step that failed or broke, by its stable id; later failures often follow from it. Pass that id toagent inspect.Store step ids, not indexes. An index counts runtime steps, so a conditional or a retry can shift it. A step id stays with the step.
Read a bundle when the run matters later. A bundle is verified on every read and keeps its own copy of the flow, so its report stays trustworthy after the session is gone.
Missing evidence is marked, not invented. A step's
deltasays for the screen, logs and requests whether evidence isavailable,partialorunavailable, instead of showing an empty list as if nothing happened.The snapshot travels with the run.
capabilitiesis the capability snapshot the run was checked against, andsetuplists what the run applied and verified.
Reference
Both commands take the same sources.
| Command | What it does |
|---|---|
autonom agent export --out FILE | Writes the autonom.agent-report/v1 file of the current session's latest run. |
autonom agent inspect --step STEP | Prints one step by runtime index or stable step id, with the attempt and that step's attachments. |
--bundle DIR | Reads a report bundle, after verifying every file against its digest. |
--run ID | Reads one run of the session instead of its latest. |
--session ID | Reads from that session, running or stopped, instead of the current one. |
The fields of autonom.agent-report/v1.
| Field | What it holds |
|---|---|
schema | autonom.agent-report/v1. |
summary | The run and attempt ids, status, proof_verdict, step counts by status, the attachment count, first_causal_failure, and the case_id and history_id that stay the same across runs of one flow. |
failure | The run's first failure: error_code, error, failure_class, the command, the file, the line and the step index. null when the run passed. |
setup | What the run's setup applied, selected, used and verified, and the capabilities that were available. |
capabilities | The autonom.provider/v1 snapshot the run was checked against. |
replay | How the run can be rebuilt. A replay's own report adds the step it stopped at and cleanup_hooks_skipped. |
steps | Every step: step_id, index, name, command, status, error, delta and attachment_ids. |
attachments | Every piece of evidence: id, type, name, MIME type, path relative to the session's directory and, in a bundle, blob (the file's place in the bundle), size and sha256. |
The refusals, each with exit code 2.
| Error code | When |
|---|---|
flow_replay_step_not_reached | --step names no step of the run. |
report_integrity_failed | The bundle has no manifest, or a file in it no longer matches its digest. |
no_active_session | There is no --bundle, no --session, and no current session. |
usage_error | --out is missing from agent export, or --step from agent inspect. |
Next steps
Your agent can read a run as compact JSON and inspect any step.