Python SDK
Initialize the Python SDK
st.init() boots the Staso client. Call it once, at process start, before any traced code runs.
import staso as st
st.init(
api_key="ak_...",
agent_name="my-agent",
)That is the minimum. Everything else has a default.
Signature
st.init(
*,
api_key: str | None = None,
agent_name: str | None = None,
base_url: str | None = None,
batch_size: int = 100,
flush_interval: float = 5.0,
max_queue_size: int = 10_000,
enabled: bool = True,
debug: bool | None = None,
environment: str | None = None,
workspace_slug: str | None = None,
capture_messages: bool = True,
capture_git: bool = True,
) -> ClientAll arguments are keyword-only.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
api_key | str | None | None | Your Staso API key. Falls back to STASO_API_KEY. Required. |
agent_name | str | None | None | Baseline agent name for this process. Required. Falls back to STASO_AGENT_NAME. The @st.agent decorator overrides this per entry point — use init(agent_name=...) as the default, the decorator when you run multiple agents in one process. See decorators. |
base_url | str | None | None | Staso API base URL. Falls back to STASO_BASE_URL, then https://api.staso.ai. |
batch_size | int | 100 | Spans flushed per batch. Tune for throughput. |
flush_interval | float | 5.0 | Seconds between background flushes. |
max_queue_size | int | 10_000 | Backpressure cap. Spans beyond this are dropped. |
enabled | bool | True | Set False in local dev or CI to disable all tracing at zero cost. |
debug | bool | None | None | Verbose SDK logs. Falls back to STASO_DEBUG. |
environment | str | None | None | Deployment tag: "staging", "prod", etc. Falls back to STASO_ENVIRONMENT, then "default". |
workspace_slug | str | None | None | Target workspace. Falls back to STASO_WORKSPACE_SLUG, then "default". |
capture_messages | bool | True | Capture LLM message content on spans. Set False to redact PII. |
capture_git | bool | True | Auto-detect commit SHA, branch, and repo on init. |
Environment variable fallbacks
When a parameter is omitted, init() reads these env vars:
| Parameter | Env var |
|---|---|
api_key | STASO_API_KEY |
agent_name | STASO_AGENT_NAME |
base_url | STASO_BASE_URL |
debug | STASO_DEBUG |
environment | STASO_ENVIRONMENT |
workspace_slug | STASO_WORKSPACE_SLUG |
api_key and agent_name are required — init() raises ValueError if neither the argument nor the env var is set.
The full list of supported variables lives in the environment variables reference.
Shutdown
st.shutdown()Flushes any pending spans and tears down the background transport. You rarely need to call this — init() registers it with atexit, so it runs on normal process exit. Call it manually in short-lived scripts or serverless handlers that may exit before the scheduler flushes.