Runs, traces, and versions

A run is one execution of an agent or workflow. A trace is the detailed record of what happened during that execution. A version is the immutable definition that the run used.

A run is the operational record

A useful run record connects the input to its outcome. It identifies the workspace, actor, agent or workflow version, status, duration, cost, and any output or artifact produced.

A trace explains the path

For intelligent work, the final answer is not enough. A trace should make it possible to follow the execution:

CopyInput
  → context retrieval and entity resolution
  → model route and reasoning step
  → tool calls and policy decisions
  → waits, retries, and state transitions
  → output, action, or stop reason

This lets a developer distinguish missing context from a bad mapping, an unsuitable tool, a policy denial, a runtime failure, or an agent behaviour problem.

Versions make change reversible

Treat changes to an agent brief, tool configuration, workflow definition, ontology mapping, or model route as version changes. Test a candidate against known cases, promote it with evidence, and retain the previous stable version for rollback. A historical run retains the version it started with, so its explanation remains meaningful after the system evolves.

Next: Evaluation and observability.