Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/salesforce/ai-economist/llms.txt

Use this file to discover all available pages before exploring further.

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

"uniform/simple_wood_and_stone"
Procedurally generated map with randomized resource placement.
"layout_from_file/simple_wood_and_stone"
Fixed map layout loaded from a .txt file.
"CovidAndEconomySimulation"
Joint pandemic health and economic simulation. Requires activation code for real-world data mode.
"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.

Build docs developers (and LLMs) love

Get started for freeTalk to us