agentcrash-core — Reliability framework for agentic workflows

agentcrash-core (import package agentcrash) is the reusable core extracted from the AgentCrash reliability project. It observes host workflows without owning them: buffered SDK instrumentation, a versioned event schema, domain-free invariants, deterministic fault injection, and a loopback control plane (Lab + /v1 API).

Domain workflows live in their own repos and depend on this package — e.g. the NL-to-ODRL agent in nl2odrl-responsible-ai. Any agentic workflow can do the same.

Install

pip install agentcrash-core            # SDK + control-plane client
pip install "agentcrash-core[server]"  # control-plane service extras

Use it in your workflow

from agentcrash import AgentCrash, WorkflowConfig

ac = AgentCrash(WorkflowConfig(project="my-workflow", fault_injection=True))

with ac.run(name="my-run") as run:
    with run.step("my-step"):
        ...  # your business logic; AgentCrash never orchestrates it

Disabled mode (AGENTCRASH_DISABLED=1) turns every call into a no-op passthrough, so hosts work with or without the framework installed.

Judge a trace

# verify registry invariants against an SDK-schema JSONL trace
agentcrash check --trace run.jsonl --invariant required_step:my-step --report-out verdict.json

# run the control plane (Lab + /v1 API, local only)
agentcrash serve --port 8901

Hosts register their own invariants (e.g. odrl_valid, exactly_once_save) alongside the generic core checks (required_step:*, duplicate_mutating_effect, fresh_write_only, no_lost_update).

Core principle

Model-generated diagnosis is strictly separated from deterministic verification. The model can explain a failure and propose candidate policy edits, but independent checks against recorded trace events and environment state determine whether a run passes or fails.

Develop

Prerequisites: WSL Ubuntu-24.04, Python 3.11+, uv.

git clone https://github.com/SahilSatyam/AgentCrash.git && cd AgentCrash
uv venv && uv pip install -e ".[dev]"
pytest -q

Layout

• src/agentcrash/ — sdk, events, invariants, evaluate, server, verifiers (registry + generic checks), tracer, clock, injector, ledger, policy, scan_pii, db, lab/ (control-plane UI assets), schemas/ (bundled policy schemas)
• examples/minimal_agent/ — second-app sample with zero domain imports
• examples/README.md — writing your own host

Docs

See docs/ — start with docs/architecture-decoupling.md, which defines the core/host boundary.