Errors

AgentIdem uses structured errors to distinguish failures in traced execution from failures in write identity resolution.

The important public error types currently include:

TracedExecutionError
IdentityResolutionError

TracedExecutionError

TracedExecutionError is used when a target fails during traced execution.

The important behavior is that AgentIdem should preserve the partial trace recorded before the failure.

For example:

from agentidem import run_traced, 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")

trace = run_traced(
    "example.failing_agent",
    failing_agent,
)

If the target fails after the write has already run, AgentIdem can raise:

TracedExecutionError

while still preserving the operations recorded before the failure.

Why partial traces matter

A failed target does not mean that no side effects occurred.

Consider:

WRITE create_order
status: SUCCESS

target raises exception

The order may already exist even though the overall target failed.

Discarding the trace would hide important execution history.

TracedExecutionError is intended to preserve that context.

Handling TracedExecutionError

You can catch the error when you need to inspect or report the failure explicitly.

from agentidem import TracedExecutionError, run_traced

try:
    trace = run_traced(
        "example.failing_agent",
        failing_agent,
    )
except TracedExecutionError as error:
    print(error)

The error should preserve the partial trace captured before the target stopped.

The exact attributes exposed by the error may depend on the SDK version.

IdentityResolutionError

IdentityResolutionError is used when AgentIdem cannot resolve the configured logical identity for a write.

For example:

from agentidem import write

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

AgentIdem uses the configured identity function to determine what makes repeated writes represent the same logical side effect.

If that identity cannot be resolved correctly, AgentIdem can raise:

IdentityResolutionError

Why identity errors are explicit

Logical write identities are important for duplicate detection.

Silently ignoring a failed identity would make duplicate detection less trustworthy.

For example:

WRITE refund
identity: unresolved

should not silently be treated as though AgentIdem knows whether another refund represents the same logical side effect.

An explicit IdentityResolutionError makes the failure visible.

Handling IdentityResolutionError

You can catch the error when identity resolution needs explicit handling.

from agentidem import IdentityResolutionError

try:
    result = refund("payment-123")
except IdentityResolutionError as error:
    print(error)

The exact point at which the error is surfaced depends on when AgentIdem resolves the configured identity during execution.

Execution failures are not automatically safety failures

AgentIdem keeps execution outcome separate from safety outcome.

For example:

execution: failed
safety: safe

can be valid.

A fault scenario may intentionally produce an exception without causing a duplicate side effect.

Likewise:

execution: succeeded
safety: unsafe

can also be valid if execution completes but repeats the same logical write.

An exception alone does not determine whether the execution was safe.

Baseline failures

Before running fault scenarios, AgentIdem can run a baseline execution.

If the baseline itself fails, AgentIdem should represent that explicitly.

Conceptually:

baseline
status: failed

The fault suite should not pretend that the target was meaningfully tested under fault scenarios when normal execution could not complete.

A baseline failure is therefore an execution or setup problem rather than automatically being treated as a duplicate side effect finding.

Fault scenario failures

A fault scenario may intentionally cause execution to fail.

For example, a lost acknowledgement can cause the agent to observe an injected failure even though the write succeeded.

Conceptually:

WRITE refund
status: SUCCESS
observation: LOST

agent receives failure

The resulting execution failure is part of the scenario.

AgentIdem then evaluates whether the resulting behavior remained safe.

Error information in traces

A traced operation can contain error information when an operation fails.

For example:

operation: get_payment
kind: READ
status: FAILED
observation: FAILED
error: Database unavailable

or:

operation: refund
kind: WRITE
status: FAILED
observation: FAILED
error: Payment service unavailable

This lets traces explain where execution stopped and what failed.

Error information in reports

Structured reports can also include execution failures and findings.

A report may contain:

• baseline result
• individual fault results
• execution status
• findings
• invariant results
• safety status

This keeps operational errors and safety findings distinguishable.

Errors and CLI exit codes

When using the AgentIdem CLI, operational errors should use an exit code distinct from unsafe results.

The general exit code model is:

Examples of operational errors can include:

• invalid target
• loading failure
• baseline failure
• invalid trace
• other execution or setup failures

This separation makes AgentIdem easier to use in CI and automation.

Error handling principles

When working with AgentIdem errors, keep these distinctions in mind:

1. a target failure does not mean no side effect happened
2. partial traces should be preserved when possible
3. identity resolution failures should be explicit
4. execution failure and safety failure are separate concepts
5. operational errors should remain distinguishable from unsafe test results

Next steps

• Traces
• Duplicate detection
• Fault scenarios
• Run traced execution
• Run async traced execution