camel-ai/oasis: running social media simulations with LLM agents

What OASIS simulates, and who the simulator is for

OASIS builds a synthetic social platform where every account is driven by a large language model. The README describes it as "a scalable, open-source social media simulator that incorporates large language model agents to realistically mimic the behavior of up to one million users on platforms like Twitter and Reddit." The stated research targets are information spread, group polarization and herd behaviour.

The audience is narrow and academic. If you need to observe how a rumour moves through a follower graph, or how a recommendation feed changes what a population sees over time, this gives you a controllable environment. If you want a chatbot framework, or a way to test prompts against a single model, OASIS is the wrong layer: it is concerned with populations, feeds and step-by-step platform state, not with one conversation.

The repository ships a dataset on Hugging Face and a paper on arXiv, which tells you the intended output is a reproducible experiment, not a deployed service. The examples directory carries scenario files such as twitter_misinforeport.py and twitter_interview.py, so the maintainers treat specific research questions as first-class starting points.

The agent graph, the database and the step loop

The core abstraction is an agent graph. generate_reddit_agent_graph takes a profile path, a model and the list of available actions, and returns the graph. Each agent is reachable through env.agent_graph.get_agent(id) or iterated with env.agent_graph.get_agents(). That graph is passed to oasis.make together with a platform type and a database path.

State lives in a SQLite file. The README example deletes ./data/reddit_simulation.db before constructing the environment, which is the simplest way to guarantee a clean run. Simulation therefore advances in discrete steps rather than in real time: you call await env.reset(), then await env.step(actions) as many times as your scenario needs, then await env.close().

Actions come in two flavours. ManualAction carries explicit action_args, so you can script a known post or comment into the timeline. LLMAction hands the decision to the model. Mixing them in one step is supported: the README's first step injects a post and two comments manually, and the second step assigns LLMAction() to every agent in the graph. That split is the most useful design decision in the API, because it lets you seed a scenario deterministically and then let the population react.

The README lists 23 actions across following, commenting and reposting, and the quick-start example enumerates thirteen of them: LIKE_POST, DISLIKE_POST, CREATE_POST, CREATE_COMMENT, LIKE_COMMENT, DISLIKE_COMMENT, SEARCH_POSTS, SEARCH_USER, TREND, REFRESH, DO_NOTHING, FOLLOW and MUTE. Recommendation is built in, with interest-based and hot-score-based algorithms described as the two options.

Installing camel-oasis and running a first two-step simulation

The package is on PyPI under the name camel-oasis, not oasis. Installing it pulls camel-ai as a dependency, which is where ModelFactory and the ModelPlatformType and ModelType enums come from.

pip install camel-oasis

The model credentials are read from the environment. The README gives the Bash form and the Windows Command Prompt form separately.

export OPENAI_API_KEY=<insert your OpenAI API key>

You also need a profile file. The README points at data/reddit/user_data_36.json in the repository and suggests placing it in a local ./data/reddit folder. Note the Python version constraint in pyproject.toml: python = ">=3.10.0,<3.12". A 3.12 interpreter will not satisfy it.

The smallest useful run creates the model, builds the graph, opens the environment, injects scripted actions and then lets the models act.

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)

The environment is created against the Reddit platform and a database path. Deleting the old file first is what the README does, so a rerun does not inherit prior state.

env = oasis.make(
    agent_graph=agent_graph,
    platform=oasis.DefaultPlatformType.REDDIT,
    database_path="./data/reddit_simulation.db",
)
await env.reset()

In the first step the README attaches ManualAction objects to two agents: one creates a post with content "Hello, world!" and a comment on post_id "1", the other comments on the same post. In the second step every agent gets LLMAction(). After the steps, await env.close() shuts the environment down. The expected observable result is a database containing the seeded post and comments plus whatever the model-driven agents chose to do with them.

What the token table tells you, and what it does not

The README includes a measured token consumption reference for a deliberately small configuration: 100 agents, activation probability 1, one time step, model QWEN_TURBO. That run consumed 335,600 input tokens and 16,750 output tokens.

The arithmetic is worth doing before you plan anything larger. One hundred agents at one step cost roughly 336k input tokens. The README also advertises support for up to one million agents. Those two numbers sit in the same document without a cost model connecting them, and that gap is the single biggest practical risk in adopting OASIS. Activation probability is the lever that makes large populations affordable, because agents below the threshold do not call the model in a given step, but the README does not document how the sampling interacts with the recommendation algorithms or with the action distribution.

There is a second, quieter cost: every step that uses LLMAction writes to the SQLite database. Long runs accumulate state on disk, and the README does not describe a pruning or checkpoint policy. If your experiment runs for thousands of steps, plan for the database file, not just the API bill.

Where OASIS breaks down or is simply the wrong tool

The Python constraint is hard, not advisory. pyproject.toml declares python = ">=3.10.0,<3.12", so a modern interpreter will not install the package cleanly. That is a real friction point for anyone on a current base image.

The dependency list is heavy and pinned to exact versions: pandas 2.2.2, igraph 0.11.6, cairocffi 1.7.1, sentence-transformers 3.0.0, unstructured 0.13.7, neo4j 5.23.0, mcp 1.29.0, camel-ai 0.2.90. Several of these are unrelated to simulation itself, which suggests the package is assembled from a broader toolkit rather than trimmed to its own needs. Expect resolution conflicts when you combine it with an existing environment.

Reproducibility is the deeper limitation. LLM-driven agents are not deterministic across providers or model versions, and the README does not document a seed mechanism for the model calls. Two runs of the same script can diverge, which is awkward for a tool whose stated purpose is studying social phenomena. The database gives you a record of what happened, but not a guarantee that it will happen again.

Finally, OASIS models platforms, not people. If your question is about a single user's behaviour, or about a workflow that has nothing to do with feeds and followers, the abstraction is pure overhead.

How OASIS differs from general multi-agent frameworks

The obvious comparison is a general multi-agent orchestration library such as CAMEL itself, which OASIS depends on through camel-ai 0.2.90. In a general framework, agents converse to complete a task, and success is measured by whether the task finished. There is no feed, no follower graph and no notion of a post being recommended to someone who did not ask for it.

OASIS inverts that. The interesting output is not a completed task but an emergent distribution: which posts spread, which agents clustered, how the hot-score ranking reshaped what the population saw. That requires machinery a task-oriented framework does not have, namely the platform layer, the recommendation algorithms and the persistent database of posts, comments and relationships.

The cost of that machinery is that OASIS is far less general. You cannot ask it to write code or answer a support ticket. Choosing between them is really choosing what you want to measure: task completion, or population-level dynamics over time.

Licence, maintenance and upgrade cost

OASIS is released under Apache-2.0, both in the repository and in pyproject.toml. That is a permissive licence, and it is the same licence family as the CAMEL project it builds on. The repository also contains a licenses/ directory, which suggests bundled third-party components with their own terms; if you redistribute the package or ship it inside a product, read that directory rather than assuming the top-level licence covers everything. This is a description of what the repository contains, not legal advice.

The last push to the default branch was on 2026-08-27, and the most recent release in the list is v0.2.5 from 2025-12-04. Development is ongoing, but the release cadence is slow: v0.2.2 and v0.2.3 landed two days apart in June 2025, and then nothing until December. If you depend on a behaviour, pin the version.

Upgrade cost is dominated by the pinned dependency set. Moving from one OASIS release to the next may force a coordinated bump of camel-ai, sentence-transformers and the rest, and any of those can change model-calling behaviour. Budget for re-running a baseline experiment after each upgrade, because token counts and agent decisions are not guaranteed stable across versions.

Editorial conclusion

Adopt OASIS if you are researching information spread, group polarization or herd behaviour and you already have an OpenAI-compatible model budget. Skip it if you need a stable API for a product, or if your Python is 3.12 or newer, since pyproject.toml pins python to >=3.10.0,<3.12. Before committing, verify the token cost of your own scenario rather than trusting the README table, and check that your platform choice (Twitter or Reddit) has profiles in the shape generate_reddit_agent_graph expects.

Frequently asked questions

Official sources

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