{"id":13572092,"url":"https://github.com/google-deepmind/concordia","last_synced_at":"2026-02-04T21:02:50.898Z","repository":{"id":211278468,"uuid":"721643027","full_name":"google-deepmind/concordia","owner":"google-deepmind","description":"A library for generative social simulation","archived":false,"fork":false,"pushed_at":"2025-06-10T13:54:53.000Z","size":3424,"stargazers_count":899,"open_issues_count":12,"forks_count":195,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-06-10T15:28:10.268Z","etag":null,"topics":["agent-based-simulation","generative-agents","multi-agent","social-simulation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google-deepmind.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.bib","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-11-21T13:34:11.000Z","updated_at":"2025-06-10T14:04:23.000Z","dependencies_parsed_at":"2023-12-11T14:33:08.452Z","dependency_job_id":"7324f9fd-f3b5-465f-8b68-390c5ecf721b","html_url":"https://github.com/google-deepmind/concordia","commit_stats":null,"previous_names":["google-deepmind/concordia"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/google-deepmind/concordia","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fconcordia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fconcordia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fconcordia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fconcordia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google-deepmind","download_url":"https://codeload.github.com/google-deepmind/concordia/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google-deepmind%2Fconcordia/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260268635,"owners_count":22983601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-based-simulation","generative-agents","multi-agent","social-simulation"],"created_at":"2024-08-01T14:01:13.061Z","updated_at":"2026-02-04T21:02:50.892Z","avatar_url":"https://github.com/google-deepmind.png","language":"Python","funding_links":[],"categories":["Python","Simulation, Forecasting and Macro Modeling","Agentic Frameworks","Datasets and Environments"],"sub_categories":["Agent-Based Models and LLM Simulation"],"readme":"# Concordia\n\n*A library for generative social simulation*\n\n\u003c!-- GITHUB --\u003e\n\u003c!-- disableFinding(LINK_RELATIVE_G3DOC) --\u003e\n[![Python](https://img.shields.io/pypi/pyversions/gdm-concordia.svg)](https://pypi.python.org/pypi/gdm-concordia)\n[![PyPI version](https://img.shields.io/pypi/v/gdm-concordia.svg)](https://pypi.python.org/pypi/gdm-concordia)\n[![PyPI tests](../../actions/workflows/pypi-test.yml/badge.svg)](../../actions/workflows/pypi-test.yml)\n[![Tests](../../actions/workflows/test-concordia.yml/badge.svg)](../../actions/workflows/test-concordia.yml)\n[![Examples](../../actions/workflows/test-examples.yml/badge.svg)](../../actions/workflows/test-examples.yml)\n\u003c!-- /GITHUB --\u003e\n\n[Concordia Tech Report](https://arxiv.org/abs/2312.03664) | [Concordia Design Pattern](https://arxiv.org/abs/2507.08892) | [Code Cheat Sheet](CHEATSHEET.md)\n\n## About\n\nConcordia is a library to facilitate construction and use of generative\nagent-based models to simulate interactions of agents in grounded physical,\nsocial, or digital space. It makes it easy and flexible to define environments\nusing an interaction pattern borrowed from tabletop role-playing games in which\na special agent called the Game Master (GM) is responsible for simulating the\nenvironment where player agents interact (like a narrator in an interactive\nstory). Agents take actions by describing what they want to do in natural\nlanguage. The GM then translates their actions into appropriate implementations.\nIn a simulated physical world, the GM would check the physical plausibility of\nagent actions and describe their effects. In digital environments that simulate\ntechnologies such as apps and services, the GM may, based on agent input, handle\nnecessary API calls to integrate with external tools.\n\nConcordia supports a wide array of applications, ranging from social science\nresearch and AI ethics to cognitive neuroscience and economics; Additionally,\nit also can be leveraged for generating data for personalization applications\nand for conducting performance evaluations of real services through simulated\nusage.\n\nConcordia requires access to a standard LLM API, and optionally may also\nintegrate with real applications and services.\n\n## How it Works\n\nConcordia operates like a **Game Engine** for generative agents.\n\n*   **Entities**: The actors in the simulation. These can be player characters\n    (Agents) or system controllers (Game Masters).\n*   **Components**: The building blocks of an Entity. Just as a game object\n    might have a \"coorindates\" component, a Concordia agent has components for\n    **Memory**, **Observation**, **Planning**, and **Actuation**.\n*   **Engine**: The loop that drives the simulation. It asks agents for\n    actions and asks the Game Master to resolve them.\n\nThis modular architecture allows you to assemble complex behaviors from simple,\nreusable parts.\n\n## Folder Structure\n\n*   **[`concordia/prefabs`](concordia/prefabs/README.md)**: Pre-assembled\n    recipes for common agents and Game Masters.\n*   **[`concordia/components`](concordia/components/README.md)**: Modular\n    building blocks for agents, including memory systems, reasoning chains, and\n    sensory modules.\n*   **[`concordia/environment`](concordia/environment/README.md)**: The \"engine\"\n    of the simulation, containing the Game Master and the turn-taking loop.\n*   **[`concordia/thought_chains`](concordia/thought_chains/README.md)**: Logic\n    for internal reasoning steps (e.g., Chain of Thought).\n*   **[`concordia/document`](concordia/document/README.md)**: Utilities for\n    managing LLM prompts and context.\n*   **[`concordia/language_model`](concordia/language_model/README.md)**: LLM\n    integration and API wrappers.\n*   **[`examples/`](examples/)**: Tutorials and example simulations to help you\n    get started.\n\n\u003e [!TIP]\n\u003e 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\n\u003e **[`examples/tutorial.ipynb`](examples/tutorial.ipynb)** and then try\n\u003e modifying the **Prefabs** to see how agent behavior changes.\n\n## Installation\n\n[Concordia is available on PyPI](https://pypi.python.org/pypi/gdm-concordia)\nand can be installed using:\n\n```shell\npip install gdm-concordia\n```\n\nAfter doing this you can then `import concordia` in your own code.\n\n## Development\n\n### Codespace\n\nThe easiest way to work on the Concordia source code, is to use our\npre-configured development environment via a\n[Github CodeSpace](https://github.com/features/codespaces).\n\nThis provides a tested development workflow that allows for reproducible builds,\nand minimizes dependency management. We strongly advise preparing all Pull\nRequests for Concordia via this workflow.\n\n### Manual setup\n\nIf you want to work on the Concordia source code within your own development\nenvironment you will have to handle installation and dependency management\nyourself.\n\nFor example, you can perform an editable installation as follows:\n\n1.  Clone Concordia:\n\n    ```shell\n    git clone -b main https://github.com/google-deepmind/concordia\n    cd concordia\n    ```\n\n2.  Create and activate a virtual environment:\n\n    ```shell\n    python -m venv venv\n    source venv/bin/activate\n    ```\n\n3.  Install Concordia:\n\n    ```shell\n    pip install --editable .[dev]\n    ```\n\n4.  Test the installation:\n\n    ```shell\n    pytest --pyargs concordia\n    ```\n\n5.  Install any additional language model dependencies you will need, e.g.:\n\n    ```shell\n    pip install .[google]\n    pip install --requirement=examples/requirements.in\n    ```\n\n    Note that at this stage you may find that your development environment is\n    not supported by some underlying dependencies and you will need to do some\n    dependency management.\n\n## Bring your own LLM\n\nConcordia requires a access to an LLM API. Any LLM API that supports sampling\ntext should work. The quality of the results you get depends on which LLM you\nselect. Some are better at role-playing than others. You must also provide a\ntext embedder for the associative memory. Any fixed-dimensional embedding works\nfor this. Ideally it would be one that works well for sentence similarity or\nsemantic search.\n\n## Example usage\n\nFind below an illustrative social simulation where 4 friends are stuck in a\nsnowed in pub. Two of them have a dispute over a crashed car.\n\nThe agents are built using a simple reasoning inspired by March and Olsen (2011)\nwho posit that humans generally act as though they choose their actions by\nanswering three key questions:\n\n1. What kind of situation is this?\n2. What kind of person am I?\n3. What does a person such as I do in a situation such as this?\n\nThe agents used in the following example implement exactly these questions:\n\n[![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)\n\n## Citing Concordia\n\nIf you use Concordia in your work, please cite the accompanying article:\n\n\u003c!-- disableFinding(SNIPPET_INVALID_LANGUAGE) --\u003e\n```bibtex\n@article{vezhnevets2023generative,\n  title={Generative agent-based modeling with actions grounded in physical,\n  social, or digital space using Concordia},\n  author={Vezhnevets, Alexander Sasha and Agapiou, John P and Aharon, Avia and\n  Ziv, Ron and Matyas, Jayd and Du{\\'e}{\\~n}ez-Guzm{\\'a}n, Edgar A and\n  Cunningham, William A and Osindero, Simon and Karmon, Danny and\n  Leibo, Joel Z},\n  journal={arXiv preprint arXiv:2312.03664},\n  year={2023}\n}\n```\n\n## Disclaimer\n\nThis is not an officially supported Google product.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fconcordia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle-deepmind%2Fconcordia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle-deepmind%2Fconcordia/lists"}