prefactor_http.endpoints package

prefactor_http.endpoints package

Prefactor HTTP Client endpoints.

class prefactor_http.endpoints.AgentClient(http_client: PrefactorHttpClient)

Bases: object

Client for Agent endpoints.

Provides methods to manage agents including:

• create: Create a new agent
• get: Fetch an agent by ID
• update: Update an agent
• list: List agents
• show: Look up an agent by ID or external_identifier
• retire: Retire an agent
• reinstate: Reinstate a retired agent
• delete: Delete an agent

async create(details: AgentForCreate, idempotency_key: str | None = None) → Agent

Create a new agent.

POST /api/v1/agent

• Parameters:
  • details – Agent creation parameters.
  • idempotency_key – Optional idempotency key.
• Returns: The created agent.
• Raises:
  • PrefactorApiError – On API errors.
  • PrefactorValidationError – On validation errors.

async delete(agent_id: str, idempotency_key: str | None = None) → Agent

Delete an agent.

DELETE /api/v1/agent/{agent_id}

• Parameters:
  • agent_id – The agent ID to delete.
  • idempotency_key – Optional idempotency key.
• Returns: The deleted agent.
• Raises:
  • PrefactorNotFoundError – If agent not found.
  • PrefactorApiError – On other errors.

async get(agent_id: str) → Agent

Fetch an agent by ID.

GET /api/v1/agent/{agent_id}

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

async list_agents(risk_profile_id: str | None = None, team_id: str | None = None, owner_person_id: str | None = None, sorting: str | None = None, offset: int | None = None, page_size: int | None = None) → list[AgentSummary]

List agents.

GET /api/v1/agent

• Parameters:
  • risk_profile_id – Filter by risk profile (null for agents with none).
  • team_id – Filter by team (null for agents with no team).
  • owner_person_id – Filter by owner (null for agents with no owner).
  • sorting – Sort order (e.g. "name" or "-id").
  • offset – Zero-based offset for pagination.
  • page_size – Number of items per page (1-100).
• Returns: List of agent summaries.
• Raises: PrefactorApiError – On API errors.

async reinstate(agent_id: str, idempotency_key: str | None = None) → Agent

Reinstate a retired agent.

POST /api/v1/agent/{agent_id}/reinstate

• Parameters:
  • agent_id – The agent ID to reinstate.
  • idempotency_key – Optional idempotency key.
• Returns: The updated agent.
• Raises:
  • PrefactorNotFoundError – If agent not found.
  • PrefactorApiError – On other errors.

async retire(agent_id: str, idempotency_key: str | None = None) → Agent

Retire an agent.

POST /api/v1/agent/{agent_id}/retire

• Parameters:
  • agent_id – The agent ID to retire.
  • idempotency_key – Optional idempotency key.
• Returns: The updated agent.
• Raises:
  • PrefactorNotFoundError – If agent not found.
  • PrefactorApiError – On other errors.

async show(, agent_id: str | None = None, external_identifier: str | None = None, environment_id: str | None = None, include_counts: bool = False, include_risk_rollup: bool = False) → Agent

Look up an agent by ID or external_identifier.

GET /api/v1/agent/show

Provide exactly one of agent_id or external_identifier.

• Parameters:
  • agent_id – Agent ID to look up.
  • external_identifier – External identifier to look up (exact match).
  • environment_id – Optional environment to scope risk rollup and counts.
  • include_counts – Include instance counts in the response.
  • include_risk_rollup – Include risk rollup in the response.
• Returns: The agent.
• Raises:
  • PrefactorNotFoundError – If agent not found.
  • PrefactorApiError – On other errors.

async update(agent_id: str, details: AgentForUpdate, idempotency_key: str | None = None) → Agent

Update an agent.

PUT /api/v1/agent/{agent_id}

• Parameters:
  • agent_id – The agent ID to update.
  • details – Fields to update (only provided fields are changed).
  • idempotency_key – Optional idempotency key.
• Returns: The updated agent.
• Raises:
  • PrefactorNotFoundError – If agent not found.
  • PrefactorApiError – On other errors.

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

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

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’, ‘terminated’], 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, control_signal_callback: Callable[[str | None], None] | 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:
  • PrefactorApiError – On API errors
  • PrefactorValidationError – On validation errors

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, control_signal_callback: Callable[[str | None], None] | 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:
  • PrefactorNotFoundError – If span not found
  • PrefactorApiError – On other errors

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

``

`

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

Execute multiple queries/actions in a single request.

• Parameters: request – The bulk request containing items to process.
• Returns: BulkResponse with outputs keyed by idempotency_key.
• Raises:
  • PrefactorValidationError – If the request is invalid.
  • PrefactorRetryExhaustedError – If the request fails after all retries.
  • PrefactorApiError – If the API returns an error response.

Submodules

• prefactor_http.endpoints.agent module
  • AgentClient
    • AgentClient.create()
    • AgentClient.delete()
    • AgentClient.get()
    • AgentClient.list_agents()
    • AgentClient.reinstate()
    • AgentClient.retire()
    • AgentClient.show()
    • AgentClient.update()
• prefactor_http.endpoints.agent_instance module
  • AgentInstanceClient
    • AgentInstanceClient.finish()
    • AgentInstanceClient.get()
    • AgentInstanceClient.record_quality()
    • AgentInstanceClient.register()
    • AgentInstanceClient.start()
• prefactor_http.endpoints.agent_span module
  • AgentSpanClient
    • AgentSpanClient.create()
    • AgentSpanClient.finish()
• prefactor_http.endpoints.bulk module
  • BulkClient
    • BulkClient.execute()