stateweave-sdk

Run your own AI agent on StateWeave. StateWeave gives you working copies of the apps your agent uses (Slack, Gmail, Google Calendar, Sheets and Drive, Salesforce, Shopify, Zendesk), filled with a company's data, and tests with answer keys. Your agent stays on your machine and connects to the apps over their real APIs or MCP. Every run is graded and shown, call by call, on your StateWeave page.

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.

Five minutes

sw login --url https://<you>.app.stateweave.net       # asks for an API key: make one under Connect an agent
sw env ls                                              # your scenarios
sw task ls                                             # the tests you can run
sw run t-3fa2c1 --agent my-agent@0.1 -- python my_agent.py

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

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.

With Claude Code as the agent, on a test of Slack and Gmail:

sw run t-3fa2c1 --agent claude-code -- sh -c 'claude -p "$STATEWEAVE_PROMPT" \
  --mcp-config "$STATEWEAVE_MCP_CONFIG" --strict-mcp-config --allowedTools "mcp__slack__*" "mcp__gmail__*"'

In print mode Claude Code refuses any tool nobody approved, so --allowedTools must name each app the test uses. --strict-mcp-config keeps your own MCP servers out of the run. The MCP servers page has a script that works out the apps by itself and hands in the answer for answer tasks.

Give each version of your agent its own --agent label. The Runs page compares the labels.

Your own scenarios, tests and data

sw env new --apps gmail,zendesk --describe "A 40-person logistics software company after a carrier outage"
sw task new p-9c41d2 --request "Which enterprise customers were hit by last week's outage?"
sw task new p-9c41d2 --request "Refund #1042." --criteria "Only order #1042 is refunded, in full."
sw task new p-9c41d2 --suggest 5 --focus "refunds promised but never processed" --random-faults
sw task faults p-9c41d2
sw data kinds p-9c41d2
sw data add p-9c41d2 gmail email --from dana@northwind.example --subject "Credit?" --body-file mail.txt
sw task recheck p-9c41d2

• Your own requests. A request you write is kept word for word. StateWeave builds its answer key and checker, or tells you why the request can't be a test as written and suggests a rewording. --criteria says, in your words, what a right outcome must meet.
• Faults. Tests can inject the failures real APIs have: presets (--faults, listed by sw task faults) or random ones (--random-faults).
• Your own data. Added data joins the app's data as if the scenario had generated it. Only the scenario's people and contacts may appear in it.
• Re-checking. After you add data, that app's tests need a re-check before they run again.

In Python

import stateweave

with stateweave.start("t-3fa2c1", agent="my-agent@0.1") as run:
    answer = my_agent(run.prompt, run.apps)     # run.apps: each app's URLs, credentials and MCP server
    result = run.finish(answer)
print(result.passed, result.reasons, result.url)

stateweave.Client also has projects(), create_project(), data(), add_data(), write_tests(), suggest_tests(), faults(), fault_targets(), job() and recheck().

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.