Reproducible Agentic Environments System

RAES, the Reproducible Agentic Environments System, helps you describe and check an agentic environment. RAES SDL is its YAML language for authored scenarios.

You can use RAES to record nodes, links, participants, objectives, workflows, variation, and evidence needs without tying the scenario to one deployment backend.

Validate your first scenario

You need Python 3.11 or newer.

python -m venv .venv
source .venv/bin/activate
python -m pip install raes

Save this file as first-scenario.sdl.yaml:

name: first-scenario
description: A small network with one Linux host.

nodes:
  lab-network:
    type: Switch
  web:
    type: VM
    os: linux
    resources:
      ram: 2 GiB
      cpu: 1

infrastructure:
  lab-network:
    count: 1
    properties:
      cidr: 10.0.0.0/24
      gateway: 10.0.0.1
  web:
    count: 1
    links:
      - lab-network

Validate it:

python - <<'PY'
from pathlib import Path
from raes import parse_sdl_file

scenario = parse_sdl_file(Path("first-scenario.sdl.yaml"))
print(f"Validated {scenario.name} with {len(scenario.nodes)} nodes.")
PY

The command prints:

Validated first-scenario with 2 nodes.

RAES has checked the file shape and current semantic rules. It has not created infrastructure. Continue with the quickstart to learn what each part means.

Choose your route

• Scenario authors: Start with the SDL guide and worked examples.
• Python users: Use the Python guide and API reference.
• CLI users: See the command-line guide.
• Backend implementers: Read the backend and conformance guide.
• Researchers: Review the research context, current limits, and citation guide.
• Contributors: Follow CONTRIBUTING.md and the developer documentation index.

Understand what RAES promises

An authored scenario records intent. A processor and backend may turn supported parts of that intent into runtime resources. Reports and evidence show what was accepted, changed, observed, or left unsupported.

RAES can support a bounded reproduction attempt. It does not promise deterministic runtime behavior, equal outcomes, exact replay, scientific validity, or reproducibility.

The repository does not include a production deployment backend or a managed environment service. It includes contracts, stubs, examples, conformance checks, and reference code. Read the current limits before choosing it for a study or integration.

See where RAES fits

Cyber, AI security, AI safety, testing, research, and evaluation are non-exhaustive application areas. Additional domains can add their own profiles, assets, examples, vocabularies, backends, and evidence rules.

RAES separates these concerns:

• Authored scenario: The meaning written in RAES SDL.
• Processor: The code that validates, expands, and compiles that meaning.
• Backend: The implementation that accepts a supported runtime request.
• Runtime: The resources and participant activity that occur during a run.
• Evidence: The records used to state and inspect a bounded result.

The strongest current examples come from cyber ranges and agent evaluation. The core model is not limited to those areas.

Work from a repository checkout

Install the locked development environment:

git clone https://github.com/RAESystem/rae.git
cd rae
uv sync --project implementations/python --all-extras --frozen
uv run --project implementations/python raes --help

Run the canonical verification graph:

uv tool run --from 'nox[uv]==2026.4.10' nox -f noxfile.py -s verify

Useful repository roots are:

• docs/public/ for hosted reader documentation;
• docs/README.md for developer and working records;
• specs/ for normative specifications;
• contracts/ for published schemas and fixtures;
• examples/ for authored scenarios and reusable patterns;
• implementations/python/ for the reference implementation.

Project status

RAES is an academic and engineering project with one maintainer. Contributions are welcome. The project does not require a second maintainer or independent reviewer for every change.

Release Please owns package versions, GitHub releases, and CHANGELOG.md. Published schemas carry separate stability labels. See GOVERNANCE.md and MAINTAINERS.md for the current decision and maintenance model.

Cite RAES

@software{raes,
  author  = {Edwards, Brad},
  title   = {RAES: Reproducible Agentic Environments System},
  year    = {2026},
  license = {MIT},
  url     = {https://github.com/RAESystem/rae}
}

RAES is released under the MIT License. Third-party notices are in THIRD_PARTY_NOTICES.md.