AI Social Scientist User Guide

AI Social Scientist is the interactive research assistant for AgentSociety 2, provided as a VSCode extension that offers visual configuration, backend management, and research orchestration capabilities. It supports two usage modes:

  • Online Workspace: Use directly through the web platform, no local installation required, ideal for quick onboarding.

  • Local Development: Install the extension and dependencies locally, suitable for advanced users who need a customized environment.

Online Workspace

We recommend using the online platform for experiments. The platform comes pre-installed with the agentsociety2 library, the AI Social Scientist extension, and the Claude Code CLI.

Platform URL: https://agentsociety2.fiblab.net/

Registration and Login

  1. Open the platform homepage and click “Login”.

Platform login page

  1. If you don’t have an account, click “Register” to complete the registration process. Users with an existing FIBLAB account can log in directly.

Registration page

Note

After logging in, you may need to contact the platform administrator to approve your account permissions. Once approved, refresh the page.

Create a Workspace

  1. Go to the workspace management page, click “Create Workspace”, enter a name and confirm.

Create a Workspace

  1. Wait for the workspace status to change from “Creating” to “Running”.

Workspace running

  1. Click on the workspace to view Coder credentials, free LLM API endpoint, and API Key information. Please save these securely.

Workspace credentials and API information

  1. Copy the Coder credentials shown at the top of the page, then click “Open” to enter the development environment.

Coder login

  1. On the Coder page, select code-server (recommended) or VS Code Desktop to open the development environment.

Select code-server or VSCode Desktop code-server interface

Local Installation

Prerequisites

  • Operating System: macOS or Linux (Windows users should use WSL)

  • Python: 3.11 or higher. We recommend using uv for management

# 安装 uv（macOS/Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh

Install agentsociety2

# 使用 uv
uv venv && source .venv/bin/activate
uv pip install agentsociety2

# 或使用 pip
pip install agentsociety2

Important

Make sure you are installing the latest version. Check the current latest version at: https://pypi.org/project/agentsociety2/

Install the AI Social Scientist Extension

  1. Download the latest VSIX file from the Release page.

  2. In VSCode, press Cmd/Ctrl + Shift + P, type Extensions: Install from VSIX....

  3. Select the downloaded VSIX file to complete the installation.

Configure the Coding Agent

When the extension initializes a workspace, it automatically syncs AI Social Scientist skills to the .claude/skills/ directory. You can also click “Sync AI Assistant Resources” in the sidebar to sync manually.

Sync AI assistant resources

Claude Code (recommended):

npm install -g @anthropic-ai/claude-code

When configuring a third-party proxy service, create ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_BASE_URL": "YOUR_BASE_URL",
    "ANTHROPIC_MODEL": "claude-sonnet-4-6"
  }
}

也可以通过 AI Social Scientist 插件的 高级配置 → Claude / Codex 路由 打开图形化配置页，使用内置的本地 AI Gateway 统一管理供应商（见下文）。

本地 AI Gateway

AI Gateway 是插件内置的本地 HTTP 代理，运行在 127.0.0.1:15721-15820 端口范围内。它拦截 Claude Code 和 Codex CLI 的 API 请求，将其转发到你 配置的上游供应商，并自动完成协议格式转换与模型名映射。

它的核心价值在于：让你用任意第三方 LLM 供应商（OpenAI 兼容、智谱、 DeepSeek 等）来驱动 Claude Code / Codex，无需每个供应商都去申请 官方 Anthropic / OpenAI 账号。

简单说，请求流是这样的：

Claude Code ─┐                         ┌─► Anthropic 原生供应商
(Anthropic   │   本地 AI Gateway        │     (直通)
 协议)       ├─► 127.0.0.1:<port>    ───┤
             │   · 协议翻译            ├─► OpenAI 兼容供应商
Codex CLI  ──┘   · 模型名映射          │     (翻译为 Chat Completions)
(Responses      · 故障转移 / 用量统计   │
 协议)                                └─► …更多供应商

Gateway 对 Claude Code 始终呈现一个标准的 Anthropic Messages 端点 （/v1/messages），对 Codex 始终呈现一个标准的 OpenAI Responses 端点 （/v1/responses）。因此这两个 CLI 不需要知道背后其实是哪家供应商、 哪种协议——Gateway 会在中间完成所有转换。

供应商与路由

Gateway 提供一个**共享供应商池**——供应商只保存一份，但可以在供应商 卡片上分别「激活」到 Claude Code 或 Codex CLI 角色：

  • Anthropic 原生供应商 （如 api.anthropic.com、DeepSeek 的 /anthropic 端点）：直接服务 Claude Code，请求直通转发。

  • OpenAI 兼容供应商 （如 api.openai.com、智谱 paas/v4、DeepSeek /v1）：可同时服务 Claude Code 和 Codex CLI。 - 服务 Claude Code 时，Gateway 会把 Claude Code 发出的 Anthropic Messages 请求实时翻译成 OpenAI Chat Completions，再把返回的 SSE 流翻译回去。 - 服务 Codex CLI 时，Gateway 会把 Codex 发出的 OpenAI Responses 请求翻译成 OpenAI Chat Completions。

添加供应商时需要选择正确的接口类型：

  • 若供应商提供 Anthropic Messages 协议（/v1/messages），选择 Anthropic。

  • 若供应商只提供 OpenAI Chat 协议（/v1/chat/completions），选择 OpenAI 兼容。

内置预设已覆盖常见供应商（Anthropic、DeepSeek、智谱、Kimi、MiniMax、 火山引擎、OpenRouter、阿里百炼、Moonshot、SiliconFlow 等），可直接选用。

协议格式转换

Gateway 在转发过程中会做以下转换，确保第三方模型的行为尽可能贴近原生体验：

  • 请求方向：system 提示、tools 工具定义、tool_choice、 thinking``（扩展思考，会映射为 ``reasoning_effort）、max_tokens 等都会按目标协议规范化。

  • 响应方向：第三方模型的 reasoning_content``（思考过程）会被翻译成 Anthropic 的 ``thinking 内容块；tool_calls 会被翻译成 tool_use 内容块，保证 Claude Code 能正确识别工具调用（这是保证工具调用 / 多轮 对话不中断的关键）。

  • 模型名映射：Claude Code 发出的 claude-sonnet-* / claude-opus-* / claude-haiku-* / claude-fable-* 会自动映射为供应商配置的对应角色 模型；[1M] 等本地能力标记会在转发前剥离，避免泄漏给供应商。

故障转移与用量统计

  • 故障转移：可为 Claude 和 Codex 分别开启多供应商优先级，单点失败后 自动切换到下一个候选供应商，并由断路器（circuit breaker）抑制反复 失败的上游。切换成功后会更新活跃供应商，UI 会同步反映。

  • 用量统计：面板按天展示请求趋势，区分 Claude 与 Codex 来源，支持 7 天 / 30 天 / 全部 筛选。会分别统计输入、输出、缓存读取、缓存写入 token。

  • 费用估算：定价来源优先级为 自定义 > 远程（OpenRouter / LiteLLM）> 内置， 远程定价 24 小时缓存。对 Codex / OpenAI 兼容记录，会先从可计费输入中 扣除缓存命中再计费，缓存读取单独计价。

  • 状态栏：启用 Gateway 后，VS Code 状态栏会显示 Gateway 端口及路由状态（Claude / Codex / Claude + Codex），点击可打开后端状态菜单或回到配置页。

Gateway 排错

  • 查看日志：打开 AI CLI Gateway 输出通道，每行记录请求路径、 上游地址、HTTP 状态码、耗时与模型名，形如 POST /v1/messages → 200 (4183ms) [deepseek-v4-pro] [https://...]。

  • 日志显示 ``in:0 out:0``：表示该次响应未提取到 token 用量，常见于流 式响应提前中断或上游未返回 usage 字段。

  • 请求中断 / 对话到一半停止：通常是对话中触发了工具调用，但旧版本 网关未正确翻译 tool_calls。请确认使用的是已修复该问题的扩展版本。

  • 403 key_model_access_denied：上游拒绝该 API Key 访问请求的模型， 说明模型名映射未生效或供应商未开通该模型权限，请在供应商卡片核对模型。

  • 手动校验健康状态：curl http://127.0.0.1:<port>/health 应返回 {"ok": true, ...}。

You can also install the Claude Code VSCode extension. Clicking “AI Chat” in the extension sidebar will open the Claude Code chat panel directly:

Claude Code VSCode integration

Note

Skills synced to .claude/skills/ are automatically recognized by Claude Code and Cursor. The extension also creates a symbolic link for CodeX (.codex) automatically — no manual action needed.

Environment Configuration

Create a New Workspace

In the online workspace, create a new folder in the left file tree as your workspace (e.g., demo), then open it via File → Open Folder.

New workspace folder

Configuration Wizard

首次打开工作区且尚未完成初始配置时，扩展会**自动打开配置页**并显示 **5 步向导**（不会同时弹出额外的欢迎 Toast）。向导步骤如下：

步骤 1：仿真 LLM — 填写默认大模型 API 信息并点击验证：

Parameter

Description

Required

LLM API Key

API key for the LLM service, used for default conversations, analysis, and other core features

Yes

LLM API Base URL

Base URL of the API, e.g., https://api.openai.com/v1

Yes

LLM Model Name

Model name to use, default gpt-5.5

Yes

验证通过后会自动进入下一步。AgentSociety 支持任何 OpenAI 接口兼容的大模型 API。

步骤 2：保存配置 — 查看摘要并保存到工作区 .env。必须包含有效的 API Key 才会标记为「已完成初始配置」。

步骤 3：启动后端 — 选择或自动检测 PYTHON_PATH，点击「保存并启动后端」。成功后状态栏显示 Backend 端口；向导会自动进入可选步骤。

Parameter

Description

Recommended

Python Path

Python 运行环境路径，留空则自动检测已安装 agentsociety2 的环境

uv sync 后的 .venv/bin/python

步骤 4：文献检索（可选） — 配置学术文献 MCP 网关，可跳过。

步骤 5：CLI 网关（可选） — 配置 Claude Code / Codex 本地 AI Gateway 供应商与路由，可跳过。

完成或退出向导后，可随时通过配置页「打开向导」重新进入。向导退出状态保存在扩展全局状态中（非 Webview localStorage）。

高级配置

在配置页切换到完整模式后，可展开 专用与运行 标签页，按需填写（均可留空，沿用默认 LLM）：

  • 专用模型：代码生成（Coder）、Embedding

  • Python 环境：扫描并选择解释器

  • 文献检索：MCP URL 与 API Key

  • Claude / Codex 路由：本地 AI Gateway 供应商池

Parameter

Description

Recommended

Embedding Model

Text embedding model

text-embedding-3-large (dimensions 1024)

Literature Search Service

Academic literature search MCP gateway URL

Platform URL: https://agentsociety2.fiblab.net/

状态栏与输出

  • 状态栏：Backend（端口）、Gateway（路由状态/成功率）、LLM（验证通过时显示模型名）

  • 输出通道：AI Social Scientist``（主通道，含 ``[API] [Chat] 等前缀）、AI Social Scientist Backend、AI CLI Gateway

  • 扩展默认启用 python.terminal.useEnvFile，集成终端会自动加载工作区 .env

Start the Backend

配置向导第 3 步或配置页中的「保存并启动后端」会自动保存配置并启动后端服务。也可通过状态栏 Backend 菜单或命令面板启动。从配置页启动时，成功/失败提示仅在配置页内显示，避免与命令 Toast 重复。

右下角状态栏显示后端运行状态（含端口号）表示启动成功。

Start Research

Initialize Workspace

After the backend starts successfully, click “Initialize Workspace” in the extension panel, enter a research topic (e.g., “polarization”) and press Enter. The system will automatically create TOPIC.md and the relevant directory structure.

Initialize Workspace

TOPIC.md is the central document throughout the research process. You can edit it at any time to add research descriptions, background information, and research directions.

Collaborate with Claude Code

Click the “AI Chat” button in the extension sidebar to enter Claude Code:

Claude Code login

Once in the chat interface, describe your research needs in natural language. The platform encapsulates key research operations as Skills, which Claude Code automatically recognizes and invokes.

Claude Code chat interface

Recommended Research Workflow

We recommend following the sequence below, but each stage can be revisited or skipped at any time:

初始化研究话题 → 文献检索 → 假设管理 → 实验配置
     │
     ▼
运行实验 → 数据分析 → 综合报告 → 论文生成

For details on each stage, see Research Skills.

Workspace Directory Structure

As research progresses, the workspace will gradually form the following structure (no manual creation needed):

工作区/
├── TOPIC.md                          # 研究叙事中心文档
├── .env                              # 环境配置
├── papers/
│   ├── literature_index.json         # 文献索引
│   └── literature/                   # 文献摘要
├── user_data/                        # 用户数据
├── datasets/                         # 数据集
├── hypothesis_1/
│   ├── HYPOTHESIS.md                 # 假设描述
│   ├── SIM_SETTINGS.json             # 模块配置
│   ├── experiment_1/                 # 实验 1（对照组）
│   │   ├── init/
│   │   │   ├── init_config.json      # 智能体与环境配置
│   │   │   └── steps.yaml            # 仿真步骤
│   │   └── run/                      # 运行产出
│   └── experiment_2/                 # 实验 2（处理组）
├── presentation/                     # 分析报告
│   └── hypothesis_1/
│       └── experiment_1/
│           ├── report.md
│           ├── report.html
│           └── charts/
├── synthesis/                        # 综合报告
└── custom/                           # 自定义模块
    └── envs/

FAQ

code-server shows unhealthy

When creating a workspace for the first time, the backend service may still be starting. Wait a moment and refresh the page until the status changes to a green “Running”. If the issue persists, try restarting the workspace.

502 error when opening code-server

The backend service has not started correctly. Please wait and refresh the page. If the problem persists, check the backend logs or contact the platform administrator.

Local Python environment path issues

The online platform has Python pre-installed. For local usage (especially with virtual environments created via uv), you need to specify the correct Python path in the advanced configuration:

source .venv/bin/activate
which python3

Enter the output path in the Python path field of the “Backend Service” step in the configuration wizard.

Experiment execution failed

Common causes:

  • LLM API connection failure: Check the API configuration in .env

  • Module instantiation failure: Check that the parameters in init_config.json match the module requirements

  • Insufficient memory: Reduce the number of agents or simulation steps

For more CLI usage, see Command Line Interface. For research skills, see Research Skills.