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

# Firedrill documentation

> Give your AI agent controlled, stateful Tools and verify what it actually does.

Firedrill is a stateful simulation and testing framework for action-taking AI agents. It replaces real dependencies with controlled **Tools**, lets your existing agent act through its normal interface, and checks tool calls, state changes, events, ordering, faults, and time.

```bash theme={null}
firedrill init --custom records
firedrill serve
```

The local inspector opens with a working synthetic backend. Add a drill when you want that interaction to become a repeatable behavioral test.

<Note>
  The packages are currently release candidates and are not yet on public package registries. The [quickstart](/quickstart) uses a source checkout and marks the future package-install path separately.
</Note>

## The working loop

<Steps>
  <Step title="Add useful Tools and data">
    Install a reusable Tool or create one in your repository. A Tool defines callable operations, deterministic behavior, and the state those operations change.
  </Step>

  <Step title="Connect the existing agent">
    Point the agent's configurable MCP, HTTP, CLI, function, SDK, or browser seam at Firedrill. Your application, model, and agent runner remain yours.
  </Step>

  <Step title="Run a drill">
    Give the agent a task in an isolated world. Define the starting scenario and assert on observable consequences rather than model wording.
  </Step>

  <Step title="Inspect and reproduce">
    Review the causal timeline, tool activity, data changes, assertions, logs, and optional captures. Re-run the same build and seed when you need to reproduce a result.
  </Step>
</Steps>

## Start with your goal

<CardGroup cols={2}>
  <Card title="Start synthetic Tools" icon="plug" href="/guides/start-local-tools">
    Create a controlled backend and inspect its state before writing a test.
  </Card>

  <Card title="Test an agent locally" icon="vial" href="/quickstart">
    Run one complete drill and open its evidence report.
  </Card>

  <Card title="Connect an existing agent" icon="link" href="/guides/connect-agent">
    Use an existing MCP, HTTP, CLI, function, SDK, or browser boundary.
  </Card>

  <Card title="Mock one dependency" icon="code-branch" href="/guides/mock-dependencies">
    Inject synthetic behavior from Jest, Vitest, Mocha, or another runner.
  </Card>

  <Card title="Reproduce a failure" icon="rotate-left" href="/concepts/evidence-reset">
    Control state, time, faults, seeds, resets, and immutable builds.
  </Card>

  <Card title="Use Firedrill in code" icon="code" href="/sdk/overview">
    Drive local worlds and drills through the TypeScript SDK.
  </Card>
</CardGroup>

## What Firedrill controls

| Firedrill controls                          | You keep control of                      |
| ------------------------------------------- | ---------------------------------------- |
| Synthetic Tool behavior and state           | Agent code and orchestration             |
| Per-run isolation and reset                 | Model provider and credentials           |
| Virtual time, faults, events, and callbacks | Production services and application data |
| Assertions and ordered evidence             | The test runner and CI system            |

Firedrill does not host or rewrite your agent in the local workflow. It gives the agent a safe world to act inside and records the consequences.

<Card title="Run the quickstart" icon="arrow-right" href="/quickstart">
  Go from a source checkout to a passing drill and a local HTML report.
</Card>