AgentSociety 从入门到实践：面向开发者的功能部署指南

AgentSociety 是一个基于大语言模型的开源社会模拟平台，通过 LLM 驱动的智能体模拟人类行为与社会现象。本文档将帮助开发者完成从环境部署到核心功能配置的全流程，掌握开源项目的安装配置与功能使用方法。

一、基础认知：平台架构与核心特性

1.1 功能特性速览

AgentSociety 提供以下核心能力：

• 多智能体系统：支持千级智能体并发交互，模拟社会群体行为
• 环境建模：基于地理信息构建城市级虚拟环境
• 动态交互：智能体间可通过消息系统进行实时通信
• 实验管理：完整的实验设计、运行与数据采集流程
• 可视化分析：WebUI 实时展示智能体分布与行为轨迹

1.2 系统架构解析

平台采用模块化设计，核心组件包括：

• 社会智能体层：实现个体决策与行为逻辑
• 环境模拟层：提供地理空间与资源系统支持
• 交互网络层：处理智能体间通信与关系维护
• 实验管理层：控制模拟流程与数据采集
• 可视化层：Web 界面展示与交互控制

AgentSociety 架构概览 - 展示核心模块与应用场景关系

二、环境部署：从源码到运行

2.1 环境准备

硬件要求：

• 最低配置：4核CPU，16GB内存，10GB存储空间
• 推荐配置：8核CPU，32GB内存，SSD存储

软件依赖：

• Python 3.11+
• Linux X86_64 或 MacOS ARM 系统
• Git 版本控制工具

2.2 源码获取与安装

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/ag/agentsociety
cd agentsociety

# 安装核心包
pip install .

# 可选：安装社区扩展与基准测试工具
pip install ./packages/agentsociety-community ./packages/agentsociety-benchmark

安装验证：

agentsociety --version
# 预期输出：AgentSociety x.y.z

2.3 启动验证

# 检查系统依赖
agentsociety check

# 预期输出：
# ✅ Python版本满足要求 (3.11.4)
# ✅ 必要依赖已安装
# ✅ 端口8080可用

三、核心功能配置：构建模拟环境

3.1 LLM 服务配置

智能体推理依赖大语言模型API，支持主流LLM提供商。

配置步骤：

1. 复制配置模板：

cp examples/config_templates/example_config.yaml my_config.yaml

2. 编辑LLM配置段：

llm:
  - name: primary_llm  # 配置名称
    provider: openai   # 服务提供商
    model: gpt-4o      # 模型名称
    api_key: "sk-xxx"  # API密钥
    semaphore: 100     # 并发控制数

配置建议：

• 4核CPU环境：semaphore建议设为50-80
• 8核CPU环境：semaphore可设为100-200
• 生产环境建议配置多个LLM实例实现负载均衡

LLM API配置界面 - 支持多提供商与并发控制设置

3.2 地图环境配置

地图文件定义模拟的地理空间环境：

map:
  file_path: "./data/map/city.geojson"  # 地图数据路径
  resolution: 1000                     # 空间分辨率(米)

配置建议：

• 测试环境：使用示例地图（<10MB）
• 生产环境：根据模拟规模选择合适精度（推荐500-2000米分辨率）

3.3 智能体配置

定义模拟智能体的数量与类型：

agents:
  citizens:
    - agent_class: "cityagent"  # 智能体类型
      number: 500               # 数量
      profile_path: "./profiles/basic_citizen.json"  # 画像文件

配置建议：

• 初次测试：100-200个智能体
• 标准模拟：500-1000个智能体
• 大规模模拟：建议使用分布式部署

四、场景化应用：实验设计与运行

4.1 WebUI 启动与使用

WebUI提供可视化配置与实验管理功能：

1. 创建UI配置文件：

# ui_config.yaml
addr: "0.0.0.0:8080"  # 绑定地址与端口
env:
  db:
    enabled: true
    db_type: sqlite
  home_dir: "./agentsociety_data"  # 数据存储目录

2. 启动WebUI：

agentsociety ui -c ui_config.yaml

3. 访问界面：在浏览器打开 http://localhost:8080

AgentSociety WebUI首页 - 提供实验管理与配置入口

4.2 实验创建与执行

通过WebUI创建模拟实验的步骤：

1. 导航至"实验"页面，点击"新建实验"
2. 配置实验参数（名称、时长、智能体数量）
3. 选择已配置的LLM与地图
4. 点击"启动实验"开始模拟

4.3 模拟结果可视化

实验运行时，可通过地图视图观察智能体分布与行为：

智能体模拟运行界面 - 展示城市环境中智能体分布与交互

五、问题解决：常见故障排查

5.1 安装问题

Q: 执行agentsociety命令提示"command not found"
A: 检查Python环境变量配置，或使用完整路径：~/.local/bin/agentsociety

5.2 运行问题

Q: WebUI启动后无法访问
A: 检查防火墙设置，确认端口未被占用，或修改配置文件中的addr为"0.0.0.0:8080"

Q: 实验运行中出现LLM请求失败
A: 检查API密钥有效性，网络连接状态，或降低semaphore值减少并发请求

附录：配置检查清单

环境配置

• [ ] Python版本 ≥3.11
• [ ] 磁盘空间 ≥10GB
• [ ] 网络连接正常

功能配置

• [ ] LLM API密钥已配置
• [ ] 地图文件路径正确
• [ ] 智能体数量与硬件匹配
• [ ] 数据库配置正确

运行检查

• [ ] WebUI可正常访问
• [ ] 实验可成功启动
• [ ] 智能体行为符合预期
• [ ] 数据记录正常