> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usestatemachines.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Give an agent a disposable environment

> Give an agent instructions, credentials, and a bounded create, connect, verify, and cleanup procedure.

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](/skill.md) and the [documentation index](/llms.txt). 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](/get-started/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:

```text theme={null}
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](/get-started/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](/environments/access).

## Follow the agent procedure

The agent follows these steps for each task. The [agent skill](/skill.md) 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](/environments/access). `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](/environments/credentials) 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:

```ts theme={null}
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](/sdk-api/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](/apps/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](/snapshots/create).

### 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](/sdk-api/testing) and [operation recovery](/sdk-api/recovery).

## Choose the documentation format

| Resource | Use it for |
| - | - |
| [Agent skill](/skill.md) | The procedure, credential handling, and cleanup rules |
| [Documentation index](/llms.txt) | Finding the guides a task needs |
| [Complete documentation](/llms-full.txt) | 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](/openapi.json) | 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.