Metadata-Version: 2.5
Name: stateweave-sdk
Version: 0.6.3
Summary: Test your AI agent on working copies of Slack, Gmail, Google Workspace, Salesforce, Shopify, Zendesk, WhatsApp, Microsoft Teams, Stripe, HubSpot and GitHub: sandboxes, tasks judged through the apps' APIs, and graded runs
Project-URL: Homepage, https://stateweave.net
Project-URL: Documentation, https://stateweave.net/docs/
Author-email: StateWeave <support@stateweave.net>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent evaluation,ai agents,digital twin,mcp,salesforce,shopify,slack,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# stateweave-sdk

Test your AI agent on [StateWeave](https://stateweave.net): 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.

```bash
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](https://stateweave.net/docs/).

## Sign in

```bash
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)

```bash
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.

```bash
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](https://harborframework.com)'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
```

```bash
sw task import ./kickoff --check                       # prove it: doing nothing must fail; nothing is kept
```

## Run your agent and judge it

```python
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.

```bash
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:

```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](https://stateweave.net/docs/faults#faults-in-a-task)). 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`.
