# tsinghua-fib-lab/agentsociety architecture

> Architecture diagram of the GitHub repository tsinghua-fib-lab/agentsociety, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsinghua-fib-lab/agentsociety
- Repository: https://github.com/tsinghua-fib-lab/agentsociety

## Overview

##### Project Type and Purpose
- AgentSociety is a simulation framework designed for building LLM-driven agents operating in urban environments. Its purpose is to simulate human-like decision-making, social interactions, and urban dynamics using an advanced layered architecture that separates agent behaviors, messaging, environmental interactions, LLM integrations, and supporting tools.

##### Analyzing the File Structure
- The top-level “agentsociety” directory contains most of the core code with sub-packages such as:
- agent & cityagent: implementing core agent behaviors and specialized urban agent variants (e.g., bankagent, governmentagent).
- environment: covering simulation services (like sim submodule with services for clocks, lanes, roads, etc.), interaction with urban context, and sidecar mechanisms.
- memory: handling memory modules for agents including memory profiles, querying (e.g., using faiss), and state management.
- llm: managing integration with Large Language Models (including embeddings and utilities).
- workflow & message: defining how agent actions are triggered and how messages are exchanged.
- Additional directories and files (e.g., configs, simulation, tools, docs, examples) provide configuration templates, simulation storage mechanisms, experimental use cases, and design documentation.
- Notice also support files like Dockerfile, Makefile, and CI/CD configurations which highlight the project’s deployment and integration testing approach.

##### Specific Elements
- Command and configuration flows (from Model to Agent).
- Communication flows among agents (within Message Layer).
- Feedback from simulation data (Environment to Agent).
- Integration calls between Agent workflows and the LLM services.
- Rectangles for core modules (Agent, Environment, LLM).
- Ovals or circles for external services (databases, MLFlow).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Model Layer
    subgraph "Model Layer"
        M1["Configs"]:::model
        M2["Config Const"]:::model
    end

    %% Agent Layer
    subgraph "Agent Layer"
        A1["Base Agent"]:::agent
        A2["City Agent"]:::agent
    end

    %% Message Interface
    subgraph "Message Interface"
        MSG1["Message Interceptor"]:::message
        MSG2["Messager"]:::message
    end

    %% Environment Services
    subgraph "Environment Services"
        ENV1["Sim Services"]:::environment
        ENV2["Economy"]:::environment
        ENV3["Sidecar"]:::environment
        ENV4["Env Utils"]:::environment
    end

    %% LLM Integration
    subgraph "LLM Integration"
        LLM1["LLM Core"]:::llm
        LLM2["Embeddings"]:::llm
        LLM3["LLM Utils"]:::llm
    end

    %% Memory Module
    subgraph "Memory Module"
        MEM1["Memory Core"]:::memory
        MEM2["Memory Base"]:::memory
        MEM3["FAISS Query"]:::memory
    end

    %% Tools & Utilities
    subgraph "Tools & Utilities"
        T1["Tools"]:::tools
        T2["Code Block Parser"]:::tools
        T3["JSON Parser"]:::tools
    end

    %% Workflow Component
    subgraph "Workflow Component"
        WF1["Workflow Block"]:::workflow
        WF2["Prompt Handler"]:::workflow
        WF3["Trigger"]:::workflow
    end

    %% External Systems
    subgraph "External Systems"
        EX1["PostgreSQL Storage"]:::external
        EX2["MLFlow Client"]:::external
        EX3["MLFlow Docker"]:::external
    end

    %% UI/Visualization & Documentation
    subgraph "UI/Visualization"
        UI1["UI/Docs"]:::ui
        UI2["Examples"]:::ui
    end

    %% Connections
    %% Model Layer to Agent Layer (configuration flow)
    M1 -->|"configFlow"| A1
    M1 -->|"configFlow"| A2
    M2 -->|"configFlow"| A1

    %% Agent Layer to Message Interface (communication)
    A1 -->|"sendMsg"| MSG1
    A2 -->|"sendMsg"| MSG2

    %% Message Interface to Environment Services (signals)
    MSG1 -->|"envUpdate"| ENV1
    MSG2 -->|"envUpdate"| ENV1
    MSG2 -->|"envUpdate"| ENV2

    %% Environment feedback to Agent Layer
    ENV1 -->|"feedback"| A1

    %% LLM Integration supports Agent decisions
    LLM1 -->|"decisionSupport"| A1

    %% Memory Module integrated with Agent Layer
    A1 -->|"memoryQuery"| MEM1
    A2 -->|"memoryQuery"| MEM1

    %% Workflow triggers Agent actions and LLM prompts
    WF1 -->|"trigger"| A1
    WF2 -->|"prompt"| LLM1
    WF3 -->|"trigger"| A1

    %% Tools support several components
    T1 -->|"support"| A1
    T1 -->|"support"| LLM1
    T1 -->|"support"| MEM1

    %% External Systems integration with Environment and Model layers
    EX1 -->|"storeSim"| ENV1
    EX2 -->|"metrics"| M1
    EX3 -->|"containerize"| EX2

    %% UI/Visualization connected to Environment
    ENV1 -->|"display"| UI1
    ENV1 -->|"display"| UI2

    %% Class Definitions for Styling
    classDef model fill:#f9c,stroke:#333,stroke-width:2px;
    classDef agent fill:#bbf,stroke:#333,stroke-width:2px;
    classDef message fill:#afa,stroke:#333,stroke-width:2px;
    classDef environment fill:#ffd,stroke:#333,stroke-width:2px;
    classDef llm fill:#faa,stroke:#333,stroke-width:2px;
    classDef memory fill:#cfc,stroke:#333,stroke-width:2px;
    classDef tools fill:#fcf,stroke:#333,stroke-width:2px;
    classDef workflow fill:#cff,stroke:#333,stroke-width:2px;
    classDef external fill:#ddd,stroke:#333,stroke-width:2px;
    classDef ui fill:#eef,stroke:#333,stroke-width:2px;

    %% Click Events
    click M1 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/agentsociety/configs"
    click M2 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/utils/config_const.py"
    
    click A1 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/agentsociety/agent"
    click A2 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/agentsociety/cityagent"
    
    click MSG1 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/message/message_interceptor.py"
    click MSG2 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/message/messager.py"
    
    click ENV1 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/agentsociety/environment/sim"
    click ENV2 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/agentsociety/environment/economy"
    click ENV3 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/agentsociety/environment/sidecar"
    click ENV4 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/agentsociety/environment/utils"
    
    click LLM1 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/llm/llm.py"
    click LLM2 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/llm/embeddings.py"
    click LLM3 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/llm/utils.py"
    
    click MEM1 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/memory/memory.py"
    click MEM2 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/memory/memory_base.py"
    click MEM3 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/memory/faiss_query.py"
    
    click T1 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/agentsociety/tools"
    click T2 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/utils/parsers/code_block_parser.py"
    click T3 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/utils/parsers/json_parser.py"
    
    click WF1 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/workflow/block.py"
    click WF2 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/workflow/prompt.py"
    click WF3 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/workflow/trigger.py"
    
    click EX1 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/simulation/storage/pg.py"
    click EX2 "https://github.com/tsinghua-fib-lab/agentsociety/blob/main/agentsociety/metrics/mlflow_client.py"
    click EX3 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/docker/mlflow"
    
    click UI1 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/docs/05-ui-interface"
    click UI2 "https://github.com/tsinghua-fib-lab/agentsociety/tree/main/examples"
```
