mseep-agentops 0.4.18__py3-none-any.whl

agentops/semconv/resource.py

@@ -0,0 +1,52 @@
+"""
+Resource attribute semantic conventions for AgentOps.
+
+This module defines standard resource attributes used to identify resources in
+AgentOps telemetry data.
+"""
+
+
+class ResourceAttributes:
+    """
+    Resource attributes for AgentOps.
+
+    These attributes provide standard identifiers for resources being monitored
+    or interacted with by AgentOps.
+    """
+
+    # Project identifier - uniquely identifies an AgentOps project
+    PROJECT_ID = "agentops.project.id"
+
+    # Service attributes
+    SERVICE_NAME = "service.name"
+    SERVICE_VERSION = "service.version"
+
+    # Environment attributes
+    ENVIRONMENT = "agentops.environment"
+    DEPLOYMENT_ENVIRONMENT = "deployment.environment"
+
+    # SDK attributes
+    SDK_NAME = "agentops.sdk.name"
+    SDK_VERSION = "agentops.sdk.version"
+
+    # Host machine attributes
+    HOST_MACHINE = "host.machine"
+    HOST_NAME = "host.name"
+    HOST_NODE = "host.node"
+    HOST_OS_RELEASE = "host.os_release"
+    HOST_PROCESSOR = "host.processor"
+    HOST_SYSTEM = "host.system"
+    HOST_VERSION = "host.version"
+
+    # CPU attributes
+    CPU_COUNT = "cpu.count"
+    CPU_PERCENT = "cpu.percent"
+
+    # Memory attributes
+    MEMORY_TOTAL = "memory.total"
+    MEMORY_AVAILABLE = "memory.available"
+    MEMORY_USED = "memory.used"
+    MEMORY_PERCENT = "memory.percent"
+
+    # Libraries
+    IMPORTED_LIBRARIES = "imported_libraries"

agentops/semconv/span_attributes.py

@@ -0,0 +1,118 @@
+"""Span attributes for OpenTelemetry semantic conventions."""
+
+
+class SpanAttributes:
+    # Semantic Conventions for LLM requests based on OpenTelemetry Gen AI conventions
+    # Refer to https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-spans.md
+    #
+    # TODO: There is an important deviation from the OpenTelemetry spec in our current implementation.
+    # In our OpenAI instrumentation, we're mapping from source→target keys incorrectly in the _token_type function
+    # in shared/__init__.py. According to our established pattern, mapping dictionaries should consistently use
+    # target→source format (where keys are target attributes and values are source fields).
+    #
+    # Current implementation (incorrect):
+    # def _token_type(token_type: str):
+    #     if token_type == "prompt_tokens":  # source
+    #         return "input"  # target
+    #
+    # Correct implementation should be:
+    # token_type_mapping = {
+    #     "input": "prompt_tokens",  # target → source
+    #     "output": "completion_tokens"
+    # }
+    #
+    # Then we have to adapt code using the function to handle the inverted mapping.
+
+    # System
+    LLM_SYSTEM = "gen_ai.system"
+
+    # Request attributes
+    LLM_REQUEST_MODEL = "gen_ai.request.model"
+    LLM_REQUEST_MAX_TOKENS = "gen_ai.request.max_tokens"
+    LLM_REQUEST_TEMPERATURE = "gen_ai.request.temperature"
+    LLM_REQUEST_TOP_P = "gen_ai.request.top_p"
+    LLM_REQUEST_TOP_K = "gen_ai.request.top_k"
+    LLM_REQUEST_SEED = "gen_ai.request.seed"
+    LLM_REQUEST_SYSTEM_INSTRUCTION = "gen_ai.request.system_instruction"
+    LLM_REQUEST_CANDIDATE_COUNT = "gen_ai.request.candidate_count"
+    LLM_REQUEST_STOP_SEQUENCES = "gen_ai.request.stop_sequences"
+    LLM_REQUEST_TYPE = "gen_ai.request.type"
+    LLM_REQUEST_STREAMING = "gen_ai.request.streaming"
+    LLM_REQUEST_FREQUENCY_PENALTY = "gen_ai.request.frequency_penalty"
+    LLM_REQUEST_PRESENCE_PENALTY = "gen_ai.request.presence_penalty"
+    LLM_REQUEST_FUNCTIONS = "gen_ai.request.functions"
+    LLM_REQUEST_HEADERS = "gen_ai.request.headers"
+    LLM_REQUEST_INSTRUCTIONS = "gen_ai.request.instructions"
+    LLM_REQUEST_VOICE = "gen_ai.request.voice"
+    LLM_REQUEST_SPEED = "gen_ai.request.speed"
+
+    # Content
+    LLM_PROMPTS = "gen_ai.prompt"
+    LLM_COMPLETIONS = "gen_ai.completion"  # DO NOT SET THIS DIRECTLY
+    LLM_CONTENT_COMPLETION_CHUNK = "gen_ai.completion.chunk"
+
+    # Response attributes
+    LLM_RESPONSE_MODEL = "gen_ai.response.model"
+    LLM_RESPONSE_FINISH_REASON = "gen_ai.response.finish_reason"
+    LLM_RESPONSE_STOP_REASON = "gen_ai.response.stop_reason"
+    LLM_RESPONSE_ID = "gen_ai.response.id"
+
+    # Usage metrics
+    LLM_USAGE_COMPLETION_TOKENS = "gen_ai.usage.completion_tokens"
+    LLM_USAGE_PROMPT_TOKENS = "gen_ai.usage.prompt_tokens"
+    LLM_USAGE_TOTAL_TOKENS = "gen_ai.usage.total_tokens"
+    LLM_USAGE_CACHE_CREATION_INPUT_TOKENS = "gen_ai.usage.cache_creation_input_tokens"
+    LLM_USAGE_CACHE_READ_INPUT_TOKENS = "gen_ai.usage.cache_read_input_tokens"
+    LLM_USAGE_REASONING_TOKENS = "gen_ai.usage.reasoning_tokens"
+    LLM_USAGE_STREAMING_TOKENS = "gen_ai.usage.streaming_tokens"
+    LLM_USAGE_TOOL_COST = "gen_ai.usage.total_cost"
+
+    # Message attributes
+    # see ./message.py for message-related attributes
+
+    # Token type
+    LLM_TOKEN_TYPE = "gen_ai.token.type"
+
+    # User
+    LLM_USER = "gen_ai.user"
+
+    # OpenAI specific
+    LLM_OPENAI_RESPONSE_SYSTEM_FINGERPRINT = "gen_ai.openai.system_fingerprint"
+    LLM_OPENAI_RESPONSE_INSTRUCTIONS = "gen_ai.openai.instructions"
+    LLM_OPENAI_API_BASE = "gen_ai.openai.api_base"
+    LLM_OPENAI_API_VERSION = "gen_ai.openai.api_version"
+    LLM_OPENAI_API_TYPE = "gen_ai.openai.api_type"
+
+    # AgentOps specific attributes
+    AGENTOPS_ENTITY_OUTPUT = "agentops.entity.output"
+    AGENTOPS_ENTITY_INPUT = "agentops.entity.input"
+    AGENTOPS_SPAN_KIND = "agentops.span.kind"
+    AGENTOPS_ENTITY_NAME = "agentops.entity.name"
+    AGENTOPS_DECORATOR_SPEC = "agentops.{entity_kind}.spec"
+    AGENTOPS_DECORATOR_INPUT = "agentops.{entity_kind}.input"
+    AGENTOPS_DECORATOR_OUTPUT = "agentops.{entity_kind}.output"
+
+    # Operation attributes
+    OPERATION_NAME = "operation.name"
+    OPERATION_VERSION = "operation.version"
+
+    # Session/Trace attributes
+    AGENTOPS_SESSION_END_STATE = "agentops.session.end_state"
+
+    # Streaming-specific attributes
+    LLM_STREAMING_TIME_TO_FIRST_TOKEN = "gen_ai.streaming.time_to_first_token"
+    LLM_STREAMING_TIME_TO_GENERATE = "gen_ai.streaming.time_to_generate"
+    LLM_STREAMING_DURATION = "gen_ai.streaming_duration"
+    LLM_STREAMING_CHUNK_COUNT = "gen_ai.streaming.chunk_count"
+
+    # HTTP-specific attributes
+    HTTP_METHOD = "http.method"
+    HTTP_URL = "http.url"
+    HTTP_ROUTE = "http.route"
+    HTTP_STATUS_CODE = "http.status_code"
+    HTTP_REQUEST_HEADERS = "http.request.headers"
+    HTTP_RESPONSE_HEADERS = "http.response.headers"
+    HTTP_REQUEST_BODY = "http.request.body"
+    HTTP_RESPONSE_BODY = "http.response.body"
+    HTTP_USER_AGENT = "http.user_agent"
+    HTTP_REQUEST_ID = "http.request_id"

agentops/semconv/span_kinds.py

@@ -0,0 +1,50 @@
+"""Span kinds for AgentOps."""
+
+from enum import Enum
+
+
+class AgentOpsSpanKindValues(Enum):
+    """Standard span kind values for AgentOps."""
+
+    WORKFLOW = "workflow"
+    SESSION = "session"
+    TASK = "task"
+    OPERATION = "operation"
+    AGENT = "agent"
+    TOOL = "tool"
+    LLM = "llm"
+    TEAM = "team"
+    CHAIN = "chain"
+    TEXT = "text"
+    GUARDRAIL = "guardrail"
+    HTTP = "http"
+    UNKNOWN = "unknown"
+
+
+# Legacy SpanKind class for backward compatibility
+class SpanKind:
+    """Legacy span kind definitions - use AgentOpsSpanKindValues instead."""
+
+    # Agent action kinds
+    AGENT_ACTION = "agent.action"  # Agent performing an action
+    AGENT_THINKING = "agent.thinking"  # Agent reasoning/planning
+    AGENT_DECISION = "agent.decision"  # Agent making a decision
+
+    # LLM interaction kinds
+    LLM_CALL = "llm.call"  # LLM API call
+
+    # Workflow kinds
+    WORKFLOW_STEP = "workflow.step"  # Step in a workflow
+    WORKFLOW = AgentOpsSpanKindValues.WORKFLOW.value
+    SESSION = AgentOpsSpanKindValues.SESSION.value
+    TASK = AgentOpsSpanKindValues.TASK.value
+    OPERATION = AgentOpsSpanKindValues.OPERATION.value
+    AGENT = AgentOpsSpanKindValues.AGENT.value
+    TOOL = AgentOpsSpanKindValues.TOOL.value
+    LLM = AgentOpsSpanKindValues.LLM.value
+    TEAM = AgentOpsSpanKindValues.TEAM.value
+    UNKNOWN = AgentOpsSpanKindValues.UNKNOWN.value
+    CHAIN = AgentOpsSpanKindValues.CHAIN.value
+    TEXT = AgentOpsSpanKindValues.TEXT.value
+    GUARDRAIL = AgentOpsSpanKindValues.GUARDRAIL.value
+    HTTP = AgentOpsSpanKindValues.HTTP.value

agentops/semconv/status.py

@@ -0,0 +1,11 @@
+"""Status enumerations for spans."""
+
+from enum import Enum
+
+
+class ToolStatus(Enum):
+    """Tool status values."""
+
+    EXECUTING = "executing"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"

agentops/semconv/tool.py

@@ -0,0 +1,15 @@
+"""Attributes specific to tool spans."""
+
+
+class ToolAttributes:
+    """Attributes specific to tool spans."""
+
+    # Identity
+    TOOL_ID = "tool.id"  # Unique identifier for the tool
+    TOOL_NAME = "tool.name"  # Name of the tool
+    TOOL_DESCRIPTION = "tool.description"  # Description of the tool
+
+    # Execution
+    TOOL_PARAMETERS = "tool.parameters"  # Parameters passed to the tool
+    TOOL_RESULT = "tool.result"  # Result returned by the tool
+    TOOL_STATUS = "tool.status"  # Status of tool execution

agentops/semconv/workflow.py

@@ -0,0 +1,69 @@
+"""Attributes specific to workflow spans."""
+
+
+class WorkflowAttributes:
+    """Workflow specific attributes."""
+
+    # Core workflow attributes
+    WORKFLOW_NAME = "workflow.name"  # Name of the workflow
+    WORKFLOW_TYPE = "workflow.type"  # Type of workflow
+    WORKFLOW_ID = "workflow.workflow_id"  # Unique identifier for the workflow instance
+    WORKFLOW_RUN_ID = "workflow.run_id"  # Unique identifier for this workflow run
+    WORKFLOW_DESCRIPTION = "workflow.description"  # Description of the workflow
+
+    # Input/Output
+    WORKFLOW_INPUT = "workflow.input"  # Input to the workflow
+    WORKFLOW_INPUT_TYPE = "workflow.input.type"  # Type of input to the workflow
+    WORKFLOW_OUTPUT = "workflow.output"  # Output from the workflow
+    WORKFLOW_OUTPUT_TYPE = "workflow.output.type"  # Type of output from the workflow
+    WORKFLOW_FINAL_OUTPUT = "workflow.final_output"  # Final output of the workflow
+
+    # Workflow step attributes (only keep used ones)
+    WORKFLOW_STEP_TYPE = "workflow.step.type"  # Type of workflow step
+    WORKFLOW_STEP_STATUS = "workflow.step.status"  # Status of the workflow step
+
+    # Configuration
+    WORKFLOW_MAX_TURNS = "workflow.max_turns"  # Maximum number of turns in a workflow
+    WORKFLOW_DEBUG_MODE = "workflow.debug_mode"  # Whether debug mode is enabled
+    WORKFLOW_MONITORING = "workflow.monitoring"  # Whether monitoring is enabled
+    WORKFLOW_TELEMETRY = "workflow.telemetry"  # Whether telemetry is enabled
+
+    # Memory and Storage
+    WORKFLOW_MEMORY_TYPE = "workflow.memory_type"  # Type of memory used by the workflow
+    WORKFLOW_STORAGE_TYPE = "workflow.storage_type"  # Type of storage used by the workflow
+
+    # Session context (simplified)
+    WORKFLOW_SESSION_ID = "workflow.session_id"  # Session ID for the workflow execution
+    WORKFLOW_SESSION_NAME = "workflow.session_name"  # Session name for the workflow
+    WORKFLOW_USER_ID = "workflow.user_id"  # User ID associated with the workflow
+    WORKFLOW_APP_ID = "workflow.app_id"  # Application ID associated with the workflow
+
+    # Input metadata
+    WORKFLOW_INPUT_PARAMETER_COUNT = "workflow.input.parameter_count"  # Number of input parameters
+    WORKFLOW_INPUT_PARAMETER_KEYS = "workflow.input.parameter_keys"  # Keys of input parameters
+    WORKFLOW_METHOD_PARAMETER_COUNT = "workflow.method.parameter_count"  # Number of method parameters
+    WORKFLOW_METHOD_RETURN_TYPE = "workflow.method.return_type"  # Return type of the workflow method
+
+    # Output metadata (commonly used)
+    WORKFLOW_OUTPUT_CONTENT_TYPE = "workflow.output.content_type"  # Content type of the output
+    WORKFLOW_OUTPUT_EVENT = "workflow.output.event"  # Event type of the output
+    WORKFLOW_OUTPUT_MODEL = "workflow.output.model"  # Model used for the output
+    WORKFLOW_OUTPUT_MODEL_PROVIDER = "workflow.output.model_provider"  # Model provider for the output
+    WORKFLOW_OUTPUT_MESSAGE_COUNT = "workflow.output.message_count"  # Number of messages in output
+    WORKFLOW_OUTPUT_TOOL_COUNT = "workflow.output.tool_count"  # Number of tools in output
+    WORKFLOW_OUTPUT_IS_STREAMING = "workflow.output.is_streaming"  # Whether output is streaming
+
+    # Media counts (used by agno)
+    WORKFLOW_OUTPUT_IMAGE_COUNT = "workflow.output.image_count"  # Number of images in output
+    WORKFLOW_OUTPUT_VIDEO_COUNT = "workflow.output.video_count"  # Number of videos in output
+    WORKFLOW_OUTPUT_AUDIO_COUNT = "workflow.output.audio_count"  # Number of audio items in output
+
+    # Session-specific attributes (used by agno)
+    WORKFLOW_SESSION_WORKFLOW_ID = "workflow.session.workflow_id"  # Workflow ID in session context
+    WORKFLOW_SESSION_USER_ID = "workflow.session.user_id"  # User ID in session context
+    WORKFLOW_SESSION_STATE_KEYS = "workflow.session.state_keys"  # Keys in session state
+    WORKFLOW_SESSION_STATE_SIZE = "workflow.session.state_size"  # Size of session state
+    WORKFLOW_SESSION_STORAGE_TYPE = "workflow.session.storage_type"  # Storage type for session
+    WORKFLOW_SESSION_RETURNED_SESSION_ID = "workflow.session.returned_session_id"  # Returned session ID
+    WORKFLOW_SESSION_CREATED_AT = "workflow.session.created_at"  # Session creation timestamp
+    WORKFLOW_SESSION_UPDATED_AT = "workflow.session.updated_at"  # Session update timestamp

agentops/validation.py

@@ -0,0 +1,357 @@
+"""
+AgentOps Validation Module
+
+This module provides functions to validate that spans have been sent to AgentOps
+using the public API. This is useful for testing and verification purposes.
+"""
+
+import time
+import requests
+from typing import Optional, Dict, List, Any, Tuple
+
+from agentops.logging import logger
+from agentops.exceptions import ApiServerException
+
+
+class ValidationError(Exception):
+    """Raised when span validation fails."""
+
+    pass
+
+
+def get_jwt_token(api_key: Optional[str] = None) -> str:
+    """
+    Exchange API key for JWT token.
+
+    Args:
+        api_key: Optional API key. If not provided, uses AGENTOPS_API_KEY env var.
+
+    Returns:
+        JWT bearer token
+
+    Raises:
+        ApiServerException: If token exchange fails
+    """
+    if api_key is None:
+        from agentops import get_client
+
+        client = get_client()
+        if client and client.config.api_key:
+            api_key = client.config.api_key
+        else:
+            import os
+
+            api_key = os.getenv("AGENTOPS_API_KEY")
+            if not api_key:
+                raise ValueError("No API key provided and AGENTOPS_API_KEY environment variable not set")
+
+    try:
+        response = requests.post(
+            "https://api.agentops.ai/public/v1/auth/access_token", json={"api_key": api_key}, timeout=10
+        )
+        response.raise_for_status()
+        return response.json()["bearer"]
+    except requests.exceptions.RequestException as e:
+        raise ApiServerException(f"Failed to get JWT token: {e}")
+
+
+def get_trace_details(trace_id: str, jwt_token: str) -> Dict[str, Any]:
+    """
+    Get trace details from AgentOps API.
+
+    Args:
+        trace_id: The trace ID to query
+        jwt_token: JWT authentication token
+
+    Returns:
+        Trace details including spans
+
+    Raises:
+        ApiServerException: If API request fails
+    """
+    try:
+        response = requests.get(
+            f"https://api.agentops.ai/public/v1/traces/{trace_id}",
+            headers={"Authorization": f"Bearer {jwt_token}"},
+            timeout=10,
+        )
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.RequestException as e:
+        raise ApiServerException(f"Failed to get trace details: {e}")
+
+
+def get_trace_metrics(trace_id: str, jwt_token: str) -> Dict[str, Any]:
+    """
+    Get trace metrics from AgentOps API.
+
+    Args:
+        trace_id: The trace ID to query
+        jwt_token: JWT authentication token
+
+    Returns:
+        Trace metrics including token counts and costs
+
+    Raises:
+        ApiServerException: If API request fails
+    """
+    try:
+        response = requests.get(
+            f"https://api.agentops.ai/public/v1/traces/{trace_id}/metrics",
+            headers={"Authorization": f"Bearer {jwt_token}"},
+            timeout=10,
+        )
+        response.raise_for_status()
+        return response.json()
+    except requests.exceptions.RequestException as e:
+        raise ApiServerException(f"Failed to get trace metrics: {e}")
+
+
+def check_llm_spans(spans: List[Dict[str, Any]]) -> Tuple[bool, List[str]]:
+    """
+    Check if any LLM spans are present in the trace.
+
+    Args:
+        spans: List of span dictionaries
+
+    Returns:
+        Tuple of (has_llm_spans, llm_span_names)
+    """
+    llm_spans = []
+
+    for span in spans:
+        span_name = span.get("span_name", "unnamed_span")
+
+        # Check span attributes for LLM span kind
+        span_attributes = span.get("span_attributes", {})
+        is_llm_span = False
+
+        # If we have span_attributes, check them
+        if span_attributes:
+            # Try different possible structures for span kind
+            span_kind = None
+
+            # Structure 1: span_attributes.agentops.span.kind
+            if isinstance(span_attributes, dict):
+                agentops_attrs = span_attributes.get("agentops", {})
+                if isinstance(agentops_attrs, dict):
+                    span_info = agentops_attrs.get("span", {})
+                    if isinstance(span_info, dict):
+                        span_kind = span_info.get("kind", "")
+
+            # Structure 2: Direct in span_attributes
+            if not span_kind and isinstance(span_attributes, dict):
+                # Try looking for agentops.span.kind as a flattened key
+                span_kind = span_attributes.get("agentops.span.kind", "")
+
+            # Structure 3: Look for SpanAttributes.AGENTOPS_SPAN_KIND
+            if not span_kind and isinstance(span_attributes, dict):
+                from agentops.semconv import SpanAttributes
+
+                span_kind = span_attributes.get(SpanAttributes.AGENTOPS_SPAN_KIND, "")
+
+            # Check if this is an LLM span by span kind
+            is_llm_span = span_kind == "llm"
+
+            # Alternative check: Look for gen_ai.prompt or gen_ai.completion attributes
+            # These are standard semantic conventions for LLM spans
+            if not is_llm_span and isinstance(span_attributes, dict):
+                gen_ai_attrs = span_attributes.get("gen_ai", {})
+                if isinstance(gen_ai_attrs, dict):
+                    # If we have prompt or completion data, it's an LLM span
+                    if "prompt" in gen_ai_attrs or "completion" in gen_ai_attrs:
+                        is_llm_span = True
+
+            # Check for LLM_REQUEST_TYPE attribute (used by provider instrumentations)
+            if not is_llm_span and isinstance(span_attributes, dict):
+                from agentops.semconv import SpanAttributes, LLMRequestTypeValues
+
+                # Check for LLM request type - try both gen_ai.* and llm.* prefixes
+                # The instrumentation sets gen_ai.* but the API might return llm.*
+                llm_request_type = span_attributes.get(SpanAttributes.LLM_REQUEST_TYPE, "")
+                if not llm_request_type:
+                    # Try the llm.* prefix version
+                    llm_request_type = span_attributes.get("llm.request.type", "")
+
+                # Check if it's a chat or completion request (the main LLM types)
+                if llm_request_type in [LLMRequestTypeValues.CHAT.value, LLMRequestTypeValues.COMPLETION.value]:
+                    is_llm_span = True
+
+        if is_llm_span:
+            llm_spans.append(span_name)
+
+    return len(llm_spans) > 0, llm_spans
+
+
+def validate_trace_spans(
+    trace_id: Optional[str] = None,
+    trace_context: Optional[Any] = None,
+    max_retries: int = 10,
+    retry_delay: float = 1.0,
+    check_llm: bool = True,
+    min_spans: int = 1,
+    api_key: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Validate that spans have been sent to AgentOps.
+
+    Args:
+        trace_id: Direct trace ID to validate
+        trace_context: TraceContext object from start_trace (alternative to trace_id)
+        max_retries: Maximum number of retries to wait for spans to appear
+        retry_delay: Delay between retries in seconds
+        check_llm: Whether to specifically check for LLM spans
+        min_spans: Minimum number of spans expected
+        api_key: Optional API key (uses environment variable if not provided)
+
+    Returns:
+        Dictionary containing validation results and metrics
+
+    Raises:
+        ValidationError: If validation fails
+        ValueError: If neither trace_id nor trace_context is provided
+    """
+    # Extract trace ID
+    if trace_id is None and trace_context is None:
+        # Try to get from current span
+        try:
+            from opentelemetry.trace import get_current_span
+
+            current_span = get_current_span()
+            if current_span and hasattr(current_span, "get_span_context"):
+                span_context = current_span.get_span_context()
+                if hasattr(span_context, "trace_id") and span_context.trace_id:
+                    if isinstance(span_context.trace_id, int):
+                        trace_id = format(span_context.trace_id, "032x")
+                    else:
+                        trace_id = str(span_context.trace_id)
+        except ImportError:
+            pass
+
+    elif trace_context is not None and trace_id is None:
+        # Extract from TraceContext
+        if hasattr(trace_context, "span") and trace_context.span:
+            span_context = trace_context.span.get_span_context()
+            if hasattr(span_context, "trace_id"):
+                if isinstance(span_context.trace_id, int):
+                    trace_id = format(span_context.trace_id, "032x")
+                else:
+                    trace_id = str(span_context.trace_id)
+
+    if trace_id is None:
+        raise ValueError("No trace ID found. Provide either trace_id or trace_context parameter.")
+
+    # Get JWT token
+    jwt_token = get_jwt_token(api_key)
+
+    logger.info(f"Validating spans for trace ID: {trace_id}")
+
+    for attempt in range(max_retries):
+        try:
+            # Get trace details
+            trace_details = get_trace_details(trace_id, jwt_token)
+            spans = trace_details.get("spans", [])
+
+            if len(spans) >= min_spans:
+                logger.info(f"Found {len(spans)} span(s) in trace")
+
+                # Prepare result
+                result = {
+                    "trace_id": trace_id,
+                    "span_count": len(spans),
+                    "spans": spans,
+                    "has_llm_spans": False,
+                    "llm_span_names": [],
+                    "metrics": None,
+                }
+
+                # Get metrics first - if we have token usage, we definitely have LLM spans
+                try:
+                    metrics = get_trace_metrics(trace_id, jwt_token)
+                    result["metrics"] = metrics
+
+                    if metrics:
+                        logger.info(
+                            f"Trace metrics - Total tokens: {metrics.get('total_tokens', 0)}, "
+                            f"Cost: ${metrics.get('total_cost', '0.0000')}"
+                        )
+
+                        # If we have token usage > 0, we definitely have LLM activity
+                        if metrics.get("total_tokens", 0) > 0:
+                            result["has_llm_spans"] = True
+                            logger.info("LLM activity confirmed via token usage metrics")
+                except Exception as e:
+                    logger.warning(f"Could not retrieve metrics: {e}")
+
+                # Check for LLM spans if requested and not already confirmed via metrics
+                if check_llm and not result["has_llm_spans"]:
+                    has_llm_spans, llm_span_names = check_llm_spans(spans)
+                    result["has_llm_spans"] = has_llm_spans
+                    result["llm_span_names"] = llm_span_names
+
+                    if has_llm_spans:
+                        logger.info(f"Found LLM spans: {', '.join(llm_span_names)}")
+                    else:
+                        logger.warning("No LLM spans found via attribute inspection")
+
+                # Final validation
+                if check_llm and not result["has_llm_spans"]:
+                    raise ValidationError(
+                        f"No LLM activity detected in trace {trace_id}. "
+                        f"Found spans: {[s.get('span_name', 'unnamed') for s in spans]}, "
+                        f"Token usage: {result.get('metrics', {}).get('total_tokens', 0)}"
+                    )
+
+                return result
+
+            else:
+                logger.debug(
+                    f"Only {len(spans)} spans found, expected at least {min_spans}. "
+                    f"Retrying... ({attempt + 1}/{max_retries})"
+                )
+
+        except ApiServerException as e:
+            logger.debug(f"API error during validation: {e}. Retrying... ({attempt + 1}/{max_retries})")
+
+        if attempt < max_retries - 1:
+            time.sleep(retry_delay)
+
+    raise ValidationError(
+        f"Validation failed for trace {trace_id} after {max_retries} attempts. "
+        f"Expected at least {min_spans} spans"
+        + (", including LLM activity" if check_llm else "")
+        + ". Please check that tracking is properly configured."
+    )
+
+
+def print_validation_summary(result: Dict[str, Any]) -> None:
+    """
+    Print a user-friendly summary of validation results.
+
+    Args:
+        result: Validation result dictionary from validate_trace_spans
+    """
+    print("\n" + "=" * 50)
+    print("🔍 AgentOps Span Validation Results")
+    print("=" * 50)
+
+    print(f"✅ Found {result['span_count']} span(s) in trace")
+
+    if result.get("has_llm_spans"):
+        if result.get("llm_span_names"):
+            print(f"✅ Found LLM spans: {', '.join(result['llm_span_names'])}")
+        else:
+            # LLM activity confirmed via metrics
+            print("✅ LLM activity confirmed via token usage metrics")
+    elif "has_llm_spans" in result:
+        print("⚠️  No LLM activity detected")
+
+    if result.get("metrics"):
+        metrics = result["metrics"]
+        print("\n📊 Trace Metrics:")
+        print(f"   - Total tokens: {metrics.get('total_tokens', 0)}")
+        print(f"   - Prompt tokens: {metrics.get('prompt_tokens', 0)}")
+        print(f"   - Completion tokens: {metrics.get('completion_tokens', 0)}")
+        print(f"   - Total cost: ${metrics.get('total_cost', '0.0000')}")
+
+    print("\n✅ Validation successful!")