Staso Python SDK

Observe, guard, and control your AI agents. Every tool call, LLM interaction, token count, latency, and error -- on your Staso dashboard. Guard agent actions before they execute -- block dangerous operations, modify risky inputs, escalate to humans.

pip install staso

import staso as st
from staso import guard

st.init(api_key="ak_...", agent_name="my-agent")

@st.agent(name="support-agent")
def handle_request(message: str) -> str:
    context = search_kb(message)
    return call_llm(context, message)

@st.tool(name="search_kb")
def search_kb(query: str) -> str:
    return db.search(query)

@st.tool(name="process_refund")
def process_refund(customer_id: str, amount: float) -> str:
    result = guard(tool_name="process_refund", tool_input={"amount": amount})
    if result.action == "block":
        return f"Blocked: {result.reason}"
    return do_refund(customer_id, amount)

with st.conversation("conversation-123"):
    handle_request("How do I reset my password?")

st.shutdown()

Open your dashboard. Full execution tree -- agents, tools, LLM calls, tokens, timing, errors. Guard evaluations on every tool call.

Auto-Instrument LLM Calls

pip install "staso[anthropic]"  # or "staso[openai]" or "staso[all]"

st.init() detects installed provider SDKs (OpenAI, Anthropic, LiteLLM) and patches them automatically -- every LLM call is traced with tokens, model, latency, and errors. The whole integration:

import staso as st
st.init(agent_name="my-agent")

Prefer explicit control? Set STASO_AUTO_PATCH=false and patch yourself:

st.integrations.patch_anthropic()
st.integrations.patch_openai()

Both sync and async clients. Streaming fully supported.

Guard Agent Actions

Evaluate tool calls before they execute. Four actions: allow, block, modify, escalate.

from staso import guard

result = guard(tool_name="delete_records", tool_input={"table": "users"})
if result.action == "block":
    raise PermissionError(result.reason)

Guards run automatically in Claude Code and Codex sessions -- blocking dangerous tools and modifying risky inputs in real-time. In patched LLM SDK integrations (Anthropic, OpenAI), a tool call that trips an enforce rule raises staso.GuardBlocked -- catch it in your agent loop:

try:
    response = client.chat.completions.create(model="gpt-4o", messages=messages, tools=tools)
except st.GuardBlocked as blocked:
    handle_blocked_tool(blocked.tool_name, blocked.reason)

Score Agent Runs

Evaluate completed traces against built-in or custom rules -- task completion, output quality, drift across prompt versions.

run = st.evals.run(
    scope={"session_id": "run-2026-05-10-001"},
    zero_configs=["task_completion_rate", "hallucination", "output_artifact_quality"],
    name="run-001 eval",
)
summary = st.evals.summary(run.id)
print(summary.passed, "/", summary.total)

A/B compare two runs to gate prompt or model rollouts -- st.evals.compare(v1.id, v2.id) returns per-rule deltas plus the traces that flipped.

CLI Agent Integrations

Trace Claude Code (39 tool types) and Codex (32 tool types) sessions automatically. Every tool call renders as a human-readable card on your dashboard -- diffs, terminal output, agent trees, plan steps. Not raw JSON. Guards evaluate each tool before execution.

Run the interactive wizard:

staso setup

Or pass flags directly:

staso setup --target claude-code --api-key ak_... --workspace my-workspace
staso setup --target codex --api-key ak_... --workspace my-workspace
# Add --scope project to configure only the current project; the default is global.

Setup stores the API key in ~/.staso/credentials.json, outside agent settings and restricted to the current user. Agent hook files contain only a non-secret credential reference. In CI and containers, an injected STASO_API_KEY environment variable takes precedence. The credential file is plaintext and must not be shared; its directory and file are restricted to the current user with modes 0700 and 0600 respectively.

CLI Commands

staso setup                                              # interactive setup wizard
staso setup     --target claude-code --api-key ak_...    # scripted setup
staso status                                             # show what's configured
staso sync                                               # sync hooks after upgrade
staso update                                             # upgrade package + sync
staso uninstall --target codex                           # remove hooks, clean up
staso version                                            # show version info

For Codex, setup enables the current [features].hooks = true setting and writes hooks at either ~/.codex/hooks.json (global) or ./.codex/hooks.json (project). Codex still requires the user to review and trust each non-managed command hook in its Hooks settings; Staso never bypasses that security boundary. Use staso status --target codex to distinguish configured hooks from hooks that still need Codex trust review. An explicit --target is honored by the wizard. Because migrating or changing a Codex command changes its exact trusted hook definition, review the hooks again after the first credential migration.

Docs

Quickstart -- 5 minutes to first trace
Guards -- evaluate, block, modify, and escalate tool calls
Tracing -- @agent, @tool, @trace, st.span()
Conversations -- group traces by conversation
Integrations -- Anthropic, OpenAI, Claude Code, Codex
Configuration -- all options and env vars
Troubleshooting -- common issues

Python 3.11+ · Apache 2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

staso-0.5.8.tar.gz (492.1 kB view details)

Uploaded Aug 20, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

staso-0.5.8-py3-none-any.whl (137.8 kB view details)

Uploaded Aug 20, 2026 Python 3

File details

Details for the file staso-0.5.8.tar.gz.

File metadata

Download URL: staso-0.5.8.tar.gz
Upload date: Aug 20, 2026
Size: 492.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for staso-0.5.8.tar.gz
Algorithm	Hash digest
SHA256	`e8347f08484d5132da9e795ea9c7c929d3e3129da34164d9b0ff879db2959be2`
MD5	`fb79724f48beef91815b0fab6c82b9c8`
BLAKE2b-256	`4f29646d068167d8c5c9dc03ae9b8a901b7f2a8952f1be70641f17fd628d1fc6`

See more details on using hashes here.

Provenance

The following attestation bundles were made for staso-0.5.8.tar.gz:

Publisher: build_deploy_pip_registry.yml on StasoAI/sdk-python

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: staso-0.5.8.tar.gz
- Subject digest: e8347f08484d5132da9e795ea9c7c929d3e3129da34164d9b0ff879db2959be2
- Sigstore transparency entry: 2523580080
- Sigstore integration time: Aug 20, 2026
Source repository:
- Permalink: StasoAI/sdk-python@e1d73df9aae337a08f83344eceee7d057a261f7b
- Branch / Tag: refs/heads/main
- Owner: https://github.com/StasoAI
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: build_deploy_pip_registry.yml@e1d73df9aae337a08f83344eceee7d057a261f7b
- Trigger Event: push