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

5.6 KB
Raw Blame
---
title: Sessions
description: Detailed breakdown of initializing AgentOps and managing sessions.
---

A **Session** encapsulates a singular execution instance of your workflow, bringing together all agents, LLMs, 
actions, etc., under one umbrella. Consequently, it is imperative for each event to be associated with a session. 
The AgentOps dashboard provides detailed insights at the session level, including costs, token counts, errors, and more.

**There must be an active session in order to use AgentOps.**

---

## `Session`

### Properties

Sessions possess the following attributes:
- **ID**: A unique identifier for the session.
- **Project ID**: Identifies the project associated with the session, determined by the API Key used.
- **Starting Timestamp**: Marks the beginning of the session.
- **Ending Timestamp**: Indicates when the session concludes.
- **End State**: Signifies the success or failure of the session.

Optionally, sessions may include:
- **End State Reason**: Explains why the session ended, whether due to an error or a user-triggered interrupt (SIGINT).
- **Tags**: Tags allow for the categorization and later retrieval of sessions.
- **Host Environment**: Automatically gathers basic information about the system on which the session ran.
- **Video**: If applicable, an optional video recording of the session.


### Methods
#### `end_session`
**Params**
- **end_state** (str, enum): Success|Failure|Indeterminate
- **end_state_reason** (optional, str): additional notes on end state

**Returns** (str): Total cost of session in USD

#### `record`
**Params**
- **event** ([Event](/v1/concepts/events#event-class)): The Event to record as part of the session

#### `get_analytics`
**Returns** (dict): A dictionary containing various analytics metrics for the session.


## Starting a Session
When you call `agentops.init()`, a session is automatically started.
Calling `agentops.init(auto_start_session=False)` will initialize the AgentOps SDK but not start a session.

To start a session later, call `agentops.start_session()` [(reference)](/v1/usage/sdk-reference/#start-session)

Both `agentops.init()` and `agentops.start_session()` work as a factory pattern and return a `Session` object. The above methods can all be called on this session object.

## Ending a Session
If a process ends without any call to agentops, it will show in the dashboard as `Indeterminate`.
To end with a state, call either `agentops.end_session(...)` [(reference)](/v1/usage/sdk-reference/#end-session) if only one session is in use. Otherwise use `session.end_session(...)`.

## Inherited Sessions
When working with multiple agents running in different processes, it's possible to initialize AgentOps or start a session
with an existing session_id.

`agentops.init(inherited_session_id=<id>)`
`agentops.start_session(inherited_session_id=<id>)`

You can retrieve the current `session_id` by assigning the returned value from `init()` or `start_session()`.

<CodeGroup>

```python
import agentops
session = agentops.init()
# pass session.session_id to the other process
```

```python
# -- other process --
session_id = retrieve_session_id() # <-- your function
agentops.init(inherited_session_id=<id>)
```

</CodeGroup>

Both processes will now contribute data to the same session.

## Session Data Export
AgentOps provides REST endpoints to export your session data and statistics. These endpoints allow you to retrieve detailed information about your sessions programmatically.

### Authentication
All data export requests require a single header:
- `X-Agentops-Api-Key`: Your AgentOps API key

### Available Endpoints

#### Get Session Statistics
```http
GET /v2/sessions/<session_id>/stats
```

Returns statistics for the specified session including:
- Event counts
- Duration
- Costs
- Token usage
- Other session metrics

#### Export Complete Session Data
```http
GET /v2/sessions/<session_id>/export
```

Returns comprehensive session data including:
- Session metadata
- Statistics
- All recorded events:
  - Actions
  - LLM calls
  - Tool usage
  - Errors

### Example Usage
```python
import requests

# Your AgentOps API key
api_key = "your-api-key"
session_id = "your-session-id"

headers = {
    "X-Agentops-Api-Key": api_key
}

# Get session stats
stats_url = f"https://api.agentops.ai/v2/sessions/{session_id}/stats"
stats_response = requests.get(stats_url, headers=headers)
stats = stats_response.json()

# Export complete session data
export_url = f"https://api.agentops.ai/v2/sessions/{session_id}/export"
export_response = requests.get(export_url, headers=headers)
session_data = export_response.json()
```

## Session Analytics
You can retrieve the analytics for a session by calling `session.get_analytics()`.

The example below shows how to record events and retrieve analytics.

<CodeGroup>

```python
import agentops
session = agentops.init()
session.record(ActionEvent("llms"))
session.record(ActionEvent("tools"))
analytics = session.get_analytics()
print(analytics)
session.end_session("Success")
```

The output will look like this -

```bash
{'LLM calls': 0, 'Tool calls': 0, 'Actions': 0, 'Errors': 0, 'Duration': '0.9s', 'Cost': '0.00'}
```

</CodeGroup>

## The AgentOps SDK Client
_More info for the curious_

Under the hood, `agentops.init()` creates a `Client` object with various configuration options. Whenever you start a new session, these configuration options will automatically
be applied. You can also apply different configuration options when you start a new session by passing in a
[Config](/v1/usage/sdk-reference/#config) object.

<script type="module" src="/scripts/github_stars.js"></script>
<script type="module" src="/scripts/adjust_api_dynamically.js"></script>