Python SDK

The SideSeat Python SDK (sideseat) provides OpenTelemetry instrumentation with automatic binary data handling, framework detection, and multiple export options. Stream runs into the local AI development workbench while keeping your stack intact.

What you’ll learn:

Install and configure the Python SDK
Set up OTLP, console, and file exporters
Handle binary data and framework detection

Prerequisites

SideSeat running locally (sideseat)
Python 3.10+

Installation

pip install sideseat
# or
uv add sideseat

Or with your package manager:

pip install sideseat

uv add sideseat

poetry add sideseat

Optional extras

The base package exports traces on its own. Instrumenting a specific framework pulls in that framework’s instrumentor, which ships as an extra:

pip install "sideseat[langchain]"
pip install "sideseat[openai,anthropic]"   # combine freely
pip install "sideseat[all]"                # every extra below

| Extra | For | | -------------------------------------------- | ------------------------------------------ | | langchain, langgraph | LangChain / LangGraph | | crewai | CrewAI | | autogen | AutoGen (AgentChat) | | ag2 | AG2 | | agno | Agno | | smolagents | Smolagents | | haystack | Haystack | | openai, openai-agents | OpenAI SDK / OpenAI Agents SDK | | anthropic | Anthropic SDK | | google-genai, vertex-ai | Google GenAI / Vertex AI | | pydantic-ai | Pydantic AI | | aws | Bedrock via boto3 | | ws, agui | Runtime channel — presence and invocation |

Quick Start

Add two lines at the top of your entry point:

from sideseat import SideSeat, Frameworks
from strands import Agent

SideSeat(framework=Frameworks.Strands)

agent = Agent()
response = agent("Hello!")

That’s it. Runs flow to SideSeat at http://localhost:5388.

Features

Automatic Framework Detection

When you do not pass framework=, the SDK looks for the first supported framework package that is installed and uses its distribution name as service.name — strands-agents for a Strands app, langchain-core for LangChain, and so on.

The full ordered list is in Configuration → framework. Passing framework= explicitly is recommended for anything non-trivial: detection is a convenience, and it cannot tell which of several installed frameworks you actually drive.

Override the service name with either of:

SideSeat(service_name="my-custom-service")

export OTEL_SERVICE_NAME=my-custom-service

Binary Data Handling

AI frameworks often use binary data (images, audio). The SDK automatically encodes binary data as base64:

# Default: encode binary as base64
client = SideSeat(encode_binary=True)

# Disable if not needed (saves bandwidth)
client = SideSeat(encode_binary=False)

Debug Exporters

Configure additional exporters for debugging:

client = SideSeat()

# Console (for debugging)
client.telemetry.setup_console_exporter()

# File (JSONL format)
client.telemetry.setup_file_exporter("traces.jsonl")

Resource Attributes

The SDK automatically sets these OpenTelemetry resource attributes:

| Attribute | Value | |-----------|-------| | service.name | Auto-detected or user-provided | | service.version | Package version (if detected) | | telemetry.sdk.name | sideseat | | telemetry.sdk.version | SDK version | | telemetry.sdk.language | python |

Context Manager

Use the context manager for automatic shutdown:

from sideseat import SideSeat, Frameworks
from strands import Agent

with SideSeat(framework=Frameworks.Strands) as client:
    agent = Agent()
    print(agent("Hello!"))
# Traces flushed and connection closed automatically on exit

Graceful Shutdown

The SDK registers an atexit handler for automatic shutdown. You can also call it explicitly:

client = SideSeat()

# ... your code ...

# Flush all pending spans before exit
client.shutdown()

Next Steps

Configuration — detailed configuration options
API Reference — SideSeat class reference
Exporters — console and file exporters for debugging