Skip to content
Prefactor Docs

prefactor_http.endpoints package

prefactor_http.endpoints package

Section titled “prefactor_http.endpoints package”

Prefactor HTTP Client endpoints.

class prefactor_http.endpoints.AgentInstanceClient(http_client: PrefactorHttpClient)

Section titled “class prefactor_http.endpoints.AgentInstanceClient(http_client: PrefactorHttpClient)”

Bases: object

Client for AgentInstance POST endpoints.

Provides methods to interact with agent instances including:

  • register: Create a new agent instance
  • start: Mark an instance as started
  • finish: Mark an instance as finished

async finish(agent_instance_id: str, status: Literal[‘complete’, ‘failed’, ‘cancelled’] | None = None, timestamp: datetime | None = None, idempotency_key: str | None = None) → AgentInstance

Section titled “async finish(agent_instance_id: str, status: Literal[‘complete’, ‘failed’, ‘cancelled’] | None = None, timestamp: datetime | None = None, idempotency_key: str | None = None) → AgentInstance”

Mark an agent instance as finished.

POST /api/v1/agent_instance/{agent_instance_id}/finish

  • Parameters:
    • agent_instance_id – The instance ID
    • status – Optional finish status (complete, failed, cancelled)
    • timestamp – Optional finish time (defaults to now)
    • idempotency_key – Optional idempotency key
  • Returns: The updated agent instance
  • Raises:

async register(agent_id: str, agent_version: dict, agent_schema_version: dict, id: str | None = None, idempotency_key: str | None = None, update_current_version: bool = True) → AgentInstance

Section titled “async register(agent_id: str, agent_version: dict, agent_schema_version: dict, id: str | None = None, idempotency_key: str | None = None, update_current_version: bool = True) → AgentInstance”

Register a new agent instance.

POST /api/v1/agent_instance/register

  • Parameters:
    • agent_id – ID of the agent to create an instance for
    • agent_version – Version info dict with name, external_identifier, description
    • agent_schema_version – Schema version dict with external_identifier and span type definitions (span_type_schemas, span_schemas, and/or span_result_schemas)
    • id – Optional custom ID for the instance
    • idempotency_key – Optional idempotency key
    • update_current_version – Whether to update the current version (defaults to True)
  • Returns: The created agent instance
  • Raises:

async start(agent_instance_id: str, timestamp: datetime | None = None, idempotency_key: str | None = None) → AgentInstance

Section titled “async start(agent_instance_id: str, timestamp: datetime | None = None, idempotency_key: str | None = None) → AgentInstance”

Mark an agent instance as started.

POST /api/v1/agent_instance/{agent_instance_id}/start

  • Parameters:
    • agent_instance_id – The instance ID
    • timestamp – Optional start time (defaults to now)
    • idempotency_key – Optional idempotency key
  • Returns: The updated agent instance
  • Raises:

class prefactor_http.endpoints.AgentSpanClient(http_client: PrefactorHttpClient)

Section titled “class prefactor_http.endpoints.AgentSpanClient(http_client: PrefactorHttpClient)”

Bases: object

Client for AgentSpan POST endpoints.

Provides methods to interact with agent spans including:

  • create: Create a new agent span
  • finish: Mark a span as finished

async create(agent_instance_id: str, schema_name: str, status: Literal[‘pending’, ‘active’, ‘complete’, ‘failed’, ‘cancelled’], payload: dict | None = None, result_payload: dict | None = None, id: str | None = None, parent_span_id: str | None = None, started_at: datetime | None = None, finished_at: datetime | None = None, idempotency_key: str | None = None) → AgentSpan

Section titled “async create(agent_instance_id: str, schema_name: str, status: Literal[‘pending’, ‘active’, ‘complete’, ‘failed’, ‘cancelled’], payload: dict | None = None, result_payload: dict | None = None, id: str | None = None, parent_span_id: str | None = None, started_at: datetime | None = None, finished_at: datetime | None = None, idempotency_key: str | None = None) → AgentSpan”

Create a new agent span.

POST /api/v1/agent_spans

  • Parameters:
    • agent_instance_id – ID of the agent instance this span belongs to
    • schema_name – Name of the schema for this span
    • status – Status for the span
    • payload – Optional span payload data
    • result_payload – Optional result payload data
    • id – Optional custom ID for the span
    • parent_span_id – Optional parent span ID
    • started_at – Optional start time
    • finished_at – Optional finish time
    • idempotency_key – Optional idempotency key
  • Returns: The created agent span
  • Raises:

async finish(agent_span_id: str, status: Literal[‘complete’, ‘failed’, ‘cancelled’] | None = None, result_payload: dict | None = None, timestamp: datetime | None = None, idempotency_key: str | None = None) → AgentSpan

Section titled “async finish(agent_span_id: str, status: Literal[‘complete’, ‘failed’, ‘cancelled’] | None = None, result_payload: dict | None = None, timestamp: datetime | None = None, idempotency_key: str | None = None) → AgentSpan”

Finish an agent span.

POST /api/v1/agent_spans/{agent_span_id}/finish

  • Parameters:
    • agent_span_id – The span ID
    • status – Optional finish status (complete, failed, cancelled)
    • result_payload – Optional result payload data
    • timestamp – Optional finish time (defaults to now)
    • idempotency_key – Optional idempotency key
  • Returns: The updated agent span
  • Raises:

class prefactor_http.endpoints.BulkClient(http_client: PrefactorHttpClient)

Section titled “class prefactor_http.endpoints.BulkClient(http_client: PrefactorHttpClient)”

Bases: object

Client for bulk action operations.

Execute multiple POST actions in a single HTTP request. This endpoint allows you to batch multiple operations together, reducing the number of round trips to the API.

Key Features: : - Each item in the request is processed independently in its own database transaction

  • Processing stops early if any item returns an error
  • All successfully processed items up to the error are returned
  • Any unprocessed items (after the first error) are excluded from the result
  • All items must include a unique idempotency_key (minimum 8 characters)
  • Results are returned as a map keyed by idempotency_key

Example

Section titled “Example”
``
`

python request = BulkRequest(

items=[ : BulkItem( # type: ignore[call-arg] : _type=”agent_instances/register”, idempotency_key=”register-instance-001”, agent_id=”agent_123”, agent_version={“name”: “My Agent”, “external_identifier”: “v1.0.0”}, agent_schema_version={
> “external_identifier”: “v1.0.0”, > “span_type_schemas”: [
> > { > > : “name”: “agent:llm”, > > “title”: “LLM Call”, > > “params_schema”: { > >
> > > “type”: “object”, > > > “properties”: { > >
> > > > “model”: {“type”: “string”}, > > > > “prompt”: {“type”: “string”}, > >
> > > }, > > > “required”: [“model”, “prompt”], > >
> > }, > > “result_schema”: { > >
> > > “type”: “object”, > > > “properties”: { > >
> > > > “response”: {“type”: “string”}, > >
> > > }, > >
> > },
> > },
> ],
},
), BulkItem( # type: ignore[call-arg]

_type=”agent_spans/create”, idempotency_key=”create-span-001”, agent_instance_id=”instance_123”, schema_name=”agent:llm”, status=”active”,


),

]

) response = await client.bulk.execute(request) print(response.outputs[“create-span-001”].status)

``
`

async execute(request: BulkRequest) → BulkResponse

Section titled “async execute(request: BulkRequest) → BulkResponse”

Execute multiple queries/actions in a single request.

Submodules

Section titled “Submodules”