Verdi: an auditable testbed for societies of LLM agents

Run a society of language-model agents over time, let them govern themselves, hit them with shocks, and measure how their values and institutions drift and recover. Reproducible, seeded, and fully logged.

Get started Compare models View on GitHub

Install in one line

No virtual environment needed: uv fetches Verdi on first use. Works with any OpenAI-compatible endpoint (vLLM, Ollama, hosted APIs).

uvx verdi-agents init my-study          # example scenarios, sweeps, .env template
cd my-study                             # add your key to .env, endpoint to examples/starter.yaml
uvx verdi-agents run examples/starter.yaml
open runs/starter/report.html

Or pip install verdi-agents, then run verdi-agents directly.

What Verdi measures

Built for research on AI safety, alignment and governance in multi-agent LLM systems.

Auditable by construction

Every action, vote, law, sanction and appeal is written to an append-only event log and replayed to an identical state hash.

Declared vs observed values

Agents state their values; Verdi measures what they actually do. The gap over time is the measurement.

Self-governing societies

Universal laws plus a constitution agents can amend in assemblies: quorum, thresholds, sanctions, appeals, restoration.

Shocks and recovery

Deterministic exogenous shocks, a constrained economy and objective delivery tasks show whether a society recovers.

Compare models with sweeps

Vary the model, quorum or shock size in one YAML file; every combination runs on the same seeds, in parallel, resumable.

One-click reports

Each run renders a self-contained report.html; each sweep a comparison page and a spreadsheet.

How it works

Describe a society

One YAML file: the model endpoint, agents with roles and declared values, resources, laws, constitution, shocks and when to interview them. See the scenario reference.

Run it

verdi-agents run scenario.yaml drives every agent through every tick, validates each action against the law, and writes the full event ledger.

Compare

verdi-agents sweep reruns the scenario across models and settings and summarizes the outcomes per condition. See sweeps.

Compare LLMs on the same society

Change only the model; everything else stays identical.

name: model_comparison
scenario: examples/full.yaml
vary:
  model.name: [model-a, model-b]
parallel_runs: 2

uvx verdi-agents sweep examples/sweeps/model_comparison.yaml --dry-run   # plan + cost
uvx verdi-agents sweep examples/sweeps/model_comparison.yaml             # run, resumable