Agent Configuration

Agent configuration defines the settings for different types of agents in the simulation, supporting various types such as citizens, enterprises, banks, national statistics bureaus, and governments. Its main uses are as follows:

  • Citizens: Simulate residents in the city who can work, consume, travel, etc.

  • Enterprises: Simulate enterprises in the city that provide jobs and pay salaries to residents

  • Banks: Regulate interest rate levels and regularly distribute interest based on residents’ deposits

  • Statistics Bureau: Collect data on residents’ income, consumption, etc., for macroeconomic analysis

  • Government: Adjust tax rates to influence macroeconomic conditions

  • Supervisor: Regulate conversations between citizens through online social media and filter specific information

Configuration

Main Fields of AgentsConfig:

  • citizens (list[AgentConfig]): Citizen agent configuration, required and must contain at least one configuration

  • firms (list[AgentConfig]): Enterprise agent configuration, optional

  • banks (list[AgentConfig]): Bank agent configuration, optional

  • nbs (list[AgentConfig]): National Statistics Bureau agent configuration, optional

  • governments (list[AgentConfig]): Government agent configuration, optional

  • supervisor (Optional[AgentConfig]): Supervisor agent configuration, optional

Main Fields of Individual AgentConfig:

  • agent_class (Union[type[Agent], str]): Agent class name or type

  • number (int): Number of agents, default 1, must be greater than or equal to 0

  • agent_params (Optional[Any]): Agent parameter configuration, used to customize agent behavior

    • Supports any type, specific parameters are defined by the agent class

    • Parameters must be filled in according to the agent class used

    • For example: SocietyAgent supports parameters such as enable_cognition, max_plan_steps, etc.

    • Parameters will affect the agent’s decision logic and behavior patterns

  • blocks (Optional[dict]): Agent behavior module configuration, defining the agent’s functional modules

    • Keys are module class names or string identifiers

    • Values are the specific configuration parameters of the modules

    • Parameters must be filled in according to the module type used

    • Common modules: MobilityBlock, EconomyBlock, SocialBlock, etc.

    • Module configuration will affect the agent’s capability scope and behavior patterns

  • memory_from_file (Optional[str]): Load initial memory configuration from file

    • File path, supports local files and S3 files

    • File format should be JSON, containing the agent’s initial attributes

    • Mutually exclusive with memory_distributions

  • tools (Optional[list[CustomTool]]): Agent tool configuration, extending agent capabilities

    • Each tool includes fields such as name, description, tool, category, etc.

    • category supports: NORMAL (normal tools), MCP (Model Context Protocol tools)

    • Tools can extend agent capabilities, such as weather queries, path planning, etc.

    • File configuration scheme not supported

Note

All class-related configurations loaded from files (such as agent_class, Block, etc.) need to be converted from the community

Configuration Example

Basic Citizen Configuration:

agents:
  citizens:
    - agent_class: citizen
      number: 100

Multi-Type Agent Configuration:

agents:
  citizens:
    - agent_class: citizen
      number: 1000
  firms:
    - agent_class: firm
      number: 5
  governments:
    - agent_class: government
      number: 1
  nbs:
    - agent_class: nbs
      number: 1
  banks:
    - agent_class: bank
      number: 1

Load Agent Configuration from File:

agents:
  citizens:
    - agent_class: citizen
      memory_from_file: ./agent_profiles.json

Custom Agent Parameter Configuration:

agents:
  citizens:
    - agent_class: citizen
      number: 100
      agent_params:
        enable_cognition: true
        max_plan_steps: 5
        need_initialization_prompt: "你是一个市民，需要满足基本需求"
        plan_generation_prompt: "根据当前需求制定详细计划"
        block_dispatch_prompt: "根据意图选择合适的模块"

Note

The specific parameters of agent_params need to be determined according to the agent class used.

Configure Agent Behavior Modules:

agents:
  citizens:
    - agent_class: citizen
      number: 100
      blocks:
        MyBlock:
          max_speed: 5.0
          preferred_transport: "walking"

Note

The blocks configuration needs to determine parameters according to the module type used.