> ## Documentation Index
> Fetch the complete documentation index at: https://salesforce-ai-economist.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
pip install ai-economist
```

See the [Installation](https://salesforce-ai-economist.mintlify.site/installation.md) 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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
# 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):

```python theme={null}
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**

```python theme={null}
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:

```python theme={null}
env.seed(42)
obs = env.reset()  # Reproducible starting state
```

## Examining the world

```python theme={null}
# 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](https://salesforce-ai-economist.mintlify.site/concepts/framework-overview.md)**
>
> Understand Scenarios, Components, Agents, and Entities.

> **[Simulations](https://salesforce-ai-economist.mintlify.site/simulations/gather-trade-build.md)**
>
> Explore the built-in simulation environments.

> **[Training with RL](https://salesforce-ai-economist.mintlify.site/training/overview.md)**
>
> Train agents using RLlib or WarpDrive.

> **[Extending Foundation](https://salesforce-ai-economist.mintlify.site/extending/custom-components.md)**
>
> Build custom components and scenarios.

> [!TIP]
>
> The [Google Colab tutorials](https://github.com/salesforce/ai-economist/tree/master/tutorials) let you run interactive examples in your browser without any local setup.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.