Command Line Interface¶

AgentSociety 2 provides a powerful command line interface (CLI) for running experiments.

Overview¶

The CLI is the primary way to run AgentSociety 2 experiments. It provides:

Experiment configuration loading and validation
Step-by-step execution tracking
Progress persistence (pid.json)
Flexible logging configuration
Background execution support

Basic Usage¶

python -m agentsociety2.society.cli [OPTIONS]

Required Arguments¶

Parameter	Description
`--config` <PATH>	Initialization configuration file path (init_config.json)
`--steps` <PATH>	Step configuration file path (steps.yaml)

Optional Arguments¶

Parameter	Default value	Description
`--run-dir` <PATH>	current directory	Run output directory path
`--experiment-id` <TEXT>	None	experiment identifier
`--log-level`	INFO	Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
`--log-file` <PATH>	None	Log file path (required for background execution)
`--batch-size` <INT>	`AGENTSOCIETY_BATCH_SIZE` 或 256	每个 `step_agent_batch` Ray Task 处理的 agent 数
`--replay-disable`	false	禁用回放写入（百万级 agent 场景适用）
`--resume`	false	Resume an interrupted experiment from `run_dir/SOCIETY.json` and `SOCIETY_STEP.json`. The CLI restores the society clock, step counts, and env-module state, then skips completed `RunStep` entries. `Ask`, `Intervene`, and `Questionnaire` run again, so their artifact timestamps are updated. If `steps.yaml` does not match the checkpoint, the CLI emits a warning.

Running Experiments¶

Foreground Execution (Debug Mode)¶

python -m agentsociety2.society.cli \
    --config hypothesis_1/experiment_1/init/init_config.json \
    --steps hypothesis_1/experiment_1/init/steps.yaml \
    --run-dir hypothesis_1/experiment_1/run \
    --log-level DEBUG

Log output to the console.

Background Execution (Production Mode)¶

Important: When running in background, you must specify --log-file to capture logs.

python -m agentsociety2.society.cli \
    --config hypothesis_1/experiment_1/init/init_config.json \
    --steps hypothesis_1/experiment_1/init/steps.yaml \
    --run-dir hypothesis_1/experiment_1/run \
    --experiment-id "1_1" \
    --log-level INFO \
    --log-file hypothesis_1/experiment_1/run/output.log &

Checking Experiment Status¶

# 检查 pid.json 查看运行状态
cat hypothesis_1/experiment_1/run/pid.json

# 查看日志
tail -f hypothesis_1/experiment_1/run/output.log

Stopping Experiments¶

# 查找进程 ID
pid=$(jq -r '.pid' hypothesis_1/experiment_1/run/pid.json)

# 发送 SIGTERM 信号
kill $pid

Resuming Interrupted Experiments¶

The experiment writes checkpoints atomically at the end of each step. Even if the process crashes during a write, the existing checkpoint is not corrupted:

run_dir/SOCIETY.json – written once during initialization. It stores immutable full-run configuration such as agent_specs, env module types and kwargs, batch_size, and steps_hash.
run_dir/SOCIETY_STEP.json – per-step scalars: current time, step count, completed top-level step count, and terminated.
Each env module writes its state to run_dir/env/{module_type}/state/ENV_STATE.json. The module chooses the concrete format.

Use --resume to continue from the last completed step:

python -m agentsociety2.society.cli \
    --config hypothesis_1/experiment_1/init/init_config.json \
    --steps hypothesis_1/experiment_1/init/steps.yaml \
    --run-dir hypothesis_1/experiment_1/run \
    --resume \
    --log-file hypothesis_1/experiment_1/run/output.log &

On resume, the checkpointed env module types and kwargs, clock, and step counts take precedence over the config file. This avoids configuration drift. RunStep skips completed work according to the cursor; Ask, Intervene, and Questionnaire run again. If the steps.yaml hash does not match the checkpoint, the CLI prints a WARNING. You can inspect the restore point with:

cat hypothesis_1/experiment_1/run/SOCIETY_STEP.json   # step_count / completed_step_count

Note

Only env modules that override to_workspace() and restore() can restore dynamic state during resume; see Environment Modules. Modules that do not override them start in a fresh state after resume.

Configuration Files¶

init_config.json¶

The initialization configuration file defines the basic settings of the experiment:

{
    "agents": [
        {
            "agent_id": 1,
            "agent_type": "PersonAgent",
            "kwargs": {
                "id": 1,
                "name": "Alice",
                "personality": "friendly"
            }
        }
    ],
    "env_modules": [
        {
            "module_type": "SimpleSocialSpace",
            "kwargs": {
                "agent_id_name_pairs": [[1, "Alice"]]
            }
        }
    ],
    "codegen_router": {
        "final_summary_enabled": true
    }
}

steps.yaml¶

The step configuration file defines the execution steps of the experiment:

start_t: "2026-01-01T00:00:00"
steps:
  - type: ask
    question: "Introduce yourself to the group"

  - type: run
    num_steps: 1
    tick: 3600

  - type: intervene
    instruction: "Make everyone feel better"

Step Types¶

Type	Description
`ask`	Read-only query, do not modify the environment
`intervene`	Read and write operations can modify the environment
`step`	Execute a simulation step (specify tick duration)

Output Files¶

After running an experiment, the run-dir directory will contain:

hypothesis_1/experiment_1/run/
├── pid.json              # 进程信息（PID、启动时间、状态）
├── output.log            # 日志文件（如果指定了 --log-file）
├── replay/               # _schema.json + sharded JSONL replay datasets
├── trace/                # sharded JSONL trace spans
├── agents/               # agent workspaces
└── artifacts/            # 步骤产物（如果启用了 save_artifact）
    ├── step_1_ask.json
    ├── step_2_intervene.json
    └── ...

pid.json Format¶

{
    "pid": 12345,
    "start_time": "2026-03-20T10:30:00",
    "status": "running",
    "config": {
        "config_path": "/path/to/init_config.json",
        "steps_path": "/path/to/steps.yaml"
    }
}

Log Levels¶

Available log levels:

Level	Usage
`DEBUG`	Detailed debugging information, including LLM calls
`INFO`	General operating information (default)
`WARNING`	Warning message
`ERROR`	Error message
`CRITICAL`	Critical error

Example: Complete Workflow¶

# 1. 准备配置文件
mkdir -p my_experiment/init my_experiment/run
# ... 创建 init_config.json 和 steps.yaml ...

# 2. 前台测试运行
python -m agentsociety2.society.cli \
    --config my_experiment/init/init_config.json \
    --steps my_experiment/init/steps.yaml \
    --run-dir my_experiment/run \
    --log-level DEBUG

# 3. 后台生产运行
python -m agentsociety2.society.cli \
    --config my_experiment/init/init_config.json \
    --steps my_experiment/init/steps.yaml \
    --run-dir my_experiment/run \
    --experiment-id "exp_001" \
    --log-level INFO \
    --log-file my_experiment/run/output.log &

# 4. 监控运行
tail -f my_experiment/run/output.log

# 5. 完成后检查 replay catalog
python - <<'PY'
from agentsociety2.storage import ReplayReader
reader = ReplayReader("my_experiment/run/replay")
print([d["dataset_id"] for d in reader.load_dataset_catalog()])
reader.close()
PY