OASIS by CAMEL-AI: Open Source Million-Agent Social Media Simulator for Computational Social Science and Multi-Agent System Scaling Laws

OASIS serves as the definitive bridge between individual LLM reasoning and massive collective social dynamics, empowering researchers to simulate up to one million autonomous agents and observe emergent phenomena such as information spread, group polarization, and herd effects at unprecedented real-world scale.

Introduction

OASIS (Open Agent Social Interaction Simulations) constitutes a landmark open source social media simulator developed by the CAMEL-AI team. It enables the realistic modeling of digital societies comprising up to one million LLM-powered agents on platforms analogous to Twitter (X) and Reddit. Unlike prior small-scale agent tests limited to dozens or hundreds of participants, OASIS replicates macro-scale social phenomena by orchestrating decentralized, autonomous agents whose interactions produce verifiable emergent behaviors.

This million-agent simulation capability addresses a critical gap in computational social science AI: the inability of traditional models to capture scaling laws in multi-agent systems. By grounding agents in dynamic social networks and realistic content feeds, OASIS allows researchers to study information propagation, opinion polarization, and collective decision-making with statistical fidelity previously unattainable. The framework’s modular design further supports extension to custom platforms, establishing it as the premier tool for open source social media simulator applications in AI-driven social research.

Architecture Overview

The OASIS framework is engineered around five tightly integrated core components that collectively enable scalable, real-time social simulations while preserving interpretability and efficiency.

Environment Server

The Environment Server functions as the persistent state backbone, utilizing a relational database (SQLite by default) to manage all entities: user profiles, posts, comments, relationships (follows, mutes), action histories, and recommendation caches. It supports fully dynamic updates, allowing new users, posts, or network edges to be injected in real time without restarting the simulation. This component ensures platform-agnostic adaptability, whether modeling Twitter-style follower graphs or Reddit-style subreddit communities.

Recommendation System (RecSys)

The Recommendation System (RecSys) governs content visibility and information flow through dual algorithms: interest-based ranking (leveraging embeddings such as TwHIN-BERT for semantic similarity) and hot-score-based ranking (computed via upvotes, downvotes, and temporal decay). Users receive a tunable mix of in-network (followed) and out-of-network content, with cache sizes scaled dynamically according to agent population. This dual RecSys directly influences emergent dynamics such as viral spread or echo chambers.

Agent Module

The Agent Module equips each LLM-powered entity with a memory store (retaining past actions, observed posts, and reasoning traces) and an action executor. Agents employ Chain-of-Thought prompting to select contextually appropriate behaviors, ensuring interpretable decision-making at scale.

Time Engine

The Time Engine enforces temporal realism through a 24-dimensional hourly activity probability vector per agent, combined with discrete 3-minute time steps. Probabilistic activation schedules agents according to real-world diurnal patterns, while linear time mapping guarantees precise timestamping of actions and content creation.

Scalable Inferencer

The Scalable Inferencer provides distributed, asynchronous LLM inference across multiple GPUs (supporting vLLM for local deployment). Independent modules communicate via message queues, enabling load-balanced processing of up to one million concurrent agent requests with dynamic GPU allocation.

Together, these components deliver deterministic yet stochastic social evolution, directly supporting multi-agent system scaling laws analysis.

Key Features

OASIS distinguishes itself through its comprehensive action space, dynamic network topology, and production-grade recommendation mechanisms.

Agents support 23 distinct actions, including LIKE_POST, DISLIKE_POST, CREATE_POST, CREATE_COMMENT, FOLLOW, MUTE, SEARCH_POSTS, TREND, REFRESH, REPORT_POST, quote/repost variants, and DO_NOTHING. This rich vocabulary enables fine-grained modeling of real user behaviors on social platforms.

Dynamic networks evolve continuously as agents form or dissolve follows and mutes, preserving scale-free properties observed in real social graphs. The framework initializes networks from either real data seeds or procedurally generated profiles while maintaining core-ordinary user distributions.

Recommendation algorithms integrate seamlessly: interest-based matching for personalized discovery and hot-score prioritization for trending content. Both are cached and tunable, allowing researchers to isolate variables when studying polarization or herd effects. These features collectively position OASIS as the leading open source social media simulator for rigorous computational social science AI experiments.

Installation Guide

OASIS installs via the Python Package Index for immediate access to core functionality.

pip install camel-oasis

For full examples and data preparation, clone the repository:

git clone https://github.com/camel-ai/oasis.git
cd oasis

Set the OpenAI API key for default operation:

export OPENAI_API_KEY=<your_openai_key>   # Linux/macOS
# or
set OPENAI_API_KEY=<your_openai_key>     # Windows

For local model deployment (vLLM or Ollama), install additional dependencies and configure via CAMEL’s ModelFactory as demonstrated in the repository’s examples/twitter_simulation_vllm.py.

Prepare agent profiles by downloading sample data (e.g., user_data_36.json for testing) or generating large-scale profiles using the provided user-generation tutorial. Place profiles in ./data/reddit/ (or ./data/twitter/) as required by the platform generator. For million-agent experiments, leverage the Hugging Face dataset or custom generation scripts to produce realistic demographic and interest distributions while preserving network scaling laws.

Running a Simulation

A complete Twitter- or Reddit-like simulation follows a concise asynchronous workflow using the PettingZoo-style environment interface.

Begin by importing required modules and defining the model (OpenAI example shown; substitute vLLM configuration for local inference):

import asyncio
import os
from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType
import oasis
from oasis import (ActionType, LLMAction, ManualAction,
                   generate_reddit_agent_graph)

async def main():
    model = ModelFactory.create(
        model_platform=ModelPlatformType.OPENAI,
        model_type=ModelType.GPT_4O_MINI,
    )

    available_actions = [
        ActionType.LIKE_POST, ActionType.DISLIKE_POST,
        ActionType.CREATE_POST, ActionType.CREATE_COMMENT,
        ActionType.FOLLOW, ActionType.MUTE,
        ActionType.SEARCH_POSTS, ActionType.TREND,
        ActionType.REFRESH, ActionType.DO_NOTHING,
        # additional actions as needed
    ]

    agent_graph = await generate_reddit_agent_graph(
        profile_path="./data/reddit/user_data_36.json",
        model=model,
        available_actions=available_actions,
    )

    db_path = "./data/reddit_simulation.db"
    if os.path.exists(db_path):
        os.remove(db_path)

    env = oasis.make(
        agent_graph=agent_graph,
        platform=oasis.DefaultPlatformType.REDDIT,
        database_path=db_path,
    )

    await env.reset()

    # Example manual seed actions
    actions_1 = {
        env.agent_graph.get_agent(0): [
            ManualAction(ActionType.CREATE_POST, {"content": "Initial discussion on emerging AI trends"}),
        ]
    }
    await env.step(actions_1)

    # Autonomous LLM-driven simulation loop
    for step in range(50):  # Adjust for desired time steps
        actions = {agent: LLMAction() for _, agent in env.agent_graph.get_agents()}
        await env.step(actions)
        # Optional: query database or RecSys cache for metrics

    await env.close()

if __name__ == "__main__":
    asyncio.run(main())

For Twitter-style simulations, replace the generator with the appropriate Twitter variant and platform enum. Monitor progress through the SQLite database or integrated logging. Scale to thousands or millions of agents by increasing profile count and deploying the Scalable Inferencer across multiple GPUs with vLLM. Researchers can inject controlled seed posts or intervene via manual actions to test specific hypotheses on information spread or polarization.

Practical Considerations for Large-Scale Deployment

When targeting million-agent simulations, allocate sufficient GPU resources (approximately 27 A100-equivalent GPUs for 1M agents at 3-minute steps) and tune RecSys cache sizes proportionally. The Time Engine’s probabilistic activation ensures computational efficiency without sacrificing realism. Post-simulation analysis leverages the persistent database for metrics such as propagation depth, opinion divergence, and network centrality—directly supporting quantitative validation of multi-agent system scaling laws.

OASIS thus provides computational social science AI practitioners with a production-ready, fully auditable platform for exploring collective intelligence at societal scale. By combining the five core components with extensible action spaces and dual RecSys algorithms, it establishes new benchmarks for open source social media simulator research and paves the way for deeper understanding of digital society dynamics.