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.

Names and grouping

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:

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 and Anthropic Messages integrations evaluate 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.

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.