Concepts

Organization
└── Workspace
    └── Trace
        ├── Agent span
        ├── LLM span
        └── Tool span

Trace

One explicitly instrumented agent run. Put @st.agent on the entry point to create the supported root.

Each span has a structural operation name supplied by your code or its SDK adapter. Staso selects the actual null-parent span as the root; child names never determine the root. Explicit names from @st.agent, @st.trace, and manual roots are preserved. SDK-created roots use a stable structural name such as agent_run, while the user-authored request is recorded separately in the root input as prompt for the trace's human-facing preview. Provider request payloads remain on the LLM child spans.

session_id groups related traces. Set STASO_SESSION_ID when one process needs a stable grouping identifier. If it is unset, the SDK generates one process-default identifier during st.init(). Staso does not currently define or generate a conversation title.

Span

One recorded operation inside a trace. The launch path uses:

Kind	Meaning
`agent`	The entry point wrapped by `@st.agent`.
`llm`	A supported native provider call inside the agent.
`tool`	Actual Python tool execution wrapped by `@st.tool`.

Each span can contain parent and child IDs, duration, status, captured input and output, model, provider-reported token usage, and an error message when one is recorded.

Agent

The logical unit emitting traces. @st.agent(name="...") sets the name for its root and nested spans. st.init(agent_name="...") supplies the process default.

The decorator is a Python instrumentation primitive. It is not a hosted coding-agent product.

Tool

@st.tool records the Python function that actually ran. It does not enforce Guard on its own.

Patched OpenAI Chat Completions, Anthropic Messages, and direct LiteLLM integrations evaluate supported provider-proposed tool calls before returning them to the normal dispatch loop. Direct tool calls require an explicit st.guard() check when they need enforcement. Coding agent hooks check proposals at their exposed PreToolUse event.

Guard policy

A configured set of rules applied to proposed tool calls:

Audit: record a would-block and allow the proposal to continue.
Enforce: block a matching proposal and raise st.GuardBlocked in a patched provider loop.

Built-in rules are templates until you attach them to a policy.

Environment and workspace

environment labels spans, such as prod or staging. workspace_slug selects the target workspace. Both default to default and can be set in st.init() or with environment variables.

See workspaces and Guard rules and policies.