Tasks and runs

### Build an agent

StateWeave tests your agent; it doesn't supply one. The agent is your own program, the one you'd ship: your prompt, your model, your tools. In sw run t-… -- python my\_agent.py , my\_agent.py is that program. This page shows three ways to get one running.

### What an agent does in a run

Whatever it's built with, an agent in a test run does three things:

Reads the task. The request is in STATEWEAVE\_PROMPT . The apps it may use, with their addresses and the persona's tokens, are in the file STATEWEAVE\_RUN\_FILE names.

Works in the apps. It calls the apps' real APIs (or their MCP servers), as many times as it needs.

Answers, if asked. For an answer task, it writes its answer to STATEWEAVE\_ANSWER\_FILE , as JSON in the shape of STATEWEAVE\_ANSWER\_FORMAT (plain text is handed in as a string). For an action task, the changes it made are the result.

Then it exits, and StateWeave grades the run. It may also write its own record of the run (messages, tool calls) to STATEWEAVE\_TRANSCRIPT\_FILE , which is kept with the run. Run your agent lists everything a run hands over.

### Option 1: the agent you already have

If you already have an agent, you only change where it gets its task, its connections and where its answer goes:

Task: take the request from STATEWEAVE\_PROMPT instead of your usual input.

Connections: point its tools at the run's apps. Read each app's address and token from the run file instead of your config. Most client libraries need one setting; see Client libraries . An agent that uses MCP takes the run's MCP config instead; see MCP servers .

Answer: for an answer task, write the answer to STATEWEAVE\_ANSWER\_FILE .

Then run it with sw run . If your harness is a Python program that should start the run itself, use the Python SDK instead: run.prompt , run.apps , run.finish(answer) .

### Develop against a twin run

Before a graded run, try your agent on a twin run: fresh copies of a sandbox's apps with no test, which you can reset and run again. Its apps and env are the same as a test run's.

Python

import

stateweave

with

stateweave.

Client

().

open\_twins

(

"p-7d21c4"

, apps=\[

"slack"

,

"zendesk"

\])

as

twins:

my\_agent

(twins.apps)

\# your own code, on fresh copies of the latest version

print

(twins.

changes

())

\# what it changed in each app

twins.

reset

()

\# back as they opened, for the next try

A twin run stays up an hour unless you stop it, and is not graded: judge it with a task's checks, as in Twin runs . sw run p-… -- COMMAND opens one around your command, and your coding agent can do it for you; see From your coding agent .

### Option 2: Claude Code, no code

To see a run end to end before you write anything, let Claude Code be the agent. It reaches the apps through their MCP servers:

Shell

sw

run t-0e4243

--agent

claude-code -- sh

-c

'claude -p "$STATEWEAVE\_PROMPT" \\ --mcp-config "$STATEWEAVE\_MCP\_CONFIG" --strict-mcp-config \\ --allowedTools "mcp\_\_slack\_\_\*"'

This works for tests whose apps all have an MCP server (Slack, Gmail, Salesforce, Shopify, WhatsApp, Microsoft Teams, Stripe, HubSpot, GitHub). The MCP servers page has a script that also hands in answers and Claude Code's transcript.

### Option 3: a complete agent in Python

This agent uses the tools the vendors define themselves. For every app whose run lists an MCP server, the agent connects to it and hands its tools to Claude as they are: no tool code. Zendesk has no MCP server, so the agent adds two tools of its own for it, built on Zenpy, Zendesk's Python library. That's how most teams handle an API without an MCP server: a few tools for just the actions the agent needs.

| App | Tools | Defined by |
| --- | --- | --- |
| Slack, Gmail, Salesforce, Shopify, WhatsApp, Microsoft Teams, Stripe, HubSpot, GitHub | Each vendor's MCP tools, such as slack\_send\_message , search\_threads , soqlQuery , list-orders | The vendor |
| Zendesk | find\_zendesk\_tickets , update\_zendesk\_ticket | This file |
| Any | submit\_answer , for questions | This file |

Claude only gets the tools of the apps the test uses. Google Calendar, Sheets and Drive have no MCP server in StateWeave either: for a test that needs them, add tools the same way as for Zendesk. HubSpot's MCP server only reads, so a test where the agent writes to HubSpot needs such tools too. GitHub's MCP server has no tools to make webhooks, milestones or releases, so a test where the agent makes those needs such tools as well.

Shell

pip

install stateweave-sdk

"anthropic\[mcp\]"

zenpy

export

ANTHROPIC\_API\_KEY=sk-ant-...

\# from console.anthropic.com

my\_agent.py

"""A complete agent for StateWeave: Claude with the official MCP servers of the run's apps (Slack, Gmail, Salesforce, Shopify, WhatsApp, Microsoft Teams, Stripe, HubSpot, GitHub), whose tools the vendors define, plus two tools of its own for Zendesk, which has no MCP server. pip install "anthropic\[mcp\]" zenpy export ANTHROPIC\_API\_KEY=sk-ant-... sw run t-753b29 --agent my-agent@0.1 -- python my\_agent.py \`sw run\` hands it the run (STATEWEAVE\_RUN\_FILE, STATEWEAVE\_PROMPT, ...). For a question, the answer goes to STATEWEAVE\_ANSWER\_FILE. An app with neither an MCP server nor tools here is out of the agent's reach."""

import

asyncio

import

contextlib

import

itertools

import

json

import

os

import

sys

import

anthropic

import

httpx2

from

anthropic

import

beta\_async\_tool

from

anthropic.lib.tools.mcp

import

async\_mcp\_tool

from

mcp

import

ClientSession

from

mcp.client.streamable\_http

import

streamable\_http\_client

from

zenpy

import

Zenpy

from

zenpy.lib.api\_objects

import

Comment run = json.

load

(

open

(os.environ\[

"STATEWEAVE\_RUN\_FILE"

\])) answer = \{\}

\# set by submit\_answer

\# ------------------------------------------------------------------ Zendesk: no MCP server, so two tools of our own

def

zendesk

() -&gt; Zenpy: app = run\[

"apps"

\]\[

"zendesk"

\] subdomain, \_, domain = app\[

"base\_url"

\].

removeprefix

(

"https://"

).

partition

(

"."

) token =

next

(v

for

label, v

in

app\[

"credentials"

\].

items

()

if

label.

startswith

(

"user:"

))

return

Zenpy

(subdomain=subdomain, domain=domain, oauth\_token=token) @beta\_async\_tool

async

def

find\_zendesk\_tickets

(query: str) -&gt; str:

"""Find Zendesk tickets, each with its people and comments. Uses Zendesk's search syntax: words from the ticket, a ticket number, status:open, tags:vip, ... Args: query: The search query. """

def

find

(): z =

zendesk

()

return

json.

dumps

(\[\{

"id"

: t.id,

"subject"

: t.subject,

"status"

: t.status,

"priority"

: t.priority,

"tags"

: t.tags,

"requester"

: t.requester

and

t.requester.email,

"assignee"

: t.assignee

and

t.assignee.email,

"comments"

: \[\{

"author"

: c.author.name,

"public"

: c.public,

"body"

: c.body\[:

2000

\]\}

for

c

in

z.tickets.

comments

(ticket=t.id)\], \}

for

t

in

itertools.

islice

(z.

search

(query, type=

"ticket"

),

10

)\])

return

await

asyncio.

to\_thread

(find) @beta\_async\_tool

async

def

update\_zendesk\_ticket

(ticket\_id: int, status: str \|

None

=

None

, assignee\_email: str \|

None

=

None

, add\_tags: list\[str\] \|

None

=

None

, comment: str \|

None

=

None

, public: bool =

False

) -&gt; str:

"""Change a Zendesk ticket. Only what you give changes. Args: ticket\_id: The ticket's number. status: new, open, pending, hold, solved or closed. assignee\_email: The email of the agent to assign it to. add\_tags: Tags to add. comment: A comment to add. public: True for a reply the requester sees, False for an internal note (the default). """

def

update

(): z =

zendesk

() t = z.

tickets

(id=ticket\_id)

if

status: t.status = status

if

assignee\_email: t.assignee\_id =

next

(u.id

for

u

in

z.

search

(assignee\_email, type=

"user"

)

if

u.email == assignee\_email)

if

add\_tags: t.tags =

sorted

(

set

(t.tags) \|

set

(add\_tags))

if

comment: t.comment =

Comment

(body=comment, public=public) z.tickets.

update

(t)

return

f"Ticket \{ticket\_id\} updated."

return

await

asyncio.

to\_thread

(update) @beta\_async\_tool

async

def

submit\_answer

(answer\_json: str) -&gt; str:

"""Hand in the answer to a question, as JSON in the format the task asks for. Args: answer\_json: The answer as JSON text. """

answer\[

"value"

\] = json.

loads

(answer\_json)

return

"Answer recorded."

\# ------------------------------------------------------------------ the agent

async

def

main

() -&gt;

None

:

async

with

contextlib.

AsyncExitStack

()

as

stack: tools = \[submit\_answer\]

for

name, app

in

run\[

"apps"

\].

items

():

if

app.

get

(

"mcp"

):

\# the vendor's MCP server: its tools, as the vendor defines them

http =

await

stack.

enter\_async\_context

(httpx2.

AsyncClient

(headers=app\[

"mcp"

\]\[

"headers"

\])) streams =

await

stack.

enter\_async\_context

(

streamable\_http\_client

(app\[

"mcp"

\]\[

"url"

\], http\_client=http)) session =

await

stack.

enter\_async\_context

(

ClientSession

(streams\[

0

\], streams\[

1

\]))

await

session.

initialize

() tools \+= \[

async\_mcp\_tool

(tool, session)

for

tool

in

(

await

session.

list\_tools

()).tools\]

elif

name ==

"zendesk"

: tools \+= \[find\_zendesk\_tickets, update\_zendesk\_ticket\] persona = run\[

"persona"

\] system = (

f"You work for \{persona\['name'\]\} (\{persona\['title'\]\}) and act with their accounts in the company's "

f"apps, using your tools. The apps in this task: \{', '.join(run\['apps'\])\}. If the task needs an app "

"you have no tool for, do what you can and say what you could not do. Look things up before you "

"change anything, and change only what the task asks for. "

\+ (

f"When you know the answer, call submit\_answer with it in this format: \{run\['answer\_format'\]\}"

if

run\[

"kind"

\] ==

"answer"

else

"When the changes are made, say in a sentence what you did."

)) client = anthropic.

AsyncAnthropic

() runner = client.beta.messages.

tool\_runner

( model=

"claude-opus-5-5"

, max\_tokens=

16000

, output\_config=\{

"effort"

:

"high"

\}, cache\_control=\{

"type"

:

"ephemeral"

\},

\# each turn resends the conversation so far: cache it

betas=\[

"server-side-fallback-2026-07-01"

\], fallbacks=

"default"

,

\# if Claude Opus 5.5 declines, another model carries on

max\_iterations=

60

, system=system, tools=tools, messages=\[\{

"role"

:

"user"

,

"content"

: run\[

"prompt"

\]\}\], )

async

for

message

in

runner:

for

block

in

message.content:

if

block.type ==

"tool\_use"

:

print

(

f" \{block.name\} \{json.dumps(block.input)\[:120\]\}"

, file=sys.stderr)

if

message.stop\_reason ==

"refusal"

:

print

(

"Claude declined the task"

, file=sys.stderr)

if

"value"

in

answer:

with

open

(os.environ\[

"STATEWEAVE\_ANSWER\_FILE"

\],

"w"

)

as

f: json.

dump

(answer\[

"value"

\], f) asyncio.

run

(

main

())

Shell

sw

run t-72abae

--agent

my-agent@0.1 -- python my\_agent.py

Output

sw: run r-ef8604ff of t-72abae started: https://acme.app.stateweave.net/\#/runs/r-ef8604ff list-orders \{"query": "Harbor", "first": 20\} find \{"q": "FIND \{Harbor\} IN ALL FIELDS RETURNING Account(Id, Name), Contact(Id, Name, Email, AccountId)"\} list-customers \{"query": "email:simone.hartley@harbor-co.example"\} soqlQuery \{"q": "SELECT Id, Name, Description, ShippingStreet, ShippingCity, ShippingState, ShippingPostalCode, …"\} … graphql\_mutation \{"query": "mutation($input: OrderInput\!) \{ orderUpdate(input: $input) \{ order \{ id note shipping…"\} updateSobjectRecord \{"sobject-name": "Note", "id": "002iu0000Buxt3sAQA", "body": \{"Body": "Account ACC-0142. Order…"\}\} passed 23 calls https://acme.app.stateweave.net/\#/runs/r-ef8604ff NG-4817 shipping address and note and the Harbor &amp; Co. delivery note now carry Pier 9 / 410 Waterfront Ave by noon on 2026-11-06; nothing else changed

In our own sandbox, served over HTTPS as hosted runs are, it passed three tests: a question in Shopify (6 tool calls), a change across Shopify and Salesforce while Salesforce had an outage (17 tool calls), and reopening and cross-linking Zendesk tickets (4 tool calls). Each took under a minute. None of them used WhatsApp.

### How it works

MCP tools. For each app with an MCP server, the agent opens a session to the address and headers the run gives ( run\["apps"\]\[app\]\["mcp"\] ), lists the server's tools, and turns each into a tool for Claude with async\_mcp\_tool from the Anthropic SDK. When Claude calls one, the call goes to that MCP server.

Your own tools. An async Python function marked @beta\_async\_tool . The SDK turns its signature and docstring into the description Claude reads, so the docstring is part of the prompt.

The loop. The Anthropic SDK's tool runner calls Claude, runs the tools Claude asks for, sends back the results, and repeats until Claude is done, at most 60 times. A tool that fails goes back to Claude as an error to work around.

The model. claude-opus-5-5 at high effort. Each turn resends the conversation so far, so cache\_control caches it. fallbacks="default" lets another model carry on if Claude Opus 5.5 declines a request.

The answer. For a question, Claude calls submit\_answer , and the agent writes that JSON to STATEWEAVE\_ANSWER\_FILE before it exits.

### Make it yours

This is a starting point, not part of StateWeave. Change the prompt, add tools of your own, swap the model or the framework. Give each version its own label ( --agent my-agent@0.2 ), run the same tests, and compare the versions on the Runs board. See Run your agent .

[Run your agent](https://stateweave.net/docs/run)

[Client libraries](https://stateweave.net/docs/libraries)

[MCP servers](https://stateweave.net/docs/mcp)

[Python SDK](https://stateweave.net/docs/python)

[Twin runs](https://stateweave.net/docs/run#twin-runs)

[From your coding agent](https://stateweave.net/docs/coding-agents)

[MCP servers](https://stateweave.net/docs/mcp#claude-code)