Instance
An instance is a single run of an agent from start to finish: one discrete execution, tracked by Prefactor as a unit.
Every time your agent runs, Prefactor creates an instance record. That record collects everything that happened during that run: the spans produced (each LLM call, tool invocation, or sub-agent execution), the agent version that was running, the environment it ran in, and the lifecycle state the run reached. The instance is the level at which risk is assessed. If the agent has a risk profile, the risk classification for that run is attributed to the instance, derived from its spans.
An instance moves through a set of states as it runs. It starts as Pending, becomes Active once running, and finishes as Complete, Failed, Cancelled, or Terminated depending on how it ends. A judge run starts one step earlier, as Preparing, while Prefactor writes the input it will judge.
Complete, Failed, and Cancelled come from the agent itself: the run finishes, fails, or is cancelled before it starts. Terminated means the run was stopped from outside: by someone on your team, from the web app or through the API. Termination always carries a reason, which is recorded on the instance and in the audit trail, and a terminated run counts as a failure in quality statistics. Only an active run can be terminated, and an agent cannot terminate its own run, because its API token doesn’t carry that permission.
Termination is cooperative rather than a hard kill. Prefactor signals the running agent to stop, and the agent’s integration winds the run down; until it does, Prefactor keeps accepting its spans. Prefactor never terminates a run on its own schedule; there are no idle timeouts or run-duration limits.
Each instance also records a purpose: why the run happened. Live (live) is a real run (the default), Eval (eval) is an evaluation run, and Smoke test (smoke_test) is a pipeline check. The integration sets the purpose when it registers the run, and it is shown wherever the instance appears, so evaluation traffic never masquerades as production traffic.
Each instance contains exactly the spans that were recorded during that run. The spans it contains and how detailed they are depend on the choices made by the team building the agent: what they chose to instrument and at what granularity.
Input, result, and metadata
Section titled “Input, result, and metadata”An instance can also record what the run was asked to do, what it produced, and facts about the run itself, separate from its spans. The input is set when the run is registered, the result is set when it finishes, and metadata is set at registration and never changes. Each has its own schema, declared on the activity schema version the run was registered with, and each is optional: a run records only the ones its schema version declares.
Unlike a span, an instance payload that doesn’t match its schema is rejected rather than recorded. A result is only recorded when the run finishes as Complete or Failed. Values marked as sensitive are stored and redacted the same way they are in spans, and for these three payloads the marking is always on.
A judge’s run uses the same fields: its input is the question put to it, and its result is its verdict. Evals explains how judge runs relate to the runs they score.
Quality payloads
Section titled “Quality payloads”After the run, an instance can carry a quality payload for each named quality schema declared in the agent’s activity schema. A quality payload is the result of evaluating that run against that schema. Each payload is set through the SDK or the API, and every change to it is recorded as its own quality span within the instance, so the evaluation history is part of the run’s record. See Quality and performance for how evaluations work.
In the web app
Section titled “In the web app”- Agent instance page — terminate an active run from the strip above the tabs, reason required.
- Agent › History tab — the per-agent table of every run, filterable by environment and status.
- Agent › Instance › Details tab — lifecycle timestamps and the recorded input, result, and metadata for a single run.
- Agent › Instance › Activity tab — the full span hierarchy for a single run.
- Agent › Instance › Quality tab — the quality evaluations attached to a single run.
- Agent › Instance › Alerts tab — the alerts raised on a single run.
- Agent › Instance › Risk tab — the risk classification and contributors for a single run.
- Agent › Configuration tab — each instance records the agent version it ran under.
Related concepts
Section titled “Related concepts”- Agent — every instance belongs to one agent.
- Activity schema — each instance is tied to the activity schema version supplied when that run was registered.
- Span — the individual steps recorded within an instance.
- Alert — a notice raised on an instance when something needs attention.
- Environment — instances are attributed to the environment the agent reported when the run started.
- Risk profile — risk classification is calculated and displayed at the instance level.