agentidem replay
Use agentidem replay to rerun a Python target against a previously recorded AgentIdem trace.
Replay helps verify whether the target still produces the same meaningful traced behavior.
Basic usage
agentidem replay module.path:function --trace trace.json
For example:
agentidem replay examples.refund_agent:run --trace failed-run.json
The target uses this format:
module.path:function
The trace file provides the previously recorded execution that AgentIdem should compare against.
Typical workflow
First, record a trace:
agentidem record examples.refund_agent:run --trace failed-run.json
Then replay the same target:
agentidem replay examples.refund_agent:run --trace failed-run.json
What replay compares
Replay reruns the target and compares meaningful operation behavior against the recorded trace.
That can include fields such as:
- operation name
- operation kind
- arguments
- logical identity
- result
- error
- execution status
- observation state
Volatile values should not determine whether replay matches.
Examples include:
- trace IDs
- operation IDs
- timestamps
Example recorded trace
A recorded execution might contain:
READ
name: get_payment
status: SUCCESS
observation: RECEIVED
WRITE
name: refund
identity: payment-123
status: SUCCESS
observation: RECEIVED
Replay runs the target again and compares the new traced behavior with the recorded execution.
Replay mismatch
If the new execution differs from the recorded trace in meaningful operation behavior, replay can report a mismatch.
For example:
recorded:
WRITE refund
identity: payment-123
status: SUCCESS
but the replayed execution produces:
WRITE refund
identity: payment-456
status: SUCCESS
That represents different logical behavior.
Target format
The target must point to an importable Python function.
module.path:function
Example:
examples.refund_agent:run
This resolves to:
module:
examples.refund_agent
function:
run
See Targets.
Trace input
Pass the recorded trace using:
--trace
Example:
agentidem replay examples.refund_agent:run --trace trace.json
The trace should come from a compatible AgentIdem recording.
Exit codes
agentidem replay uses the standard CLI exit code model.
| Exit code | Meaning |
|---|---|
0 | Replay matched successfully |
1 | Replay mismatch |
2 | Operational or setup error |
Example:
agentidem replay examples.refund_agent:run --trace trace.json
echo $?
See Exit codes.
replay vs record
Use:
agentidem record
to create a trace.
Use:
agentidem replay
to rerun the target and compare its behavior with that trace.
replay vs test
replay checks behavior against a previously recorded trace.
test runs the AgentIdem reliability test suite.
Use:
agentidem replay
when you want to compare against a known recorded execution.
Use:
agentidem test
when you want fault scenarios and side effect safety testing.