agentidem record

Use agentidem record to execute a Python target and record its AgentIdem trace.

Basic usage

agentidem record module.path:function

For example:

agentidem record examples.refund_agent:run

The target uses this format:

module.path:function

AgentIdem imports the module, resolves the function, executes it, and records the traced operations.

What the command does

agentidem record runs the target once and captures the execution trace.

That trace can include:

• read operations
• write operations
• arguments
• logical identities
• results
• errors
• execution status
• observation state
• timestamps

Unlike agentidem test, the command is focused on recording one execution rather than running the full fault suite.

Example target

from agentidem import read, write

@read
def get_payment(payment_id: str):
    return payments.get(payment_id)

@write(identity=lambda payment_id: payment_id)
def refund(payment_id: str):
    return payments.refund(payment_id)

def run():
    payment = get_payment("payment-123")

    if payment["status"] == "paid":
        return refund("payment-123")

    return "no_refund"

Record the execution with:

agentidem record examples.refund_agent:run

Save the trace

Use --trace to choose the trace output file.

agentidem record examples.refund_agent:run --trace trace.json

For example:

agentidem record examples.refund_agent:run --trace failed-run.json

The resulting trace can be inspected later or used with replay.

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 for more information.

Recorded operations

Functions decorated with @read are recorded as:

READ

Functions decorated with @write are recorded as:

WRITE

For example:

READ
name: get_payment
status: SUCCESS
observation: RECEIVED

WRITE
name: refund
identity: payment-123
status: SUCCESS
observation: RECEIVED

Failed executions

A target can fail after some operations have already executed.

For example:

WRITE refund
status: SUCCESS

target raises exception

The trace recorded before the failure is still important because the side effect may already have happened.

AgentIdem preserves traced execution information so failures do not erase earlier operation history.

record vs test

Use:

agentidem record

when you want:

one execution
+
saved trace

Use:

agentidem test

when you want:

baseline execution
+
fault scenarios
+
safety findings
+
reliability result

record vs replay

Use record to create a trace:

agentidem record examples.refund_agent:run --trace trace.json

Then use replay to run the target again against that recorded trace:

agentidem replay examples.refund_agent:run --trace trace.json

See replay.

Exit codes

The CLI uses the standard AgentIdem exit code model:

For record, operational failures should use the operational error exit code.

See Exit codes.

Next steps

• replay
• test
• Targets
• Exit codes
• Traces