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

# prefactor_http.endpoints.agent_span module

AgentSpan endpoint client.

### *class* prefactor_http.endpoints.agent_span.AgentSpanClient(http_client: [PrefactorHttpClient](prefactor_http.md#prefactor_http.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'], 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) → [AgentSpan](prefactor_http.models.agent_span.md#prefactor_http.models.agent_span.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**](prefactor_http.md#prefactor_http.PrefactorApiError) – On API errors
  * [**PrefactorValidationError**](prefactor_http.md#prefactor_http.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) → [AgentSpan](prefactor_http.models.agent_span.md#prefactor_http.models.agent_span.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**](prefactor_http.md#prefactor_http.PrefactorNotFoundError) – If span not found
  * [**PrefactorApiError**](prefactor_http.md#prefactor_http.PrefactorApiError) – On other errors