Worlds

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

world.json

{
  "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

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.

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:

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`.

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.

Run drills

Plan, apply and run.

Synthetic tools

Choose tools for your dependencies.

Get started

Coding agents

Connect your agent

Build a world

Run drills

Read results

Account

Reference

Example

Save it

Fields

Dependencies

Execution

What the plan review checks

Run drills

Synthetic tools

Example

Save it

Fields

Dependencies

Execution

What the plan review checks

Share and reuse worlds

Run drills

Synthetic tools