Development Guide

This guide is for contributors to AgentSociety 2.

Setting Up Development Environment

  1. Fork and clone the repository:

git clone https://github.com/your-username/agentsociety.git
cd agentsociety

  1. Install in development mode:

# Using uv (recommended)
uv sync

# Or using pip
pip install -e "packages/agentsociety2[dev]"

  1. Install pre-commit hooks:

cd packages/agentsociety2
pre-commit install

Running Tests

cd packages/agentsociety2
pytest

With coverage:

pytest --cov=agentsociety2 --cov-report=html

Code Style

AgentSociety 2 uses ruff for linting and formatting:

# Check code
ruff check .

# Format code
ruff format .

We also use mypy for type checking:

mypy agentsociety2/

Project Structure

agentsociety2/
├── agent/           # Agent implementations
├── backend/         # FastAPI backend service (REST API)
├── config/          # Configuration and LLM routing
├── contrib/         # Contributed agents and environments
├── custom/          # Custom module templates
├── env/             # Environment modules and routers
├── logger/          # Enhanced logging with file support
├── registry/        # Module registry for custom components
├── skills/          # Research skills (literature, experiment, hypothesis, etc.)
├── society/         # Society helper utilities and CLI
├── storage/         # Replay storage system
└── trace/           # Distributed trace span writers

Research Skills Module

The skills/ module provides LLM-native research workflow:

  • literature: Academic literature search and management

  • experiment: Experiment configuration and execution

  • hypothesis: Hypothesis generation and management

  • analysis: Data Analysis and Reporting

Backend API

The backend/ module provides the FastAPI REST API:

  • Routers: * /api/v1/prefill-params - prefill parameters for module configuration * /api/v1/experiments - experiment management * /api/v1/modules - module management * /api/v1/replay - replay data access * /api/v1/custom - custom module registration * /api/v1/agent-skills - Agent Skills scanning, importing, and hot reloading

  • Service Layer: Business logic layer

Start the backend:

python -m agentsociety2.backend.run

# 访问 http://localhost:8001/docs 查看 API 文档

Logging System

Enhanced logging system support:

  • Colored console output: colorized by log level

  • File logging: write log files with add_file_handler()

  • LiteLLM integration: custom callback logger for LLM calls

from agentsociety2.logger import get_logger, set_logger_level, add_file_handler

# 设置日志级别
set_logger_level("DEBUG")

# 添加文件处理器
add_file_handler("output.log", level="INFO")

logger = get_logger()
logger.info("Hello, AgentSociety!")

Contributing

Please see Contributing to AgentSociety 2 for contribution guidelines.

Build Documentation

cd packages/agentsociety2/docs
make html

Built documentation will be in _build/html/.

For live preview while editing:

make livehtml

Release Process

  1. Update version in pyproject.toml

  2. Update CHANGELOG.md

  3. Commit changes

  4. Create tag: git tag agentsociety2-vX.Y.Z

  5. Push: git push --tags

  6. GitHub Actions will build and publish to PyPI