Data model

The supported launch path produces an explicit agent root, decorated tool spans, and native provider LLM spans.

Span kinds

Value	Launch use
`agent`	Agent entry point created by `@st.agent`.
`tool`	Actual Python tool execution created by `@st.tool`.
`llm`	OpenAI Chat Completions or Anthropic Messages call.

Other enum values remain available for compatibility but are outside the supported launch configuration.

Statuses

Value	Meaning
`ok`	The observed operation completed.
`error`	The observed operation raised an exception.
`timeout`	A timeout status reported by the observed path.

Core span fields

Field	Type	Description
`name`	`str`	Span label.
`kind`	`SpanKind`	`agent`, `tool`, or `llm` on the launch path.
`status`	`SpanStatus`	`ok`, `error`, or `timeout`.
`trace_id`	`uuid`	Identifier shared by spans in one trace.
`span_id`	`uuid`	Identifier for this span.
`parent_span_id`	`uuid \| null`	Parent identifier, or `null` for the root.
`model`	`str`	Provider model name when reported.
`input_tokens`	`int`	Provider-reported input usage when present.
`output_tokens`	`int`	Provider-reported output usage when present.
`total_tokens`	`int`	Provider-reported total usage when present.
`input`	`dict`	Captured request data for the instrumented path.
`output`	`dict`	Captured response data for the instrumented path.
`metadata`	`dict`	Provider and SDK metadata.
`agent_name`	`str`	Name set by `@st.agent` or `st.init`.
`error_message`	`str \| null`	Recorded exception message when present.
`capture`	`CaptureStateMap`	Complete per-span capture outcome sent by this SDK.

Capture-state map

Every span emitted by this SDK includes all five keys: request, system_prompt, tool_schema, tool_arguments, and output.

{
  "capture": {
    "request": "captured",
    "system_prompt": "suppressed",
    "tool_schema": "captured",
    "tool_arguments": "suppressed",
    "output": "captured"
  }
}

The SDK emits only captured or suppressed. Suppression means the governed value was removed before SDK payload serialization. The backend can change captured to the storage-only state redacted after sanitizing enabled content. This SDK never emits redacted.

Older clients may omit the complete map; the backend treats that legacy payload as all captured before its sanitizer. A partial map, unknown category or state, or client-supplied redacted rejects the complete ingest request.

Common provider metadata

Native integrations may record request settings such as temperature, max_tokens, and tool_choice; response values such as stop_reason, response_id, and provider; and provider-specific cache or reasoning token counts when those values are returned.

Guard metadata

Key	Type
`guard_action`	`str`, either ordinary `allow` or enforced `block`
`guard_reason`	`str`
`guard_latency_ms`	`float`
`guard_decision_id`	`str`, the unique decision identity
`guard_decision_source`	`str`, the decision origin
`guard_decision_available`	`bool`, whether Guard returned a policy decision
`guard_evaluation_status`	`evaluated`, `skipped`, `abstained`, or `unavailable`
`guard_failure_kind`	Stable failure category or `None`
`guard_failure_mode`	`fail_open` or `fail_closed`
`guard_retryable`	`bool`, whether a later retry can reasonably succeed

In audit mode, the top-level decision remains allow. A failed audit rule and a guard:would-block:<tool> child span record what would have been blocked. When guard_decision_available is false, the effective action follows guard_failure_mode; use guard_failure_kind instead of parsing reason prose.

Skipped and abstained checks create no violation span. Unavailable checks use guard:unavailable:<tool> and remain distinct from policy findings. Repeated observations of a genuine tool invocation reuse the decision and corresponding Guard span identity. Separate invocations with identical arguments remain separate decisions.

On this page