Metadata-Version: 2.5
Name: stateweave-sdk
Version: 0.4.0
Summary: Run your own AI agent on StateWeave: environments, tests, data of your own, and graded runs
Project-URL: Homepage, https://stateweave.net
Project-URL: Documentation, https://stateweave.net/docs/
Author-email: StateWeave <mikewei@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 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.

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

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

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.

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

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:

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