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

# Tools Test

> Run an agent-authored snippet in a UseAgents sandbox: install named packages, write files, and execute an entry file.

Test a small program against a package without running it on the caller's machine. The endpoint creates an isolated Upstash Box, installs the listed packages, writes your files, runs the entry file, and returns structured stdout/stderr. The response includes a `sessionId` you can pass on the next call to reuse the same box. The box is paused between runs so it has no hard TTL.

## Endpoint

```text theme={null}
POST /tools/test
```

Base URL:

```text theme={null}
https://api.useagents.site
```

<Note>
  Pass config and secrets through optional `env` as `{ name, value?, secret? }`. Each item needs a `value` or a `secret`. Logs store env names only. The sandbox allows outbound network so live vendor API calls can run. JavaScript and TypeScript (`runtime: node`) use the Bun runtime to add packages and run files. Pass `sessionId` from a previous result to reuse the same sandbox. The box is paused between runs and has no hard TTL.
</Note>

## Request body

| Field       | Type      | Required | Description                                                                                  |
| ----------- | --------- | -------- | -------------------------------------------------------------------------------------------- |
| `language`  | string    | Yes      | Snippet language, for example `typescript` or `python`                                       |
| `runtime`   | string    | Yes      | `node`, `python`, `golang`, `ruby`, or `rust`                                                |
| `files`     | array     | Yes\*    | 1–20 objects with `path` (relative) and `code`. Required unless `sessionId` is set           |
| `packages`  | string\[] | No       | Package names to install (`bun add`, `pip install`, `go get`, `gem install`, or `cargo add`) |
| `entry`     | string    | No       | File to execute. Defaults to the first `files` path. Required when `files` is empty          |
| `sessionId` | string    | No       | Previous `test_tool` session. Reuses packages and files; the box is paused between runs      |
| `slug`      | string    | No       | Registry slug this snippet is testing (used for analytics)                                   |
| `env`       | array     | No       | Optional `{ name, value?, secret? }` pairs. Omit or pass `[]` for none                       |
| `timeoutMs` | number    | No       | Wall-clock timeout, 1000–60000. Default 30000                                                |

Query parameter `format` is `json` (default) or `toon`, same as the other tools endpoints.

## Example request

```bash theme={null}
curl -X POST "https://api.useagents.site/tools/test" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "resend",
    "language": "typescript",
    "runtime": "node",
    "packages": ["resend"],
    "env": [{ "name": "RESEND_API_KEY", "secret": "re_test" }],
    "files": [
      {
        "path": "src/index.ts",
        "code": "import { Resend } from \"resend\";\nconsole.log(typeof new Resend(\"re_test\").emails.send);\n"
      }
    ]
  }'
```

## Response

| Field               | Description                                                                   |
| ------------------- | ----------------------------------------------------------------------------- |
| `ok`                | `true` when `status` is `ran`                                                 |
| `status`            | `ran`, `failed_install`, `failed_run`, `timeout`, `blocked`, or `unavailable` |
| `phases`            | Timing for provision, install, and run                                        |
| `stdout` / `stderr` | Truncated to 8 KB and redacted                                                |
| `sessionId`         | Returned session to pass on the next call                                     |
| `sessionExpiresAt`  | Always `null` for durable paused boxes                                        |
| `sessionReused`     | `true` when this call attached to an existing session                         |
| `error`             | Present when the sandbox or input is invalid                                  |

A failed snippet is still HTTP 200 with `ok: false`. HTTP 422 is invalid input. HTTP 503 means the sandbox provider is unavailable. HTTP 429 is the dedicated 5 requests/minute limiter.

## Typical workflow

1. Call [`GET /tools/search`](/api-reference/tools-search).
2. Call `GET /tools/context/:slug` for install and usage context.
3. Write a small program from that context.
4. Call `POST /tools/test` with `runtime`, `packages`, and `files`.

## Related

* [`test_tool` MCP tool](/mcp/tools-reference/test-tool)
* [UseAgents CLI test command](/agents/cli)