Actions
An action is a single instrumented unit of work in your agent (a tool call, API request, DB query, etc.).
In the Python SDK, actions are created by decorating functions with @guarded_action(...).
Each action records:
- Name:
name argument (or the function name)
- Cost:
cost_usd (you supply the estimate for that call)
- Duration: measured automatically
- Outcome:
"success", "error", or "replayed"
- Inputs/outputs: captured from the call
- Tags: optional list of strings
Runs
A run represents one execution of your agent (one “session” you want to analyze end-to-end).
On the platform, a run:
- Owns many actions
- Aggregates
total_cost
- Has a
status such as "running" / "completed"
Run IDs
SDK 0.2.0 stamps a run_id onto every ledger entry, taken from the active ExecutionContext. To group actions into a logical run:
from agent_sentinel import ExecutionContext
with ExecutionContext(run_id="my-run-id", agent_id="my-agent"):
do_thing() # ledger entry includes run_id="my-run-id"
do_other()
run_id is sent alongside the batched entries (see Remote sync) so platform-side run grouping is consistent with local ledger filtering.
If you launch agents from a parent process, set ExecutionContext once per logical run rather than per call so every action lands in the same run on the platform.
