Python SDK Configuration

This page covers all configuration options for the SideSeat Python SDK.

Constructor Parameters

Every parameter is keyword-only — the * means there are no positional arguments, so SideSeat("http://localhost:5388") raises TypeError.

SideSeat(
    *,
    # Connection
    endpoint: str | None = None,
    project_id: str | None = None,
    api_key: str | None = None,

    # Framework
    framework: str | list[str] | None = None,
    auto_instrument: bool = True,

    # Service identity
    service_name: str | None = None,
    service_version: str | None = None,

    # Telemetry signals
    enable_traces: bool = True,
    enable_metrics: bool = True,
    enable_logs: bool | None = None,   # None -> env var, else False

    # Content capture
    capture_content: bool = True,
    encode_binary: bool = True,

    # Control
    disabled: bool | None = None,      # None -> SIDESEAT_DISABLED, else False
    debug: bool | None = None,         # None -> SIDESEAT_DEBUG, else False
)

Note

disabled, enable_logs and debug default to None, not False. None means “consult the environment”; passing False explicitly pins the value and overrides the env var. This is what lets SIDESEAT_DISABLED=true work without the constructor arguing with it.

Connection Parameters

endpoint

SideSeat server URL.

# Default
client = SideSeat()  # Uses http://127.0.0.1:5388

# Custom endpoint
client = SideSeat(endpoint="http://sideseat.example.com:5388")

project_id

Project identifier for organizing traces.

client = SideSeat(project_id="my-project")

api_key

Authentication key for the SideSeat server.

client = SideSeat(api_key="pk-your-api-key")

Framework Parameters

framework

Explicitly select a framework to instrument.

from sideseat import SideSeat, Frameworks

client = SideSeat(framework=Frameworks.LangGraph)

Available frameworks:

• Frameworks.Strands
• Frameworks.LangGraph
• Frameworks.LangChain
• Frameworks.CrewAI
• Frameworks.AutoGen
• Frameworks.AG2
• Frameworks.OpenAIAgents
• Frameworks.GoogleADK
• Frameworks.PydanticAI
• Frameworks.AgentFramework
• Frameworks.ClaudeAgentSDK — Claude Agent SDK (claude-agent-sdk)
• Frameworks.Agno
• Frameworks.Smolagents
• Frameworks.AgentScope
• Frameworks.Langflow
• Frameworks.Haystack
• Frameworks.BrowserUse
• Frameworks.OpenAI
• Frameworks.Anthropic
• Frameworks.GoogleGenAI
• Frameworks.VertexAI — native Vertex AI SDK (vertexai)

If not specified, the SDK auto-detects by looking for the first of these packages that is installed, in this order:

1. Strands (strands-agents)
2. LangGraph (langgraph)
3. LangChain (langchain-core)
4. CrewAI (crewai)
5. AutoGen (autogen-agentchat)
6. OpenAI Agents (agents)
7. Google ADK (google-adk)
8. PydanticAI (pydantic-ai)
9. Microsoft Agent Framework (agent-framework-core)
10. Claude Agent SDK (claude-agent-sdk)
11. Agno (agno)
12. Smolagents (smolagents)
13. AgentScope (agentscope)
14. Langflow (langflow)
15. AG2 (ag2)
16. Haystack (haystack-ai)
17. browser-use (browser-use)
18. Vertex AI (vertexai)

If none match, the framework falls back to sideseat.

Note

openai, anthropic and google-genai are never auto-detected — they are too common as transitive dependencies, so their presence says nothing about what your app actually uses. Pass framework=Frameworks.OpenAI (or the relevant constant) explicitly to instrument them.

LangGraph is checked before LangChain, so a LangGraph app is identified as langgraph even though langchain-core is also installed. Both map to the same instrumentor.

auto_instrument

Enable automatic framework instrumentation.

# Auto-instrument (default)
client = SideSeat(auto_instrument=True)

# Skip instrumentation
client = SideSeat(auto_instrument=False)

Tip

Set auto_instrument=False if your framework isn’t supported or you want to use native instrumentation.

The framework parameter also accepts provider identifiers and lists:

from sideseat import SideSeat, Frameworks

# Instrument direct Bedrock API calls
client = SideSeat(framework=Frameworks.Bedrock)

# Framework + provider together
client = SideSeat(framework=[Frameworks.Strands, Frameworks.Bedrock])

Available providers:

• Frameworks.Bedrock — Amazon Bedrock (patches botocore to capture model, tokens, and messages)

Note

Use provider identifiers when calling provider SDKs directly. Framework instrumentation (Strands, LangGraph, etc.) captures LLM calls through their own telemetry and does not need providers. Azure OpenAI uses the same openai SDK, so use Frameworks.OpenAI for Azure OpenAI as well.

Service Identity

service_name

Override the auto-detected service name. Resolved as: this argument → OTEL_SERVICE_NAME → the detected framework’s package name.

# Auto-detect (default): the framework package name
client = SideSeat()

# Explicit name
client = SideSeat(service_name="my-agent")

# Same effect, without touching code
export OTEL_SERVICE_NAME=my-agent

service_version

Set the service version for resource attributes.

client = SideSeat(
    service_name="my-agent",
    service_version="1.2.3"
)

Telemetry Signals

enable_traces

Enable trace span export.

client = SideSeat(enable_traces=True)  # Default

enable_metrics

Enable metrics export.

client = SideSeat(enable_metrics=True)  # Default

enable_logs

Enable log export.

client = SideSeat(enable_logs=False)  # Default

Content Capture

capture_content

Capture LLM prompts and responses.

# Capture content (default)
client = SideSeat(capture_content=True)

# Disable for privacy
client = SideSeat(capture_content=False)

encode_binary

Base64 encode binary data in spans.

# Encode binary (default)
client = SideSeat(encode_binary=True)

# Leave as-is (may cause export errors)
client = SideSeat(encode_binary=False)

Tip

Keep encode_binary=True unless you’re sure your spans don’t contain binary data. Base64 encoding ensures compatibility with JSON-based exporters.

Control Parameters

disabled

Disable all telemetry.

# Disabled mode
client = SideSeat(disabled=True)

Useful for testing or CI environments.

debug

Enable verbose logging.

client = SideSeat(debug=True)

Environment Variables

The SDK respects these environment variables:

| Variable | Default | Description | |----------|---------|-------------| | SIDESEAT_ENDPOINT | http://127.0.0.1:5388 | Server URL | | SIDESEAT_PROJECT_ID | default | Project identifier | | SIDESEAT_PROJECT | default | Legacy alias for SIDESEAT_PROJECT_ID | | SIDESEAT_API_KEY | — | Authentication key | | SIDESEAT_DISABLED | false | Disable all telemetry | | SIDESEAT_DEBUG | false | Enable verbose logging |

Standard OpenTelemetry variables are also supported:

| Variable | Description | |----------|-------------| | OTEL_SERVICE_NAME | Override service name | | OTEL_EXPORTER_OTLP_ENDPOINT | Default OTLP endpoint | | OTEL_EXPORTER_OTLP_HEADERS | Extra headers (comma-separated k=v), merged with the API-key header | | OTEL_EXPORTER_OTLP_TRACES_HEADERS | As above, trace-only; takes precedence | | OTEL_EXPORTER_OTLP_TIMEOUT | Export timeout in seconds (default 30) — the TypeScript SDK reads this same variable in milliseconds, per each ecosystem’s OpenTelemetry convention | | OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED | Enable log export (enable_logs) | | OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT | Capture prompt/response content |

Configuration Priority

Settings are resolved in this order (highest to lowest):

1. Constructor parameters
2. SIDESEAT_* environment variables
3. OTEL_* environment variables
4. Defaults

One exception: content capture

capture_content=True sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT only when that variable is not already set, so a pre-existing value wins over the constructor — the reverse of the order above. This is deliberate: instrumentors read the variable directly, and an operator who has turned content capture off for a whole environment should not have it re-enabled by an application argument. To force it from code, set the variable yourself before constructing SideSeat.

Complete Example

from sideseat import SideSeat, Frameworks

# Full configuration
client = SideSeat(
    # Connection
    endpoint="http://localhost:5388",
    project_id="my-project",
    api_key="pk-xxx",

    # Framework
    framework=Frameworks.Strands,
    auto_instrument=True,

    # Service identity
    service_name="my-agent",
    service_version="1.0.0",

    # Telemetry signals
    enable_traces=True,
    enable_metrics=True,
    enable_logs=False,

    # Content capture
    capture_content=True,
    encode_binary=True,

    # Control
    disabled=False,
    debug=False,
)

# Add debug exporters
client.telemetry.setup_file_exporter("traces.jsonl")

# Your agent code here...

# Explicit shutdown (or let atexit handle it)
client.shutdown()

Next Steps

• SideSeat Class — API reference
• Exporters — debug exporters