Core Concepts

This section describes the system structure and terminology of AgentSociety 2. The AgentSociety 2 section “Research Background and Platform Positioning” covers motivation from paradigms and collaboration; here the focus is implementation-level component relationships.

Architecture Overview

AgentSociety 2 is built around three main components:

• Agents: Autonomous entities that use LLMs to interact with environments

• Environment Modules: Composable components that define simulation rules

• AgentSociety: Coordinator that manages agents and environments

Agents do not directly own runtime objects such as env, LLM, trace, or replay. Instead, they receive shared service handles through a ServiceProxy container; environment routing runs in a dedicated Ray actor. See Architecture and Scalability.

Interrupt recovery: agent, env-module, and society state needed for recovery is written atomically into the workspace. Agents use AGENT.json; env modules usually use state/ENV_STATE.json; society uses immutable SOCIETY.json plus the per-step SOCIETY_STEP.json. The CLI --resume option can continue an experiment from the interruption point; see Command Line Interface. This mechanism is independent from replay. Replay is append-only time-series data for analysis; see Storage and Result Access.

Full System Architecture

Agent-Environment Interface

Agents interact with environments through two main methods:

• ask(): Query or observe environment state

• intervene(): Modify environment state

This unified interface allows agents to communicate naturally with any environment module.

The @tool Decorator

Environment modules expose their functionality through the @tool decorator:

from agentsociety2.env import EnvBase, tool

class MyEnvironment(EnvBase):
    @tool(readonly=True, kind="observe")
    def get_weather(self, agent_id: int) -> str:
        """Get current weather for agent."""
        return f"Weather for agent {agent_id}"

    @tool(readonly=False)
    def set_temperature(self, temp: int) -> str:
        """Set temperature."""
        self._temperature = temp
        return f"Temperature set to {temp}"

Parameters:

• readonly (bool): Whether the function modifies state * True = read-only, can be used in queries * False = modifies state, can be used in interventions

• kind (str): The type of tool * "observe": Single-parameter observations (requires readonly=True) * "statistics": Aggregate queries (no parameters, requires readonly=True) * None or omitted: Regular tool (any signature, any readonly value)

CodeGenRouter

CodeGenRouter connects agents to environment modules by:

1. Extracting tool signatures from environment modules

2. Generating code to call appropriate tools based on agent input

3. Safely executing code in a sandboxed environment

4. Returning results to the agent

This approach allows agents to interact with any combination of environment modules without code changes.

Router Selection

RouterBase has multiple implementations that can be swapped as needed:

• CodeGenRouter (default): generates call code and executes it in a sandbox, with AST guards and caching.

• ReActRouter: ReAct-style tool selection.

• PlanExecuteRouter: plan first, then execute.

• TwoTierReActRouter / TwoTierPlanExecuteRouter: two-tier routing for large tool sets.

• SearchToolRouter: selects tools through retrieval.

In production, routing runs in a dedicated Ray actor (EnvRouterProxy); see Architecture and Scalability.

Tool Categories

Observation Tools (readonly=True, kind="observe")

Agent-specific observations with a single agent_id parameter:

@tool(readonly=True, kind="observe")
def get_agent_location(self, agent_id: int) -> str:
    """Get current location of agent."""
    return f"Agent {agent_id} is at location X"

Statistics Tools (readonly=True, kind="statistics")

Aggregate queries with no parameters (except self):

@tool(readonly=True, kind="statistics")
def get_average_happiness(self) -> str:
    """Get average happiness of all agents."""
    avg = sum(self.happiness.values()) / len(self.happiness)
    return f"Average happiness: {avg}"

Regular Tools

General-purpose tools with any signature:

@tool(readonly=False)
def set_happiness(self, agent_id: int, value: float) -> str:
    """Set happiness level for agent."""
    self.happiness[agent_id] = value
    return f"Set agent {agent_id}'s happiness to {value}"

Tool Category Hierarchy

Agent-Environment Interaction Flow