DOCSEARCHbyAlgolia
Submit Docs

AgentSociety Documentation

repository·main·Indexed 22 days ago

https://github.com/tsinghua-fib-lab/agentsociety

A framework for building LLM-based agent simulations in urban environments and research workflows. It supports large-scale city simulations (v1) and LLM-native research platforms (v2), including the AI Social Scientist VS Code/Cursor extension for social science research. The documentation covers the Daily Mobility ground truth dataset, simulation configuration, benchmark evaluation, and the installation and setup of the AI Social Scientist workbench.

Tokens
351.8K
Snippets
884
Records
1.5K
Agent score
76%

What's inside AgentSociety

  1. Overview of AgentSociety Webview Components

    main
    The extension/src/webview directory contains the React-based frontend components used within the VSCode extension. These components provide visual interfaces for configuration, parameter viewing, simulation replay, and settings editing. The components are compiled via webpack into JavaScript files located in extension/out/webview/.

  2. Overview of AgentSociety 2

    main

    AgentSociety 2 is a modern, LLM-native agent simulation and research platform designed for computational social science. It provides an asynchronous framework for managing agents, environment modules, and research skills.

    Key capabilities include:

    • LLM-driven Agents: Agents with personality, memory, and reasoning capabilities.
    • Flexible Environments: Customizable simulation environments built with composable tools and state management.
    • Asynchronous Design: High-performance architecture for efficient multi-agent simulations.
    • Experiment Tracking: Uses append-only JSONL replay, _schema.json catalogs, and DuckDB for analysis.
    • Resumability: Atomic persistence of agent, environment, and society states allows experiments to be resumed using the CLI --resume flag.
    • Research Skills: Built-in workflows for literature retrieval, hypothesis generation, experiment design, and paper writing.
    • Multiple Interfaces: Supports interaction via a Python asynchronous API, a FastAPI-based REST API, and a CLI tool.

  3. Overview of the BehaviorModeling Benchmark

    main
    The BehaviorModeling benchmark is designed to evaluate the capabilities of LLM agents in modeling user behavior. It focuses on two primary tasks: predicting user preferences through item recommendation and simulating user feedback through review generation. The benchmark supports both test mode (for evaluation) and inference mode (for deployment/usage).

  4. Overview of the agentsociety.agent module

    main

    The agentsociety.agent module is the core component for defining and managing agents within the AgentSociety framework. It provides the fundamental building blocks for agent behavior, including base classes, parameter configurations, and specialized agent types.

    Key submodules include:

    • agentsociety.agent.agent: The primary Agent class.
    • agentsociety.agent.agent_base: Base classes for agent implementation.
    • agentsociety.agent.prompt: Tools for managing agent prompts.
    • agentsociety.agent.memory_config_generator: Utilities for configuring agent memory.
    • agentsociety.agent.toolbox: Tools available to agents.
    • agentsociety.agent.context: Management of agent execution context.
    • agentsociety.agent.dispatcher: Logic for routing agent actions/messages.
    • agentsociety.agent.decorator: Decorators for agent functionality.

  6. Overview of the AgentSociety2 Recommendation Module

    main

    The AgentSociety2 Recommendation Module provides recommendation algorithm implementations based on collaborative filtering, supporting real-time incremental updates and flexible service composition. It uses a layered architecture that separates algorithm implementation, recommendation services, and training logic.

    Key Features:

    • Multi-algorithm support: Currently implements Matrix Factorization (MF), with architecture designed for expansion.
    • Optional Incremental Training: Supports real-time data updates via IncrementalTrainer.
    • Asynchronous & Non-blocking: Background training does not interrupt the recommendation service.
    • Concurrency Safety: Uses asyncio.Lock to ensure safe model access.
    • Model Persistence: Supports saving and loading models.
    • Cold Start Handling: Strategies for new users/items.
    • Flexible Composition: Service and training layers can be used independently.

  7. Glossary of AgentSociety² and AI Social Scientist terms

    main

    This glossary provides definitions for key terms used within the AgentSociety² framework and the AI Social Scientist VS Code extension. Use these terms to navigate documentation, configure experiments, and understand the research workflow.

    Core Framework & Roles

    • AgentSociety²: An LLM-native agentic research framework for turning social science questions into runnable and inspectable computational experiments.
    • AI Social Scientist: The agentic research role that coordinates literature, hypotheses, experiment design, simulation, analysis, and manuscript drafting.
    • PersonAgent: The default human-like agent in AgentSociety², used to simulate individuals with profiles, memory, intentions, and actions.
    • Silicon Participant (or Silicon Subject): A simulated participant that generates behavioral responses, receives interventions, and is measured in a configurable social environment.
    • Agent: An entity that can observe an environment, plan actions, call tools, and keep state toward a goal.

    Research Paradigms

    • Theoretical paradigm: Developing concepts, hypotheses, mechanisms, and explanatory frames.
    • Computational paradigm: Instantiating mechanisms with agents, environments, and rules, then testing them through simulation.
    • Empirical paradigm: Obtaining evidence through observations, surveys, experiments, or behavioral data.
    • Data-intensive paradigm: Understanding large-scale data through retrieval, processing, statistics, visualization, and pattern discovery.

    Technical Components & Configuration

    • Environment: The simulated setting in which agents act (e.g., space, resources, economic rules, social relations).
    • Skill: An installable capability module.
      • Agent runtime skill: Installed under custom/skills/, used by agents during simulations.
      • Claude Code skill: Installed under .claude/skills/, used by coding assistants in the IDE.
    • Experiment Config: Files defining how an experiment is initialized, executed, and saved.
    • Steps Config: A configuration file describing experiment actions (e.g., ask, intervene, run simulation steps, save artifacts).
    • Run Directory: The output directory for an experiment run, containing logs, config snapshots, results, and replay data.
    • Replay: Recorded experiment traces used to inspect agent behavior, environment changes, and results.
    • Evidence Graph: A visualization of evidence relationships in analysis results (viewable by right-clicking in the project tree).
    • Literature Library: The project area for paper PDFs, Markdown notes, literature indexes, and research materials.
    • Paper Workspace: The paper/ directory containing sections, reviews, and compile outputs managed by paper-toolkit.

    Development & Environment Setup

    • Backend (FastAPI backend): The local Python API service. Starting it enables full extension features like agent runtime skill management, module discovery, prefill parameters, replay endpoints, and API docs.
    • AI CLI Gateway: A built-in local proxy gateway that routes Claude Code and Codex CLI requests through third-party providers.
    • .env: A local workspace configuration file used for API endpoints, keys, model names, and runtime settings.
    • API Base: The service endpoint for model calls (e.g., https://api.openai.com/v1).
    • API Key: The secret key for a model provider. Do not commit this to a public repository.
    • MCP (Model Context Protocol): Allows coding assistants (like Claude Code) to connect to external tools, remote HTTP/SSE services, or local backends.
    • Context Preset: Controls available context length via standard-200k or long-1m.
    • VS Code workspace: The project folder currently open in VS Code. The extension reads/writes .env, configs, results, skills, and replay data here.

  8. Use the agentsociety.survey module for survey management

    main

    The agentsociety.survey module provides the core abstractions for designing, managing, and executing surveys within the AgentSociety framework. It is composed of several key classes used to define the structure of questions and the lifecycle of a survey process.

    Key components include:

    • QuestionType: Defines the nature of the questions being asked.
    • Question: Represents an individual unit of inquiry.
    • Survey: Represents the complete collection of questions and the survey structure.
    • SurveyManager: The primary interface for orchestrating survey execution and managing data.

    For detailed implementation of these components, refer to the agentsociety.survey.models and agentsociety.survey.manager submodules.

  9. Use agentsociety.commercial.billing.calculator for billing operations

    main
    The agentsociety.commercial.billing.calculator module provides asynchronous functions to manage commercial billing, check tenant balances, and record experiment-related costs within the AgentSociety ecosystem. It requires a sqlalchemy.ext.asyncio.AsyncSession for database interactions.

  11. Use agentsociety.environment.economy for economic simulations

    main

    The agentsociety.environment.economy module provides the core components for managing economic environments within AgentSociety. It is primarily used to interact with economic systems through a client-server or client-environment model, allowing agents to participate in economic activities.

    The module exposes two main components:

    • EconomyClient: The primary interface for interacting with the economic environment.
    • EconomyEntityType: An enumeration or type definition used to categorize different types of entities within the economy.

  12. Explore AgentSociety subpackages

    main

    The agentsociety package is organized into several specialized subpackages that handle different aspects of agent simulation and management. Key subpackages include:

    • agentsociety.agent: Core agent definitions and logic.
    • agentsociety.taskloader: Loading and managing tasks for agents.
    • agentsociety.vectorstore: Vector database integration for retrieval-augmented generation.
    • agentsociety.environment: Simulation environment management.
    • agentsociety.storage & agentsociety.s3: Data persistence and S3 integration.
    • agentsociety.llm: Large Language Model interfaces.
    • agentsociety.memory: Agent memory management.
    • agentsociety.simulation: Orchestrating multi-agent simulations.
    • agentsociety.executor: Task execution logic.
    • agentsociety.webapi: Web-based API interfaces.
    • agentsociety.configs: Configuration management.
    • agentsociety.cityagent: Specialized city-scale agent logic.
    • agentsociety.survey: Survey-related agent capabilities.
    • agentsociety.message: Messaging and communication protocols.
    • agentsociety.filesystem: Filesystem operations.
    • agentsociety.logger: Logging utilities.