A Mass Simulation is a collection of Sessions where the same agent runs the same task multiple times. Due to the inherent non-determinism of autonomous agents, a single run is often misleading — Mass Sims let you observe what your agent can do, usually does, and sometimes fails to do. Learn more about Mass Sims in the Mass Simulations section.
There are 2 ways to create a mass sim: 1) in the UI OR 2) using the Python SDK

​
How to Create a Mass Simulation

​
Option 1. Create in UI

  • Go to the “Mass Sims” tab inside your Agent
  • Click “Create New Mass Simulation”
  • Copy the Mass Sim ID into your SDK: 
lai.init(
    session_name="run_37",
    providers=["openai"],
    mass_sim_id="abc123"
)
  • You’re done! Now the sessions that you run under this mass simulation ID will be grouped together into one mass simulation. If you want to create another one, just repeat the process and make sure to use the right mass sim ID!

​
Option 2. Create in Python SDK

This approach to creating a mass simulation doesn’t need any UI interaction at all! It is often more convenient to create a mass simulation using the Python SDK if you want to do things such as create a script that creates multiple mass simulations. You can programmatically create a mass simulation using the create_mass_sim() function: 
import lucidicai as lai

mass_sim_id = lai.create_mass_sim(
    mass_sim_name="search_performance_test",
    total_num_sessions=50,
    api_key="your-api-key",  # Or use env var: LUCIDIC_API_KEY
    agent_id="your-agent-id",        # Or use env var: LUCIDIC_AGENT_ID
    task="Search Wikipedia for Steve Jobs biography",
    tags=["search", "performance", "wikipedia"]
)

print(f"Created mass simulation with ID: {mass_sim_id}")

​
Returns

  • A string containing the unique ID of the created mass simulation.

​
Example Usage

Create a mass simulation and then use the returned ID in your session initialization: 
import lucidicai as lai

# Create a mass simulation with 25 sessions
mass_sim_id = lai.create_mass_sim(
    mass_sim_name="product_search_test",
    total_num_sessions=25,
    task="Search for iPhone 15 Pro Max",
    tags=["gemini", "search", "e-commerce"]
)

# Use the mass_sim_id in your session initialization
lai.init(
    session_name="search_run",
    providers=["gemini"],
    mass_sim_id=mass_sim_id
)

# Continue with your agent logic...

​
🏃 How to Run your Mass Simulation

A Mass Simulation is just a way to group multiple sessions with the same task together and see the analytics of the sessions as a whole. Therefore, it is still necessary to run the sessions under the mass simulation ID. Feel free to run your sessions however you like! For your convenience, we created two bash scripts to help you run your sessions in a loop.

​
1. Running the sessions in a mass simulation sequentially:

This means it will run your agent script one at a time, waiting for each session to finish before running the next one. 
for i in {1..[n]}; do python3 [your-script.py]; done
Where n is the number of sessions you want to run and your-script.py is the file path from the current directory to the script that runs your agent. Example Usage: 
for i in {1..5}; do python3 examples/models/gemini.py; done
This would run the gemini.py agent 5 times.

​
2. Running the sessions in a mass simulation in parallel:

This means it will run your agent script multiple times at the same time (in parallel), so it will run faster.
Important Note: If you are running more than 5 sessions in parallel, ensure that your computer can handle it! 
for i in {1..[n]}; do python3 [your-script.py]&; done
Note: The & at the end of the command runs the process in the background and allows you to run multiple processes at the same time.
Where n is the number of sessions you want to run and your-script.py is the file path from the current directory to the script that runs your agent. Example Usage: 
for i in {1..5}; do python3 examples/models/gemini.py&; done
This would run the gemini.py agent 5 times in parallel (i.e. launch 5 processes at the same time).