Research Skills

AgentSociety 2 includes a set of LLM-native research skills for automating scientific research workflows.

Overview

The research skills module provides the following capabilities:

  • Literature Search: Search and manage academic papers

  • Hypothesis Generation: Generate testable hypotheses from research questions

  • Experiment Design: Design complete experiment configurations

  • 论文撰写: 通过独立 paper-toolkit 工作流完成，不再由 agentsociety2.skills 包内模块提供

  • Data Analysis: Analyze experiment data and generate reports

The research skill modules publicly exposed in the current Python package are agentsociety2.skills.literature, agentsociety2.skills.hypothesis, agentsociety2.skills.experiment, agentsociety2.skills.analysis, and agentsociety2.skills.paper.

Claude Code Skills

Research workflows are primarily provided through Claude Code’s “skills-first” approach:

  • AgentSociety built-in research skills: packaged with the VSCode plugin and can be browsed in the plugin tree view (read-only).

  • Agent (Person) extended skills: managed by the backend /api/v1/agent-skills/*, supporting scanning/import/hot reload.

  • agentsociety-literature-search - Literature search

  • agentsociety-hypothesis - Assumption management (add, get, list, delete)

  • agentsociety-experiment-config - Experimental configuration generation and verification

  • agentsociety-run-experiment - Experiment execution and monitoring

  • agentsociety-analysis - Data analysis and cross-experimental synthesis

  • agentsociety-create-agent - Custom Agent generation and verification

  • paper-toolkit - 独立论文写作工具链入口

Note

The .agentsociety/bin/ags.py commands shown on this page are intended for an initialized workspace. If the current directory does not yet contain .agentsociety/, run the following first:

agentsociety-workspace init --target-dir .

An equivalent entry point is python -m agentsociety2.society.workspace init --target-dir ..

create-agent skill

agentsociety-create-agent Used to create or revise custom Agent types in the workspace. It is not a built-in cognitive skill of PersonAgent, but a development auxiliary skill in the research workflow: when the experiment requires an Agent class that does not currently exist, it is usually called by the agentsociety-experiment-config branch.

File location and scan rules:

  • New Agent modules should be placed under custom/agents/, for example custom/agents/research/lab_agent.py.

  • The scanner reads *.py in this directory, but skips files whose path fragment contains examples/.

  • It is recommended to have one main Agent class per file; when there are multiple AgentBase subclasses in a file, the scanner can also find it.

Base class selection:

Base class

Applicable scenarios

AgentBase

Simple experiments, games/benchmark scenarios, developers manage the status by themselves.

PersonAgent

Requires skills-first tool loops, workspace, checkpoint/WAL and persistent memory.

Local validation:

agentsociety-workspace init --target-dir .
PYTHON_PATH=$(grep "^PYTHON_PATH=" .env | cut -d'=' -f2)
PYTHON_PATH=${PYTHON_PATH:-.venv/bin/python}
$PYTHON_PATH .agentsociety/bin/ags.py create-agent --file custom/agents/my_agent.py
$PYTHON_PATH .agentsociety/bin/ags.py create-agent --file custom/agents/my_agent.py --json

The validator will check: the target file is a Python file, there is at least one class that directly inherits AgentBase or PersonAgent, ask / step / dump / load are all async def, the module can be imported dynamically, and the target class is not abstract class. After creation, execute Scan Custom Modules in the VS Code extension to let the backend rediscover the module.

Experiment workflow

The backbone of the research pipeline is:

literature-search → hypothesis → experiment-config → run-experiment → analysis → paper-orchestrator

The two core skills related to experiments are:

Skill

Main input

Main output

agentsociety-experiment-config

SIM_SETTINGS.json, existing Agent/Env/Dataset information

init_config.json、steps.yaml、config_params.py

agentsociety-run-experiment

init_config.json + steps.yaml

run/replay/, logs, artifacts, and pid.json

Recommended process:

  1. First confirm that the workspace already contains init_config.json, steps.yaml, and the required module information.

  2. During the experiment-config stage, scan modules first. If an Agent or environment module is missing, add the corresponding custom module and then scan again.

  3. Run experiment-config check or equivalent verification to confirm that the configuration and step files are available.

  4. Use run-experiment when starting the experiment; a log file must be specified for background execution to avoid losing verbose output.

  5. After the experiment is completed, check run/replay/_schema.json, logs, and artifacts before entering the analysis phase.

Analysis workflow

agentsociety-analysis handles data interpretation, charts, and report generation for completed experiments. Replay data lives in run/replay/ and can be read through ReplayReader / DuckDB. If _schema.json does not exist, return to run-experiment or the configuration repair phase.

Recommended process:

  1. Load context: Read hypothesis, experiment config, steps, and run metadata.

  2. Clarify the question: Clarify whether this analysis is to test hypotheses, explain anomalies, compare differences between groups, or generate a report.

  3. Explore data: List replay datasets and view the schema, number of rows, key fields, and missing values.

  4. Propose findings: Present testable findings first, then decide which charts are needed.

  5. Generate charts: A single experiment can have up to 5 charts by default; each chart must have a corresponding explanation in the report.

  6. Write report: Single-experiment output goes to presentation/hypothesis_{id}/, and cross-experiment synthesis output goes to synthesis/.

Commonly used commands:

$PYTHON_PATH .agentsociety/bin/ags.py analysis load-context --workspace . --hypothesis-id 1 --experiment-id 1
python - <<'PY'
from agentsociety2.storage import ReplayReader
reader = ReplayReader("hypothesis_1/experiment_1/run/replay")
for dataset in reader.load_dataset_catalog():
    print(dataset["dataset_id"], dataset["table_name"])
reader.close()
PY

Literature search service

agentsociety-literature-search Collect academic literature through a unified remote search service and save the results to the workspace papers/ directory. All configured data sources are retrieved by default: local, arxiv, crossref, openalex.

Configuration:

LITERATURE_SEARCH_MCP_URL=https://llmapi.fiblab.net/mcp/
LITERATURE_SEARCH_API_KEY=your-literature-search-key

Search command example:

$PYTHON_PATH .agentsociety/bin/ags.py literature-search "agent-based modeling social networks"
$PYTHON_PATH .agentsociety/bin/ags.py literature-search "urban mobility simulation LLM agents" --year-from 2020 --year-to 2026 --multi-query

Output convention:

  • papers/literature_index.json is a stable index, recording title, author, year, source, query, score and local file_path.

  • Each document is saved as papers/<title>_<timestamp>.md, which is the main local note cited in subsequent hypothesis, analysis and paper skills.

  • If the original PDF is to be downloaded, it should be placed in papers/full_texts/ and recorded in extra_fields.full_text.file_path; do not replace file_path in the index from Markdown notes to PDF.

  • Literature search does not bypass publisher access controls. PDF downloads only process open-access or user-authorized files. If no open PDF is available, local Markdown notes may be added together with the recorded source.

Python API

Research skills can also be called directly through the Python API.

Literature Skill

By default, the literature skill uses the configured LITERATURE_SEARCH_API_URL and LITERATURE_SEARCH_API_KEY to call the unified search service. It is recommended to use search_literature_and_save instead of calling the underlying search_literature directly: the former will drop the search results into the workspace, ensuring that subsequent Agent, Claude Code and paper writing skills can continue to reference these documents through local files.

from agentsociety2.skills.literature import search_literature_and_save, load_literature_index

# 搜索并保存文献（默认 10 篇、所有数据源，并更新 papers/literature_index.json）
result = await search_literature_and_save(
    workspace_path=Path("./workspace"),
    query="agent-based modeling social networks",
    year_from=2020,      # 可选：年份筛选
    year_to=2024,
    enable_multi_query=True,  # 可选：启用多查询模式
)

# 指定数据源搜索
await search_literature_and_save(
    workspace_path=Path("./workspace"),
    query="machine learning",
    sources=["local", "arxiv"],  # 可选：指定数据源
)

# 加载文献索引
index = load_literature_index(workspace_path=Path("./workspace"))

Save results:

  • Each search result will be saved as papers/<title>_<timestamp>.md. This Markdown file is a stable local literature note that contains title, search terms, year, journal, DOI/URL, abstract, author, and related content fragments.

  • papers/literature_index.json will be updated simultaneously. file_path in the index points to the local Markdown literature note, so the @cite button in the plug-in can be copied as @papers/<title>_<timestamp>.md for Claude Code or Agent to read.

  • When a search is run repeatedly, new local literature notes are generated and appended to the index, allowing context to be retained across different search rounds.

Full-text download (on demand by Claude/Agent):

The literature skill does not hardcode download policies in the Python API. The search results will try to retain meta-information such as doi, url, pdf_url, full_text_url, download_url, open_access, best_oa_location; Claude Code or Agent can download the open access original text on demand based on these clues.

Recommended download conventions:

  • The original PDF is located at papers/full_texts/*.pdf.

  • Priority is given to PDF direct links returned by the API; arXiv papers can be converted from /abs/<id> to https://arxiv.org/pdf/<id>.pdf.

  • The DOI is only used as a landing page clue, and there is no guarantee that the PDF will be obtained directly; if you need to download it, you should confirm that the final response is indeed a PDF.

  • After the download is completed, it can be recorded in extra_fields["full_text"] of the corresponding index entry:

    {
  "status": "downloaded",
  "file_path": "papers/full_texts/example.pdf",
  "source_url": "https://arxiv.org/pdf/2401.01234.pdf"
}

    If the open original text is not found, you can also record {"status": "no_candidate"} or {"status": "failed", "reason": "..."} to facilitate the plug-in page to display the status.

Note

Many CrossRef/OpenAlex results only offer a DOI or landing page, not necessarily an open PDF. Claude/Agent should not bypass publisher permissions or save HTML landing pages as PDFs.

Data sources: - local: RAGFlow local knowledge base - arxiv: arXiv preprint platform - crossref: CrossRef DOI metadata repository - openalex: OpenAlex scholarly graph (250 million+ papers)

Configuration: configure MCP in workspace .env. Claude mcp.json is not needed unless Claude should independently connect to the same gateway:

LITERATURE_SEARCH_MCP_URL=https://llmapi.fiblab.net/mcp/
LITERATURE_SEARCH_API_KEY=your-literature-search-key

Hypothesis Skill

from agentsociety2.skills.hypothesis import add_hypothesis, get_hypothesis, list_hypotheses

# 添加假设
add_hypothesis(
    workspace_path=Path("./workspace"),
    hypothesis="网络密度越高，信息传播速度越快"
)

# 列出假设
hypotheses = list_hypotheses(workspace_path=Path("./workspace"))

Experiment Skill

from agentsociety2.skills.experiment import (
    start_experiment, get_experiment_status,
    get_available_env_modules, get_available_agent_modules
)

# 获取可用模块
env_modules = get_available_env_modules()
agent_modules = get_available_agent_modules()

# 启动实验
await start_experiment(
    workspace_path=Path("./workspace"),
    hypothesis_id="1",
    experiment_id="1"
)

Analysis Skill

from pathlib import Path

from agentsociety2.storage import ReplayReader
from agentsociety2.skills.analysis import ContextLoader

workspace = Path("./workspace")
context = ContextLoader(workspace).load_context("1", "1")
reader = ReplayReader(workspace / "hypothesis_1" / "experiment_1" / "run" / "replay")
datasets = reader.load_dataset_catalog()
rows = reader.fetch_dataset_rows(
    reader.get_dataset_by_id("core.agent_profile"),
    limit=5,
)
reader.close()

The cross-experiment comparison no longer uses independent comprehensive skills, but is completed in Claude Code as Stage 5 of agentsociety-analysis.

论文写作

论文写作已从 agentsociety2.skills 包内移出，后续通过独立 paper-toolkit 工作流承载。核心模拟、实验、分析链路仍由本页上方的 research skills 提供；需要论文交付时，在完成分析报告和图表审计后进入 外部论文工具链。

Complete Workflow Example

Here’s a typical research workflow using Claude Code Skills:

  1. Define research topic - Edit TOPIC.md

  2. Literature search - Use /agentsociety-literature-search

  3. Create hypothesis - Use /agentsociety-hypothesis add

  4. Configure experiment - Use /agentsociety-experiment-config validate/prepare/run

  5. Run experiment - Use /agentsociety-run-experiment start

  6. Analyze results - Use /agentsociety-analysis

  7. 生成论文 - 使用独立 paper-toolkit 工作流

Configuration

Research skills use the same LLM configuration. Different models can be configured for specific skills via environment variables:

# 默认 LLM
export AGENTSOCIETY_LLM_MODEL="gpt-5.5"

# 代码生成（实验设计、分析）
export AGENTSOCIETY_CODER_LLM_MODEL="gpt-5.5"

# 高频操作（智能体生成）
export AGENTSOCIETY_NANO_LLM_MODEL="gpt-5.5"

Agent Skills

AgentSociety 2 also supports Agent Skills. The current PersonAgent uses a metadata-first, selected-only model: the LLM first sees each skill name / description, and only selected skills are activated and read. The only built-in skill is daily-guidance; the old observation / cognition / plan / memory skills have been removed. Custom skills live under custom/skills/, and scripts execute by default through the in-process entrypoint(argv, ctx).

  • daily-guidance - daily behavior, needs decay, and short-horizon action guidance

  • custom skills - workspace-level custom capabilities, activated on demand and able to access the agent workspace

See Agent Skills for details.

References