How to beginner · 3 min read

How to replay agent sessions in AgentOps

Q: How to replay agent sessions in AgentOps

Use the agentops Python SDK to retrieve and replay agent sessions by their session ID. Initialize agentops with your API key, then call agentops.replay_session(session_id) to replay the session and inspect the recorded interactions.

Quick answer

Use the agentops Python SDK to retrieve and replay agent sessions by their session ID. Initialize agentops with your API key, then call agentops.replay_session(session_id) to replay the session and inspect the recorded interactions.

PREREQUISITES

Python 3.8+
AgentOps API key
pip install agentops

Setup

Install the agentops Python package and set your API key as an environment variable.

Install package: pip install agentops
Set environment variable: export AGENTOPS_API_KEY=your_api_key (Linux/macOS) or set AGENTOPS_API_KEY=your_api_key (Windows)

bash

pip install agentops

output

Collecting agentops
  Downloading agentops-1.0.0-py3-none-any.whl (10 kB)
Installing collected packages: agentops
Successfully installed agentops-1.0.0

Step by step

Use the agentops SDK to replay a session by its ID. This example initializes the SDK, replays the session, and prints the recorded events.

python

import os
import agentops

# Initialize AgentOps with API key from environment
agentops.init(api_key=os.environ["AGENTOPS_API_KEY"])

# Replace with your actual session ID
session_id = "your-session-id"

# Replay the session
session = agentops.replay_session(session_id)

# Iterate over recorded events and print details
for event in session.events:
    print(f"Timestamp: {event.timestamp}, Type: {event.type}, Data: {event.data}")

output

Timestamp: 2026-04-01T12:00:00Z, Type: llm_call, Data: {'prompt': 'Hello', 'response': 'Hi there!'}
Timestamp: 2026-04-01T12:00:05Z, Type: tool_call, Data: {'tool': 'search', 'query': 'AgentOps docs'}
Timestamp: 2026-04-01T12:00:10Z, Type: llm_call, Data: {'prompt': 'Summarize results', 'response': 'AgentOps helps replay sessions easily.'}

Common variations

You can replay sessions asynchronously or filter events by type. Also, you can replay sessions from different agents or date ranges by querying session metadata.

python

import asyncio
import agentops

async def replay_async(session_id: str):
    agentops.init(api_key=os.environ["AGENTOPS_API_KEY"])
    session = await agentops.replay_session_async(session_id)
    for event in session.events:
        print(f"[Async] {event.timestamp} {event.type}: {event.data}")

# Usage
asyncio.run(replay_async("your-session-id"))

output

[Async] 2026-04-01T12:00:00Z llm_call: {'prompt': 'Hello', 'response': 'Hi there!'}
[Async] 2026-04-01T12:00:05Z tool_call: {'tool': 'search', 'query': 'AgentOps docs'}
[Async] 2026-04-01T12:00:10Z llm_call: {'prompt': 'Summarize results', 'response': 'AgentOps helps replay sessions easily.'}

Troubleshooting

If you get an authentication error, verify your AGENTOPS_API_KEY environment variable is set correctly.
If the session ID is invalid or not found, confirm the ID is correct and the session exists in your AgentOps dashboard.
For network issues, check your internet connection and firewall settings.

✅

Key Takeaways

Initialize AgentOps with your API key using agentops.init() before replaying sessions.
Use agentops.replay_session(session_id) to retrieve and inspect past agent interactions.
Async replay is supported via agentops.replay_session_async() for non-blocking workflows.
Ensure your session IDs are correct and API keys are valid to avoid errors.
AgentOps session replay helps debug and audit agent behavior effectively.

Verified 2026-04

Verify ↗