Skip to main content

stateweave-sdk

Test your AI agent on StateWeave: working copies of the apps it uses (Slack, Gmail, Google Calendar, Sheets and Drive, Salesforce, Shopify, Zendesk, WhatsApp, Microsoft Teams, Stripe, HubSpot and GitHub). You fill a sandbox with the data your agent needs, write tasks whose checks go through the apps' own APIs, and run your agent on fresh copies as often as you like. Your agent stays where it runs and reaches the apps over their real APIs or MCP; every call is recorded.

pip install stateweave-sdk

This installs the sw command and the stateweave Python module. It uses only the standard library and needs Python 3.10 or later. The full documentation is at stateweave.net/docs.

Sign in

sw login --url https://<you>.app.stateweave.net       # asks for an API key: the key icon in your workspace's rail

In CI, set STATEWEAVE_URL and STATEWEAVE_API_KEY instead.

In your coding agent (Claude Code, Codex, Cursor)

sw setup                                               # gives the coding agents it finds here StateWeave's skills

Then, in a new session of your coding agent, in your agent's project, say what you want:

  • "Set up StateWeave for my agent"
  • "Write three StateWeave tasks for what my agent does, one with a Slack outage, and upload them"
  • "My agent sends duplicate Slack messages when it handles a refund: reproduce it on StateWeave and fix it"

sw setup adds two skills, without asking: stateweave-setup (read your code, pick or make a sandbox, wire your agent to the apps' copies with a stateweave-agent.sh, run it once) and stateweave-use (sandboxes, tasks with checks and injected faults, uploads, runs, and why a run failed). Your coding agent then works through sw, without stopping to ask. --client claude-code|codex|cursor picks the agents; --project writes the project's .claude/skills and .agents/skills instead, to commit; --remove takes them out again. It also takes out the MCP server that sw mcp install added before 0.6.

A sandbox

A sandbox is the apps your agent works in and their data. Its id starts with p-. A new one is blank: each app holds only its account, its owner and the owner's token. Fill it in edit mode through the apps' own APIs, then switch it to test mode: that keeps a version, and every run starts from fresh copies of it.

sw sandbox new Acme --apps slack,zendesk               # p-7d21c4
eval "$(sw sandbox connect p-7d21c4 --env)"            # STATEWEAVE_SLACK_URL, STATEWEAVE_SLACK_USER_TOKEN, ...
python fill.py                                         # your own script, through the apps' own APIs
sw sandbox act p-7d21c4 slack add_person --handle grace --name "Grace Hopper" --email grace@acme.example
sw sandbox mode p-7d21c4 test                          # version 1

sw sandbox act does what the real APIs cannot (someone joins, a customer writes on WhatsApp); sw sandbox actions lists them. Or fill a blank sandbox with a made-up company from a description: sw sandbox generate.

A task

A task is a folder in Harbor's layout: what your agent is asked, and how a run is judged, only through the apps' public APIs, the agent's answer and the requests it sent.

kickoff/
├── instruction.md        Post exactly 'Kickoff at 10' in #general.
├── task.toml             [metadata] stateweave_sandbox = "p-7d21c4", stateweave_kind = "action"
├── tests/checks.json     checks: an app's API after the agent, the agent's requests, its answer
├── tests/verify.py       optional: code, for what checks cannot say
└── solution/solve.py     optional: a reference solution
sw task import ./kickoff --check                       # prove it: doing nothing must fail; nothing is kept

Run your agent and judge it

import json
import stateweave

checks = json.load(open("kickoff/tests/checks.json"))
with stateweave.Client().open_twins("p-7d21c4") as twins:
    my_agent(open("kickoff/instruction.md").read(), twins.apps)   # each app's URLs, credentials and MCP server
    print(twins.check(checks))                                    # judged by the task's own checks
    twins.reset()                                                 # back to the version, for the next attempt

From a shell, sw run p-7d21c4 --agent my-agent@dev --prompt "$(cat kickoff/instruction.md)" --checks kickoff -- python my_agent.py does the same around any command, and sw trace r-… writes a run's whole record to files.

A twin run also has call() (a look at an app that is not counted as your agent's), changes() (how many records each app gained, changed and lost), trace(), download() (every call, whole, for judging), attach_transcript() and verdict(). twins.env holds the apps as environment variables.

Upload it

Uploading is how a task becomes a test in your workspace (StateWeave does not write tasks): every run of it is graded and kept with every call, and the Runs page compares versions of your agent on it.

sw task import ./kickoff                               # Kept as t-4f2a9c
sw run t-4f2a9c --agent my-agent@0.1 -- python my_agent.py

sw run starts a run, runs your command with the run in environment variables, then grades it:

variable what it holds
STATEWEAVE_PROMPT what to ask your agent
STATEWEAVE_KIND answer (it finds something out) or action (it changes the apps)
STATEWEAVE_ANSWER_FORMAT for an answer task, the JSON value to answer with
STATEWEAVE_RUN_FILE the whole run as JSON: each app's base_url, endpoints, credentials and MCP server
STATEWEAVE_MCP_CONFIG {"mcpServers": {...}}, for any MCP client
STATEWEAVE_ANSWER_FILE where your agent writes its answer (JSON, or plain text); nothing for an action task
STATEWEAVE_TRANSCRIPT_FILE where your agent may write its own record of the run (messages, tool calls); handed in with the run when it is not empty
STATEWEAVE_RUN the run's id

The run is graded when your command exits, whatever its exit code. Ctrl-C gives the run up instead. sw run exits 0 when the run passed. Give each version of your agent its own --agent label.

In Python:

import stateweave

with stateweave.start("t-4f2a9c", agent="my-agent@0.1") as run:
    answer = my_agent(run.prompt, run.apps)
    result = run.finish(answer)               # transcript=pathlib.Path("session.jsonl") hands in your agent's own
print(result.passed, result.reasons, result.url)

A task can make the apps fail the way the real services do: one of stateweave_faults (presets, from sw task faults p-7d21c4), stateweave_random_faults or stateweave_pinned_faults under [metadata] in task.toml (Faults). With faults, the reference solution must pass under them and without them. After a new version changes an app, that app's tests need sw task recheck before they run again.

Where the address and key come from

The first of these that is set wins:

  1. Client(url=..., api_key=...)
  2. STATEWEAVE_URL and STATEWEAVE_API_KEY
  3. What sw login kept in ~/.config/stateweave/config.json, which only you can read

To forget it: sw logout.

Metadata

Release files for stateweave-sdk 0.6.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stateweave-sdk 0.6.3
File Size Uploaded Provenance Actions
stateweave_sdk-0.6.3.tar.gz 54.1 kB Without provenance Details for stateweave_sdk-0.6.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stateweave-sdk 0.6.3
File Interpreter ABI Platform Actions
stateweave_sdk-0.6.3-py3-none-any.whl Python 3 none any Details for stateweave_sdk-0.6.3-py3-none-any.whl

Total release size: 115.8 kB

Release files / stateweave_sdk-0.6.3.tar.gz

Download URL stateweave_sdk-0.6.3.tar.gz
Size 54.1 kB
Tags Source
SHA-256 checksum
How to use checksums
1d86b7d4a6c083dc5644b5702566aa4301da347627a2da48887c1f4d8bad8511
BLAKE2b-256 checksum
How to use checksums
b1061e2da7b0792828601e0ee0abcc9d11cd34308f16c0da78dd14754e5a9d21
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.11

Release files / stateweave_sdk-0.6.3-py3-none-any.whl

Download URL stateweave_sdk-0.6.3-py3-none-any.whl
Size 61.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f48c52ed6937e50d9c9c8b097cd5393a3892a68535aea4aba18e1762a0a7320b
BLAKE2b-256 checksum
How to use checksums
132362db9c45bc69a5e4cda337d0fcf87d9c705c04cf7949b3dbc138852fc3f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.11

Security for stateweave-sdk 0.6.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page