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.

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.

After the run, an instance can carry a quality payload for each named quality schema declared in the agent’s activity schema — 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

• Agent › Instances tab — the per-agent table of every run, filterable by environment and status.
• Agent › Instance › Details tab — lifecycle timestamps 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 › Risk tab — the risk classification and contributors for a single run.
• Agent › Versions tab — each instance records the agent version it ran under.

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.
• 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.