Quickstart

Install the client, sign in to your workspace and run an agent on a test. It takes about five minutes.

#1. Install the client

The stateweave-sdk package installs the sw command and the stateweave Python module. It needs Python 3.10 or later and has no dependencies beyond the standard library, so it installs next to any harness.

pip install stateweave-sdk
sw --version

#2. Create an API key

Open your workspace, click Connect an agent under Runs in the sidebar, name the key (for example after the machine it will live on) and click Create key. The key starts with sw_ and is shown once, so copy it now.

#3. Sign in

sw login --url https://acme.app.stateweave.net

sw login asks for the key without echoing it, checks it with your workspace, then keeps the address and key in ~/.config/stateweave/config.json, readable only by you. In CI, set STATEWEAVE_URL and STATEWEAVE_API_KEY instead (see Configuration).

sw whoami

https://acme.app.stateweave.net  key “my laptop” (k-3c19a2)

#4. Find a test

sw task ls

t-bde537  answer  shopify                Combined spend of a duplicate shopper
t-0e4243  action  google_calendar,slack  Book the Harbor coordination meeting
t-753b29  action  zendesk,gmail,slack    Fix and cross-link the two Harbor tickets

An answer test asks your agent to find something out. An action test asks it to change something in the apps. The last columns list the apps the test uses.

#5. Run your agent

sw run starts a run, runs your agent's command with the run in its environment, hands in the answer when the command exits, and prints the result.

sw run t-bde537 --agent my-agent@0.1 -- python my_agent.py

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

import stateweave

with stateweave.start("t-bde537", agent="my-agent@0.1") as run:
    answer = my_agent(run.prompt, run.apps)   # your agent, your code
    result = run.finish(answer)

print(result.passed, result.reasons, result.url)

my_agent.py stands for your own agent: StateWeave tests it, it doesn't supply one. Your agent reads the request from STATEWEAVE_PROMPT and the apps' addresses and credentials from the file STATEWEAVE_RUN_FILE names. For an answer test it writes its answer, as JSON, to STATEWEAVE_ANSWER_FILE.

sw: run r-de238618 of t-bde537 started: https://acme.app.stateweave.net/#/runs/r-de238618
failed  14 calls  https://acme.app.stateweave.net/#/runs/r-de238618
  total 312.40 != expected 349.10

sw run exits with 0 when the run passed and 1 when it did not, so it drops into scripts and CI as is.

#6. See the run

Open the link. The run's page shows the verdict and why, every call your agent made in order with its request and response, any faults the test injected, and what changed in each app. The Runs board puts your agent labels side by side, test by test.

#Next steps