agentsociety-scan-modules

name	agentsociety-scan-modules
version	1.0.0
description	Use when agent or environment module names are unknown, need validation, or the user asks which modules are available in the workspace.

Scan Modules

Scan and query available agent classes and environment modules in the AgentSociety2 workspace.

When to Use

• User asks what agents or environment modules are available
• Need to find a module by name or keyword before configuring an experiment
• Preparing module data for hypothesis generation or experiment-config
• Validating that a custom module is loadable

Do NOT use when:

• You already know the exact class name and just need to write code that imports it
• The task is about creating a new module (use create-agent instead)

Quick Reference

Use the Python interpreter from .env. See CLAUDE.md for setup.

Run commands from the workspace root through .agentsociety/bin/ags.py.

Action	Command
List all modules	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules list
List short names	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules list --short
Filter by type	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules list --type agent (or env)
Custom modules only	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules list --custom-only
Full descriptions	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules list --full
JSON output	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules list --json
Module info	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules --workspace PATH info --type TYPE --name NAME
Search by keyword	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules --workspace PATH search --keyword KEYWORD [--type TYPE]
Export to JSON	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules --workspace PATH export --output FILE
Validate module	$PYTHON_PATH .agentsociety/bin/ags.py scan-modules --workspace PATH validate --type TYPE --name NAME

Common options: --workspace PATH to target a specific workspace directory. scan_modules.py now accepts --workspace either before or after the subcommand, but prefer the form before the subcommand in examples for consistency.

info

$PYTHON_PATH .agentsociety/bin/ags.py scan-modules --workspace PATH info --type TYPE --name NAME [--json]

Shows: full description, constructor parameters, file location, import path, prefill parameters.

search

$PYTHON_PATH .agentsociety/bin/ags.py scan-modules --workspace PATH search --keyword KEYWORD [--type TYPE] [--json]

export

$PYTHON_PATH .agentsociety/bin/ags.py scan-modules --workspace PATH export --output FILE

validate

$PYTHON_PATH .agentsociety/bin/ags.py scan-modules --workspace PATH validate --type TYPE --name NAME

Checks that the module can be imported and instantiated.

Module Locations

• Built-in Agents: packages/agentsociety2/agentsociety2/agent/person.py
• Built-in Envs: packages/agentsociety2/agentsociety2/contrib/env/
• Contrib Agents: packages/agentsociety2/agentsociety2/contrib/agent/
• Custom Modules: <workspace>/custom/agents/ and <workspace>/custom/envs/

Note: packages/agentsociety2/agentsociety2/custom/ contains template files copied to workspace during init — it is not a runtime module location.

Module Type Identifiers

Use the class name as the type identifier:

Class Name	Type Identifier
PersonAgent	PersonAgent
SimpleSocialSpace	SimpleSocialSpace
PrisonersDilemmaEnv	PrisonersDilemmaEnv

Common Mistakes

Mistake	Fix
Using snake_case names as type identifiers (e.g., person_agent)	Use the exact class name (e.g., PersonAgent)
Skipping validate before relying on a module	Always run validate after discovering a module you plan to use
Searching with wrong --type filter	Use --type agent for agents, --type env for environments; omit --type to search both

Pipeline Position

Predecessors: None Successors: hypothesis, experiment-config Required Sub-Skills: None

Called as an optional discovery and validation helper by hypothesis and experiment-config.