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 stores named environment profiles in ~/.staso/profiles.json. Both are restricted to the current user. Agent hook files contain only stable Staso entrypoints. 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 profile set local --api-key ak_... --base-url http://localhost:6999 --workspace qa --environment local
staso profile use local                                 # activate for CLI-agent testing
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

The active profile applies globally to installed Codex and Claude Code hooks, including Codex Desktop. Use STASO_PROFILE=<name> for a one-process CLI override without changing the saved active profile. After staso profile use, staso sync intentionally replaces legacy per-hook routing with stable entrypoints; the selected active profile is the routing authority for every installed hook.

Without an active profile, sync converts legacy hooks only when their effective configuration can be unified safely. Otherwise it keeps every legacy route, reports the conflict, and exits nonzero if required hook events cannot be repaired without guessing a route.

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