Skip to main content

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:
When using remote sync, the same 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.