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 step function, 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 build an agent graph from a JSON profile file, hand it a list of ActionType values and a model, and pass both to oasis.make together with a platform constant and a database path. That call returns an environment. You then call await env.reset() to initialize, await env.step(actions) to advance one time step, and await env.close() when finished. The database path is not incidental. The README example deletes ./data/reddit_simulation.db before constructing the environment, which implies the simulation state persists on disk across a run and that a stale file would otherwise carry state into a fresh experiment. Two action channels exist. ManualAction lets you script a specific agent's behavior with explicit arguments, for example creating a post with a given content string or commenting on a post identified by post_id. LLMAction hands the decision to the model. In the README example the first step mixes both: two agents post and comment manually, then the second step converts every agent in the graph to LLMAction(). The README lists 23 actions overall, with the example enumerating thirteen for Reddit, including LIKE_POST, DISLIKE_POST, CREATE_POST, CREATE_COMMENT, SEARCH_POSTS, SEARCH_USER, TREND, REFRESH, DO_NOTHING, FOLLOW and MUTE. The README also states the simulator includes interest-based and hot-score-based recommendation algorithms, which is what makes SEARCH_POSTS and TREND meaningful rather than decorative: 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, which takes profile_path, model and available_actions. The environment is built by oasis.make with agent_graph, platform set to oasis.DefaultPlatformType.REDDIT, and database_path. Individual agents are retrieved with env.agent_graph.get_agent(0) for a specific index or env.agent_graph.get_agents() for all of them, and the README uses the latter in a dict comprehension to assign LLMAction() to every agent at once. The whole thing runs inside asyncio.run(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 does not publish a cost table for larger configurations, so anyone planning a large run has to extrapolate from the 100-agent row and validate it 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 and the example shows thirteen for Reddit. Any behavior outside that set cannot be expressed as an agent action without extending the framework, so a study of, say, direct messaging or content editing would need work the README does not describe. Third, the persistence model cuts both ways. Because state lives in a SQLite-style database file at database_path, reproducibility depends on managing that file deliberately, which is exactly why the README deletes it before each run. Forget that step and you are resuming an old simulation while believing you started a new one. Finally, the platform coverage is narrower than the marketing line suggests. The README says platforms like Twitter and Reddit, but the only worked example is Reddit, the profile path is data/reddit/user_data_36.json, and the graph builder is named generate_reddit_agent_graph. Treat Twitter support as something to confirm in the documentation rather than assume.

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, a step function, 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.2 and v0.2.3 within two days of each other in June 2025, then v0.2.5 in December 2025, with the last push in August 2026. That pattern, clustered patch releases followed by a longer gap, 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 (oasis.make, generate_reddit_agent_graph, env.step) 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. The README does not describe a deprecation policy, so 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 actually implemented: the README example uses REDDIT and mentions Twitter, but the documented action list in that example is Reddit-shaped, so confirm the Twitter action set in the docs before committing.

Official sources

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