1concordia/
 2├── agents/                    # Entity Agent 核心實作
 3│   ├── entity_agent.py        # 基礎代理人類別
 4│   └── entity_agent_with_logging.py  # 帶日誌的代理人
 5├── associative_memory/        # 關聯式記憶體實作
 6│   └── basic_associative_memory.py   # 基於 embedding 的記憶
 7├── components/                # 元件庫
 8│   ├── agent/                 # 代理人元件 (memory, plan, observation...)
 9│   └── game_master/           # GM 元件 (event_resolution, inventory...)
10├── contrib/                   # 社群貢獻
11│   ├── language_models/       # LLM 整合 (Gemini, GPT, Ollama, Mistral...)
12│   └── prefabs/               # 進階預製組件
13├── document/                  # LLM Prompt 管理與上下文建構
14├── environment/               # 模擬引擎
15│   ├── engine.py              # 引擎基礎類別
16│   ├── engines/               # Sequential, Simultaneous 等引擎
17│   └── scenes/                # 場景 (Scene) 管理
18├── prefabs/                   # 核心預製組件
19│   ├── entity/                # Entity Prefabs
20│   ├── game_master/           # GM Prefabs
21│   └── simulation/            # Simulation 預製組件
22├── typing/                    # 型別定義
23│   ├── entity.py              # Entity 介面
24│   ├── entity_component.py    # Component 介面
25│   ├── prefab.py              # Prefab 設定介面
26│   ├── scene.py               # Scene 定義
27│   └── simulation.py          # Simulation 介面
28└── utils/                     # 工具函式
29examples/                      # 教學與範例
30├── tutorial.ipynb             # 入門教學 Notebook
31├── alice.ipynb                # Alice in Wonderland 敘事模擬
32├── marketplace.ipynb          # 市場經濟模擬
33├── selling_cookies.ipynb      # 賽局理論範例
34├── dialog.ipynb               # 對話模擬
35├── resource_dilemma/          # 資源困境 (公地悲劇)
36├── games/                     # 多種賽局實驗
37└── social_media/              # 社群媒體模擬

1# 建議使用 uv 建立虛擬環境
2uv venv concordia-env
3source concordia-env/bin/activate
4
5# 安裝 Concordia
6pip install gdm-concordia
7
8# 驗證安裝
9python -c "import concordia; print('Concordia installed successfully')"

 1# 1. Clone 儲存庫
 2git clone -b main https://github.com/google-deepmind/concordia
 3cd concordia
 4
 5# 2. 建立虛擬環境
 6python -m venv venv
 7source venv/bin/activate
 8
 9# 3. 可編輯安裝 (Editable Install)
10pip install --editable .[dev]
11
12# 4. 執行測試
13pytest --pyargs concordia
14
15# 5. 安裝 LLM 相依套件
16pip install .[google]                        # Google Gemini
17pip install --requirement=examples/requirements.in  # 範例依賴

 1# 範例：使用 Google Gemini
 2import os
 3os.environ['GOOGLE_API_KEY'] = 'your-api-key-here'
 4
 5from concordia.contrib.language_models.google import gemini_model
 6
 7model = gemini_model.GeminiLanguageModel(model_name='gemini-2.0-flash')
 8
 9# 範例：使用 Ollama（本地部署，無需 API Key）
10from concordia.contrib.language_models.ollama import ollama_model
11
12model = ollama_model.OllamaLanguageModel(
13    model_name='llama3',
14    base_url='http://localhost:11434'
15)

1# 使用 sentence-transformers
2from sentence_transformers import SentenceTransformer
3
4st_model = SentenceTransformer('all-MiniLM-L6-v2')
5embedder = lambda text: st_model.encode(text)

 1from concordia.prefabs import entity as entity_prefabs
 2from concordia.prefabs import game_master as game_master_prefabs
 3from concordia.prefabs.simulation import generic as simulation
 4from concordia.typing import prefab as prefab_lib
 5from concordia.utils import helper_functions
 6
 7# 1. 載入可用的 Prefab
 8prefabs = {
 9    **helper_functions.get_package_classes(entity_prefabs),
10    **helper_functions.get_package_classes(game_master_prefabs),
11}
12
13# 2. 定義代理人實例 (Agent Instances)
14instances = [
15    prefab_lib.InstanceConfig(
16        prefab="basic__Entity",
17        role=prefab_lib.Role.ENTITY,
18        params={"name": "Alice", "goal": "Make new friends"},
19    ),
20    prefab_lib.InstanceConfig(
21        prefab="basic__Entity",
22        role=prefab_lib.Role.ENTITY,
23        params={"name": "Bob", "goal": "Find a business partner"},
24    ),
25]
26
27# 3. 加入 Game Master
28instances.append(
29    prefab_lib.InstanceConfig(
30        prefab="dialogic__GameMaster",
31        role=prefab_lib.Role.GAME_MASTER,
32        params={
33            "name": "conversation rules",
34            "next_game_master_name": "conversation rules",
35        },
36    )
37)
38
39# 4. 建立模擬設定 (Simulation Config)
40config = prefab_lib.Config(
41    default_premise="Alice and Bob meet at a coffee shop on a rainy afternoon.",
42    default_max_steps=20,
43    prefabs=prefabs,
44    instances=instances,
45)
46
47# 5. 初始化並執行模擬
48sim = simulation.Simulation(config=config, model=model, embedder=embedder)
49results = sim.play()

 1# 定義角色
 2characters = [
 3    prefab_lib.InstanceConfig(
 4        prefab="basic__Entity",
 5        role=prefab_lib.Role.ENTITY,
 6        params={
 7            "name": "Tom",
 8            "goal": "Resolve the car dispute peacefully",
 9        },
10    ),
11    prefab_lib.InstanceConfig(
12        prefab="basic__Entity",
13        role=prefab_lib.Role.ENTITY,
14        params={
15            "name": "Jerry",
16            "goal": "Get compensation for the crashed car",
17        },
18    ),
19    prefab_lib.InstanceConfig(
20        prefab="conversational__Entity",
21        role=prefab_lib.Role.ENTITY,
22        params={
23            "name": "Sarah",
24            "goal": "Keep the peace among friends",
25        },
26    ),
27    prefab_lib.InstanceConfig(
28        prefab="conversational__Entity",
29        role=prefab_lib.Role.ENTITY,
30        params={
31            "name": "Mike",
32            "goal": "Have a good time despite the situation",
33        },
34    ),
35]
36
37# 設定初始化器 -- 為代理人建立背景記憶
38initializer = prefab_lib.InstanceConfig(
39    prefab="formative_memories_initializer__GameMaster",
40    role=prefab_lib.Role.INITIALIZER,
41    params={
42        "name": "initial setup",
43        "next_game_master_name": "pub rules",
44        "shared_memories": [
45            "Tom, Jerry, Sarah, and Mike have been friends since college.",
46            "They are snowed in at The Red Lion pub.",
47            "The blizzard is expected to last until morning.",
48        ],
49        "player_specific_context": {
50            "Tom": "You accidentally crashed Jerry's car last week.",
51            "Jerry": "Tom crashed your car and hasn't offered to pay.",
52            "Sarah": "You know about the car incident and want to mediate.",
53            "Mike": "You just want everyone to relax and enjoy the evening.",
54        },
55    },
56)
57
58# 設定 Game Master
59gm = prefab_lib.InstanceConfig(
60    prefab="generic__GameMaster",
61    role=prefab_lib.Role.GAME_MASTER,
62    params={
63        "name": "pub rules",
64        "acting_order": "random",  # 隨機發言順序增加真實感
65    },
66)
67
68# 組裝設定
69config = prefab_lib.Config(
70    default_premise=(
71        "Four friends are stuck at The Red Lion pub during a blizzard. "
72        "Tom and Jerry have an unresolved dispute about a car crash."
73    ),
74    default_max_steps=30,
75    prefabs=prefabs,
76    instances=characters + [initializer, gm],
77)

 1from concordia.typing import scene as scene_lib
 2from concordia.typing import entity as entity_lib
 3
 4# 定義場景 (Scene)：先對話再做決策
 5conversation_scene = scene_lib.SceneTypeSpec(
 6    name='discussion',
 7    game_master_name='conversation rules',
 8    action_spec=entity_lib.free_action_spec(
 9        call_to_action=entity_lib.DEFAULT_CALL_TO_SPEECH
10    ),
11)
12
13decision_scene = scene_lib.SceneTypeSpec(
14    name='decision',
15    game_master_name='decision rules',
16    action_spec={
17        'Alice': entity_lib.choice_action_spec(
18            call_to_action='Do you cooperate or defect?',
19            options=['Cooperate', 'Defect'],
20        ),
21        'Bob': entity_lib.choice_action_spec(
22            call_to_action='Do you cooperate or defect?',
23            options=['Cooperate', 'Defect'],
24        ),
25    },
26)
27
28# 定義場景序列 (Scene Sequence)
29scenes = [
30    scene_lib.SceneSpec(
31        scene_type=conversation_scene,
32        participants=['Alice', 'Bob'],
33        num_rounds=3,
34        premise={
35            'Alice': ['You and Bob are about to make a critical decision.'],
36            'Bob': ['You and Alice are about to make a critical decision.'],
37        },
38    ),
39    scene_lib.SceneSpec(
40        scene_type=decision_scene,
41        participants=['Alice', 'Bob'],
42        num_rounds=1,
43        premise={
44            'Alice': ['Time to decide: cooperate or defect.'],
45            'Bob': ['Time to decide: cooperate or defect.'],
46        },
47    ),
48]
49
50# 定義收益函式 (Payoff Function)
51def action_to_scores(joint_action):
52    a, b = joint_action.get('Alice'), joint_action.get('Bob')
53    payoff_matrix = {
54        ('Cooperate', 'Cooperate'): {'Alice': 3, 'Bob': 3},
55        ('Cooperate', 'Defect'):    {'Alice': 0, 'Bob': 5},
56        ('Defect', 'Cooperate'):    {'Alice': 5, 'Bob': 0},
57        ('Defect', 'Defect'):       {'Alice': 1, 'Bob': 1},
58    }
59    return payoff_matrix.get((a, b), {'Alice': 0, 'Bob': 0})
60
61def scores_to_observation(scores):
62    return {p: f"Your score this round: {s}" for p, s in scores.items()}

 1import dataclasses
 2from concordia.typing import entity_component
 3
 4@dataclasses.dataclass
 5class EmotionTracker(entity_component.ContextComponent):
 6    """追蹤代理人的情緒狀態。"""
 7
 8    def __init__(self, model, memory, agent_name: str):
 9        self._model = model
10        self._memory = memory
11        self._agent_name = agent_name
12        self._current_emotion = "neutral"
13
14    def pre_act(self, action_spec) -> str:
15        # 從近期記憶推斷當前情緒
16        recent_memories = self._memory.retrieve_recent(k=5)
17        context = "\n".join(recent_memories)
18
19        prompt = (
20            f"Based on {self._agent_name}'s recent experiences:\n"
21            f"{context}\n"
22            f"What is {self._agent_name}'s current emotional state? "
23            f"Respond with one word (e.g., happy, angry, anxious, calm)."
24        )
25        self._current_emotion = self._model.sample_text(prompt).strip()
26        return f"{self._agent_name} is feeling {self._current_emotion}."
27
28    def get_state(self) -> str:
29        return f"Current emotion: {self._current_emotion}"

 1import dataclasses
 2from concordia.typing import prefab as prefab_lib
 3
 4@dataclasses.dataclass
 5class EmotionalEntity(prefab_lib.Prefab):
 6    """帶有情緒追蹤功能的代理人 Prefab。"""
 7
 8    @classmethod
 9    def get_default_params(cls):
10        return {
11            "name": "EmotionalAgent",
12            "goal": "",
13            "emotion_sensitivity": "high",
14        }
15
16    def build(self, model, memory, embedder, **kwargs):
17        # 建構元件堆疊
18        components = self._build_base_components(model, memory)
19        components['emotion'] = EmotionTracker(
20            model=model,
21            memory=memory,
22            agent_name=self.params['name'],
23        )
24        return self._assemble_entity(components)

 1from concordia.environment.engines import simultaneous
 2
 3# 建立同時行動引擎
 4engine = simultaneous.Simultaneous()
 5
 6# 在模擬設定中使用
 7sim = simulation.Simulation(
 8    config=config,
 9    model=model,
10    embedder=embedder,
11    engine=engine,  # 替換預設的 Sequential 引擎
12)

1from concordia.agents import entity_agent_with_logging
2
3# 使用帶日誌的代理人
4# entity_agent_with_logging 會記錄每個元件的輸入/輸出與推理過程
5
6# 使用 concordia-log CLI 工具檢視日誌
7# $ concordia-log <log_file_path>

 1@article{vezhnevets2023generative,
 2  title={Generative agent-based modeling with actions grounded in physical,
 3  social, or digital space using Concordia},
 4  author={Vezhnevets, Alexander Sasha and Agapiou, John P and Aharon, Avia and
 5  Ziv, Ron and Matyas, Jayd and Du{\'e}{\~n}ez-Guzm{\'a}n, Edgar A and
 6  Cunningham, William A and Osindero, Simon and Karmon, Danny and
 7  Leibo, Joel Z},
 8  journal={arXiv preprint arXiv:2312.03664},
 9  year={2023}
10}