必须自备 LLM API 和文本嵌入模型,库本身不含模型;开发模式需 Python 3.12 或更新版本;部分底层依赖可能与本地环境不兼容,需自行处理依赖
concordia
google-deepmindApache-2.0活跃维护基于生成式智能体的社会模拟库,能搭建多智能体虚拟社会,观察角色互动与群体行为,适合研究社会现象和测试协作策略。
A library for generative social simulation
pip install gdm-concordiaREADME 未说明显存或 GPU 要求;需可访问标准 LLM API,并额外提供文本嵌入模型用于联想记忆
用 LLM 驱动的生成式智能体社会模拟库,让实体在物理、社会或数字环境中交互
基于生成式智能体的社会模拟库,能搭建多智能体虚拟社会,观察角色互动与群体行为,适合研究社会现象和测试协作策略。
核心能力
- 用 Game Master 实体模拟环境并裁决玩家动作
- 实体由组件拼装,Prefab 模板可覆盖名称与目标
- 引擎按 run_loop 分配玩家与 GM 角色组织回合
- 内置记忆系统、感知模块与提示词管理工具
- 提供 GUI 与 CLI 编辑器和示例教程
容易踩的坑
- v2.4.0最新正式版2026-03-06 · 2026-03-06 19:05 UTC
[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.
- Add name of the current active game master to StepData so we can visualize it in the UI.
- Wrap entity_agent
actandobservecalls in try...except blocks in order to surface more helpful error messages during async usage. - Refactor to push "thought chains" concept down into the event_resolution component since it's not a general Concordia concept but rather an implementation detail of a specific component.
- Small tweaks to social media example scenario 1 and the contrib forum component to get it to produce more interesting memes.
- Improve image_text_act component and pass more params through basic_with_image prefab.
- Avoid printing long bytes representations of images.
- Migrated deprecated google.generativeai and vertexai package to the newer google.genai package
- Add deprecation warning on entity_agent.stateless_act, use act instead.
- generic simulation now saves more info in checkpoints
Added
- Entities can now be passed a custom Measurements object.
- Support images in the generic log viewer html.
- Add log analysis CLI
- Add gpt_model_multimodal.py and rename gemini_model_vision.py to gemini_model_multimodal.py
- Add social media example with image generation.
- Add a text+image generation act component and a prefab that uses it.
- Add dynamic state editing in the visual interface and additional visualization improvements:
- Add async_social_media prefab and its associated forum component to facilitate social media simulations. These parts work well with the asynchronous engine. The forum component is thread safe.
- Add simulation server for play/pause user interface visualization
- Add support for logs produced by the asynchronous engine to the generic log viewer.
- Add asynchronous engine
- Improve logging, AIAgentLogInterface, and the documentation for how to use them.
- Add functionality to allow an interactive GUI view of a running simulation. Augment the engine API to allow passing a step_controller to start, pause, and step the simulation from the UI and a step_callback to control what information is passed to the UI on each step.
- Add tool-use capabilities to InteractiveDocument
- Improve analyze-logs agent skill for use with antigravity, claude code, etc
- Improve the structured logging library and extract out its HTML writing function to a different file.
- Update generic simulation to improve data stored in checkpoints and to pass args needed to allow the visual UI.
Fixed
- Fix logging for async engine by introducing ReactiveMeasurements.
- Fixing scene serialisation error that was crashing jobs after restoration from a checkpoint.
- Fix broken HTML log rendering due to broken regex in structured_logging_html.py. The regex patterns for matching content_ref and image markdown in the JavaScript rendering code used new RegExp('...') with Python string interpolation, which required backslashes to survive three parsing layers (Python string → JS string → RegExp). The escaping was wrong, producing Unmatched ')' SyntaxError that crashed renderGMLog() before any content was injected into the DOM, resulting in empty simulation HTML logs.
- Fix deduplication for large images in structured_logging.
- Add gemini_model_vision.py, a model wrapper with image generation and image interpretation functionality.
- Added optional event_filter_fn to DisplayEvents component. Can use this for entity-aware filtering of events (e.g.
- v2.3.12026-02-04 · 2026-02-04 19:16 UTC
查看更新说明
[2.3.1] - 2026-02-04
Fixed
- Remove a flaky profiler test.
- v2.3.02026-02-04 · 2026-02-04 18:58 UTC
查看更新说明
[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.
- Update default constants suggesting action spec formats to suggest the json approach
- Improve observation queue handling and add scene-aware event delivery.
- Add allow_duplicates option to AssociativeMemoryBank Fixes a bug where identical actions across rounds were incorrectly deduplicated, causing EventResolution to pick up stale data. - Add allow_duplicates constructor parameter to AssociativeMemoryBank - Enable allow_duplicates for game_master memory_bank in generic.py
- Copybara import of the project:
- Fixing the search for the last event generated by the player
- Remove the
concordia/prefabs/configuratordirectory. - Correct several lingering references to deprecated types.
- Add physically situated and dramaturgic game master prefab. This prefab is similar to the situated_in_time_and_place prefab, but with scenes added in.
- add support for extra_components in dialogic_and_dramaturgic game master.
- Changed action spec parsing to json for more robustness than string matching
Added
- Add support for deepseek in the together_ai llm wrapper and fix its gemma support.
- README.md for thought_chains
- README.md for the environment
- typing README
- adding a README.md to the components folder, which documents the use of components
- documentation for the interactive_document
- Add PuppetActComponent and Puppet entity prefab.
- Add a rational actor entity
- Create SceneBasedTerminator and update GameMaster prefabs.
- README for language_model
- README for prefabs
- add structured logging
Fixed
- Add dramaturgic formative memories initializer to prevent bug in which the premise of the first scene was not delivered.
- Fix event resolution to correctly filter putative events by active player and add test for puppet_act
- fixing scene based termination
- v2.2.02026-01-12 · 2026-01-12 13:09 UTC
查看更新说明
[2.2.0] - 2026-01-12
Changed
- Allowing commas in the options of the multiple-choice action_spec by using ","
- move prefix_entity_name to config parameters
- refactor questionnaire components logging
- Update README.md with concordia.contrib.language_models changes
- Replace unmaintained
retrydependency withtenacity - Remove dependency on typing_extensions
- Move language models to concordia.contrib.language_models
- Require Python >= 3.12
- For simultaneous engine, skip entity.observe if make observation emits an empty observation
- Skip entity.observe if make observation emits an empty observation
- Improve typing of OutputType
- Improved formatting of multiple-choice questionnaire observations
- Add absl logging in the questionnaire simulation and engine
- More explicitly check questionnaire type. Raise error if type not found.
- Change GPT model verbosity to 'medium' for GPT-4o, since 'low' is apparently no longer allowed for it. Otherwise use the specified verbosity.
- Remove top_p from gpt models (deprecated from GPT-5)
- improve base questionnaire default aggregate robustness
- Fix ollama client temperature, top_p and top_k args
- add top_p and top_k parameters to clients to fix build errors
- Update default sampling temperature from 0.5 to 1.0
- Expose temperature, add top_p and top_k args
- Raise error when preloading memories fails
- Update switch_act default for invalid float response to match concat_act
- Return 'nan' instead of '0.0' on float conversion error for float_action_spec in ConcatActComponent
- small changes to prompts in the conversational entity prefab.
- prevent YOLO termination during formative memories init GM and optionally prevent the same thing in the dialogic GM (default behavior remains unchanged). Also update dialog example to set the conversation GM to avoid stopping in this way. Note: the reason for this change is just that we noticed some language models are more prone to deciding they want to terminate in YOLO mode than others. This lets the user have finer control in such cases.
- Correct name for Depression Anxiety Stress Scale questionnaire
- move FormativeMemoriesInitializer to its own py file for clarity
Added
- Add HuggingFace language model wrapper
- Add DayInTheLifeInitializer component that generates "day in the life" observations for two agents to set up a conversation scenario. It generates personal daily events for each agent and a shared event to bring them together.
- add
get_context_concat_orderfunction on ConcatAct and SwitchAct - Add dimension ranges abstract method to questionnaires
- Add CombinedPerception component
- Add README to language_models page encouraging users to add language model wrappers for additional models and APIs, and to help maintain them. This README also explains how to implement the two necessary functions on each language model wrapper.
- adding context argument in questionnaires
- Questionnaire component
- Generalize the together_ai language model wrapper to allow more models.
Fixed
- Fix bugs in contrib.language_models
- Fixes bug where ActionSpec choice options containing commas were incorrectly split by the parser. Replaced with |
- v2.1.02025-08-18 · 2025-08-18 21:15 UTC
查看更新说明
[2.1.0] - 2025-08-18
Changed
- Set randomize choices to false in questionnaires
- Added configurable number of sentences per episode in formative memory generators
- added exponential backoff in retry wrapper
- Increase DEFAULT_MAX_TOKENS.
- Adding fixed acting order to dialogic GM
- Move configurable component preact values above recent observations in question_of_recent_memories prompt so the former can contextualize the latter e.g. this is the sensible ordering if you pass instructions.
- small improvement to a prompt in the GenerativeClock component
- Modernize the situation_representation_via_narrative component.
- use verbosity and reasoning_effort parameters inside the OpenAI wrapper
- Make formative memories generator throw an error if passed wrong shape parameters
Added
- Add option to remove duplicates, when extracting data from the logs
- Add acting component flag to randomize choices
- Create non-deprecated no_op_context_processor
- An actor and a game master prefabs and required components for running a simulation that follows a strict script. This can be used for generating fine tuning data.
- Parallel stateless questionnaire
- Adding a callback to get the state of the simulation after every step, which can be used to implement custom checkpointing
- Enable loading presaved memory states from agent config
- Marketplace component that handles logic for buyers and sellers trading goods
- questionnaire simulation load memories
- Added a death component
- Add situated_in_time_and_place game master prefab
- Add support for open weights OpenAI models via Together AI.
- Implementing multi-step questionnaire that can handle both open-ended and multiple-choice questions.
- Add option to return raw log from simulation.play
Fixed
- Dummy language model options
- create game_master module in contrib to fix typecheck error
- making OutputTypes explicit strings and adding conversion to and from dictionaries. This enables serialisation.
- fix serialisation to handle action_spec correctly
- Fix action_spec serialization for death gm component
- fix SendEventToRelevantPlayers serialisation to handle action_spec correctly
- Fixing and improving MakeObservation and SendEventToRelevantPlayers by replacing certain llm calls with simple string editing and fixing logic.
- prevent premature termination in default make_observation component
- Minor fix of next acting component, which makes sure the fixed random order starts with the first actor
- OpenAI models no longer support terminators, and remove their hardcoded output limit.
- always use temperature 1.0 for OpenAI since GPT-5 crashes for all other values.
- use
max_completion_tokensinstead ofmax_tokensin base_gpt_model. - Make it so that calling get_currently_active_player on NextActingAllEntities throws a legible error.
用户点评
登录用户的真实使用记录,可按版本和硬件筛选还没有人点评。第一个说出真实体验的人最有价值。
Concordia
A library for generative social simulation
Concordia Tech Report | Concordia Design Pattern | Code Cheat Sheet
About
Concordia is a library for constructing and running generative agent-based models that simulate interactions among entities in grounded physical, social, or digital environments. It uses an interaction pattern inspired by tabletop role-playing games: a special entity called the Game Master (GM) simulates the environment in which player entities interact. Entities describe their intended actions in natural language, and the GM translates these into appropriate outcomes e.g. checking physical plausibility in simulated worlds.
Concordia supports a broad range of applications, including social science research, AI safety and ethics, cognitive neuroscience, economics, synthetic data generation for personalization, and performance evaluation of real services through simulated usage.
Concordia requires access to a standard LLM API and may optionally integrate with external applications and services.
How it Works
A simulation is built from entities. Each entity contains components that supply behavior and state, such as instructions, memory and action selection. Prefabs are prebuilt entity templates. Instantiate a prefab, then override parameters such as the entity’s name, instructions or goal. Its standard factory constructs the components from those settings.
The engine organizes execution. For each run_loop call, entities are
assigned player or game master roles. The engine requests player entity actions
and asks game master entities to provide observations and resolve those actions.
These are roles in that call, rather than intrinsic entity classes.
Start with the GUI and CLI entity-component guide to inspect components, edit a simulation, and observe its behavior.
Folder Structure
concordia/prefabs: Pre-assembled starting configurations for entities and their components.concordia/components: Modular building blocks for entities, including memory systems, and sensory modules.concordia/environment: Contains the engine interfaces which determine turn-taking, simultaneous action, or asynchronous action.concordia/document: Utilities for managing LLM prompts and context.concordia/language_model: LLM integration and API wrappers.examples/: Tutorials and example simulations to help you get started.
Tutorials
- A tutorial that focuses on interaction with the GUI editor and CLI interface: Concordia GUI and CLI Tutorial.
- In-depth tutorial lecture on YouTube: Concordia: Building Generative Agent-Based Models, works with
examples/tutorial.ipynb.
Installation
Concordia is available on PyPI and can be installed using:
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.
This provides a tested, reproducible development workflow that minimizes dependency management. We strongly recommend 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:
-
Clone Concordia:
git clone -b main https://github.com/google-deepmind/concordia cd concordia -
Create and activate a virtual environment (Python 3.12 or newer is required):
python3.12 -m venv venv source venv/bin/activate -
Install Concordia:
pip install --editable .[dev] -
Test the installation:
pytest --pyargs concordia -
Install any additional language model dependencies you will need, e.g.:
pip install .[google] pip install --requirement=examples/requirements.inNote 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 access to an LLM API. Any LLM API that supports sampling text should work, though result quality depends on the capabilities of the chosen model. You must also provide a text embedder for associative memory. Any fixed-dimensional embedding works for this, ideally one suited to 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:
- What kind of situation is this?
- What kind of person am I?
- 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:
Citing Concordia
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}
}
Disclaimer
This is not an officially supported Google product.
For a complete interactive authoring walkthrough and explicit editor/CLI coverage, see the GUI and CLI entity-component guide.