A library for generative social simulation

Concordia Tech Report

Concordia is a library to facilitate construction and use of generative agent-based models to simulate interactions of agents in grounded physical, social, or digital space. It makes it easy and flexible to define environments using an interaction pattern borrowed from tabletop role-playing games in which a special agent called the Game Master (GM) is responsible for simulating the environment where player agents interact (like a narrator in an interactive story). Agents take actions by describing what they want to do in natural language. The GM then translates their actions into appropriate implementations. In a simulated physical world, the GM would check the physical plausibility of agent actions and describe their effects. In digital environments that simulate technologies such as apps and services, the GM may, based on agent input, handle necessary API calls to integrate with external tools.

Concordia supports a wide array of applications, ranging from social science research and AI ethics to cognitive neuroscience and economics; Additionally, it also can be leveraged for generating data for personalization applications and for conducting performance evaluations of real services through simulated usage.

Concordia requires access to a standard LLM API, and optionally may also integrate with real applications and services.

Concordia is available on PyPI and can be installed using:

pip install gdm-concordia

If you want to work on the Concordia source code, you can perform an editable installation as follows:

1. Clone Concordia:

   git clone -b main https://github.com/google-deepmind/concordia
   cd concordia

2. Install Concordia:

   pip install --editable .[dev]

3. (Optional) Test the installation:

   pytest --pyargs concordia

This project includes a pre-configured development environment (devcontainer).

You can launch a working development environment with one click, using e.g. Github Codespaces or the VSCode Containers extension.

Concordia requires a access to an LLM API. Any LLM API that supports sampling text should work. The quality of the results you get depends on which LLM you select. Some are better at role-playing than others. You must also provide a text embedder for the associative memory. Any fixed-dimensional embedding works for this. Ideally it would be one that works well for sentence similarity or semantic search.

Find below an illustrative social simulation where 4 friends are stuck in a snowed in pub. Two of them have a dispute over a crashed car.

The agents are built using a simple reasoning inspired by March and Olsen (2011) who posit that humans generally act as though they choose their actions by answering three key questions:

1. What kind of situation is this?
2. What kind of person am I?
3. What does a person such as I do in a situation such as this?

The agents used in the following example implement exactly these questions:

This repository includes an evolutionary simulation framework that models the evolution of cooperation and selfishness in public goods games. The simulation demonstrates how agent strategies evolve over multiple generations through selection, mutation, and environmental pressures.

• 🧬 Evolutionary Algorithms: Population-based evolution with configurable selection methods (top-k, probabilistic)
• 🎮 Public Goods Game: Agents choose between cooperative and selfish strategies in multi-round games
• 📊 Comprehensive Measurements: Detailed tracking of population dynamics, fitness statistics, and convergence metrics
• 🔄 Checkpointing System: Save and resume simulations from any generation
• 🧪 Modular Architecture: Type-safe design with separated concerns (typing, checkpointing, algorithms)

The evolutionary simulation framework uses the EvolutionConfig dataclass to configure all aspects of the simulation. Parameters are organized into several categories:

• pop_size (default: 4): Number of agents in the population. Larger populations provide more diversity but increase computational cost.
• num_generations (default: 10): Number of evolutionary cycles to run. Each generation includes selection, reproduction, and mutation phases.
• selection_method (default: 'topk'): Method for selecting surviving agents:
  • 'topk': Select the top-performing agents based on fitness scores
  • 'probabilistic': Select agents probabilistically based on fitness (higher fitness = higher selection probability)
• top_k (default: 2): Number of survivors when using top-k selection. Must be ≤ pop_size.
• mutation_rate (default: 0.2): Probability that an agent's strategy will mutate during reproduction (0.0 = no mutation, 1.0 = always mutate).

• num_rounds (default: 10): Number of rounds in each public goods game. More rounds provide more opportunities for strategy expression but increase simulation time.

• api_type (default: 'pytorch_gemma'): Type of language model API to use:

  • 'pytorch_gemma': Local Gemma models via PyTorch/Transformers
  • 'openai': OpenAI GPT models via API
  • 'mistral': Mistral AI models via API
  • 'amazon_bedrock': AWS Bedrock models (Claude, Llama, etc.)
  • 'google_aistudio_model': Google AI Studio models (Gemini)

• model_name (default: 'google/gemma-2b-it'): Specific model to use. Examples:

  • Gemma: 'google/gemma-2b-it', 'google/gemma-7b-it'
  • OpenAI: 'gpt-4o', 'gpt-4o-mini', 'gpt-3.5-turbo'
  • Mistral: 'mistral-large-latest', 'mistral-medium'

• embedder_name (default: 'all-mpnet-base-v2'): Sentence transformer model for generating text embeddings used in agent memory systems.

• device (default: 'cpu'): Computing device for local models:

  • 'cpu': CPU processing (slowest but universal)
  • 'cuda:0': NVIDIA GPU acceleration (fastest for compatible hardware)
  • 'mps': Mac GPU acceleration via Metal Performance Shaders

• api_key (default: None): API key for cloud-based language models. Can also be set via environment variables (e.g., OPENAI_API_KEY).

• disable_language_model (default: False): If True, uses a dummy language model that generates random responses. Useful for:

  • Testing simulation logic without LLM dependencies
  • Debugging evolutionary algorithms
  • Fast prototyping and development

Agents in the simulation can adopt one of two fundamental strategies:

• Strategy.COOPERATIVE: "Maximize group reward in the public goods game" - agents contribute to the common pool
• Strategy.SELFISH: "Maximize personal reward in the public goods game" - agents free-ride on others' contributions

Minimal Test Configuration:

config = EvolutionConfig(
    pop_size=2,
    num_generations=2,
    num_rounds=2,
    disable_language_model=True  # Fast testing
)

Research Configuration:

config = EvolutionConfig(
    pop_size=8,
    num_generations=50,
    selection_method='probabilistic',
    top_k=4,
    mutation_rate=0.15,
    num_rounds=20,
    api_type='pytorch_gemma',
    model_name='google/gemma-7b-it',
    device='cuda:0'
)

Production Configuration:

config = EvolutionConfig(
    pop_size=12,
    num_generations=100,
    selection_method='topk',
    top_k=6,
    mutation_rate=0.1,
    num_rounds=25,
    api_type='openai',
    model_name='gpt-4o',
    api_key=os.getenv('OPENAI_API_KEY')
)

The framework automatically validates parameter combinations and provides informative error messages for invalid configurations.

The evolutionary simulation is located in examples/evolutionary_simulation.py and supports multiple language model backends.

Run with no dependencies - uses a dummy language model for testing:

python examples/evolutionary_simulation.py

The simulation supports real language models for more sophisticated agent reasoning:

Setup virtual environment (recommended):

python -m venv evolutionary_env
source evolutionary_env/bin/activate  # On Windows: evolutionary_env\Scripts\activate
pip install sentence-transformers torch

Using Gemma (Local PyTorch Model):

from examples.evolutionary_simulation import evolutionary_main, GEMMA_CONFIG

# This will download google/gemma-2b-it model locally
measurements = evolutionary_main(config=GEMMA_CONFIG)

Using OpenAI GPT Models:

import os
from examples.evolutionary_simulation import evolutionary_main, OPENAI_CONFIG

# Set your OpenAI API key
os.environ['OPENAI_API_KEY'] = 'your-api-key-here'
openai_config = OPENAI_CONFIG
openai_config.api_key = os.getenv('OPENAI_API_KEY')

measurements = evolutionary_main(config=openai_config)

Custom Language Model Configuration:

from examples.evolutionary_simulation import evolutionary_main
from concordia.typing.evolutionary import EvolutionConfig

config = EvolutionConfig(
    # Evolutionary parameters
    pop_size=8,
    num_generations=20,
    selection_method='topk',
    top_k=4,
    mutation_rate=0.1,
    num_rounds=15,
    
    # Language model configuration
    api_type='pytorch_gemma',        # or 'openai', 'mistral', etc.
    model_name='google/gemma-7b-it', # Larger model for better reasoning
    embedder_name='all-mpnet-base-v2',
    device='cuda:0',                 # Use GPU if available
    disable_language_model=False
)

measurements = evolutionary_main(config)

from pathlib import Path

measurements = evolutionary_main(
    config=config,
    checkpoint_dir=Path("evolutionary_checkpoints/"),
    checkpoint_interval=5,           # Save every 5 generations
    resume_from_checkpoint=True      # Resume from latest if available
)

For local models (Gemma, Llama):

pip install torch transformers sentence-transformers

For OpenAI models:

pip install openai sentence-transformers
export OPENAI_API_KEY="your-api-key"

For Google AI Studio:

pip install google-generativeai sentence-transformers
export GOOGLE_AI_STUDIO_API_KEY="your-api-key"

• Dummy Model: Fastest, no LLM dependencies, good for testing algorithms
• Local Models: Slower startup (model download), but no API costs
• Cloud APIs: Fast startup, but incur API costs per generation

Recommended configurations:

• Development/Testing: Use dummy model (disable_language_model=True)
• Research: Use Gemma 2B for balanced performance and quality
• Production: Use GPT-4o or Gemma 7B for highest quality reasoning

The repository includes automated daily synchronization with the upstream Concordia repository and continuous testing of the evolutionary simulation. See UPSTREAM_SYNC.md for details.

This evolutionary simulation framework can be used for:

• Social Science Research: Studying cooperation evolution in social dilemmas
• Game Theory: Analyzing strategy emergence in multi-agent environments
• AI Ethics: Understanding emergent behaviors in agent populations
• Educational Purposes: Demonstrating evolutionary principles in computational settings

If you use Concordia in your work, please cite the accompanying article:

@article{vezhnevets2023generative,
  title={Generative agent-based modeling with actions grounded in physical,
  social, or digital space using Concordia},
  author={Vezhnevets, Alexander Sasha and Agapiou, John P and Aharon, Avia and
  Ziv, Ron and Matyas, Jayd and Du{\'e}{\~n}ez-Guzm{\'a}n, Edgar A and
  Cunningham, William A and Osindero, Simon and Karmon, Danny and
  Leibo, Joel Z},
  journal={arXiv preprint arXiv:2312.03664},
  year={2023}
}

This is not an officially supported Google product.