AgentLedger Core
Deterministic Run Ledger for AI Agents
Record. Inspect. Replay. Diff.
AgentLedger Core provides an append-only execution ledger with hash chain integrity for AI agent runs.
Features
- Append-only Event Ledger - Immutable record of agent execution
- Hash Chain Integrity - SHA-256 hash chain for tamper detection
- Deterministic Replay - Replay runs from recorded outputs
- Run Inspection - Timeline and failure analysis
- Run Diff - Compare runs to identify divergences
What AgentLedger Core is NOT
AgentLedger Core defines a minimal execution ledger format.
It does NOT define:
- Agent cognition
- Planning systems
- Memory architectures
- Orchestration frameworks
- LLM adapters
- Deployment systems
Installation
pip install agentledger-core
Quick Start
from agentledger import (
LocalLedger,
EventFactory,
ReplayEngine,
RunInspector,
RunStatus,
)
# Create ledger and run
ledger = LocalLedger("./runs")
ledger.create_run("run_001")
# Record events
factory = EventFactory(run_id="run_001", agent_id="my_agent")
ledger.append(factory.run_start()) # goal is optional
ledger.append(factory.tool_call("search", {"query": "example"}))
ledger.append(factory.tool_result(output={"results": ["a", "b"]}))
ledger.append(factory.run_end(status=RunStatus.COMPLETED))
# Verify determinism
engine = ReplayEngine(ledger)
result = engine.verify_determinism("run_001")
print(f"Hash chain valid: {result['hash_chain_valid']}")
print(f"Deterministic: {result['deterministic']}")
# Inspect the run
inspector = RunInspector()
events = [e.model_dump() for e in ledger.get_events("run_001")]
report = inspector.inspect(events, "run_001")
print(f"Events: {len(report.timeline)}")
print(f"Duration: {report.duration_seconds}s")
Core Event Types
The v0.1 standard defines 9 canonical event types:
| Category | Events |
|---|---|
| Run lifecycle | run.start, run.end |
| Step lifecycle | step.start, step.end |
| Tool execution | tool.call, tool.result |
| Decision | decision |
| State | state.patch |
| Error | error |
Custom extension events are supported but not part of the compliance set.
Storage Layout
runs/
run_{id}/
run.json # Run manifest
ledger/
events.jsonl # Append-only event log
blobs/ # Optional blob storage
API Reference
LocalLedger
ledger = LocalLedger("./runs")
ledger.create_run(run_id) # Initialize new run
ledger.append(event) # Append event
ledger.get_events(run_id) # Iterate events
ledger.get_run_metadata(run_id) # Get run manifest
ledger.store_blob(run_id, data) # Store large data
EventFactory
factory = EventFactory(run_id, agent_id)
factory.run_start() # Run start (all fields optional)
factory.run_end(status) # Run end
factory.step_start(step_id) # Step start
factory.step_end(step_id) # Step end
factory.tool_call(tool, input) # Tool invocation
factory.tool_result(output) # Tool response
factory.decision(decision_type) # Decision point
factory.state_patch(*patches) # Optional state mutation
factory.error(type, message) # Error event
ReplayEngine
engine = ReplayEngine(ledger)
engine.replay(run_id) # Full replay
engine.step(run_id) # Step-by-step iterator
engine.get_state_at(run_id, seq) # State at sequence
engine.verify_determinism(run_id) # Hash chain verification
engine.compare(run_a, run_b) # Compare two runs
RunInspector / RunDiffer
inspector = RunInspector()
report = inspector.inspect(events, run_id)
from agentledger import diff_runs
diff = diff_runs(events_a, events_b, "run_a", "run_b")
Standard
AgentLedger Core v0.1 defines the minimal execution ledger standard for AI agents.
This package is the reference implementation of the standard. See SPEC.md for the full specification.
CLI Usage
# Inspect a run
agent inspect run_001
# Replay a run
agent replay run_001
# Diff two runs
agent diff run_a run_b
License
MIT License
Metadata
Release files for agentledger-core 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentledger_core-0.1.1.tar.gz | 35.0 kB | Without provenance | Details for agentledger_core-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentledger_core-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for agentledger_core-0.1.1-py3-none-any.whl |
Total release size: 68.1 kB
Release files / agentledger_core-0.1.1.tar.gz
| Download URL | agentledger_core-0.1.1.tar.gz |
|---|---|
| Size | 35.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b6169ae7e1dbbeb50ddcecada0ebe8cfdbe3c9370b310fb36ebea520fdcffc1d
|
|
BLAKE2b-256 checksum How to use checksums |
6680d977508ce45e01937ab01129e2231a6310ee3c11b5a0927f57542d30fabd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.11
|
Release files / agentledger_core-0.1.1-py3-none-any.whl
| Download URL | agentledger_core-0.1.1-py3-none-any.whl |
|---|---|
| Size | 33.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b234427fe67afb8089e9e4f2a7e522f9af29e5e5a6e16d1a87e1c9c9e47ce5f6
|
|
BLAKE2b-256 checksum How to use checksums |
5fa59a2929f403e4b25a1f8ed45a33333d368f4de6bc6eaf5b334b19644099bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.11
|
Security for agentledger-core 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.