Skip to main content

​
Collecting Actions

​
Explicit Tracking

The SDK collects explicit actions that you define in your code. Use the action context manager to track discrete units of work: 
with self.client.action(anonymous_id=anonymous_id, user_id=user_id) as span:
    span.send(
        action_name="object_detection",
        **{
            "value.action.description": f"Detected {box_count} objects in {invoice_id}",
            "invoice_id": invoice_id,
            "model": "yolov8-invoice",
            "confidence_score": confidence,
            "detected_boxes": box_count,
            "processing_device": "cuda:0"
        }
    )
Each action tracks both anonymous_id and user_id to identify who performed the action. This allows you to attribute usage to specific users even when they’re not authenticated.

​
Automatic LLM Tracking

LLM traces are automatically tracked by the SDK. You don’t need to manually instrument LLM calls. The SDK captures model usage, input and output tokens, latency, cost information, and other LLM-specific metadata.

​
Computed Data Model

Based on the actions you send and the Control Plane configuration, the following data model is computed:

​
@action

A discrete unit of work performed by your agent, explicitly tracked via the SDK or automatically captured from LLM traces. Examples:
  • Object detection in an invoice processing workflow
  • LLM call to generate a response
  • Image classification task
  • Data extraction from a document
  • API call to an external service

​
@outcome

A business result derived from actions, computed by the Control Plane based on configured outcome rules. Examples:
  • Successful invoice processed (derived from object_detection actions)
  • Customer query resolved (derived from LLM call actions)
  • Document classified correctly (derived from classification actions)
  • Lead converted to customer (derived from multiple actions)
  • Task completed successfully (derived from workflow actions)

​
@user

An end user of your service, identified by user_id or anonymous_id in actions, used for per-user usage tracking and billing. Examples:
  • Authenticated user with user_id="user_123"
  • Anonymous visitor with anonymous_id="anon_456"
  • API client identified by user_id="api_client_789"
  • Internal user with user_id="internal_team_001"

​
@seat

A billing unit representing a licensed user, computed from user activity and seat assignment rules configured in the Control Plane. Examples:
  • Active user who has used the service in the last 30 days
  • User assigned a seat based on role or department