Concordia: A Library for Generative Social Simulation
A library for constructing and running generative agent-based models that simulate social interactions.
- Source repo
- google-deepmind/concordia
- Stars
- ★ 1.8k
- Last updated
- 2d ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 39/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Social science researchers simulate group dynamics and social phenomena to test theories.
- Not a fit if
- Developers wanting a turnkey tool with no embedder setup
- Researchers who need fully reproducible simulations
- Source review
- 39/100 · Major gaps 8 safety controls not found
What does this agent do, and when should you use it?
Concordia is a library developed by Google DeepMind for building and running generative agent-based models (ABMs) that simulate interactions among entities in physical, social, or digital environments. Its core innovation is the use of a 'Game Master' (GM) entity that simulates the environment, translating agents' natural language actions into appropriate outcomes. The library offers modular components and pre-built prefabs for agents and game masters, enabling complex behaviors to be assembled from simple reusable parts. Installation is straightforward via pip. The project includes tutorials and Colab notebooks for quick start. Concordia is designed for a range of applications including social science research, AI safety, economics, synthetic data generation, and evaluating real services through simulated usage.
Concordia is a Python library for creating and running generative agent-based simulations. It defines three core concepts: Entities (agents and game masters), Components (modular behavior units), and Engine (the simulation loop). The simulation loop asks entities for actions; agents express their intentions in natural language, and the Game Master uses a language model to translate these into outcomes that respect physical, social, or digital constraints. It requires access to an LLM API and optionally a text embedder for memory. Users can assemble simulations using prefabs and custom components.
- Social science researchers simulate group dynamics and social phenomena to test theories.
- AI safety researchers construct scenarios to evaluate the safety and ethical behavior of AI systems in complex social interactions.
- Economists model market interactions and decision-making processes to study economic models.
- UX teams generate synthetic interaction data for training personalization systems.
- Service providers simulate user behavior to assess the performance of real services.
- Cognitive neuroscientists build agent models inspired by neural processes to study cognition.
How do you install or deploy this agent?
Run pip install gdm-concordia in your terminal. After installation, you can import concordia in your code. Requires Python.
How do you use this agent?
First, ensure you have installed gdm-concordia and have access to an LLM API (optionally specify a text embedder). Then, run the Colab tutorial ([examples/tutorial.ipynb](examples/tutorial.ipynb)) or refer to the examples in the repository. Building a simulation typically involves defining prefabs for agents and game masters, configuring a language model, and running the simulation loop. For detailed guidance, refer to the README and tutorials.
What are this agent's strengths and limitations?
- The Game Master architecture provides an intuitive and powerful way to simulate environments.
- Modular components and prefabs allow for easy customization and reuse.
- Backed by Google DeepMind, with a comprehensive tech report and design pattern paper.
- Colab tutorials and a cheat sheet lower the learning curve.
- Requires an external LLM API, with results dependent on model capability and potential costs.
- Requires providing a text embedder, adding configuration complexity.
- As a research library, documentation is academic-oriented, which may be a barrier for general developers.
- Dependency on LLM stability and responses may affect simulation reproducibility.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Concordia: A Library for Generative Social Simulation This agent | 39 · Major gaps | Library / SDKFree + model costs | ★ 1.8k | 2d ago | Python | — |
| MiroFish Offline | 30 · Major gaps | Self-hosted serviceFree | ★ 2.6k | 6mo ago | Python | OpenAI API · Claude API |
| OASIS Social Simulation | 25 · Major gaps | Library / SDKFree + model costs | ★ 5.3k | 7d ago | Python | OpenAI API |
| AgileRL | 71 · Some gaps | Library / SDKFreemium | ★ 959 | today | Python | — |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows no explicit mechanisms for least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. Therefore all trust criteria score 0.
Self-consistency: README, directory structure, and code organization are consistent with clear module separation, score 2. Dependency availability: requirements.txt and pyproject.toml are provided, but availability not verified, score 2. Failure messages: no documentation of error handling or failure messages, score 1.
Audience and scenarios: README describes multiple application scenarios, score 2. Capability boundaries: states need for LLM API and embedder, score 2. Trigger precision: no explicit trigger conditions, score 1. Environment fit: provides installation and development environment instructions, score 2.
Information architecture: clear directory structure, score 2. Install notes: provides pip and development installation guides, score 2. Naming stability: package and module names consistent, score 2. Examples and FAQ: provides examples and tutorials but no FAQ, score 2. Known limitations: not explicitly listed, score 1. License: Apache-2.0, score 2. Versioning and changelog: no changelog provided, score 1. Maintenance responsibility: has SECURITY.md and CI but no explicit maintainer, score 2.
Output usability: provides examples and tutorials, score 2. Marginal value: unique value as generative social simulation library, score 2. Cost-benefit: no performance or cost analysis, score 1.
Claim traceability: README cites technical report, score 2. Cross-source corroboration: no external verification, score 1. Fact-inference separation: not explicitly distinguished, score 1.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- No security mechanisms such as least privilege or data flow transparency are provided; assess before use.
- Dependency security not verified; check dependency versions and vulnerabilities.
- No changelog provided; version updates may be opaque.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
[2.4.0] - 2026-03-06 Changed - Use InteractiveDocument RNG for diversified answers - NextActingActiveEntity returns the current player for async threads - Make more basic entity parameters configurable and give them more sensible default values. Remove the relevant memories component since it does not really help here, and it can confuse, especially in simulations that don't have a concrete concept of time. - Make LastNObservations component give a more sensible error message if the user passes a wrong type history length. …View on GitHub ↗ -
Release notes excerpt
[2.3.0] - 2026-02-04 Changed - Deleted all deprecated files. - Support overriding the default language model either for agents or game masters in the generic simulation prefab. - tests for event resolution filtering - Replace print() statements with absl.logging - Add analyze-logs skill - Add option on generic simulation.play to produce new style structured logs. No change to default behavior. New log style is off by default (for now). - Improve the new structured logging library and remove functions used only for comparison to the old format. …View on GitHub ↗