Environments SDK

Define an environment as one contract. The engine runs it.

Documentation · Quickstart · Authoring guide · Reference

Overview

fg-env turns one JSON contract into a running environment for AI agents. The contract declares the participants, roles, private and public information, legal actions, state transitions, stopping conditions, and measurements. The runtime builds the world, gives each agent an appropriate view and typed tools, applies actions atomically, and returns typed outputs.

Use this SDK when you need to simulate people interacting under explicit rules and run the same scenario repeatedly. Start from one of twelve reusable behavioral engines—Market, Council, Dispute, Exchange, Legislature, Contest, Deliberation, Negotiation, Population, Network, Matching, or Strategy—then customize the topic, participants, rules, information, and outcomes.

Do not treat an engine as a finished scenario. Engines provide interaction mechanics; your environment supplies the real-world question and assumptions. Named Arena games and physical, spatial, logistics, or disease models are not part of the behavioral engine catalog.

You write data, never engine code. The same contract runs with LLM agents, coded crowds, or both, and engine randomness is reproducible from its seed. Reproducing an LLM run also requires the same participant decisions; record traces for replay.

Built for LLM agents from the ground up:

• A cacheable brief and a compact update. Each turn opens with why the agent is acting, what changed since its last turn, and ranked views of the world, names first, with ids as handles. Nothing is repeated that the agent already has.
• One typed tool per legal action. JSON Schema with enums and numeric bounds. An invalid call returns exactly what to fix, and a refused action changes nothing.
• Participant text stays marked. Anything an agent writes carries its provenance through records, properties and views, and is always shown «quoted».
• Measured. Every run reports turns, tool calls, invalid calls and tokens per update.

fg-env is one of Fareground's open-source building blocks, alongside Agents SDK, agent-id, agent-memory, agent-knowledge and agent-messaging.

Install

Install Environments SDK from PyPI:

python -m pip install --upgrade fg-env

The PyPI badge at the top of this page shows the current released version. This README documents the main branch; release-specific behavior is recorded in the changelog. Python 3.11 or newer is required. The only runtime dependency is pydantic.

Quickstart

For a business walkthrough, start with weekly inventory, including exact expected outputs. The following small contract illustrates the basic API:

import fg_env

contract = {
    "name": "Coin flip",
    "brief": {"rules": "Bet some coins each round. Heads you win that much, tails you lose it."},
    "types": {"player": {"agent": True, "props": {"coins": 10}}},
    "entities": {"ann": {"type": "player"}, "bob": {"type": "player"}},
    "actions": {"bet": {"by": "player", "params": {"amount": {"type": "int", "min": 1, "max": "$actor.coins"}},
                        "do": "$actor.coins += $params.amount if $chance(0.5) else -$params.amount"}},
    "outputs": {"richest": "$best(player, $it.coins, 'random').name"},
}

print(fg_env.check(contract))        # [] — every problem would come with its path and a fix
result = fg_env.run(contract, seed=1)  # random agents; same seed, same run
print(result.outputs)                  # typed, per the contract

Start from a reusable engine

Discover a versioned engine, clone its starter, then customize the contract:

import fg_env

for engine in fg_env.list_engines():
    print(engine.id, engine.status, engine.available)

fg_env.clone_engine("market", "my_market.json", name="My market study")
result = fg_env.experiment("my_market.json", runs=20, participants="random")
print(result.table())

The catalog contains reusable behavioral engines only—not finished environments, scenario presets, or Arena games. All twelve engines are native, available, and cloneable.

Persona generation is shared infrastructure rather than an environment:

cohort = fg_env.sample_records(
    people, size=100, seed=7, run=0, resample=True,
    constraints={"region": "north"}, group_by="household_id",
    source="survey-2026",
)

See engine starters and persona sampling.

Or start from a template and read the short core guide:

fg-env new game my_game.json    # blank, game, market, simulation or social — checks clean and runs
fg-env check my_game.json       # static checks plus one played round
fg-env guide                    # the core guide; it maps every other part: fg-env guide actions, fg-env guide market.auction

What an agent receives on its turn:

env = fg_env.load(contract, seed=1)
print(env.preview("ann"))    # {'brief': ..., 'update': ..., 'tools': [...], 'tokens': {...}}

Run it with an LLM — pass your own client:

import anthropic
claude = fg_env.participants.anthropic(anthropic.Anthropic(), "YOUR_AVAILABLE_MODEL_ID")
result = fg_env.run(contract, {"player": claude}, seed=1)

Or with your own code. A participant is any function that takes a Wake:

def cautious(wake):
    print(wake.update)                                   # the same picture an LLM reads
    result = wake.call("bet", {"amount": 99})            # out of range
    print(result.text)                                   # "bet was not done: amount must be at most 10 (got 99). ..."
    wake.call("bet", {"amount": 1})

fg_env.run(contract, {"ann": cautious, "bob": claude}, seed=1)

The contract

One small, strict expression language is used everywhere: $actor.cash >= $params.qty * $params.offer.price, $count(buyer, $it.cash > 0), $top(offer, [$it.rating, -$it.price], 5). Unknown properties and type errors are reported with the fix; nothing silently evaluates to zero.

Start with fg-env guide authoring: a compact, executable path from configurable objects and tables to decisions, rounds and known-answer checks. Hosts can put fg_env.guide("authoring") directly in an authoring agent’s starting context. Field references are generated from the installed SDK; fg-env guide maps the full language and fg-env guide all prints the complete reference.

fg-env guide authoring    # or: python -c 'import fg_env; print(fg_env.guide("authoring"))'
fg-env guide              # full language map
fg-env guide stages       # one section's fields and the $roots available there
fg-env guide market       # a mechanism family; fg-env guide market.auction for one mode

Tooling

fg-env check shop.json                    # every problem with its path and a fix, plus a smoke round
fg-env expand shop.json --mechanisms       # the contract with every mechanism expanded into plain sections
fg-env preview shop.json shopper_1        # exactly what that agent reads, its tools, token estimates
fg-env preview shop.json shopper_1 --rounds 5 --agent shopper=policy:thrifty
fg-env run shop.json --seed 1 --input budget=50 --agent shopper=policy:thrifty --json
fg-env experiment shop.json --runs 20 --arms control,promo
fg-env schema                             # JSON Schema of the contract

In Python: fg_env.check, fg_env.load, env.run / env.step, env.preview, env.snapshot() / fg_env.Env.restore, and fg_env.experiment. Experiment arms share seeds run by run, so differences between arms come from the arm, not from luck.

Examples

examples/contracts/ holds complete contracts covered by golden-run tests. They demonstrate contract features and lower-level mechanics; they are examples, not entries in the behavioral engine catalog. For new human-behavior scenarios, begin with the closest engine starter and customize it rather than copying a named example.

fg-env run examples/contracts/werewolf.json --seed 3

Determinism

Every random draw comes from one seed tree per run, so a run is reproducible exactly from its seed. Adding an event with a chance roll never changes how the population was sampled. Runs snapshot to JSON between rounds and resume identically.

Template API

The earlier template-based engine API (Kernel, simulate, load_world, the registry decorators) remains available for existing templates as fg_env.legacy (from fg_env.legacy import simulate), with its commands under fg-env legacy; see docs/template_schema.md. New environments should use contracts.

Contributing

See CONTRIBUTING.md for dev setup, tests and lint. What changed is in the CHANGELOG.

License

Apache License 2.0. See LICENSE for the full terms. Security issues should follow the private reporting process in SECURITY.md.