Installation¶

Requirements¶

AgentSociety 2 requires Python 3.11 or later.

Install from PyPI¶

The easiest way to install AgentSociety 2 is using pip:

pip install agentsociety2

This will install the core package. If you want to install with development dependencies:

pip install "agentsociety2[dev]"

For documentation dependencies:

pip install "agentsociety2[docs]"

Install everything:

pip install "agentsociety2[all]"

Install from Source¶

To install from the latest source code:

git clone https://github.com/tsinghua-fib-lab/agentsociety.git
cd agentsociety/packages/agentsociety2
pip install -e .

Verify Installation¶

To verify your installation, run:

import agentsociety2
print(agentsociety2.__version__)

You should see the version number printed.

Configuration¶

AgentSociety 2 requires LLM API credentials. Set the following environment variables:

Required Configuration

# Default LLM (Required - for most operations)
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"

Required Configuration

For specialized tasks, you can configure separate LLM instances. If these are not set, they will fall back to the default LLM configuration:

# Coder LLM (for code-related tasks)
# Falls back to: AGENTSOCIETY_LLM_API_KEY, AGENTSOCIETY_LLM_API_BASE
export AGENTSOCIETY_CODER_LLM_API_KEY="your-coder-api-key"      # Optional
export AGENTSOCIETY_CODER_LLM_API_BASE="https://api.openai.com/v1"  # Optional
export AGENTSOCIETY_CODER_LLM_MODEL="gpt-5.5"                    # Optional

# Nano LLM (for high-frequency, low-latency operations)
# Falls back to: AGENTSOCIETY_LLM_API_KEY, AGENTSOCIETY_LLM_API_BASE
export AGENTSOCIETY_NANO_LLM_API_KEY="your-nano-api-key"        # Optional
export AGENTSOCIETY_NANO_LLM_API_BASE="https://api.openai.com/v1"  # Optional
export AGENTSOCIETY_NANO_LLM_MODEL="gpt-5.5"                     # Optional

# Embedding model (for text embedding and semantic search)
# Falls back to: AGENTSOCIETY_LLM_API_KEY, AGENTSOCIETY_LLM_API_BASE
export AGENTSOCIETY_EMBEDDING_API_KEY="your-embedding-api-key"  # Optional
export AGENTSOCIETY_EMBEDDING_API_BASE="https://api.openai.com/v1"  # Optional
export AGENTSOCIETY_EMBEDDING_MODEL="text-embedding-3-large"   # Optional
export AGENTSOCIETY_EMBEDDING_DIMS="1024"                      # Optional

Data Directory

# Directory for storing agent data, memory and persistence files
# Default: ./agentsociety_data
export AGENTSOCIETY_HOME_DIR="/path/to/your/data"

Using a .env File

You can also create a .env file in your project directory:

# 推荐：从仓库根目录复制模板（若你在源码仓库内）
cp .env.example .env
# 然后编辑 .env 填入 API Key

# Required - LLM API Configuration
AGENTSOCIETY_LLM_API_KEY=your-api-key
AGENTSOCIETY_LLM_API_BASE=https://api.openai.com/v1
AGENTSOCIETY_LLM_MODEL=gpt-5.5

# Optional - Agent Behavior Configuration
AGENT_MODEL=gpt-5.5                  # Override model for agents
AGENT_CONTEXT_WINDOW=200000          # Model context window
AGENT_MAX_TOOL_ROUNDS=24             # Max tool loop rounds

# Optional - Specialized LLM instances (fallback to default)
AGENTSOCIETY_CODER_LLM_MODEL=gpt-5.5
AGENTSOCIETY_NANO_LLM_MODEL=gpt-5.5
AGENTSOCIETY_EMBEDDING_MODEL=text-embedding-3-large
AGENTSOCIETY_EMBEDDING_DIMS=1024
AGENTSOCIETY_HOME_DIR=./agentsociety_data

Note

Environment variable namespaces:

AGENTSOCIETY_LLM_*: global LLM API settings for model calls
AGENT_*: agent behavior settings such as context window size and tool-loop limits

LLM Dispatch and Local Concurrency Control¶

LLM dispatch is handled by serializable LLMClient instances. When each Ray task, env router actor, or driver process calls an LLM for the first time in its own event loop, it creates a local litellm Router and AdaptiveSemaphore. AdaptiveSemaphore adapts concurrency with AIMD based on recent latency and rate-limit errors.

# Ray CPU 预算（ray.init 的 num_cpus）：封顶每 tick 同时运行的 step_agent_batch
# Ray Task 数。默认取机器 CPU 核数；调低可为 driver / env actor / trace 留出空间。
# export AGENTSOCIETY_LLM_RAY_MAX_WORKERS=8

# 每个本地 LLMClient 的 AIMD 初始并发；无人工上下限，由 AIMD 依延迟/限流自由自调节。
export AGENTSOCIETY_LLM_RAY_CONCURRENCY=16

# 每个 step_agent_batch Ray Task 处理的 agent 数；task 数 = ⌈N / BATCH_SIZE⌉，
# 应 ≥ 同时运行的 worker 数才能打满 CPU（CLI --batch-size 可覆盖）。
# export AGENTSOCIETY_BATCH_SIZE=256

# AIMD “慢调用”判定
export AGENTSOCIETY_LLM_LATENCY_DEGRADE_FACTOR=4.0   # 相对退避因子（相对健康基线的倍数）
# export AGENTSOCIETY_LLM_SLOW_LATENCY_MS=8000       # 可选：绝对延迟 SLO（毫秒）

Note

AGENTSOCIETY_LLM_RAY_CONCURRENCY 只是 AIMD 的起点，没有人工上下限——每进程并发会自动逼近 API 真实容量并在延迟/限流恶化时回退。若网关有严格 QPS 上限可调低起点；实际总并发还取决于同时运行的 Ray task 数（AGENTSOCIETY_LLM_RAY_MAX_WORKERS）。

Supported LLM Providers¶

AgentSociety 2 routes model calls through LiteLLM. Default examples in the docs use an OpenAI-compatible Chat Completions API:

AGENTSOCIETY_LLM_API_BASE=https://api.openai.com/v1
AGENTSOCIETY_LLM_MODEL=gpt-5.5

If you use another LiteLLM-supported OpenAI-compatible gateway, keep the same variable names and set AGENTSOCIETY_LLM_API_BASE and the model name to values provided by that gateway.