Ledger

The Agent Sentinel SDK writes append-only JSON Lines to a local ledger by default.

Location

Default path (relative to your current working directory):

.agent-sentinel/ledger.jsonl

Override the base directory with:

export AGENT_SENTINEL_HOME="/var/log/my-agent"

Format (JSONL)

Each line is a complete JSON object representing one action:

{
  "id": "uuid",
  "timestamp": "ISO-8601",
  "action": "action_name",
  "cost_usd": 0.01,
  "duration_ms": 123.4,
  "outcome": "success",
  "tags": ["tag1", "tag2"],
  "payload": {
    "inputs": {"args": [], "kwargs": {}},
    "outputs": {}
  }
}

Fail-open behavior

Ledger writes are fail-open: if the SDK cannot write (permissions, disk full, etc.), it logs an internal error and your agent continues.

PII / secrets

Since SDK 0.4.0, tool inputs are redacted before they are written or uploaded: sensitive keys (api_key, token, password, …) and secret-shaped strings (provider API keys, private-key headers, JWTs) become [redacted:<kind>], and the entry is marked inputs_redacted: true. Set AGENT_SENTINEL_LEDGER_INPUTS=none to skip input capture entirely. See Secret redaction. Outputs are not redacted, and redaction is pattern-based, so treat the ledger like application logs:

Store it securely
Rotate it
Avoid returning raw secrets from tool functions

Rotation

Ledger files grow over time. A simple rotation pattern:

mv .agent-sentinel/ledger.jsonl .agent-sentinel/ledger-$(date +%Y%m%d).jsonl
gzip .agent-sentinel/ledger-*.jsonl

Getting started

Concepts

SDK (Python)

AI tools

Platform API

Web Console

Location

Format (JSONL)

Fail-open behavior

PII / secrets

Rotation