Record a run's input, result, and metadata

A run usually starts with a question — which ticket to triage, which document to summarise — and ends with an answer. By default Prefactor only sees the spans in between. Recording the input and the result on the instance itself puts both on the run’s Details tab, next to metadata you choose, such as what triggered the run. By the end of this page, you have registered a run with an input and metadata, finished it with a result, and seen all three on the Details tab.

The input, result, and metadata each have their own schema, declared on the run’s activity schema version. Unlike span payloads, which Prefactor records even when they diverge from the schema, an instance payload that does not match its schema is rejected. The TypeScript and Python SDKs don’t send these fields yet, so this page calls the HTTP API directly. The Prefactor CLI can send them too; see From the CLI.

Before you start

An API token for the account. Create one from the Account › API tokens tab.
The ID of the agent and of the environment the run belongs to. Find the agent ID on the Agents page and the environment ID on the Account › Environments tab.
curl, and a shell where PREFACTOR_API_TOKEN holds your token.

Steps

Save the registration request as register.json. The three schemas sit on the schema version, and the input and metadata sit beside it:

{
  "agent_id": "YOUR_AGENT_ID",
  "environment_id": "YOUR_ENVIRONMENT_ID",
  "agent_version": { "external_identifier": "triage-1.0.0" },
  "agent_schema_version": {
    "external_identifier": "triage-schema-1",
    "instance_params_payload_schema": {
      "title": "Ticket to triage",
      "description": "What the agent was asked to do.",
      "schema": {
        "type": "object",
        "required": ["ticket_id"],
        "properties": {
          "ticket_id": { "type": "string", "title": "Ticket ID" },
          "customer_email": { "type": "string", "title": "Customer email" },
          "priority": {
            "type": "string",
            "title": "Priority",
            "enum": ["low", "normal", "urgent"]
          }
        }
      }
    },
    "instance_result_payload_schema": {
      "title": "Triage outcome",
      "description": "What the agent decided.",
      "schema": {
        "type": "object",
        "required": ["category"],
        "properties": {
          "category": {
            "type": "string",
            "title": "Category",
            "enum": ["billing", "bug", "how_to"]
          },
          "summary": {
            "type": "string",
            "title": "Summary",
            "prefactor:format": "markdown"
          }
        }
      }
    },
    "instance_metadata_schema": {
      "title": "Run context",
      "template": "Triggered by {{trigger}}",
      "schema": {
        "type": "object",
        "required": ["trigger"],
        "properties": {
          "trigger": { "type": "string", "title": "Triggered by" }
        }
      }
    }
  },
  "params_payload": {
    "ticket_id": "T-1042",
    "customer_email": {
      "$sensitive": "string",
      "labels": ["contact_information"],
      "value": "ada@example.com"
    },
    "priority": "urgent"
  },
  "metadata": { "trigger": "support-inbox" }
}

Each schema entry has a schema, which is a JSON Schema for the payload, plus an optional title, description, and template beside it. Set a title: it becomes the section heading on the Details tab, and without one the heading falls back to “Input parameters”, “Recorded result”, or “Metadata”. template is a summary template, and on the metadata schema it renders the summary line in the instance’s heading.

Prefactor creates the schema version if it hasn’t seen this one for the agent, and reuses it otherwise.

curl -s https://app.prefactorai.com/api/v1/agent_instance/register \
  -H "Authorization: Bearer $PREFACTOR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @register.json

The response’s details.id is the new instance’s ID. Keep it for the next two steps.

Start the instance:

curl -s -X POST https://app.prefactorai.com/api/v1/agent_instance/YOUR_INSTANCE_ID/start \
  -H "Authorization: Bearer $PREFACTOR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Finish it with a result:

curl -s -X POST https://app.prefactorai.com/api/v1/agent_instance/YOUR_INSTANCE_ID/finish \
  -H "Authorization: Bearer $PREFACTOR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "complete",
    "result_payload": {
      "category": "billing",
      "summary": "Customer was **charged twice**. Refund issued."
    }
  }'

From the CLI

The same three calls with the Prefactor CLI. Each schema and payload option takes JSON or @path; save the three schema entries from register.json as their own files first.

prefactor agent_instances register --agent_id YOUR_AGENT_ID --environment_id YOUR_ENVIRONMENT_ID \
  --agent_version_external_identifier triage-1.0.0 --agent_version_name triage-1.0.0 \
  --agent_schema_version_external_identifier triage-schema-1 \
  --instance_params_payload_schema @./input-schema.json \
  --instance_result_payload_schema @./result-schema.json \
  --instance_metadata_schema @./metadata-schema.json \
  --params_payload '{"ticket_id":"T-1042","priority":"urgent"}' \
  --metadata '{"trigger":"support-inbox"}'
prefactor agent_instances start YOUR_INSTANCE_ID
prefactor agent_instances finish YOUR_INSTANCE_ID --status complete \
  --result_payload '{"category":"billing","summary":"Customer was **charged twice**. Refund issued."}'

To discard an instance’s stored sensitive values, run prefactor agent_instances discard_sensitive YOUR_INSTANCE_ID.

Verify

Open the instance from the Agent page › History tab and select its Details tab. Below the lifecycle fields you should see three sections, titled Ticket to triage, Triage outcome, and Run context. Each lists its fields in alphabetical order by key, labelled with the schema’s title. The heading above the tabs shows “Triggered by support-inbox”.

The customer email reads as a labelled placeholder rather than a value. Select Show sensitive information for this instance in the heading to reveal it; the value is hidden again the next time you open the page.

What each payload accepts

Field	Set when	Rule
`params_payload`	You register the instance.	Checked against `instance_params_payload_schema`. Omitting it is checked as `null`, so it can be left out only when that schema allows `null`.
`metadata`	You register the instance. It can’t change afterwards.	Checked against `instance_metadata_schema`. Omitting it is checked as an empty object.
`result_payload`	You finish the instance with status `complete` or `failed`.	Checked against `instance_result_payload_schema` when you finish with `complete`, even if omitted. Optional on `failed`, but checked when sent. Ignored on `cancelled`.

A payload needs a schema. Sending params_payload, metadata, or result_payload for a schema version that doesn’t declare the matching schema is an error.

Prefactor checks the value inside a $sensitive marker against the schema, not the marker around it.

Mark sensitive values

Instance payloads always parse sensitive encoding; there is no flag to turn on. Wrap a value in a marker, as customer_email is above, and Prefactor stores it separately and redacts it by default. A literal $sensitive key in your own data needs the escape wrapper described in Sensitive encoding.

To delete the stored values for good, call the instance’s discard-sensitive operation. It redacts the input, result, and metadata, and leaves the spans alone.

Control how a field appears

The Details tab reads display hints from each property of your schema:

title and description replace the key as the field’s label and add a line beneath it. A field without a title shows its key in a monospace font.
A string with "format": "date-time" or "format": "date" is shown in the viewer’s timezone or as a plain date.
A string with "prefactor:format": "markdown" is rendered as formatted text.
A string with "prefactor:format": "verdict" shows a pass or fail badge when its value is pass or fail.
Objects and arrays appear as formatted JSON.

If it didn’t work

params_payload or metadata “is not allowed”. The schema version has no schema for it. Add instance_params_payload_schema or instance_metadata_schema to agent_schema_version.
metadata “is required”. The metadata schema has required fields, so the request must include metadata.
A validation error naming params_payload or metadata. The payload doesn’t match its schema. The message says which property failed.
Finish returns an error with code unexpected. The request sent result_payload for a schema version with no result schema. Add instance_result_payload_schema to the schema version, or leave result_payload out.
The Details tab shows “No payloads for this instance.” The instance has no recorded input, result, or metadata. Check that you sent them on the right call.

Instance — what the three payloads are and how they differ from spans.
Activity schema — the schema version these schemas live on.
Sensitive encoding — the marker format.
Summary templates — the language behind template.
Agent › Instance › Details tab — where the payloads appear.