Built-in context providers
Context providers control what an agent can see before it makes a decision. For example, you might give it the current order book, its available cash, and the last few trades. Each provider returns a section of text, and aigora combines those sections into the agent's update.
Add the providers you want under experiment.agents[].prompt.context_providers.
This configuration gives an agent the order book, its own holdings, and the three most recent trades in each market:
context_providers:
- type: snapshot_order_book
- type: snapshot_own_holdings
- type: snapshot_trades
params:
n: 3
Providers appear in the update in the order you list them. Each agent gets its own provider instances, which remain in use across periods.
There are two ways to present information. A snapshot describes the state at the time of the update, such as all open orders. An incremental provider describes what changed since the agent's previous committed observation. Usually, that means the observation from its last successfully parsed decision; the baseline rules cover failures and the first update.
The examples below show the plain text that agents receive. Asset names come from your configuration, prices retain their decimal precision, and markets appear in ID order. Asset descriptions are not included automatically.
Market information
snapshot_best_bid_ask
This provider shows the highest bid (offer to buy) and lowest ask (offer to sell) in each market. It includes the quantity available at each price and how much of that quantity belongs to the agent's own orders. Because those quotes can include the agent's own orders, seeing a quote does not guarantee that the agent can trade at that price.
Parameters: None.
Sample output
snapshot_order_book
This provider shows all price levels in the order book, with the remaining quantity at each price. Buy offers appear from highest to lowest price, and sell offers from lowest to highest. Where the agent has an order at a price, the text also identifies its share of the quantity.
Parameters: None.
Sample output
Current buy and sell offers:
Stock Black (market_id: black):
Traders are offering to buy a total of 5 units at 1.20 per unit. Your own orders account for 2 of these units.
Traders are offering to buy a total of 3 units at 1.10 per unit. Your own orders account for 3 of these units.
Traders are offering to sell a total of 4 units at 1.30 per unit.
incremental_order_book
This provider reports which price levels have changed since the previous committed observation, including changes to the agent's own contribution. It compares the two states of the book, so it reports the net change at each price. A decrease in quantity alone does not tell the agent whether an order traded or was cancelled.
Parameters: None.
Sample output
Changes in buy and sell offers:
Since your previous update:
Stock Black (market_id: black):
Buy offers at 1.20 per unit increased from 2 to 5 units; yours increased from 1 to 2 units.
Buy offers at 1.10 per unit increased from 0 to 3 units.
Sell offers at 1.30 per unit decreased from 4 to 0 units; yours decreased from 2 to 0 units.
snapshot_trades
This provider lists completed trades, newest first within each market. The history includes earlier periods, and any trade involving the current agent is marked “Your trade”.
Choose how much trade history to show
Set n to limit the list separately for each market; for example, n: 3 shows up to three trades per market.
Leaving n unset includes all trades, including those from earlier periods.
Parameters: n: positive integer or null; default null (all trades).
Sample output
incremental_trades
This provider lists every trade that occurred since the previous committed observation, newest first within each market. It has no limit on the number of trades returned. The trade history continues across periods, so changing periods does not discard events the agent has yet to observe.
Parameters: None.
Sample output
Your holdings and orders
snapshot_own_holdings
This provider tells an agent what it owns and what it can still offer to buy or sell. It distinguishes settled cash from available cash: money reserved by an open bid is still in the account, but cannot fund another bid. The output includes assets with zero holdings and assets that have no market.
You can change the displayed currency symbol with currency_symbol; this does not change the amounts or how cash is handled.
Parameters: currency_symbol: string without whitespace; default "$". An empty string is valid.
Sample output
Your holdings:
You currently have $80 in settled cash. Your open buy orders set aside $0, leaving $80 in available cash to spend.
Stock Black (market_id: black)
You currently own 8 units of Stock Black.
You can submit additional sell orders for up to 16 units.
Stock White
You currently own 0 units of Stock White.
Stock White cannot be traded in this experiment.
incremental_own_holdings
This provider compares the agent's holdings with its previous committed observation.
It reports changes in settled cash, available cash, asset positions, and additional order limits.
The amounts use $, and each change is a net difference between observations rather than a list of individual transactions.
Parameters: None.
Sample output
snapshot_own_orders
This provider lists the agent's open orders, including each order's full ID, price, and remaining quantity. The agent can use an order ID when it wants to cancel an order. Orders are grouped by market and sorted by ID within each market.
Parameters: None.
Sample output
incremental_own_orders
This provider explains what happened to the agent's orders since its previous committed observation. It reports fills at their execution prices, cancelled quantities, and how many units remain open. It also includes orders that opened and closed between observations, as well as cancellations at the end of a period.
Parameters: None.
Sample output
Changes in your open orders:
Since your previous update:
Stock Black (market_id: black):
Order (order_id: order-1): bought 2 units at 1.20 per unit; 3 units remain open.
Order (order_id: order-2): sold 3 units at 1.30 per unit; 0 units remain open.
Order (order_id: order-3): 4 units cancelled; 0 units remain open.
Order (order_id: order-4): bought 2 units at 1.20 per unit; 3 units cancelled; 0 units remain open.
Order (order_id: order-5): new offer to buy 1 unit at 1.10 per unit; 1 unit remains open.
Your actions and timing
snapshot_own_actions
This provider shows the agent's latest actions in the current period, starting with the most recent.
Each entry includes the outcome, any rejection details, the full order ID where relevant, and the reason the agent supplied.
Use n to choose how many actions to include; actions from earlier periods are excluded.
Parameters: n: positive integer; default 5.
Sample output
Your recent actions:
Latest 5 actions in this period, newest first.
Buy order in market black for 2 units at 1.20 per unit; accepted.
Order ID (order_id): order-123
Your reason: The price is below my estimated value.
Sell order in market black for 3 units at 1.30 per unit; rejected.
Rejection reason: Insufficient available units.
Your reason: Reduce my holdings.
Cancel order (order_id: order-456) in market black; cancelled.
Your reason: Replace my previous offer.
No action taken.
Your reason: Wait for a better price.
snapshot_last_action_outcome
This provider shows only the agent's most recent action in the current period, together with its outcome and supplied reason. An “accepted” outcome means the order passed the trading rules; it does not mean a trade took place.
Parameters: None.
Sample output
snapshot_period_timing
This provider tells an agent which period it is in and how much trading time remained when the observation was captured. It also includes the period's duration and elapsed time. Positive times below 0.1 seconds are shown as “less than 0.1 seconds”, and remaining time is never displayed as negative.
Parameters: None.
Sample output
Holdings limits
The holdings providers describe how many additional units an agent can offer to buy or sell. These limits take account of open orders, allowed sides, position bounds, and the maximum number of outstanding orders. The agent must also have enough available cash for a bid. An unfilled buy order does not provide units to sell, and an unfilled sell order does not provide cash to spend. Selling units the agent does not own also requires the market to allow short selling.
The displayed allowance is separate from the quantity limit on an individual order. For example, an agent may have room to sell 16 more units while being limited to one unit per order. The output shows zero allowances explicitly, omits unbounded allowances, and leaves out order-limit lines for assets that cannot be traded.
If you construct market snapshots yourself, include short_selling_allowed.
The providers raise an error when that rule is unknown, because they cannot determine the agent's selling allowance.
Incremental baselines
An incremental provider needs an earlier observation to compare against.
Include a snapshot for the initial state
On the first update, an incremental provider has no earlier observation, so it returns its no-change message—for example, “No new trades”. Include the corresponding snapshot provider if the agent also needs to see the initial state.
After aigora parses a valid decision, the observation used for that decision becomes the new baseline.
This includes a deliberate DoNothing action and an order that the market rejects.
The baseline does not advance after a provider error, timeout, context-window error, or exhausted parse retries.
It also stays unchanged during conversation compaction and when failure_policy: do_nothing turns a failed decision into a no-op.
Trade and cancellation histories persist across periods. For order books and holdings, incremental output describes the net difference between observations. For an agent's own orders, the provider uses recorded fills and cancellations where available; an order disappearing from the book is not, by itself, evidence of either event.
Custom providers
When the built-in providers do not cover the information your experiment needs, you can write your own class with a get_context(context) method.
The method receives a read-only snapshot and must return a string for the agent's update.
Put the class's dotted Python path in type, and aigora will pass YAML params to its constructor as keyword arguments.
By default, the section heading uses the class's full Python path.
You can give the class a context_name attribute to replace that label, or a display_name attribute to set the heading shown to the agent.
Keep research inputs, such as private-value schedules, in params so they are included in the run's recorded configuration.
See Customise what agents 'see' for a complete example and Python API for the immutable observation fields.