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

# Scenario seeding

> Define explicit seed_config JSON and find the supported fields for every twin

`seed_config` defines the starting state of your twins. Its keys are twin identifiers, and each value uses that provider's own seed format. Fields with the same name can have different shapes across services.

## Create a Scenario

Save this as `scenario.json`:

```json theme={null}
{
  "name": "Scheduling eval",
  "twins": ["gmail", "google_calendar"],
  "seed_config": {
    "gmail": {
      "email_address": "agent@example.com",
      "messages": [{
        "from": "customer@example.com",
        "to": ["agent@example.com"],
        "subject": "Schedule a call",
        "body": "Could we meet this afternoon?",
        "labels": ["INBOX", "UNREAD"]
      }]
    },
    "google_calendar": {
      "email": "agent@example.com",
      "calendars": [{
        "name": "Work",
        "timezone": "America/Los_Angeles",
        "events": [{"summary": "Focus time", "start_time": "14:00:00", "duration_minutes": 60}]
      }]
    }
  }
}
```

Import the explicit fixture:

```bash theme={null}
arga test-runner scenarios import --file scenario.json
```

Or submit the same JSON body to [POST /scenarios](https://docs.argalabs.com/api-reference/post-create-a-scenario.md). Supply `name`, `twins`, and `seed_config`; you can omit `prompt` for explicit fixtures. Scenario names have a maximum of 80 characters.

## Start a Twin Run

Use the saved Scenario ID returned by the import or API:

```bash theme={null}
arga twin-runs create --twins gmail,google_calendar --scenario-id <scenario-id> --wait
```

Arga applies the fixture before the run becomes ready. Resetting or reseeding a Scenario-backed run returns it to its configured baseline.

## Repeatable fixtures

* Supply an explicit `base_time` on a twin that supports it when your eval needs a fixed reference clock. Otherwise the twin uses the current clock.
* Supply resource dates explicitly when the exact dates matter. An explicit resource date and the twin reference clock are separate controls.
* Use each twin's documented alias and reference format. Reference syntax is provider-specific.
* Include every twin needed by your fixture in `twins`; a seed block does not provision a service by itself.
* For Google Drive, Docs, and Sheets in the same Twin Run, keep their shared identity, OAuth, and clock settings consistent. Their APIs remain independent while their file state is shared within the run.

## Provider references

Open the [twin reference](https://docs.argalabs.com/concepts/twin-reference.md#seeding-reference) for every provider.

Each provider page distinguishes Scenario fields from broader API capabilities. Exported runtime snapshots are an alternative replay format when supported; reuse the complete export instead of combining snapshot metadata with ordinary seed records.


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