Welcome to econagents's documentation!

econagents

econagents is a Python library that lets you use LLM agents in economic experiments. The framework connects agents to game servers, projects server events into typed game state, asks role-specific LLM policies for actions, and sends those actions back through protocol adapters.

Key Features

Agent Runtime: Run one explicit Agent per simulated player.
Ports and Adapters: Swap protocol codecs, transports, prompt renderers, response parsers, and state projectors.
Flexible Agent Customization: Customize behavior with Jinja templates, response schemas, personas, or custom Python phase handlers.
Event-Driven State Management: Project server events into typed public, private, and meta state.
Turn-Based and Continuous Action Support: Handle one-shot phase decisions and repeated continuous-phase actions.

Installation

# Install from PyPI
pip install econagents

# Or install directly from GitHub
pip install git+https://github.com/IBEX-TUDelft/econagents.git

Framework Components

econagents consists of these main components:

Domain Types: Event, Action, PhaseId, and AgentContext.
Ports: Interfaces for codecs, transports, prompt rendering, response parsing, and state projection.
Adapters: IBEX envelopes, WebSocket transport, Jinja prompts, JSON response parsing, and EventField state projection.
Roles: Role-specific LLM policies and phase participation rules.
Agents: One runtime per simulated player.
Game Runner: Supervises agents, logging, timeout, and cleanup.

Example Experiments

The repository includes four example games:

prisoner: An iterated Prisoner's Dilemma game with 5 rounds and 2 LLM agents, runs on a local python server (included).
dictator: A modified Dictator game with 2 LLM agents that runs on a local python server (included).
public_goods: A public goods game with 4 players that runs on a local python server (included).
continuous_double_auction: A classical continuous double auction with LLM-backed traders using a continuous market phase.

Running the Prisoner's Dilemma game

The simplest game to run is a version of the repeated prisoner's dilemma game that runs on your local machine.

# Run the server
uv run python examples/prisoner/server/server.py

# Run the experiment (in a separate terminal)
uv run python examples/prisoner/run_game.py

Note: set OPENAI_API_KEY before running OpenAI-backed examples.

Documentation

For detailed guides and API reference, visit the documentation.

You should also check out the econagents cookbook for more examples.

Contents: