---
title: "Worlds, twins, and replicas"
description: "The vocabulary behind AgentTwin: worlds, service twins, replicas, baselines, and regression artifacts."
canonical: "https://agenttwin.si/docs/concepts/"
---

# Worlds, twins, and replicas

The vocabulary behind AgentTwin: worlds, service twins, replicas, baselines, and regression artifacts.


<Info>These concepts describe the broader product contract. The current runtime uses explicit fixtures, supported operation mappings and reprovisioning. Automatic shared-identity compilation, coordinated snapshots and comprehensive provider conformance are not shipped. See [current capabilities](/status).</Info>

A useful test environment is not a pile of disconnected mock endpoints. It is a **world**: services that share the same entities, events, and state.

## Core vocabulary

| Term | Meaning |
| --- | --- |
| **World** | A set of service twins plus the shared entities and events that link them. |
| **Twin** | A service stand-in that implements the subset of provider behavior a workflow depends on. |
| **Replica** | A disposable, isolated test copy of a world, created from a baseline. |
| **Baseline** | The versioned starting state a run begins from and can be restored to. |
| **Fault injection** | A deterministic failure applied at a chosen point in a run. |
| **Manifest** | The declared coverage of a replica: what is verified, modeled, or unsupported. |
| **Regression artifact** | The saved starting state, fault point, input, and assertions from a reproduced incident. |

## Why "world" and not "mock"

One customer should be the same logical person in a billing system, a CRM, an inbox, and a support tool. A refund can update billing state, emit a webhook, change an internal record, and trigger a notification. A world evaluates that whole chain, not a single endpoint in isolation.

## What makes a world useful

- **Shared state** — related records across services represent the same people, accounts, and business events.
- **Observable effects** — writes and asynchronous events are recorded so a developer can inspect what actually changed.
- **Repeatability** — a baseline can be restored, a run repeated, and time or randomness controlled so failures can be compared.
- **Branching** — one baseline can be explored under several independent scenarios without contaminating the others.
- **Failure controls** — supported faults can occur at meaningful points, including after a service has already applied a write.
- **Outcome verification** — correctness is checked against final world state and invariants, not only the agent's natural-language explanation.
- **Honest fidelity** — each twin should state what is supported, what has been verified, what is unknown, and when verification last ran.

<Note>
  Current runs use explicit fixtures, supported service contracts and fresh sandbox provisioning. Automatic shared-identity compilation, coordinated snapshots and control of all clocks or randomness are outside current coverage.
</Note>

## The agent should not have to know

The agent should not have to know whether it is talking to production or a test world beyond the configuration boundary. The developer, however, should always be able to tell which world is active and what that world can faithfully simulate.

<Card title="Read the fidelity contract" icon="lucide:badge-check" href="/fidelity">
  How a replica publishes its limits: verified, modeled, and unsupported behavior.
</Card>