Your first experiment

Once you have installed aigora and set your API key(s), you are ready to run your first experiment.

We're going to start small, and set up a simple market experiment with two LLM agents: a buyer and a seller. In the next few examples, we'll gradually build this out until we have something that faithfully replicates a real market experiment — namely, Smith (1962).

Create an experiment.yaml file

Download the complete files and extract them into your experiment folder, keeping the examples/ directory structure. The files for this stage are in examples/tutorials/first_experiment. You can follow along by editing them or recreate them from the snippets below.

Every aigora experiment is defined a single YAML file, which we'll call experiment.yaml. Think of this file as a blueprint for the experiment: it defines all the important parameters for your experiment, including the agents, the prompts, and the rules of the market. It also serves as a record of the experiment, so you can reproduce it later.

Tip: Learn by modifying an example

The best way to learn how to write an experiment.yaml file is to start with a working example and modify it. The syntax is very readable, so you can likely guess what most of the fields mean without having to read the documentation. But of course, if you want to understand the details, all the fields are documented in the YAML configuration reference.

The experiment.yaml file below specifies a simple market experiment with two agents: a buyer and a seller. The buyer starts with 150 in cash and no units; the seller starts with one unit and no cash. We provide the buyer with a private value for the good being traded, and the seller with a private cost. The buyer's objective is to buy the good at a price lower than its value, while the seller's objective is to sell the good at a price higher than its cost. We communicate these objectives to the agents through their prompts.

Create a new file called experiment.yaml in examples/tutorials/first_experiment, and copy the contents of the snippet below into it. See if you can identify where we've specified the agents, their initial endowments, and their private information.

experiment.yaml

experiment:
  name: first_experiment
  seed: 42
  output_dir: results
  protocol:
    period_duration_seconds: 30
  assets:
  - id: asset
    name: Good
  markets:
  - id: asset
    price_min: '0'
    price_max: '150'
  agents:
  - id: buyer
    lm:
      provider: openai
      model: gpt-5.4-mini
      temperature: null
      reasoning_effort: none
      max_tokens: 4096
    prompt:
      instructions:
        content: |
          You are a buyer. You can buy one unit in this round.
          Your private value is 100. Your earnings are 100 minus the purchase price.
          If you do not trade, your earnings are zero.
          Maximise your earnings. Do not buy above your value. Do not sell.
      context_providers:
      - type: snapshot_period_timing
      - type: snapshot_order_book
      - type: snapshot_own_orders
      - type: snapshot_own_holdings
      - type: snapshot_last_action_outcome
    initial_holdings:
      cash: '150'
      units:
        asset: 0
    trading_constraints:
      allowed_sides: [bid]
      max_units:
        asset: 1
      max_order_quantity: 1
      max_outstanding_orders: 1
  - id: seller
    lm:
      provider: openai
      model: gpt-5.4-mini
      temperature: null
      reasoning_effort: none
      max_tokens: 4096
    prompt:
      instructions:
        content: |
          You are a seller. You can sell one unit in this round.
          Your private cost is 40. Your earnings are the sale price minus 40.
          If you do not trade, your earnings are zero.
          Maximise your earnings. Do not sell below your cost. Do not buy.
      context_providers:
      - type: snapshot_period_timing
      - type: snapshot_order_book
      - type: snapshot_own_orders
      - type: snapshot_own_holdings
      - type: snapshot_last_action_outcome
    initial_holdings:
      cash: '0'
      units:
        asset: 1
    trading_constraints:
      allowed_sides: [ask]
      max_order_quantity: 1
      max_outstanding_orders: 1

The context_providers list controls the information an agent receives before each decision. Here, the built-in providers tell it how much time remains, what orders are available, what it owns, and what happened to its last action. We don't need to write any Python to supply that information.

Run the experiment

To run the experiment, call the aigora.run() function, passing the path to the experiment.yaml file. The function is asynchronous, so a terminal script uses asyncio.run(...) to start it.

Create run.py alongside experiment.yaml:

Python

run.py

import asyncio

import aigora

if __name__ == "__main__":
    run_dir = asyncio.run(
        aigora.run("examples/tutorials/first_experiment/experiment.yaml")
    )
    print(f"Experiment results saved to {run_dir}")

Run the script from your experiment folder (the folder containing examples/):

python -m examples.tutorials.first_experiment.run

In a notebook, you can use await aigora.run(...) directly instead of asyncio.run(...).

Running the script in a terminal will spin up a dashboard that shows the market in real time, including the agents' orders and any trades that occur.

When the run finishes, the run_dir will contain the results of the experiment, including a CSV file with all the trades and a directory with each agent's recorded decisions. You'll find completed trades in trades.csv and each agent's recorded decisions in traces/. See Output files for the full file descriptions.

Well done! You've just run your first experiment with aigora. From here, you can start to tinker around with experiment.yaml file to see how this changes the agents' behaviour, or move on to the next example, where we'll add a second buyer and seller to the market.

Download the complete files if you want a separate copy of this stage.