OASIS: A Social Media Simulator Where Every User Is an LLM Agent

The Problem OASIS Targets: Social Dynamics You Cannot Re-run in the Wild

Studying how a rumor spreads, how a group polarizes, or how a herd forms on a real platform is difficult for reasons that have nothing to do with modeling. You cannot fork a live social network, you cannot reset it to the same initial state, and you cannot inject a controlled post and observe what a million accounts do with it. OASIS exists to make that experiment repeatable. The README states it is a simulator that uses large language model agents to mimic the behavior of up to one million users on platforms like Twitter and Reddit, and names information spread, group polarization and herd behavior as the phenomena it is built to study. The audience is therefore researchers and engineers who need a controllable stand-in for a social platform, not teams building a product feature. The distinction matters because OASIS is not a chatbot framework with a social wrapper. It is an environment with a database, a recommendation layer and an action vocabulary, and the README treats it as an experimental apparatus.

Agents, Actions and a Database: The Mechanism Visible in the README

The core loop in the README is short. You define a model with ModelFactory, list the ActionType values agents may use, and build an agent graph from a JSON profile file with generate_reddit_agent_graph, all inside an async main function. Two action channels exist: the README example imports both ManualAction and LLMAction from oasis. The README lists 23 actions overall, and the example's list of available actions begins with LIKE_POST and DISLIKE_POST. The README also states the simulator includes interest-based and hot-score-based recommendation algorithms, so content discovery is modeled, not assumed.

Getting It Running: Install, Key, Profile, Loop

The README gives four steps. Install with pip install camel-oasis. Export an API key, using export OPENAI_API_KEY=<insert your OpenAI API key> on Bash shells or set OPENAI_API_KEY=<insert your OpenAI API key> on Windows Command Prompt. Download an agent profile, with user_data_36.json from the repository's data/reddit directory as the named example, and place it in a local ./data/reddit folder. Then run the Python script. That script imports ModelFactory from camel.models and ModelPlatformType and ModelType from camel.types, which means OASIS depends on the CAMEL package for model plumbing and the model is chosen by platform and type constants rather than a raw client. The README example uses ModelType.GPT_4O_MINI. The graph is built by generate_reddit_agent_graph, imported from oasis. The example is written as async def main(), so the simulation loop is asynchronous.

The Token Bill Is the Scaling Limit, Not the Agent Count

The README claims support for up to one million agents. It also publishes a token consumption reference, and that table is the more useful number. For 100 agents, activation probability 1, one time step, on QWEN_TURBO, the measured reference is 335,600 input tokens and 16,750 output tokens. Read that carefully. One step, one hundred agents, every agent active. The input-to-output ratio is roughly twenty to one, which is what you would expect when each agent is fed platform context, available actions and history before emitting a short action. Scaling to a million agents at activation probability 1 is a linear multiplication of that figure per step, and the number of steps is your choice, not the framework's. The README's cost table covers 100, 1,000 and 10,000 agents for one time step at activation probability 0.1, so anyone planning a larger run has to extrapolate from those rows and validate them against their own model and prompt sizes. This is the honest constraint of the project. The code path to a million agents may exist; the budget to run a million agents for many steps is a separate question the README leaves to the reader.

Where OASIS Is the Wrong Tool

The most direct limitation is that the agents are language models, so the social behavior you observe is the behavior of a model conditioned on a profile, not of a person. If your research question depends on human cognitive biases that are not reproduced by the underlying model, a larger simulation will produce a more confident version of the same artifact. A second constraint is the action vocabulary. The README lists 23 actions. Any behavior outside that set cannot be expressed as an agent action without extending the framework, so a study of, say, content editing would need work the README does not describe. Finally, the README's quick start covers only Reddit: the profile path is data/reddit/user_data_36.json, and the graph builder is named generate_reddit_agent_graph. Twitter examples live in examples/, such as twitter_simulation_openai.py and twitter_interview.py.

How OASIS Differs from Generic Multi-Agent Frameworks

The obvious comparison is to a general multi-agent orchestration library such as CAMEL itself, which OASIS depends on for model creation. The difference is the environment. A generic agent framework gives you agents that talk to each other and leaves the world undefined: you write the message routing, you decide who sees what, and there is no notion of a feed, a follower graph or a trending list. OASIS inverts that. The platform is the fixed part, with a database, recommendation algorithms and a predefined action set, and the agents are the variable. That inversion is what makes the million-agent claim meaningful, because agents in a shared environment can be advanced in lockstep rather than through arbitrary pairwise conversations. It also means OASIS is worse than a generic framework for tasks that are not social-media-shaped. If you want two agents to collaborate on a document, the platform abstraction is overhead. The trade is control for realism: you give up the freedom to define arbitrary interactions and get a simulation whose dynamics are comparable across runs.

Maintenance, Licence and What the Release Cadence Suggests

OASIS is Apache-2.0, which permits commercial and academic use and modification, with the usual requirements around preserving notices and stating changes. That is a permissive choice and it matters for a research tool you may want to fork. The repository is not archived, and the release history shows v0.2.3 in June 2025, v0.2.5 in December 2025 and v0.2.6 on 2026-11-02, the same day as the last push. That pattern, patch releases separated by long gaps, is consistent with a research project that ships when a paper or a feature lands rather than on a fixed schedule. Practically, this means you should pin a version in your environment rather than track main, because the API in the README (generate_reddit_agent_graph, ActionType, LLMAction) is the kind of surface that changes between minor versions. Upgrading means re-running your simulation scripts against the new signatures and re-validating token consumption, since a change to prompt construction would move the numbers in the token table. Budget for reading release notes before each bump.

Editorial conclusion

Adopt OASIS if you are studying information spread, group polarization or herd behavior and you can budget for the token consumption the README documents (roughly 335,600 input and 16,750 output tokens for 100 agents at full activation over one step, on QWEN_TURBO). Do not adopt it if your question needs human behavioral grounding rather than LLM-generated behavior, or if you cannot run a per-step cost model before scaling past a few hundred agents. Verify first that the platform you need is covered: the README quick start uses a Reddit profile and generate_reddit_agent_graph, while examples/ includes Twitter scripts such as twitter_simulation_openai.py.

Frequently asked questions

Official sources

1. camel-ai/oasis on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases