Skip to content
Prefactor Docs

Register a new agent instance with agent version

POST
/api/v1/agent_instance/register

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”
One of:
Agent_Id

A valid agent ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Success

object
agent_schema_version
AgentSchemaVersion_Details
object
account_id
Account_Id

A valid account ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
agent_id
Agent_Id

A valid agent ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
current_agent_deployment_refs

Agent deployments whose current version uses this schema version (empty if none).

Array<string>
external_identifier

External identifier for the agent schema version

string
Example
v0
external_identifier_repeats

Count of rows sharing this external identifier (helps distinguish duplicates).

integer
id
AgentSchemaVersion_Id

A valid agent schema version ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
inserted_at

When the agent schema version was created

string format: date-time
Example
2024-01-01T00:00:00Z
span_type_schemas

Map of span type names to their params and result JSON schemas

object
key
additional properties
SpanTypeSchemaDetails
object
data_risk
DataRisk
object
action_profile
required
ActionProfile
object
create_data
required

Creates data

string
Allowed values: unknown allowed disallowed
Example
unknown
destroy_data
required

Destroys data

string
Allowed values: unknown allowed disallowed
Example
unknown
external_communication
required

Sends external communications

string
Allowed values: unknown allowed disallowed
Example
unknown
financial_transactions
required

Performs financial transactions

string
Allowed values: unknown allowed disallowed
Example
unknown
read_data
required

Reads data

string
Allowed values: unknown allowed disallowed
Example
unknown
update_data
required

Updates data

string
Allowed values: unknown allowed disallowed
Example
unknown
params_data_categories
required
DataCategories
object
authentication_and_secrets
required

Authentication and secrets present

string
Allowed values: unknown included excluded
Example
unknown
behavioural_and_inferred
required

Behavioural and inferred data present

string
Allowed values: unknown included excluded
Example
unknown
classification
required

Classification level

string
Allowed values: unknown public internal confidential restricted secret
Example
unknown
contact_information
required

Contact information present

string
Allowed values: unknown included excluded
Example
unknown
criminal_justice
required

Criminal justice data present

string
Allowed values: unknown included excluded
Example
unknown
financial_information
required

Financial information present

string
Allowed values: unknown included excluded
Example
unknown
gdpr_biometric_for_identification
required

GDPR: biometric data for identification

string
Allowed values: unknown included excluded
Example
unknown
gdpr_genetic_data
required

GDPR: genetic data

string
Allowed values: unknown included excluded
Example
unknown
gdpr_political_opinions
required

GDPR: political opinions

string
Allowed values: unknown included excluded
Example
unknown
gdpr_racial_or_ethnic_origin
required

GDPR: racial or ethnic origin

string
Allowed values: unknown included excluded
Example
unknown
gdpr_religious_or_philosophical_beliefs
required

GDPR: religious or philosophical beliefs

string
Allowed values: unknown included excluded
Example
unknown
gdpr_sex_life_or_sexual_orientation
required

GDPR: sex life or sexual orientation

string
Allowed values: unknown included excluded
Example
unknown
gdpr_trade_union_membership
required

GDPR: trade union membership

string
Allowed values: unknown included excluded
Example
unknown
health_and_medical
required

Health and medical data present

string
Allowed values: unknown included excluded
Example
unknown
location_and_tracking
required

Location and tracking data present

string
Allowed values: unknown included excluded
Example
unknown
minors_data
required

Minors data present

string
Allowed values: unknown included excluded
Example
unknown
organisational_confidential
required

Organisational confidential data present

string
Allowed values: unknown included excluded
Example
unknown
personal_identifiers
required

Personal identifiers present

string
Allowed values: unknown included excluded
Example
unknown
result_data_categories
required
DataCategories
object
authentication_and_secrets
required

Authentication and secrets present

string
Allowed values: unknown included excluded
Example
unknown
behavioural_and_inferred
required

Behavioural and inferred data present

string
Allowed values: unknown included excluded
Example
unknown
classification
required

Classification level

string
Allowed values: unknown public internal confidential restricted secret
Example
unknown
contact_information
required

Contact information present

string
Allowed values: unknown included excluded
Example
unknown
criminal_justice
required

Criminal justice data present

string
Allowed values: unknown included excluded
Example
unknown
financial_information
required

Financial information present

string
Allowed values: unknown included excluded
Example
unknown
gdpr_biometric_for_identification
required

GDPR: biometric data for identification

string
Allowed values: unknown included excluded
Example
unknown
gdpr_genetic_data
required

GDPR: genetic data

string
Allowed values: unknown included excluded
Example
unknown
gdpr_political_opinions
required

GDPR: political opinions

string
Allowed values: unknown included excluded
Example
unknown
gdpr_racial_or_ethnic_origin
required

GDPR: racial or ethnic origin

string
Allowed values: unknown included excluded
Example
unknown
gdpr_religious_or_philosophical_beliefs
required

GDPR: religious or philosophical beliefs

string
Allowed values: unknown included excluded
Example
unknown
gdpr_sex_life_or_sexual_orientation
required

GDPR: sex life or sexual orientation

string
Allowed values: unknown included excluded
Example
unknown
gdpr_trade_union_membership
required

GDPR: trade union membership

string
Allowed values: unknown included excluded
Example
unknown
health_and_medical
required

Health and medical data present

string
Allowed values: unknown included excluded
Example
unknown
location_and_tracking
required

Location and tracking data present

string
Allowed values: unknown included excluded
Example
unknown
minors_data
required

Minors data present

string
Allowed values: unknown included excluded
Example
unknown
organisational_confidential
required

Organisational confidential data present

string
Allowed values: unknown included excluded
Example
unknown
personal_identifiers
required

Personal identifiers present

string
Allowed values: unknown included excluded
Example
unknown
description
One of:

Optional description

string
name

Span type name

string
params_schema

JSON schema for the span payload

object
key
additional properties
any
params_schema_validation
SchemaValidationResult

Result of validating params_schema

object
message
One of:

Validation error message when status is ‘error’

string
status

Whether the schema is valid

string
Allowed values: success error
Example
success
result_schema

JSON schema for the span result payload (defaults to empty object if omitted when creating)

object
key
additional properties
any
result_schema_validation
SchemaValidationResult

Result of validating result_schema

object
message
One of:

Validation error message when status is ‘error’

string
status

Whether the schema is valid

string
Allowed values: success error
Example
success
template
One of:

Display template describing what happened in the span. Use {{field}} to interpolate params and result fields. Use imperative/command tense for params (e.g. “Generate {{content}}”) and past tense for result (e.g. “completed with {{finish_reason}}”).

string
title

Human-readable title (defaults to name)

string
Example
{
  "llm": {
    "name": "llm",
    "params_schema": {
      "properties": {
        "max_tokens": {
          "type": "integer"
        },
        "model": {
          "type": "string"
        },
        "temperature": {
          "type": "number"
        }
      },
      "type": "object"
    },
    "result_schema": {
      "properties": {
        "tokens": {
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "tool": {
    "name": "tool",
    "params_schema": {
      "properties": {
        "input": {
          "type": "object"
        },
        "name": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "result_schema": {
      "additionalProperties": false,
      "type": "object"
    }
  }
}
type

Type of resource (always ‘agent_schema_version’)

string
Allowed values: agent_schema_version
Example
agent_schema_version
updated_at

When the agent schema version was last updated

string format: date-time
Example
2024-01-01T00:00:00Z
agent_version
AgentVersion_Details
object
account_id
Account_Id

A valid account ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
agent_id
Agent_Id

A valid agent ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
agent_schema_version_id
AgentSchemaVersion_Id

A valid agent schema version ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
current_agent_deployment_refs

Agent deployments that pin this version as their current version (empty if none).

Array<string>
external_identifier

External identifier for the agent version

string
Example
v1.0.0
external_identifier_repeats

Count of rows sharing this external identifier (helps distinguish duplicates).

integer
id
AgentVersion_Id

A valid agent version ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
inserted_at

When the agent version was created

string format: date-time
Example
2024-01-01T00:00:00Z
runtime_environment
One of:
AgentVersion_RuntimeEnvironment
object
agent_sdk
One of:

List of package name and version strings (e.g. “package@1.0.0”)

Array<string>
os
One of:

Operating system (e.g. “linux”)

string
prefactor_sdk
One of:

List of package name and version strings (e.g. “package@1.0.0”)

Array<string>
runtime
One of:

Language runtime version (e.g. “python@3.12”)

string
type

Type of resource (always ‘agent_version’)

string
Allowed values: agent_version
Example
agent_version
updated_at

When the agent version was last updated

string format: date-time
Example
2024-01-01T00:00:00Z
details
AgentInstance_Details
object
account_id
Account_Id

A valid account ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
agent_deployment_id
AgentDeployment_Id

A valid agent deployment ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
agent_id
Agent_Id

A valid agent ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
agent_version_id
AgentVersion_Id

A valid agent version ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
environment_id
Environment_Id

A valid environment ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
finished_at
One of:

When the agent instance finished (null if still in progress)

string format: date-time
Example
2024-01-01T00:00:00Z
id
AgentInstance_Id

A valid agent instance ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
inserted_at

When the agent instance was created

string format: date-time
Example
2024-01-01T00:00:00Z
span_counts
AgentInstance_SpanCounts
object
active

Number of spans with status active (running)

integer
Example
2
cancelled

Number of spans with status cancelled

integer
0
complete

Number of spans with status complete

integer
Example
5
failed

Number of spans with status failed

integer
0
finished

Number of spans in a finished state (complete + failed + cancelled)

integer
Example
5
pending

Number of spans with status pending

integer
0
total

Total number of agent spans

integer
Example
10
started_at
One of:

When the agent instance started (null if not started yet)

string format: date-time
Example
2024-01-01T00:00:00Z
status

Status of the agent instance: ‘pending’ (not started yet), ‘active’ (started but not finished), ‘complete’ (finished successfully), ‘failed’ (ended with failure), ‘cancelled’ (never started, cancelled), or ‘terminated’ (externally terminated)

string
Allowed values: pending active complete failed cancelled terminated
Example
active
termination_reason
One of:

Reason for termination (only present when status is ‘terminated’)

string
Example
User requested termination
type

Type of resource (always ‘agent_instance’)

string
Allowed values: agent_instance
Example
agent_instance
updated_at

When the agent instance was last updated

string format: date-time
Example
2024-01-01T00:00:00Z
status
string
Allowed values: success
Example
success

default

Section titled “default ”

Error

One of:
object
code
string
Allowed values: bad_request bad_authtoken not_authenticated not_permitted not_implemented unknown not_found unexpected_ref_type unexpected invalid_action invalid_value required_value idempotency_key_already_used
Example
bad_request
message
string
status
string
Allowed values: error
Example
error