AgentSociety: 城市中的 LLM Agent

🚀 AgentSociety

   

AgentSociety 是一个专门为构建城市模拟环境中的 Agent 而设计的先进框架。借助 AgentSociety，你可以轻松创建和管理 Agent，从而高效地对复杂的城市场景进行建模和模拟。

论文已发布在 arXiv：

@article{piao2025agentsociety,
  title={AgentSociety: Large-Scale Simulation of LLM-Driven Generative Agents Advances Understanding of Human Behaviors and Society},
  author={Piao, Jinghua and Yan, Yuwei and Zhang, Jun and Li, Nian and Yan, Junbo and Lan, Xiaochong and Lu, Zhihong and Zheng, Zhiheng and Wang, Jing Yi and Zhou, Di and others},
  journal={arXiv preprint arXiv:2502.08691},
  year={2025}
}

🌟 特性

• 心智-行为耦合 (Mind-Behavior Coupling)：整合了 LLM 的规划、记忆和推理能力来生成逼真的行为，或利用马斯洛需求层次理论和计划行为理论等既定理论进行显式建模。
• 环境设计：支持基于数据集、文本和规则的环境，具备不同程度的真实感和交互性。
• 交互式可视化：提供实时界面，用于在实验过程中监控 Agent 并与之交互。
• 丰富的工具集：包含专门为社会实验量身定制的实用工具，如访谈、调查、干预和指标记录。

📑 目录

1. 新闻
2. 框架
3. 安装与设置
4. 快速开始
5. 参与贡献
6. 许可协议

📰 新闻

• 📢 02.07 - 初始版本现已发布！

敬请期待后续更新！

🛠️ 框架

AgentSociety 提供了一个稳健的框架，用于在受控的虚拟环境中模拟社会行为和经济活动。利用先进的 LLM，AgentSociety 能够模拟类人的决策和交互过程。我们的框架分为几个关键层，每一层负责不同的功能，如下图所示：

架构层级

• 模型层 (Model Layer)：作为核心，该层负责管理 Agent 配置、任务定义、日志设置和结果汇总。它为所有 Agent 进程提供统一的执行入口，通过任务配置确保对 Agent 行为和目标的集中控制。
• Agent 层 (Agent Layer)：该层实现了多头工作流（multi-head workflows）来管理 Agent 行为的各个方面。Memory 组件用于存储与 Agent 相关的信息（如位置和移动），静态配置文件维护不变的属性，自定义数据池充当工作记忆。多头工作流支持正常和事件驱动两种模式，利用 Reason Blocks（通过 LLM 基于上下文和工具进行决策）、Route Blocks（使用 LLM 或规则选择最佳路径）以及 Action Blocks（执行定义的动作）。
• 消息层 (Message Layer)：促进 Agent 之间的通信，该层支持点对点 (P2P)、点对组 (P2G) 以及群聊交互，从而在模拟中实现丰富且动态的交流。
• 环境层 (Environment Layer)：管理 Agent 与城市环境之间的交互，包括用于读取环境数据的环境感知 (Environment Sensing)、用于修改环境状态的交互处理 (Interaction Handling)，以及用于处理 Agent 进出消息的消息管理 (Message Management)。
• LLM 层 (LLM Layer)：为将大语言模型 (LLMs) 纳入 Agent 的工作流提供必要的配置和集成服务，该层支持通过 Prompting & Execution 进行模型调用和监控。它兼容各种 LLM，包括但不限于 OpenAI、Qwen 和 Deepseek 模型，在模型选择上提供了灵活性。
• 工具层 (Tool Layer)：作为框架功能的补充，该层提供了一系列实用工具，如用于解析和格式化的字符串处理、用于解释 JSON 或字典等格式响应的结果分析，以及包含排序和搜索功能的数据存储与检索机制。

⚙️ 安装与设置

你可以通过 pip 轻松安装 AgentSociety：

通过 pip 安装

Linux AMD64 或 macOS

Python >= 3.11

pip install agentsociety

🚀 快速开始

在几分钟内即可开始使用 AgentSociety！

使用示例

若要快速上手，请查阅仓库中的 examples 文件夹。其中包含了示例脚本和配置文件，可以帮助你理解如何在城市模拟环境中创建和使用 Agent。 详细的使用教程请查看我们的在线文档：AgentSociety Document。

🤝 参与贡献

我们欢迎任何形式的贡献。