AgentSociety: 面向社会的 LLM Agent 模拟平台

English · 中文

---

AgentSociety 是一个用于构建城市环境和研究工作流中基于 LLM 的 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}
}

Star History

软件包

本仓库包含两个主要的软件包：

AgentSociety 2 (推荐)

AgentSociety 2 是一个现代化的、原生支持 LLM 的 Agent 模拟平台，专为社会科学研究和实验设计而打造。

pip install agentsociety2

特性：

• LLM-Native 设计：从底层构建，专为 LLM 驱动的 Agent 而生
• 灵活的环境系统：模块化的环境组件，支持热插拔工具
• 多种推理模式：支持 ReAct、Plan-Execute、Code Generation、Two-Tier 路由器等
• 研究技能：支持文献检索、假设生成、实验设计、分析及论文工作流（通过外部 paper-toolkit 插件）
• 实验回放：基于 SQLite 的完整回放系统
• MCP 支持：集成 Model Context Protocol，增强工具扩展性

文档： agentsociety2.readthedocs.io

源码： packages/agentsociety2/

AgentSociety 1.x (遗留版本)

AgentSociety 1.x 是最初的城市模拟框架，采用基于 gRPC 的环境集成。

pip install agentsociety

特性：

• 基于 Ray 分布式计算的城市级模拟
• 城市环境模块（交通、经济、社会）
• 多 Agent 协同与通信

文档： agentsociety.readthedocs.io

源码： packages/agentsociety/

其他软件包

遗留软件包保留在此 Monorepo 中仅供参考，不参与活跃开发、CI 或安全扫描：

• agentsociety-community：社区贡献的自定义 Agent 和模块（遗留）
• agentsociety-benchmark：用于 Agent 评估的基准测试工具（遗留）

当前核心开发工作集中在 AgentSociety 2 (packages/agentsociety2)、VS Code 扩展 (extension/) 以及 Web 前端 (frontend/)。详见 .github/agentsociety2-scope.yml。

发布说明

AgentSociety 2 使用语义化版本控制（Semantic Versioning）和 Git 标签：

agentsociety2-v{major}.{minor}.{patch}

示例：agentsociety2-v2.5.2 发布内容包括：

• PyPI: agentsociety2==2.5.2
• VS Code 扩展: ai-social-scientist（版本号在 extension/package.json 中）
• GitHub Release: wheel、sdist 和 .vsix 附件

更新日志：CHANGELOG.md

项目结构

AgentSociety/
├── packages/
│   ├── agentsociety2/      # v2.x - 现代 LLM-native 平台（推荐）
│   ├── agentsociety/       # v1.x - 遗留的城市模拟版本
│   ├── agentsociety-community/
│   └── agentsociety-benchmark/
├── frontend/               # React Web 前端
├── extension/              # VSCode 扩展
├── docs_v1/                # v1 Sphinx 文档
└── examples/               # 实验示例

快速上手

AgentSociety 2

在运行示例前，请先设置 LLM 环境变量（agentsociety2 会在导入时进行验证）：

export AGENTSOCIETY_LLM_API_KEY="your-api-key"
export AGENTSOCIETY_LLM_API_BASE="https://api.openai.com/v1"
export AGENTSOCIETY_LLM_MODEL="gpt-5.5"

import asyncio
from datetime import datetime
from agentsociety2 import PersonAgent
from agentsociety2.env import CodeGenRouter
from agentsociety2.contrib.env import SimpleSocialSpace
from agentsociety2.society import AgentSociety

async def main():
    agent = PersonAgent(
        id=1,
        profile={"name": "Alice", "personality": "friendly and curious"},
    )
    env = CodeGenRouter(
        env_modules=[SimpleSocialSpace(agent_id_name_pairs=[(agent.id, agent.name)])]
    )
    society = AgentSociety(agents=[agent], env_router=env, start_t=datetime.now())
    await society.init()
    response = await society.ask("What's your name?")
    print(response)
    await society.close()

asyncio.run(main())

AgentSociety 1.x

# v1.x 示例代码（如有需要请参考对应文档）