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

# prefactor_http.endpoints.agent_instance module

AgentInstance endpoint client.

### *class* prefactor_http.endpoints.agent_instance.AgentInstanceClient(http_client: [PrefactorHttpClient](prefactor_http.md#prefactor_http.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](prefactor_http.models.agent_instance.md#prefactor_http.models.agent_instance.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:**
  * [**PrefactorNotFoundError**](prefactor_http.md#prefactor_http.PrefactorNotFoundError) – If instance not found
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On other errors

#### *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](prefactor_http.models.agent_instance.md#prefactor_http.models.agent_instance.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:**
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On API errors
  * [**PrefactorValidationError**](prefactor_http.md#prefactor_http.PrefactorValidationError) – On validation errors

#### *async* start(agent_instance_id: str, timestamp: datetime | None = None, idempotency_key: str | None = None) → [AgentInstance](prefactor_http.models.agent_instance.md#prefactor_http.models.agent_instance.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:**
  * [**PrefactorNotFoundError**](prefactor_http.md#prefactor_http.PrefactorNotFoundError) – If instance not found
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On other errors