Crate agent_effects 

Reliable side-effect execution for AI agents and autonomous applications.

agent-effects puts a durable execution boundary around operations that change the outside world: charging a card, sending an email, provisioning a server. It records intent before acting, distinguishes “failed” from “don’t know”, and resolves unknown outcomes by verification or idempotent retry instead of guessing.

It does not provide exactly-once side effects. Nothing can, without cooperation from the target system. It provides controlled execution and deduplication, and refuses to retry when a retry could duplicate an effect.

use agent_effects::{EffectFailure, EffectKind, EffectOutcome, Runtime};
use agent_effects_memory::MemoryStore;

let runtime = Runtime::new(MemoryStore::new());

let outcome = runtime
    .effect("ticket.create", "incident-42")
    .kind(EffectKind::IrreversibleWrite)
    .input(&"disk full on db-1")
    .run(|ctx| async move {
        // Call the remote system here, sending ctx.idempotency_key().
        Ok::<_, EffectFailure>(format!("TICKET-1 (attempt {})", ctx.attempt()))
    })
    .await?;

match outcome {
    EffectOutcome::Committed(ticket) => println!("created {ticket}"),
    EffectOutcome::Unknown { id } | EffectOutcome::NeedsIntervention { id } => {
        println!("effect {id} may have happened; not retrying blindly")
    }
    other => println!("{other:?}"),
}

Beyond running effects with retries, timeouts, preconditions and verification, the runtime finishes registered handlers without a caller after a crash (recovery), undoes effects (compensation), waits for approval, applies a risk policy, keeps secrets out of storage (redaction), reports metrics to observers, and prunes old records (retention).

Stores: agent-effects-memory (tests), agent-effects-sqlite, agent-effects-postgres. The persisted vocabulary (identity, kinds, the state machine) and the EffectStore contract come from agent-effects-store and are re-exported here.

Re-exports

pub use approval::ApprovalDecision;

pub use approval::ApprovalProvider;

pub use approval::ApprovalRequest;

pub use approval::CliApproval;

pub use clock::Clock;

pub use clock::ManualClock;

pub use clock::SystemClock;

pub use clock::TokioClock;

pub use compensation::CompensationBuilder;

pub use compensation::CompensationContext;

pub use compensation::CompensationOutcome;

pub use effect::EffectBuilder;

pub use effect::EffectContext;

pub use effect::EffectFailure;

pub use effect::EffectOutcome;

pub use effect::Precondition;

pub use error::RuntimeError;

pub use handler::CompensableEffect;

pub use handler::CompensationSubmission;

pub use handler::EffectHandler;

pub use handler::Handler;

pub use handler::Submission;

pub use handler::VerifiableEffect;

pub use observer::EffectObserver;

pub use observer::Observation;

pub use policy::Capabilities;

pub use policy::PolicyBuilder;

pub use policy::Requirements;

pub use policy::RiskLevel;

pub use policy::RiskPolicy;

pub use policy::UnknownPlan;

pub use recovery::RecoveryReport;

pub use recovery::Resolution;

pub use redaction::RedactKeys;

pub use redaction::Redactor;

pub use redaction::Secret;

pub use retention::PruneReport;

pub use retention::RetentionPolicy;

pub use retry::RetryPolicy;

pub use runtime::Runtime;

pub use runtime::RuntimeBuilder;

pub use verification::NotFoundReading;

pub use verification::Verification;

pub use verification::VerificationMode;

pub use agent_effects_store as store;

Modules

approval

Human approval before an effect runs.

clock

Time source for leases, retry scheduling and settle delays.

compensation

Undoing committed effects.

effect

Describing an effect: the builder, what its action sees, and how it ends.

error

Infrastructure errors.

failure

Classification of execution failures.

fault

Crash simulation for testing recovery. The injector is enabled by the fault-injection feature.

handler

Durable effect handlers: effects the runtime can finish without a caller.

id

Effect identity: record ids, logical keys and remote idempotency keys.

kind

Behavioral classification of effects.

observer

Watching effects for metrics.

policy

Policy: what the runtime may do on its own.

recovery

Recovery and the operator API.

redaction

Keeping secrets out of the store.

retention

Retention: pruning settled records.

retry

Retry policy: how many attempts, and how long to wait between them.

runtime

The effect runtime.

state

The effect state machine.

testkit

Test doubles for code built on agent-effects. Enabled by the testkit feature.

verification

Verification: asking the remote system whether an effect applied.

Structs

EffectId

Durable identity of one effect record.

EffectKey

The unique identity of a logical effect: (name, logical key).

EffectName

The type of an effect, e.g. payment.charge.

EffectRecord

The durable state of one effect.

ErrorRecord

A recorded failure.

IdempotencyKey

A key a remote system can use to deduplicate requests, such as an HTTP Idempotency-Key header.

InvalidTransition

A transition that is not legal from the current status.

Lease

Proof of holding an effect’s execution lease.

LogicalKey

The application’s identifier for one logical occurrence of an effect, e.g. the order id for payment.charge.

WorkerId

Identifies a runtime instance that holds execution leases.

Enums

Disposition

What the runtime does with a failure.

EffectKind

What re-executing an effect does to the outside world.

EffectStatus

Where an effect is in its lifecycle.

FailureClass

What kind of failure an action reported.

IdentityError

Why an EffectName or LogicalKey was rejected.

StoreError

Why a store operation failed.

Transition

Something that happens to an effect and may change its status.

Traits

EffectStore

Persistence for effect records, leases and audit events.