Concordia gives every LLM agent a Game Master to answer to

The Game Master is the whole idea

Concordia takes its interaction pattern from tabletop role-playing games. A special entity called the Game Master simulates the environment, and player entities interact inside it. Players describe what they intend to do in natural language, and the Game Master translates those intentions into outcomes, including checking physical plausibility in simulated worlds.

That single mechanism replaces a large amount of hand-written logic in conventional agent-based models. A conventional model encodes rules; here the rules are a natural language description plus a model that applies them. The trade-off is the mirror image: the environment is only as consistent as the model interpreting it, and it can change between runs.

The README lists the intended applications as social science research, AI safety and ethics, cognitive neuroscience, economics, synthetic data generation for personalisation, and performance evaluation of real services through simulated usage. That last one is the most unusual: agents talking to your actual system as load or as users.

Concordia requires access to a standard LLM API and may optionally integrate with external applications and services, so the simulations are not hermetic by default.

Entities, components and prefabs, with roles assigned per run

The object model has three layers. An entity contains components that supply behaviour and state, such as instructions, memory and action selection. A prefab is a prebuilt entity template you instantiate, after which you override parameters like the entity's name, instructions or goal, and a standard factory constructs the components from those settings.

The engine organises execution. On each run_loop call, entities are assigned either player or game master roles, and the engine then requests actions from player entities and asks game master entities to supply observations and resolve those actions.

The detail worth internalising is that those are roles in that call, not intrinsic entity classes. An entity is not permanently a player or permanently a Game Master, which means a simulation can change who is running the world partway through, and it means your entity definitions stay independent of the scenario you are running them in.

Six package directories and a documentation site per area

The folder structure maps to the concepts, which makes it easy to find the layer you need to change.

concordia/prefabs holds pre-assembled starting configurations for entities and their components. concordia/components holds the modular building blocks, explicitly including memory systems and sensory modules. concordia/environment contains the engine interfaces that determine turn-taking, simultaneous action or asynchronous action, which is the setting where your choice of execution model lives.

concordia/document manages LLM prompts and context, and concordia/language_model holds the LLM integration and API wrappers. That split is the practical one: if you need to change how a prompt is assembled, you are in document/, not in your entity code.

examples/ holds tutorials and example simulations, and the names describe the range: a resource_dilemma, marketplace.ipynb, selling_cookies.ipynb, signaling, social_media, games, an interrupt_driven example, a conversation_with_ai_companion directory, questionnaire_example.ipynb, mcp_tool_use_example.ipynb and concordia_island. The questionnaire and market examples are the ones to read first if you want to see structure rather than narrative.

Install from PyPI, or set up the source the way the project recommends

The published install is one command, and the package name on PyPI differs from the repository name:

pip install gdm-concordia

After that you can import concordia in your own code. setup.py records the version as 2.4.0, the author as DeepMind and the license as Apache 2.0.

For development the project recommends a pre-configured GitHub Codespace over a manual environment, and says pull requests should be prepared that way. The manual path is a clone, a virtual environment, an editable install and a test run:

git clone -b main https://github.com/google-deepmind/concordia
cd concordia
python -m venv venv
source venv/bin/activate
pip install --editable .[dev]
pytest --pyargs concordia

Language model dependencies come separately, with pip install .[google] as the documented example, followed by pip install --requirement=examples/requirements.in. The README warns at this point that your environment may not be supported by some underlying dependencies.

Tests run through pytest with pytest-xdist and -n auto across the concordia and examples test paths, so the example notebooks are part of the test surface rather than decorative.

Bring your own LLM and your own embedder

Concordia requires access to an LLM API, and the requirement is stated loosely on purpose: any API that can sample text should work, with the caveat that result quality depends on the capabilities of the chosen model.

That is the honest framing. A simulation run is a conversation with a model, and a model that reasons poorly about a dispute between two agents produces a dull simulation. Choosing the model is part of the experimental design here, not a deployment detail.

There is a second requirement that is easy to miss. You must also provide a text embedder for associative memory, and any fixed-dimensional embedding will do, ideally one suited to sentence similarity or semantic search. Associative memory is how an agent recalls related prior events, so the embedder is not optional decoration; a poor embedder produces an agent that forgets in a way that has nothing to do with the scenario.

The cost structure follows from this. Every run_loop asks player entities for actions and Game Master entities for observations, so both sides consume tokens. A long simulation with many entities is expensive, and running it repeatedly for statistics multiplies that. The README does not document cost control, which makes your own budgeting necessary.

The tutorial, the citations and where this is still beta

Two tutorials are offered. One focuses on the GUI editor and command line interface, hosted at concordia-tutorial.pages.dev, and the entity-component guide in concordia/command_line_interface/README.md is the documented starting point for inspecting components, editing a simulation and watching it behave. The other is a lecture on YouTube that works with examples/tutorial.ipynb, which also opens in Colab.

The example scenario the README describes is four friends stuck in a snowed-in pub, two of them disputing a crashed car. The agents are built on reasoning attributed to March and Olsen (2011), who posit that people act as though they choose actions by answering three questions: what kind of situation is this, what kind of person am I, and what does a person such as I do in a situation such as this. The example implements exactly those three as components, which is a clean way to see how a behavioural theory maps onto prefabs.

The project asks you to cite the accompanying article, and CITATION.bib at the repository root holds the BibTeX, alongside a tech report and a design pattern paper on arXiv.

setup.py classifies the package as Development Status:: 4 - Beta, and the release history shows v2.4.0 on 2026-03-06 after v2.3.1 and v2.3.0 in February 2026. The repository is not archived and the last push was on 2026-10-16, so work continues past the newest release.

Editorial conclusion

Adopt Concordia if you need LLM-driven social simulation with a documented interaction protocol and can budget the API cost of both player and Game Master calls, and start from examples/tutorial.ipynb. Do not adopt it expecting deterministic agent-based modelling or a benchmark score, since result quality depends on the model you supply and the README says so directly. Before running anything, choose both a sampling LLM API and a text embedder, since associative memory needs one, and pin a release such as v2.4.0 since the classifier still says Development Status :: 4 - Beta.

Frequently asked questions

Official sources

1. google-deepmind/concordia on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases