Give an agent a disposable environment

Give an agent access to a State Machines workspace when its task needs real HTTP calls to a replica app. The agent creates the environment, runs your integration, checks the results, and deletes the data afterward. Any agent that can read Markdown and run code can follow these instructions.

Supply the instructions and the task

Point the agent to the agent skill and the documentation index. In the dashboard, open Getting started and go to Build with agents. Its Prompt and Skill tabs hold the prompt and skill that ship with the SDK. The agent’s project needs @usestatemachines/sdk 0.6.0 or later. The quickstart covers the installation. The agent checks the version in node_modules/@usestatemachines/sdk/package.json and reads the installed README before it chooses methods. State the app behavior to test and the expected result. For example:

Test the Salesforce integration's account creation flow in State Machines.
Create a disposable Salesforce environment, create an Account through the
integration, and query it to verify the name. Report the environment ID,
HTTP statuses, and assertion result. Delete the environment in a finally
block. Do not print credentials or use a real Salesforce organization.

To hand over an environment that already runs, use the environment’s Copy prompt in the dashboard. The prompt contains credentials for one app and one actor. See Run an environment in the dashboard.

Provide access through the process

Set STATEMACHINES_API_KEY in the process that runs the agent’s code. Keep the key out of the prompt, generated source files, terminal output, and version control. The SDK does not load .env files. In a worker runtime, pass the key in the client configuration. The key’s workspace and permissions decide which management operations the agent can run. The app actor decides the permissions of native app requests. See workspace access.

Follow the agent procedure

The agent follows these steps for each task. The agent skill carries the same procedure.

Establish scope and prerequisites

Read the user’s task before taking action. Identify the integration to run, the required apps, the test data, the expected result, and whether cleanup includes snapshots. Create only the resources the task requires. Do not use an external customer’s credentials or production data as a fallback. Check that STATEMACHINES_API_KEY is present in the process without displaying its value. Do not print environment variables, credential objects, login parameters, or request headers. Check the caller’s workspace and permissions. sm.me().limits can be null, so handle that case. Do not raise permissions or change organization membership to make a test pass.

Discover the app and the actor

Use sm.apps.list() to find app IDs, and follow cursors when there are more pages. Connect by the app’s name inside the environment, which can differ from its app ID. For an explicit actor, read that app’s versionId. Page through sm.apps.versions(appId) until you find that exact version, and use an actor ID it declares. Do not pick the first version, the first app in an array, a member ID, or a role label. A Salesforce role name is not an actor ID. The credentials guide includes a checked discovery example.

Keep the environment ID before waiting

Create with { wait: false } to get the accepted environment ID. Enter a try block right away. Wait for running, connect, and run the task inside it. Await deletion in finally, including when the wait or an assertion fails. Pausing keeps data and is not cleanup. This first request shows the pattern:

import { StateMachines } from '@usestatemachines/sdk';

const sm = new StateMachines();
const env = await sm.environments.create(
  { apps: ['salesforce'] },
  { wait: false },
);

try {
  const running = await sm.environments.wait(env.id, { status: 'running' });
  const salesforce = await running.connect('salesforce');
  const response = await salesforce.fetch('/services/data/v67.0/limits');

  if (!response.ok) {
    throw new Error(`Salesforce returned ${response.status}`);
  }

  console.log(response.status, await response.json());
} finally {
  await env.delete();
}

The create call itself can have an uncertain outcome. If the job must recover after a lost response or a restart, save the input and an explicit idempotency key before that call. Replay with the same input, key, workspace, and caller. A new key creates a different operation. Follow operation recovery.

Verify the integration’s behavior

Pass the returned app URL and credentials to the integration’s configurable transport. Confirm that its requests go to that URL. A successful standalone SDK request does not prove that the integration was reconfigured. If the integration cannot take a different base URL or custom headers, fix that configuration first. Check response.ok or the exact status the test expects. For writes, read the stored result back and assert the relevant fields. For negative tests, assert the expected error code and that nothing else changed. Successful environment creation alone does not verify the integration. Use Salesforce known differences to limit what the result claims. Management calls and native app calls fail in different ways. Native credentials.fetch() returns HTTP failures as responses and never retries them. A gateway 503 does not mean you can send a write again. Read the error.code in the gateway response and check the app’s stored state. If the write’s outcome is uncertain, do not send it again.

Finish or leave recoverable evidence

A timeout or abort stops the caller’s wait. It does not cancel accepted server work. Cleanup must use a signal that is not already aborted. If cleanup fails, keep the environment ID and report that failure separately from the test result. A snapshot in saving cannot be deleted yet. Keep its ID, wait for it to reach ready or failed, then delete it. Do not delete a reusable snapshot unless the task calls for it. See snapshot creation.

Report the result

Report each of these items:

The command that ran.
The app version and the SDK version.
The selected actor.
The resource IDs, without secrets.
The response statuses and the assertions.
The cleanup outcome.

Say when a result was only typechecked or read, not executed. Do not claim production compatibility from one replica test. Deletion does not erase recorded management history, so do not claim that it does.

Make the handoff recoverable

When an operation can outlive an agent session, keep the environment ID and the create idempotency key in your job’s private state. Keep them apart from credentials and out of a public report. A polling timeout or an interrupted agent does not prove that server work stopped. For parallel tests, give each task its own environment. Start each one from a ready snapshot instead of sharing one writable environment. See isolated tests and operation recovery.

Choose the documentation format

Resource	Use it for
Agent skill	The procedure, credential handling, and cleanup rules
Documentation index	Finding the guides a task needs
Complete documentation	A tool that accepts one document. Focused pages use less context.
The page’s Markdown version	One full article, with the same examples as the website
OpenAPI contract	Management operation schemas. Vendor APIs have their own contracts.

These resources hold instructions and references. Reading them does not grant access to State Machines or create an environment. To run operations, the agent needs Node.js and the SDK or an HTTP client, an API key, and a task with a clear scope.

​Supply the instructions and the task

​Provide access through the process

​Follow the agent procedure

​Establish scope and prerequisites

​Discover the app and the actor

​Keep the environment ID before waiting

​Verify the integration’s behavior

​Finish or leave recoverable evidence

​Report the result

​Make the handoff recoverable

​Choose the documentation format