prefactor_http.endpoints.agent_instance module

prefactor_http.endpoints.agent_instance module

AgentInstance endpoint client.

class prefactor_http.endpoints.agent_instance.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

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 – If instance not found
  • PrefactorApiError – On other errors

async get(agent_instance_id: str) → AgentInstance

Fetch an agent instance by ID.

GET /api/v1/agent_instance/{agent_instance_id}

• Parameters: agent_instance_id – The instance ID to fetch.
• Returns: The agent instance.
• Raises:
  • PrefactorNotFoundError – If instance not found.
  • PrefactorApiError – On other errors.

async record_quality(agent_instance_id: str, name: str, payload: dict | None = None, idempotency_key: str | None = None) → AgentInstance

Record a quality payload on an agent instance.

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

Sets or clears one named quality payload. A null payload removes that name from the stored map. Other names are left unchanged.

• Parameters:
  • agent_instance_id – The instance ID.
  • name – Quality schema name (key in the agent schema version quality_schemas).
  • payload – Quality payload for this name, or None to remove the recorded payload for this name.
  • idempotency_key – Optional idempotency key.
• Returns: The updated agent instance.
• Raises:
  • PrefactorNotFoundError – If instance not found.
  • PrefactorApiError – On other errors.

async register(agent_version: dict, agent_schema_version: dict, agent_id: str | None = None, environment_id: str | None = None, id: str | None = None, idempotency_key: str | None = None, update_current_version: bool = True, purpose: Literal[‘live’, ‘smoke_test’, ‘eval’] | None = None) → AgentInstance

Register a new agent instance.

POST /api/v1/agent_instance/register

• Parameters:
  • agent_id – Agent ID. Omit when using a deployment-scoped token.
  • 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)
  • environment_id – Environment to deploy into. Required when using an account-scoped token; omit when using a deployment-scoped token
  • id – Optional custom ID for the instance
  • idempotency_key – Optional idempotency key
  • update_current_version – Whether to update the deployment’s pinned version (defaults to True)
  • purpose – Why this instance ran — "live", "smoke_test", or "eval". Omitted (None) lets the API default to "live".
• Returns: The created agent instance
• Raises:
  • PrefactorApiError – On API errors
  • PrefactorValidationError – On validation errors

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:
  • PrefactorNotFoundError – If instance not found
  • PrefactorApiError – On other errors