Skip to content
Prefactor Prefactor Prefactor Docs

Activity schema

An activity schema tells Prefactor what shape of work to expect from an agent — it names the span types the agent emits and declares the expected structure of each type’s inputs and outputs.

Every span type your agent records must have payload and result definitions in that agent’s activity schema — there is always a schema for each type, even when it is effectively wide open. Integration defaults are usually permissive: they allow extra fields you did not list so you can start tracing without pinning every property up front; you can tighten definitions when your instrumentation stabilises. That contract still lives in the platform: everyone reviewing a run can see which fields belong to a user turn, an assistant turn, or a given tool call, and when a payload diverges from what you declared, Prefactor surfaces that for review instead of leaving you to spot drift by hand.

The definitions for an agent cover one or more span types — for example user_message and assistant_message for conversation, plus a separate type for each tool you instrument (such as web_search and read_file), with shapes that match that tool’s arguments and results. For each type, the schema holds two definitions: one for the span payload (what went in) and one for the result (what came back).

Schemas support governance and observability, not runtime blocking. Prefactor records every span your integration sends, whether or not it matches the declared shape. A mismatch does not stop a run; it is visible so you can tighten instrumentation or adjust the schema deliberately.

Versioning

Section titled “Versioning”

Activity schemas belong to a single agent and are versioned over time. Prefactor creates a new schema version on demand: when an instance arrives with a schema not seen before for that agent, a new version is recorded automatically — the same mechanism that creates new agent versions. You do not push schema versions explicitly; they appear as a side-effect of runs arriving with new definitions. Reviewers can see which environments use which version. Each instance is tied to the activity schema version it was registered with — that is the version Prefactor uses to interpret and validate spans for that run, regardless of what changes afterward.

In the Admin UI

Section titled “In the Admin UI”
Section titled “Related concepts”
  • Agent — each agent owns its activity schema versions.
  • Span — span types and payloads are defined by the activity schema.
  • Instance — each run is tied to the activity schema version supplied when that instance was registered.