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 and WhatsApp). 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 mcp install # adds StateWeave to the coding agents it finds here
Then, in a new session of your coding agent, say what you want:
- "Fill my StateWeave sandbox with the Slack channels my agent expects"
- "Write a StateWeave task for the refund flow and run my agent on it"
- "My agent sends duplicate Slack messages when it handles a refund: reproduce it on StateWeave and fix it"
sw mcp install adds an MCP server (sw mcp serve) and two skills: stateweave (fill a sandbox, write tasks, run
your agent, judge and debug) and stateweave-task (upload a task). It shows what it will change and asks first.
--client claude-code|codex|cursor picks the agents; --project writes the project's own files instead
(.mcp.json, .cursor/mcp.json, .codex/config.toml, .claude/skills, .agents/skills), to commit.
sw mcp uninstall takes it all out again.
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
A twin run also has call() (a look at an app that is not counted as your agent's), changes(), trace(),
download() (every call, whole, for judging), attach_transcript() and verdict(). twins.env holds the apps as
environment variables.
Upload it (optional)
An uploaded task is a test in your workspace: 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)
StateWeave's Claude can also write tests for you, in the same format: sw task new p-7d21c4 --request "…" (your
words, kept as they are; --criteria says what passes) or --suggest 5 (its own ideas). 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:
Client(url=..., api_key=...)STATEWEAVE_URLandSTATEWEAVE_API_KEY- What
sw loginkept in~/.config/stateweave/config.json, which only you can read
To forget it: sw logout.
Metadata
Release files for stateweave-sdk 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| stateweave_sdk-0.4.0.tar.gz | 51.7 kB | Without provenance | Details for stateweave_sdk-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| stateweave_sdk-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for stateweave_sdk-0.4.0-py3-none-any.whl |
Total release size: 109.0 kB
Release files / stateweave_sdk-0.4.0.tar.gz
| Download URL | stateweave_sdk-0.4.0.tar.gz |
|---|---|
| Size | 51.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
89b277c6c9689ad34adfe05145b85002a1dc8c1b79bce947edf5e9c6339c4b70
|
|
BLAKE2b-256 checksum How to use checksums |
29f31bff255422336dc41526ed9e29168c6d79d1963a0e703833a3a49b076f7b
|
| 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.4.0-py3-none-any.whl
| Download URL | stateweave_sdk-0.4.0-py3-none-any.whl |
|---|---|
| Size | 57.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a093510bdccda2f7bbc73d8ae344510b9c115571b2b896079fea8d20f762e5d0
|
|
BLAKE2b-256 checksum How to use checksums |
98ba0e33e0e3f2e5b9d1110f259f1766a8128bbcdea6b55b060efd1cf78e2afc
|
| 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.4.0
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.