gdm-concordia 2.3.1
A library for building a generative model of social interacions.
License: Apache 2.0
Requires Python: >=3.12
Keywords: multi-agent agent-based-simulation generative-agents python machine-learning

# Concordia

*A library for generative social simulation*



[Concordia Tech Report](https://arxiv.org/abs/2312.03664) | [Concordia Design Pattern](https://arxiv.org/abs/2507.08892) | [Code Cheat Sheet](CHEATSHEET.md)

## About

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.

## How it Works

Concordia operates like a **Game Engine** for generative agents.

*   **Entities**: The actors in the simulation. These can be player characters
    (Agents) or system controllers (Game Masters).
*   **Components**: The building blocks of an Entity. Just as a game object
    might have a "coorindates" component, a Concordia agent has components for
    **Memory**, **Observation**, **Planning**, and **Actuation**.
*   **Engine**: The loop that drives the simulation. It asks agents for
    actions and asks the Game Master to resolve them.

This modular architecture allows you to assemble complex behaviors from simple,
reusable parts.

## Folder Structure

*   **[`concordia/prefabs`](concordia/prefabs/README.md)**: Pre-assembled
    recipes for common agents and Game Masters.
*   **[`concordia/components`](concordia/components/README.md)**: Modular
    building blocks for agents, including memory systems, reasoning chains, and
    sensory modules.
*   **[`concordia/environment`](concordia/environment/README.md)**: The "engine"
    of the simulation, containing the Game Master and the turn-taking loop.
*   **[`concordia/thought_chains`](concordia/thought_chains/README.md)**: Logic
    for internal reasoning steps (e.g., Chain of Thought).
*   **[`concordia/document`](concordia/document/README.md)**: Utilities for
    managing LLM prompts and context.
*   **[`concordia/language_model`](concordia/language_model/README.md)**: LLM
    integration and API wrappers.
*   **[`examples/`](examples/)**: Tutorials and example simulations to help you
    get started.

> [!TIP]
> The best way to learn is to watch the [Concordia: Building Generative Agent-Based Models](https://youtu.be/2FO5g65mu2I?si=TSk7XTk4gCaadEDs) tutorial on YouTube, run the
> **[`examples/tutorial.ipynb`](examples/tutorial.ipynb)** and then try
> modifying the **Prefabs** to see how agent behavior changes.

## Installation

[Concordia is available on PyPI](https://pypi.python.org/pypi/gdm-concordia)
and can be installed using:

```shell
pip install gdm-concordia
```

After doing this you can then `import concordia` in your own code.

## Development

### Codespace

The easiest way to work on the Concordia source code, is to use our
pre-configured development environment via a
[Github CodeSpace](https://github.com/features/codespaces).

This provides a tested development workflow that allows for reproducible builds,
and minimizes dependency management. We strongly advise preparing all Pull
Requests for Concordia via this workflow.

### Manual setup

If you want to work on the Concordia source code within your own development
environment you will have to handle installation and dependency management
yourself.

For example, you can perform an editable installation as follows:

1.  Clone Concordia:

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

2.  Create and activate a virtual environment:

    ```shell
    python -m venv venv
    source venv/bin/activate
    ```

3.  Install Concordia:

    ```shell
    pip install --editable .[dev]
    ```

4.  Test the installation:

    ```shell
    pytest --pyargs concordia
    ```

5.  Install any additional language model dependencies you will need, e.g.:

    ```shell
    pip install .[google]
    pip install --requirement=examples/requirements.in
    ```

    Note that at this stage you may find that your development environment is
    not supported by some underlying dependencies and you will need to do some
    dependency management.

## Bring your own LLM

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.

## Example usage

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:

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.sandbox.google.com/github/google-deepmind/concordia/blob/main/examples/tutorial.ipynb)

## Citing Concordia

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

<!-- disableFinding(SNIPPET_INVALID_LANGUAGE) -->
```bibtex
@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}
}
```

## Disclaimer

This is not an officially supported Google product.