Concepts
Organization
└── Workspace
└── Trace
└── SpanTrace
One end-to-end agent run. Created automatically when the first span opens. Identified by trace_id.
Span
One unit of work inside a trace — an LLM call, a tool call, a step. Has a kind, status, input, output, and metadata.
| Kind | Meaning |
|---|---|
llm | A call to an LLM provider. |
tool | A tool the agent invoked. |
chain | A composite step. Default for @st.trace. |
retriever | A retrieval or search step. |
agent | An agent entry point. Set by @st.agent. |
custom | Anything else. |
Agent
The logical unit emitting traces — one row in your dashboard. Tag every trace with an agent so you can slice metrics, alerts, and Guard rules per agent.
@st.agent(name="...") overrides the agent for everything inside it. st.init(agent_name=...) is the default for code that isn't decorated.
Conversation
A set of traces that share a conversation_id — the turns of one chat thread, the steps of one multi-turn task, the retries of one job. Use st.conversation(...) to group them.
with st.conversation("conv-42", user_id="user-alice"):
run_agent(query)Environment
A logical partition — prod, staging, dev. Set with environment in st.init(...) or STASO_ENVIRONMENT. Defaults to default.
Workspace
A data isolation unit inside an organization. Set with workspace_slug in st.init(...) or STASO_WORKSPACE_SLUG. See workspaces.
Organization
The billing, RBAC, and ownership boundary. Holds members, API keys, and one or more workspaces. See workspaces.