Skip to content
Prefactor Docs

prefactor_http.endpoints.agent_span module

prefactor_http.endpoints.agent_span module

Section titled “prefactor_http.endpoints.agent_span module”

AgentSpan endpoint client.

class prefactor_http.endpoints.agent_span.AgentSpanClient(http_client: PrefactorHttpClient)

Section titled “class prefactor_http.endpoints.agent_span.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’], 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

Section titled “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”

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:

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

Section titled “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”

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: