Describe a reproducible agentic environment¶
To get started and run a scenario, see LilRÆ.
RAES, the Reproducible Agentic Environments System, helps you describe an agentic environment, check it before anything runs, and keep evidence about what a run realized. RAES SDL is its YAML language for authored scenarios.
A RAES scenario records the nodes, links, participants, objectives, workflows, variation, and evidence needs of an environment. RAES checks the scenario against published rules. A backend that supports the features it needs can then run it. The backend’s reports show what was realized and observed.
How a scenario reaches a run:
Author a scenario in RAES SDL. RAES validates it and compiles a plan.
Choose an external backend that supports what the scenario needs. Shifter and LilRAE (formerly APTL) are examples. You can also write your own backend. Simulator and gym adapters are unreleased.
The backend builds the environment, and participants act in it.
Reports and evidence describe what was realized and observed.
Validate your first scenario¶
Complete the quickstart first. You install RAES, validate a small SDL file, and print its name. You need standard CPython 3.14. You do not need a backend or a repository checkout. The exercise creates no infrastructure.
To explore research questions, read the research context. To cite RAES in your work, use the citation guide.
Choose what you need¶
Tutorials (learn): Complete the quickstart. Then inspect and format a scenario. This second tutorial needs a repository checkout.
How-to guides (do a task): Use the Python guide or the command-line guide. To write and check a larger scenario, validate, compile, and inspect a scenario plan.
Reference (look up facts): Use the API reference, the SDL specifications, and the published contracts.
Explanation (understand): Read the core concepts, the research context, and the current limits.
Choose your route¶
Scenario authors: Start with the SDL guide. Browse the worked examples.
Pack authors: Follow the env-packs quickstart.
Python and CLI users: Use the Python guide, the command-line guide, and the API reference. To serve the runtime over HTTP, read serve the runtime control plane.
Participant control: Use the participant-control guide to govern participant input and output.
Backend and adapter implementers: Read the backend and conformance guide and see OpenRAE/adapters. To admit tool calls inside a participant invocation, read admit participant tool actions.
Shifter and LilRAE users: Install and run each backend from its own documentation: Shifter and LilRAE.
Researchers: Review the research context, current limits, and citation guide.
Contributors: Follow CONTRIBUTING.md, the governance model, and the developer documentation index.
Help: See get help for issues and private security reports.
What RAES provides¶
RAES owns the meaning of an authored scenario and the formats around it:
the RAES SDL language, its specifications, and published schemas;
published contracts for the data that tools and backends exchange;
validation and processing that check a scenario and compile plans;
conformance tests that check whether a backend honors a stated boundary;
reference tools: the Python package, the
raescommand, examples, and test doubles for backend authors; andevidence structures that record what was requested, realized, and observed.
These parts make scenario intent portable, checkable, and shareable. They also tie that intent to evidence about what a backend realized.
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.
Run a scenario on a backend¶
This repository includes contracts, stubs, and conformance tests. It does not include a concrete deployment backend or a managed environment service. External backends realize scenarios outside this repository: Shifter, LilRAE, or your own backend. To write a backend, start with the backend and conformance guide.
OpenRAE/adapters holds adapter projects for simulators and cyber gyms. None is released. Each adapter’s own conformance reports and evidence records state what it can run.
Shifter, LilRAE, and the adapters are separate projects with their own documentation. This repository does not ship or certify them. A backend’s own reports and conformance evidence state what it supports.
Know the limits¶
An authored scenario records intent. A backend may realize only the parts it supports. 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. Read the current limits before choosing RAES for a study or integration.
Cite RAES¶
Use the citation guide. It gives the software citation. Also record the release or commit, scenario, backend, and run evidence that you used.
RAES is released under the MIT License. Third-party notices are in THIRD_PARTY_NOTICES.md.