Quickstart | StateWeave Docs

Quickstart

Make a blank sandbox, put one message in it through Slack's own API, write a task, and run your agent against fresh copies until it passes. About fifteen minutes.

Using Claude Code, Codex or Cursor? After step 3, run sw setup and ask your coding agent to "Set up StateWeave for my agent": it knows every step on this page. See From your coding agent.

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.

ShellCopy

pip install stateweave-sdk
sw --version

2. Create an API key

Open your workspace (see Get access) and click the key icon at the bottom of the left rail: Connect your agent. Its first line is your workspace's address. Name a 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

ShellCopy

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.

4. Make a blank sandbox

In your workspace, click + beside Sandboxes, name it, pick Slack, and click Make sandbox. Or from a shell:

ShellCopy

sw sandbox new "Acme support" --apps slack

OutputCopy

p-7d21c4

The sandbox starts in edit mode, holding only Slack's workspace, its owner and the owner's token. What you do in it now becomes its data. Your workspace's Starter sandbox would do too: it holds every app StateWeave had when your workspace was made, blank, and doesn't count against your plan.

5. Fill it through Slack's API

connect starts the sandbox's apps and gives each one's address and the owner's token. Write with the client you already use: here, Slack's own slack_sdk (pip install slack_sdk).

fill.pyCopy

import stateweave
from slack_sdk import WebClient

twins = stateweave.Client().connect("p-7d21c4")
slack = twins["apps"]["slack"]
web = WebClient(token=slack["credentials"]["user:owner"], base_url=slack["endpoints"]["web_api"])

general = next(c for c in web.conversations_list()["channels"] if c["name"] == "general")
web.chat_postMessage(channel=general["id"], text="Standup moves to 9:30 from Monday")
print(general["id"])

OutputCopy

C0A1B2C3D4E

Note the channel's id: every copy of this sandbox will have the same one, so your checks can name it. See Fill a sandbox for other apps, other people's tokens and filling from a prompt.

6. Keep it as a version

ShellCopy

sw sandbox mode p-7d21c4 test

OutputCopy

p-7d21c4 is in test mode; version 1

From now on, every run starts from fresh copies of version 1. Nothing a run does reaches the sandbox.

7. Write a task

A task is a folder: what your agent is asked, and checks that decide whether it did it, through Slack's own API and the requests your agent sent.

LayoutCopy

kickoff/
├── instruction.md
├── task.toml
└── tests/checks.json

instruction.mdCopy

Post exactly 'Kickoff at 10' in #general.

task.tomlCopy

[task]
description = "Announce the kickoff"

[metadata]
stateweave_sandbox = "p-7d21c4"
stateweave_kind = "action"

tests/checks.jsonCopy

[
  {"name": "posted once", "calls": {"app": "slack", "http_method": "POST", "path": "/api/chat.postMessage"},
   "expect": [{"op": "count_eq", "value": 1}, {"path": "request.text", "op": "equals", "value": "Kickoff at 10"}]},
  {"name": "it is in #general", "app": "slack",
   "request": {"method": "GET", "path": "/api/conversations.history", "query": {"channel": "C0A1B2C3D4E"}},
   "expect": [{"path": "messages[*].text", "op": "contains", "value": "Kickoff at 10"}]}
]

Check that the task can tell a run that did nothing from one that worked. Nothing is kept:

ShellCopy

sw task import ./kickoff --check

OutputCopy

  ✓ Doing nothing fails
      with nothing done, judged failed:
      - failed: posted once: the records: wanted 1, found 0; request.text: nothing there to compare with 'Kickoff at 10'
      - failed: it is in #general: messages[*].text: no value contains 'Kickoff at 10' (found 'Standup moves to 9:30 from Monday', '<@U0B7K2M4Q1R> has joined the channel')
Proven; nothing kept (--check). Import it without --check to keep it.

See Tasks for every kind of check.

8. Run your agent and judge it

Open fresh copies of the sandbox, run your agent on them, then judge them with the task's own checks:

try_kickoff.pyCopy

import json
import stateweave

client = stateweave.Client()
prompt = open("kickoff/instruction.md").read()
checks = json.load(open("kickoff/tests/checks.json"))

with client.open_twins("p-7d21c4") as twins:
    my_agent(prompt, twins.apps)          # your agent: twins.apps holds each app's address and tokens
    result = twins.check(checks)
    print("passed" if result["passed"] else "failed")
    for r in result["results"]:
        print(" ", "ok " if r["ok"] else "no ", r["name"], "-", r["detail"])

The copies stop when the block ends. Fix your agent and run it again: each open_twins starts from version 1. See Run your agent for running a command, reading the calls your agent made and resetting the copies between attempts.

9. Upload it (optional)

Uploaded, the task is a test in your workspace: each run of it is graded, kept with every call, and comparable across versions of your agent.

ShellCopy

sw task import ./kickoff
sw run t-4f2a9c --agent my-agent@0.1 -- python my_agent.py

sw run starts a run, runs your command with the request and the apps in environment variables, grades it when the command exits, and prints the result with a link to the run's page. See Upload a task.