Instrumentation

Basic usage

from agent_sentinel import guarded_action

@guarded_action(name="search_web", cost_usd=0.02, tags=["tool", "search"], impact="read")
def search_web(query: str) -> dict:
    return {"results": ["..."], "query": query}

Calling search_web(...) will:

Measure duration
Record inputs/outputs
Append a ledger entry

Async functions

from agent_sentinel import guarded_action

@guarded_action(name="call_llm", cost_usd=0.05, tags=["llm"])
async def call_llm(prompt: str) -> str:
    return "..."

Exceptions

Agent Sentinel does not swallow your exceptions. If your function raises, the exception propagates normally — the SDK records the action as outcome="error" and logs the error string.

Fail-open vs fail-closed

Fail-open: ledger writes and remote sync should never crash your agent.
Fail-closed: policy violations intentionally raise before execution. Since 0.4.0, actions declared impact="medium" or "high" are also blocked when no policy is loaded (see Enforcement modes).

Decorator arguments

@guarded_action accepts the following keyword-only arguments. Anything beyond name, cost_usd, and tags is optional — sensible defaults apply.

Argument	Type	Purpose
`name`	`str`	Logical action name (defaults to function name)
`cost_usd`	`float`	Estimated per-call cost; deducted from budgets
`tags`	`list[str]`	Free-form tags; matched against policy `approval_tags`
`impact`	`"read" \| "low" \| "medium" \| "high"`	How consequential the action is (default `"medium"`). Drives the default `fail_closed_writes` mode and is sent to the platform
`fail_closed`	`bool \| None`	Per-action enforcement override: `True` forces `fail_closed`, `False` forces `fail_open`, `None` uses the process mode
`requires_human_approval`	`bool`	Pause and request human approval before execution
`approval_description`	`str`	Human-readable description shown in the approval inbox
`agent_id` / `task_id` / `mission_id`	`str`	Attribution overrides; default to current `ExecutionContext`
`produces_evidence`	`bool`	Mark this action as producing evidence other actions can require
`is_commit`	`bool`	Mark as a commit action (subject to evidence + grounding checks)
`requires`	`list[str]`	Names of evidence actions that must precede this one
`argument_constraints`	`dict`	JSON Schema applied to kwargs before execution
`evidence_max_age_seconds`	`int`	Maximum age of required evidence before it expires
`grounding_rules`	`dict`	Field-level grounding constraints (action arg → evidence field)
`risk_level`	`str`	One of `critical`, `high`, `medium`, `low`, `minimal`
`idempotency_key`	`str \| Callable`	Static key or `(args, kwargs) -> key` callable for replay caching
`idempotency_ttl_seconds`	`float`	TTL for the cached result (default 3600s)

@guarded_action(
    name="charge_card",
    cost_usd=0.01,
    risk_level="high",
    requires=["lookup_customer"],
    grounding_rules={"amount_cents": {"source_action": "lookup_customer", "source_field": "balance_cents"}},
    idempotency_key=lambda *_, **kw: kw["payment_id"],
    idempotency_ttl_seconds=900,
)
def charge_card(*, payment_id: str, customer_id: str, amount_cents: int) -> dict:
    return billing.charge(payment_id, amount_cents)

Secret redaction

Before a ledger entry is written or uploaded, the SDK redacts tool inputs:

Values under sensitive-looking keys (api_key, secret, token, password, passwd, authorization, credential, private_key, and similar) become [redacted:<kind>].
String values that look like secrets (OpenAI, Stripe, AWS, GitHub and Slack keys, PEM private-key headers, JWTs) are redacted wherever they appear.
Values over 8 KB are truncated with a ...[truncated N bytes] marker.

The entry carries inputs_redacted: true when anything was replaced. Your function still receives the original arguments; only the recorded copy changes. To keep inputs out of the ledger entirely:

export AGENT_SENTINEL_LEDGER_INPUTS=none

You can apply the same redaction yourself with agent_sentinel.redaction.redact_inputs(args, kwargs, max_bytes=8192).

Replay mode integration

If replay mode is active, decorated actions return recorded outputs instead of executing (and are logged with outcome="replayed"). See Replay.

Getting started

Concepts

SDK (Python)

AI tools

Platform API

Web Console