Sotopia

What does this agent do, and when should you use it?

Sotopia is the open-source environment behind an ICLR 2024 spotlight paper on interactive evaluation of social intelligence in language agents. It runs asynchronous social episodes in which an environment model and two agent models interact, configured per role through the run_async_server call. Episodes and data persist either to Redis (the default backend) or to local JSON under ~/.sotopia/data/, and the project ships a Hugging Face dataset and an online demo. It is distributed as an installable Python package with a minimal example script, under the MIT license. Running it requires your own OpenAI API key and paying for model usage.

The sotopia Python package exposes sotopia.server.run_async_server, which drives an asynchronous social episode; model_dict assigns models to env, agent1 and agent2 (for example gpt-4 for the environment and gpt-4o-mini for agents), while a sampler such as sotopia.samplers.UniformSampler picks scenarios. Output is persisted according to SOTOPIA_STORAGE_BACKEND — Redis via REDIS_OM_URL by default, or local JSON files when set to local. Setup is completed with uv run sotopia install, and examples/minimalist_demo.py gives a minimal runnable invocation. The accompanying paper defines evaluation metrics for social intelligence in language agents.

1. Social-intelligence researchers comparing how different LLMs behave as agents in the same scenarios.
2. RL and multi-agent experimenters treating open-ended social settings as an extensible environment for policies.
3. Model developers pairing a strong environment model with cheaper role agents to inspect dialogue quality.
4. Educators and demo builders showing multi-agent conversations using the hosted demo and example scripts.
5. Engineers prototyping custom scenarios and characters against the quick local JSON backend.

How do you install or deploy this agent?

Create a virtual environment and install with uv:

pip install uv
uv sync --all-extras
uv run sotopia install

If you keep the default Redis backend, start Redis with Docker:

docker run -d -p 6379:6379 redis/redis-stack-server:latest

Create a .env file in the project root with your key and backend:

cat > .env << EOF
OPENAI_API_KEY=your_openai_key_here
SOTOPIA_STORAGE_BACKEND=local
# REDIS_OM_URL=redis://localhost:6379
EOF

How do you use this agent?

uv does not load .env automaticallycopy, so pass the file or export the variables. Run the minimal demo:

uv run --env-file .env python examples/minimalist_demo.py

Or call the async server directly with per-role models:

import asyncio
from sotopia.samplers import UniformSampler
from sotopia.server import run_async_server

asyncio.run(
    run_async_server(
        model_dict={
            "env": "gpt-4",
            "agent1": "gpt-4o-mini",
            "agent2": "gpt-4o-mini",
        },
        sampler=UniformSampler(),
    )
)

The README warns that the server will not run locally without any datasets installed.

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

[![FARS review](https://followagents.com/badge/sotopia.svg)](https://followagents.com/en/agents/sotopia)

<a href="https://followagents.com/en/agents/sotopia"><img src="https://followagents.com/badge/sotopia.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

1. v0.1.5 v0.1.5 Make redis optional 2025-12-07
   Release notes excerpt

   * Feature/multi agent framework by @Keyu-He in https://github.com/sotopia-lab/sotopia/pull/329 * Fix custom/local model support bugs by @Keyu-He in https://github.com/sotopia-lab/sotopia/pull/338 * sotopia redis optional by @XuhuiZhou in https://github.com/sotopia-lab/sotopia/pull/341

   View on GitHub ↗
2. v0.1.4 2025-02-01
   Release notes excerpt

   What's Changed * Update langchain requirement from <0.3.0,>=0.2.5 to >=0.2.5,<0.4.0 by @dependabot in https://github.com/sotopia-lab/sotopia/pull/236 * [Automated] Merge release into main by @ProKil in https://github.com/sotopia-lab/sotopia/pull/235 * update macos test runner as macos-latest by @ProKil in https://github.com/sotopia-lab/sotopia/pull/238 * feat(exp_eval): support tag for combo iteration by @lwaekfjlk in https://github.com/sotopia-lab/sotopia/pull/245 …

   View on GitHub ↗
3. v0.1.3 2025-01-08
   Release notes excerpt

   What's Changed * UI update by @XuhuiZhou in https://github.com/sotopia-lab/sotopia/pull/273 Full Changelog: https://github.com/sotopia-lab/sotopia/compare/v0.1.2...v0.1.3

   View on GitHub ↗

FAQ