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

# Worlds

> A world is the synthetic environment your agent runs in: scenarios, users, tools and how many times to run each drill.

A **world** is the synthetic environment your agent runs in. It belongs to one registered agent and lists the scenarios to run, the synthetic tools your agent uses, the configuration names your agent needs and how many repetitions to run. The scenarios bring their simulated users and evaluations with them.

Scenario events change the world during a drill. They can send a new message, take a service offline and bring it back, or happen after a set time.

## Example

```json world.json theme={null}
{
  "schema": "firedrill.native-world.v1",
  "name": "Refund drills",
  "description": "",
  "dependencies": [
    {
      "alias": "mail",
      "mode": "simulated",
      "tool_version_id": "<tool version id>",
      "service_key": "gmail",
      "contract_digest": "<contract digest>",
      "operations": ["messages.list", "messages.send"],
      "seed_id": null
    }
  ],
  "resources": [
    { "origin": "native_library", "kind": "scenario", "id": "<scenario version id>", "revision": 1, "digest": "<digest>" }
  ],
  "configuration_names": [
    { "name": "OPENAI_API_KEY", "phase": "runtime" }
  ],
  "execution": { "repetitions": 3, "max_parallel": 1, "reset": "per_drill" }
}
```

## Save it

```bash theme={null}
firedrill world save --agent <agent-id> --file world.json
```

The world uses the agent's newest descriptor unless you pass `--descriptor-revision`. To save a new revision of an existing world, pass both `--world <world-id>` and `--expected-revision <n>`.

Saving a world prepares nothing and starts nothing. Next, [review the plan](https://docs.firedrill.run/run/run-drills.md).

## Fields

| Field | Description |
| - | - |
| `schema` | Always `firedrill.native-world.v1`. |
| `name`, `description` | For people reading it. |
| `dependencies` | One entry for each descriptor dependency, using the same alias. |
| `resources` | The scenarios to run. Their personas and evaluations are included automatically. |
| `configuration_names` | Every required configuration name from the descriptor, with a matching phase. |
| `execution` | `repetitions`, `max_parallel` and `reset`. |

### Dependencies

| Field | Description |
| - | - |
| `alias` | The same alias as in the descriptor. |
| `mode` | `simulated`. |
| `tool_version_id` | A tool version saved in your workspace. |
| `service_key` | The service inside the tool, such as `gmail`. |
| `contract_digest` | The tool version's contract digest. |
| `operations` | Every operation your descriptor lists for this dependency, or more. |
| `seed_id` | Starting data for the tool, or `null` for the default. |

To fill these in:

```bash theme={null}
firedrill tools save <release-id>               # add a catalog tool to your workspace
firedrill tools runnable                        # version ID and service keys
firedrill tools definitions show <version-id>   # contract digest
```

### Execution

| Field | Description |
| - | - |
| `repetitions` | How many times to run each scenario. |
| `max_parallel` | How many drills may run at once. Must be 1 unless every state domain is `independent` and `reset` is `per_drill`. |
| `reset` | `per_drill` when each drill starts from clean state, `serialized` when drills must run one after another, or `unknown`. |

Drills in the campaign = scenarios × `repetitions`.

## What the plan review checks

`firedrill plan` reports anything that would stop the world from running. Common items:

| Requirement | Fix |
| - | - |
| `dependency_mapping_incomplete` | Add a world dependency for every descriptor dependency, with the same alias. |
| `dependency_contract_mismatch` | Include every operation the descriptor lists. |
| `tool_operation_unavailable` | The tool does not offer that operation. Pick another tool or operation. |
| `scenario_required` | Add at least one scenario to `resources`. |
| `scenario_evaluation_required` | Add an evaluation to each scenario. |
| `parallel_state_boundary_required` | Set `max_parallel` to 1, or make state resettable per drill. |
| `configuration_mapping_required` | Add the missing name to `configuration_names`. |
| `library_parameters_require_binding` | Bind parameter values with `firedrill library bind`. |

## Share and reuse worlds

```bash theme={null}
firedrill world history <world-id>
firedrill world versions
firedrill world fork <version-id> --agent <agent-id>
```

Organization admins can share world versions with other workspaces. In the web app, open **Worlds**.

> [card] [Run drills](https://docs.firedrill.run/run/run-drills.md)
>
> Plan, apply and run.

> [card] [Synthetic tools](https://docs.firedrill.run/tools/overview.md)
>
> Choose tools for your dependencies.


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