Skip to content

Python SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI

4.2 KB
Raw Blame
---
title: 'Spans'
description: 'Understanding the different types of spans in AgentOps'
---
## Core Span Types

AgentOps organizes all spans with specific kinds:

| Span Kind | Description |
|-----------|-------------|
| `SESSION` | The root container for all activities in a single execution of your workflow |
| `AGENT` | Represents an autonomous entity with specialized capabilities |
| `WORKFLOW` | A logical grouping of related operations |
| `OPERATION` | A specific task or function performed by an agent |
| `TASK` | Alias for OPERATION, used interchangeably |
| `LLM` | An interaction with a language model |
| `TOOL` | The use of a tool or API by an agent |

## Span Hierarchy

Spans in AgentOps are organized hierarchically:

```
SESSION
  ├── AGENT
  │     ├── OPERATION/TASK
  │     │     ├── LLM
  │     │     └── TOOL
  │     └── WORKFLOW
  │           └── OPERATION/TASK
  └── LLM (unattributed to a specific agent)
```

Every span exists within the context of a session, and most spans (other than the session itself) have a parent span that provides context.

## Span Attributes

All spans in AgentOps include:

- **ID**: A unique identifier
- **Name**: A descriptive name
- **Kind**: The type of span (SESSION, AGENT, etc.)
- **Start Time**: When the span began
- **End Time**: When the span completed
- **Status**: Success or error status
- **Attributes**: Key-value pairs with additional metadata

Different span types have specialized attributes:

### LLM Spans

LLM spans track interactions with large language models and include:

- **Model**: The specific model used (e.g., "gpt-4", "claude-3-opus")
- **Provider**: The LLM provider (e.g., "OpenAI", "Anthropic")
- **Prompt Tokens**: Number of tokens in the input
- **Completion Tokens**: Number of tokens in the output
- **Cost**: The estimated cost of the interaction
- **Messages**: The prompt and completion content

### Tool Spans

Tool spans track the use of tools or APIs and include:

- **Tool Name**: The name of the tool used
- **Input**: The data provided to the tool
- **Output**: The result returned by the tool
- **Duration**: How long the tool operation took

### Operation/Task Spans

Operation spans track specific functions or tasks:

- **Operation Type**: The kind of operation performed
- **Parameters**: Input parameters to the operation
- **Result**: The output of the operation
- **Duration**: How long the operation took

## Creating Spans

There are several ways to create spans in AgentOps:

### Using Decorators

The recommended way to create spans is using decorators:

```python
from agentops.sdk.decorators import agent, operation, session, workflow, task

@session
def my_workflow():
    agent_instance = MyAgent()
    return agent_instance.perform_task()

@agent
class MyAgent:
    @operation
    def perform_task(self):
        # Perform the task
        return result
```

### Automatic Instrumentation

AgentOps automatically instruments LLM API calls from supported providers when `auto_instrument=True` (the default):

```python
import agentops
from openai import OpenAI

# Initialize AgentOps
agentops.init(api_key="YOUR_API_KEY")

# Initialize the OpenAI client
client = OpenAI()

# This LLM call will be automatically tracked
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

## Viewing Spans in the Dashboard

All recorded spans are visible in the AgentOps dashboard:

1. **Timeline View**: Shows the sequence and duration of spans
2. **Tree View**: Displays the hierarchical relationship between spans
3. **Details Panel**: Provides in-depth information about each span
4. **Analytics**: Aggregates statistics across spans

## Best Practices

- Use descriptive names for spans to make them easily identifiable
- Create a logical hierarchy with sessions, agents, and operations
- Record relevant parameters and results for better debugging
- Use consistent naming conventions for span types
- Track costs and token usage to monitor resource consumption

<script type="module" src="/scripts/github_stars.js"></script>
<script type="module" src="/scripts/scroll-img-fadein-animation.js"></script>
<script type="module" src="/scripts/button_heartbeat_animation.js"></script>