Configuration

Every knob beyond the minimum init lives here. If you just want to get traces flowing, start with Initialize the SDK and skip this page.

import staso as st

st.init(
    api_key="ak_...",
    agent_name="support-bot",
    environment="prod",
    workspace_slug="support",
    batch_size=200,
    flush_interval=2.0,
    capture_messages=False,
)

Environment variables

init() reads a handful of STASO_* variables as fallbacks — see the environment variables reference for the full list.

Disable in development

Set enabled=False to turn the SDK into a no-op. Decorators, manual spans, and annotations still execute without error, but nothing is sent to the backend.

st.init(
    api_key="ak_...",
    agent_name="my-agent",
    enabled=os.getenv("ENV") != "dev",
)

Batching

Spans are buffered and flushed in batches by a background worker.

Parameter	Default	When to tune
`batch_size`	`100`	Increase for high-volume agents to amortize network overhead.
`flush_interval`	`5.0` seconds	Lower for short-lived workloads that exit before a natural flush.
`max_queue_size`	`10_000`	Raise if you see drop warnings under load. Lower to bound memory.

st.init(
    api_key="ak_...",
    agent_name="my-agent",
    batch_size=500,
    flush_interval=2.0,
    max_queue_size=50_000,
)

Multi-environment

Tag each deployment with environment so traces from staging and prod are separable in the UI.

st.init(
    api_key="ak_...",
    agent_name="my-agent",
    environment="staging",   # or "prod", "dev", "preview-42"
)

One agent can emit to many environments — same agent_name, different environment values.

Multi-workspace

Target a non-default workspace with workspace_slug. Use this when one process writes to several Staso workspaces, or when your API key has access to more than one.

st.init(
    api_key="ak_...",
    agent_name="my-agent",
    workspace_slug="support-team",
)

Redacting payloads

Two levels of control:

Global — capture_messages=False stops the SDK from recording LLM message content captured by the Anthropic and OpenAI integrations.
Per-function — capture_input=False or capture_output=False on any decorator.

st.init(api_key="ak_...", agent_name="my-agent", capture_messages=False)

@st.tool(capture_input=False)
def charge_card(card_number: str, amount_cents: int) -> str:
    ...

For finer control, open a manual span and attach a sanitized payload yourself.

Git / VCS auto-detection

capture_git=True is the default. On init() the SDK detects the current commit SHA, branch, and repo, and attaches them to every trace — so you can filter by deploy.

Disable in containers where .git is not present, or if you want to avoid the subprocess call at startup:

st.init(api_key="ak_...", agent_name="my-agent", capture_git=False)

See git tracking for how this surfaces in the UI.