prefactor_core.managers.agent_instance module
prefactor_core.managers.agent_instance module
Section titled “prefactor_core.managers.agent_instance module”Agent instance handle and manager for convenient span creation.
The AgentInstanceManager handles agent instance lifecycle operations, while AgentInstanceHandle provides a high-level interface for managing an agent instance and creating spans within it.
class prefactor_core.managers.agent_instance.AgentInstanceHandle(instance_id: str, client: PrefactorCoreClient)
Section titled “class prefactor_core.managers.agent_instance.AgentInstanceHandle(instance_id: str, client: PrefactorCoreClient)”Bases: object
Handle to an agent instance with convenience methods.
This class provides a clean interface for:
- Starting and finishing the instance
- Creating spans within the instance
- Managing the instance lifecycle
Example
Section titled “Example”async with client.create_agent_instance(…) as instance:
: await instance.start()
async with instance.span(“agent:llm”) as span:
: span.set_payload({“model”: “gpt-4”})
# … do work …
await instance.finish()
async create_span(schema_name: str, parent_span_id: str | None = None, payload: dict[str, Any] | None = None) → str
Section titled “async create_span(schema_name: str, parent_span_id: str | None = None, payload: dict[str, Any] | None = None) → str”Create a span within this instance and return its ID.
The span stays open until finish_span() is called.
- Parameters:
- 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() → None
Section titled “async finish() → None”Mark the instance as finished.
This queues a finish operation for the instance.
async finish_span(span_id: str, result_payload: dict[str, Any] | None = None) → None
Section titled “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.
property id : str
Section titled “property id : str”Get the instance ID.
- Returns: The unique identifier for this agent instance.
span(schema_name: str, parent_span_id: str | None = None, payload: dict[str, Any] | None = None)
Section titled “span(schema_name: str, parent_span_id: str | None = None, payload: dict[str, Any] | None = None)”Create a span within this instance.
This is a convenience method that delegates to the client.
- Parameters:
- 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.
- Yields: SpanContext for the created span.
async start() → None
Section titled “async start() → None”Mark the instance as started.
This queues a start operation for the instance.
class prefactor_core.managers.agent_instance.AgentInstanceManager(http_client: PrefactorHttpClient, enqueue: Callable[[Operation], Awaitable[None]])
Section titled “class prefactor_core.managers.agent_instance.AgentInstanceManager(http_client: PrefactorHttpClient, enqueue: Callable[[Operation], Awaitable[None]])”Bases: object
Manages agent instance lifecycle operations.
This class provides a high-level interface for agent instance operations. Registration is done synchronously to get the API-generated ID, while start/finish operations are queued for async processing.
Example
Section titled “Example”manager = AgentInstanceManager(http_client, enqueue_func)
Register a new instance (synchronous - returns API-generated ID)
Section titled “Register a new instance (synchronous - returns API-generated ID)”instance_id = await manager.register(
agent_id=”my-agent”, agent_version={“name”: “1.0.0”}, agent_schema_version={“version”: “1.0.0”}
)
Start the instance (queued)
Section titled “Start the instance (queued)”await manager.start(instance_id)
Finish the instance (queued)
Section titled “Finish the instance (queued)”await manager.finish(instance_id)
async finish(instance_id: str) → None
Section titled “async finish(instance_id: str) → None”Mark an instance as finished.
Queues a finish operation for the instance.
- Parameters: instance_id – The ID of the instance to finish.
async finish_with_idempotency_key(instance_id: str, idempotency_key: str) → None
Section titled “async finish_with_idempotency_key(instance_id: str, idempotency_key: str) → None”Queue a finish operation using a stable idempotency key.
async register(agent_id: str, agent_version: dict[str, Any], agent_schema_version: dict[str, Any], instance_id: str | None = None) → str
Section titled “async register(agent_id: str, agent_version: dict[str, Any], agent_schema_version: dict[str, Any], instance_id: str | None = None) → str”Register a new agent instance.
Makes a synchronous API call to register the instance and returns the API-generated ID.
- Parameters:
- agent_id – ID of the agent to create an instance for.
- agent_version – Version information (name, external_identifier, etc.).
- agent_schema_version – Schema version information.
- instance_id – Optional ID to forward to the API as
id. When provided, the API uses it as the instance ID; when omitted, the API generates one.
- Returns: The instance ID (API-generated).
async start(instance_id: str) → None
Section titled “async start(instance_id: str) → None”Mark an instance as started.
Queues a start operation for the instance.
- Parameters: instance_id – The ID of the instance to start.
async start_with_idempotency_key(instance_id: str, idempotency_key: str) → None
Section titled “async start_with_idempotency_key(instance_id: str, idempotency_key: str) → None”Queue a start operation using a stable idempotency key.