Quickstart

Run your first economic simulation in minutes

This guide walks you through creating a Foundation environment, running a simulation loop, and inspecting observations and rewards.

Prerequisites

Make sure Foundation is installed:

pip install ai-economist

See the Installation page for full setup instructions including conda environments and GPU support.

Create an environment

Foundation exposes make_env_instance() as the primary entry point for creating environments:

import ai_economist.foundation as foundation

env = foundation.make_env_instance(
    scenario_name="uniform/simple_wood_and_stone",
    n_agents=4,
    world_size=[25, 25],
    episode_length=1000,
    components=[
        ("Gather", {"move_labor": 1.0, "collect_labor": 1.0, "skill_dist": "pareto"}),
        ("Build", {"payment": 10, "payment_max_skill_multiplier": 3, "skill_dist": "lognormal"}),
        ("ContinuousDoubleAuction", {"max_bid_ask": 10, "order_duration": 50}),
        ("PeriodicBracketTax", {"tax_model": "model_wrapper", "period": 100}),
    ],
    multi_action_mode_agents=False,
    multi_action_mode_planner=True,
)

Available scenario names

Simple Wood and Stone (dynamic layout)

"uniform/simple_wood_and_stone"

Procedurally generated map with randomized resource placement.

Simple Wood and Stone (from file)

"layout_from_file/simple_wood_and_stone"

Fixed map layout loaded from a .txt file.

COVID-19 and Economy

"CovidAndEconomySimulation"

Joint pandemic health and economic simulation. Requires activation code for real-world data mode.

One-Step Economy

"one-step-economy"

Single-timestep labor and tax scenario for rapid RL experimentation.

Reset and inspect

1. Reset the environment

   reset() returns a dictionary of observations keyed by agent index:

   obs = env.reset()
   
   # Observation keys
   print(list(obs.keys()))
   # ["0", "1", "2", "3", "p"]  # mobile agents + planner
   
   # Each agent's observation is a dict of named arrays
   print(list(obs["0"].keys()))
   # ["loc", "inventory", "flat", ...]
   
2. Inspect agents

   Access agents directly from the environment:

   # All agents (mobile + planner)
   for agent in env.all_agents:
       print(agent.idx, type(agent).__name__)
   # 0 BasicMobileAgent
   # 1 BasicMobileAgent
   # 2 BasicMobileAgent
   # 3 BasicMobileAgent
   # p BasicPlanner
   
   # Access by index
   agent_0 = env.get_agent("0")
   planner  = env.get_agent("p")
   
   print(agent_0.state["inventory"])   # {"Wood": 0, "Stone": 0, "Coin": 0}
   print(agent_0.state["loc"])         # [row, col]
   
3. Step the simulation

   Pass an action dict keyed by agent index. Each value is the action index (or a dict in multi_action_mode):

   import numpy as np
   
   # Sample random actions for all agents.
   # agent.action_spaces returns an int (single-action mode) — the total number of
   # available actions. Pass a random integer from 0 to action_spaces - 1.
   actions = {
       agent.idx: np.random.randint(0, agent.action_spaces)
       for agent in env.all_agents
   }
   
   obs, rew, done, info = env.step(actions)
   
   # rew is a dict of rewards keyed by agent index
   print(rew)
   # {"0": 0.12, "1": 0.07, "2": 0.15, "3": 0.09, "p": 0.0}
   
   # done is True when the episode ends
   print(done)  # False
   
4. Run a full episode

   import numpy as np
   
   obs = env.reset()
   total_rewards = {agent.idx: 0.0 for agent in env.all_agents}
   
   for t in range(env.episode_length):
       actions = {agent.idx: np.random.randint(0, agent.action_spaces)
                  for agent in env.all_agents}
       obs, rew, done, info = env.step(actions)
   
       for agent_idx, r in rew.items():
           total_rewards[agent_idx] += r
   
       if done:
           break
   
   print("Episode rewards:", total_rewards)
   

Controlling randomness

Use env.seed() to set reproducible seeds:

env.seed(42)
obs = env.reset()  # Reproducible starting state

Examining the world

# World map shape: [height, width]
print(env.world.maps.size)

# Access resource map layers
wood_map = env.world.maps.get("Wood")   # shape: [H, W]
stone_map = env.world.maps.get("Stone")

# Access component instance
gather_component = env.get_component("Gather")
tax_component    = env.get_component("PeriodicBracketTax")

Next steps

Core Concepts

Understand Scenarios, Components, Agents, and Entities.

Simulations

Explore the built-in simulation environments.

Training with RL

Train agents using RLlib or WarpDrive.

Extending Foundation

Build custom components and scenarios.

The Google Colab tutorials let you run interactive examples in your browser without any local setup.