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

# prefactor_core.client module

Main client for prefactor-core.

This module provides the PrefactorCoreClient, which is the main entry point
for the SDK. It manages the complete lifecycle of agent instances and spans
through an async queue-based architecture.

### *class* prefactor_core.client.PrefactorCoreClient(config: [PrefactorCoreConfig](prefactor_core.config.md#prefactor_core.config.PrefactorCoreConfig), queue: [Queue](prefactor_core.queue.base.md#prefactor_core.queue.base.Queue)[[Operation](prefactor_core.operations.md#prefactor_core.operations.Operation)] | None = None, sdk_header_entry: str | None = None)

Bases: `object`

Main entry point for the prefactor-core SDK.

This client provides a high-level interface for managing agent instances
and spans. All operations are queued and processed asynchronously, ensuring
minimal impact on agent execution flow.

The client must be initialized before use, either by calling initialize()
or using it as an async context manager.

### Example

config = PrefactorCoreConfig(http_config=…)

async with PrefactorCoreClient(config) as client:
: instance = await client.create_agent_instance(…)
  await instance.start()
  <br/>
  async with instance.span(“agent:llm”) as span:
  : span.set_payload({“model”: “gpt-4”})
    # Your agent logic here
  <br/>
  await instance.finish()

#### *async* close() → None

Close the client and cleanup resources.

This method gracefully shuts down the executor and closes the
HTTP client. It should be called when the client is no longer needed.

#### *async* create_agent_instance(agent_id: str, agent_version: dict[str, Any], agent_schema_version: dict[str, Any] | None = None, instance_id: str | None = None, external_schema_version_id: str | None = None) → [AgentInstanceHandle](prefactor_core.md#prefactor_core.AgentInstanceHandle)

Create a new agent instance.

Returns immediately with a handle. The actual registration happens
asynchronously via the queue.

If agent_schema_version is not provided but the client has a schema_registry,
the registry’s schemas will be used automatically.

* **Parameters:**
  * **agent_id** – ID of the agent to create an instance for.
  * **agent_version** – Version information (name, etc.).
  * **agent_schema_version** – Schema version. Uses registry if not provided
    and registry is configured.
  * **instance_id** – Optional custom ID for the instance.
  * **external_schema_version_id** – Optional external identifier for the
    schema version. Defaults to “auto-generated” when using registry.
* **Returns:**
  AgentInstanceHandle for the created instance.
* **Raises:**
  * [**ClientNotInitializedError**](prefactor_core.md#prefactor_core.ClientNotInitializedError) – If the client is not initialized.
  * **ValueError** – If no schema version provided and registry not configured.

#### *async* create_span(instance_id: str, schema_name: str, parent_span_id: str | None = None, payload: dict[str, Any] | None = None) → str

Create a span and return its ID without finishing it.

Use this for spans that need to stay open across multiple operations.
Call finish_span() when done.

* **Parameters:**
  * **instance_id** – ID of the agent instance this span belongs to.
  * **schema_name** – Name of the schema for this span.
  * **parent_span_id** – Optional explicit parent span ID.
  * **payload** – Optional initial payload (params/inputs) stored on creation.
* **Returns:**
  The span ID.

#### *async* finish_span(span_id: str, result_payload: dict[str, Any] | None = None) → None

Finish a previously created span.

* **Parameters:**
  * **span_id** – The ID of the span to finish.
  * **result_payload** – Optional result data to store on the span.

#### *async* initialize() → None

Initialize the client and start processing.

This method:
1. Initializes the HTTP client
2. Starts the task executor
3. Initializes managers

* **Raises:**
  [**ClientAlreadyInitializedError**](prefactor_core.md#prefactor_core.ClientAlreadyInitializedError) – If already initialized.

#### *property* instance_manager *: [AgentInstanceManager](prefactor_core.managers.agent_instance.md#prefactor_core.managers.agent_instance.AgentInstanceManager) | None*

Public accessor for the agent instance manager.

#### span(instance_id: str, schema_name: str, parent_span_id: str | None = None, payload: dict[str, Any] | None = None)

Context manager for creating and finishing a span.

If parent_span_id is not provided, the current span from the
SpanContextStack is used as the parent.

The returned `SpanContext` supports an explicit lifecycle:

1. `await span.start(payload)` — POST the span to the API.
2. Do work.
3. `await span.complete(result)` / `span.fail(result)` /
   `span.cancel()` — finish with a specific status.

If `start()` or a finish method is not called explicitly, the
context manager handles them automatically on exit.

* **Parameters:**
  * **instance_id** – ID of the agent instance this span belongs to.
  * **schema_name** – Name of the schema for this span.
  * **parent_span_id** – Optional explicit parent span ID.
  * **payload** – Optional initial payload sent via auto-start on exit
    if `start()` is never called explicitly.
* **Yields:**
  SpanContext for the created span.