---
title: prefactor_core.models module
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

# prefactor_core.models module

Data models for prefactor-core.

This module contains dataclasses and models used throughout the SDK.

### *class* prefactor_core.models.AgentInstance(id: str, agent_id: str, status: str = 'pending', created_at: datetime = <factory>, started_at: datetime | None = None, finished_at: datetime | None = None, metadata: dict[str, ~typing.Any]=<factory>)

Bases: `object`

Represents an agent instance.

An agent instance is a single execution of an agent. It tracks
the lifecycle from registration through completion.

#### id

Unique identifier for this instance.

* **Type:**
  str

#### agent_id

ID of the agent this is an instance of.

* **Type:**
  str

#### status

Current status (pending, active, complete).

* **Type:**
  str

#### created_at

When the instance was registered.

* **Type:**
  datetime.datetime

#### started_at

When the instance started executing (if started).

* **Type:**
  datetime.datetime | None

#### finished_at

When the instance completed (if finished).

* **Type:**
  datetime.datetime | None

#### metadata

Additional metadata about the instance.

* **Type:**
  dict[str, Any]

#### agent_id *: str*

#### created_at *: datetime*

#### finished_at *: datetime | None* *= None*

#### id *: str*

#### metadata *: dict[str, Any]*

#### started_at *: datetime | None* *= None*

#### status *: str* *= 'pending'*

### *class* prefactor_core.models.Span(id: str, instance_id: str, schema_name: str, parent_span_id: str | None = None, status: str = 'pending', payload: dict[str, ~typing.Any]=<factory>, created_at: datetime = <factory>, started_at: datetime | None = None, finished_at: datetime | None = None)

Bases: `object`

Represents a span within an agent instance.

Spans represent discrete units of work within an agent execution,
such as LLM calls, tool executions, or processing steps.

#### id

Unique identifier for this span.

* **Type:**
  str

#### instance_id

ID of the agent instance this span belongs to.

* **Type:**
  str

#### parent_span_id

ID of the parent span (if nested).

* **Type:**
  str | None

#### schema_name

Name of the schema defining this span type.

* **Type:**
  str

#### status

Current status (pending, active, complete).

* **Type:**
  str

#### payload

Arbitrary data associated with this span.

* **Type:**
  dict[str, Any]

#### created_at

When the span was created.

* **Type:**
  datetime.datetime

#### started_at

When the span started (defaults to created_at).

* **Type:**
  datetime.datetime | None

#### finished_at

When the span completed (if finished).

* **Type:**
  datetime.datetime | None

#### created_at *: datetime*

#### finished_at *: datetime | None* *= None*

#### id *: str*

#### instance_id *: str*

#### parent_span_id *: str | None* *= None*

#### payload *: dict[str, Any]*

#### schema_name *: str*

#### started_at *: datetime | None* *= None*

#### status *: str* *= 'pending'*