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: a market, a council, an exchange, a courtroom, an epidemic, a game. The contract declares the world, the people, what agents can do, what they see, how the world moves on its own, and what is measured. The engine builds the world, wakes agents, gives each a short plain-language picture with typed tools, applies their actions atomically, runs scheduled world rules, and returns typed outputs.

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 "fg-env==0.4.2"

Python ≥ 3.11. 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

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 environments. Each was written by an LLM agent from the guide alone, and each is covered by a golden-run test: a coffee market with sampled households and subscriptions, a forecasting council, a price-time-priority order-book exchange, a civil trial, a town epidemic with physics, Werewolf, a labor negotiation, Connect Four, a Hold'em-lite poker table, the beer distribution game, a climate club with a CO2 model, a ride-hailing city, checkers, a Diplomacy-style strategy game, and misinformation spreading on a follower network.

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.