Use run_traced when you want to execute a synchronous target once and record what it does without running the full AgentIdem fault suite.
This is useful for inspecting reads, writes, results, failures, identities, and observation state during a normal execution.
Basic usage
from agentidem import run_traced
trace = run_traced(
"example.refund_agent",
refund_agent,
)
The first argument identifies the target.
The second argument is the synchronous callable AgentIdem should execute.
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 refund_agent():
payment = get_payment("payment-123")
if payment["status"] == "paid":
return refund("payment-123")
return "no_refund"
Record one traced execution:
from agentidem import run_traced
trace = run_traced(
"example.refund_agent",
refund_agent,
)
What run_traced does
run_traced runs the target once while AgentIdem records decorated operations.
Conceptually:
target starts
↓
READ get_payment
↓
WRITE refund
↓
target returns
↓
trace
It does not run the complete fault suite.
If you want AgentIdem to run baseline and fault scenarios, use test_agent.
Trace contents
A trace can contain operation-level information such as:
- operation name
- operation kind
- arguments
- logical identity
- result
- error
- execution status
- observation state
- timestamps
For example, an execution might conceptually contain:
READ
name: get_payment
status: SUCCESS
observation: RECEIVED
WRITE
name: refund
identity: payment-123
status: SUCCESS
observation: RECEIVED
Read operations
Functions decorated with @read appear as READ operations.
from agentidem import read
@read
def get_order(order_id: str):
return database.get(order_id)
A traced call may appear conceptually as:
READ
name: get_order
status: SUCCESS
observation: RECEIVED
Reads are recorded for execution context, but they are not treated as side effects.
Write operations
Functions decorated with @write appear as WRITE operations.
from agentidem import write
@write(identity=lambda order_id: order_id)
def create_order(order_id: str):
return external_service.create_order(order_id)
A traced call may appear conceptually as:
WRITE
name: create_order
identity: order-123
status: SUCCESS
observation: RECEIVED
Logical identities
If a write defines an identity:
@write(identity=lambda payment_id: payment_id)
def refund(payment_id: str):
return payments.refund(payment_id)
AgentIdem can record the resolved logical identity with the operation.
For example:
operation: refund
identity: payment-123
This information can later be used when comparing operations or detecting repeated logical writes.
Running a target with arguments
If your target requires arguments, wrap the call in another callable.
from agentidem import run_traced
trace = run_traced(
"example.refund_agent",
lambda: refund_agent("payment-123"),
)
This gives run_traced a zero-argument callable while still letting your target receive the values it needs.
Failed execution
The target may fail after some operations have already been recorded.
For example:
from agentidem import write
@write(identity=lambda order_id: order_id)
def create_order(order_id: str):
return external_service.create_order(order_id)
def failing_agent():
create_order("order-123")
raise RuntimeError("Unexpected failure")
The write may already have succeeded before the target raises the exception.
AgentIdem should preserve the partial trace recorded before the failure.
TracedExecutionError
When a target fails during traced execution, AgentIdem can raise:
TracedExecutionError
The error preserves the partial trace recorded before execution stopped.
This distinction is important because:
target failed
does not mean:
nothing happened
A state-changing operation may already have completed.
Inspecting the trace
The returned trace can be inspected directly.
from agentidem import run_traced
trace = run_traced(
"example.refund_agent",
refund_agent,
)
print(trace)
The trace provides the operation-level execution record rather than the broader safety report produced by test_agent.
Trace serialization
Traces can be serialized to JSON.
This makes traced executions useful for:
- debugging
- CI artifacts
- later inspection
- replay
- automated analysis
A saved trace can also be loaded later for replay.
run_traced vs test_agent
Use run_traced when you want:
one execution
+
structured trace
Use test_agent when you want:
baseline execution
+
fault scenarios
+
safety findings
+
structured report
In short:
| API | Purpose |
|---|---|
run_traced | Execute once and record the trace |
test_agent | Run the AgentIdem reliability test suite |
Async targets
run_traced is for synchronous targets.
For asynchronous targets, use:
run_traced_async
See Run async traced execution.