ChatArena
A Python framework for building and running multi-agent language-game experiments with LLM players.
- Source repo
- Farama-Foundation/ChatArena
- Stars
- ★ 1.6k
- Last updated
- 1y ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 55/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A multi-agent researcher needs a turn-based framework for testing communication, collaboration, or social interaction among LLM players.
- Not a fit if
- Teams needing ongoing maintenance or upstream support; the project was deprecated on Aug 11, 2025
- Users wanting all backends and environments out of the box; Anthropic, Cohere, Hugging Face and PettingZoo need optional extras
- Teams unwilling to depend on an OpenAI API key or pay per-use model costs
- Maintenance
- No commits for 6+ monthslast commit 2025-08-11latest release v0.1.18 (2023-12-21)
- Source review
- 55/100 · Major gaps
What does this agent do, and when should you use it?
ChatArena is a Python library for studying autonomous LLM agents and their social interactions through multi-agent language games. Its core model consists of Arena, Environment, Language Backend, and Player: Arena manages the game loop, configuration loading, data storage, and HCI utilities such as a Web UI and CLI. Environments hold game state, apply transition logic, and render natural-language observations that players use to act. The repository includes conversation, moderator-led conversation, Chameleon, and PettingZoo-backed chess and tic-tac-toe environments, with JSON examples for running games. The project was declared deprecated on August 11, 2025, with no additional updates or support planned, so it is better suited to reproduction, experimentation, or self-maintained extensions than to a dependency requiring active upstream support.
A user can create an Arena from a JSON file with Arena.from_config("examples/nlp-classroom-3players.json") and advance the game with arena.run(num_steps=10). Arena coordinates Players and an Environment in the main loop; the Environment manages state, transitions, observations, terminal conditions, and rewards through mechanisms including step, reset, get_observation, is_terminal, and get_rewards. A Player receives a natural-language observation and, by default, queries a Language Backend before returning its response as an action. The project also exposes arena.launch_cli() for interactive use and a local Gradio Web UI launched with gradio app.py. New environments are created by extending Environment, assigning type_name, and adding the class to ALL_ENVIRONMENTS.
- A multi-agent researcher needs a turn-based framework for testing communication, collaboration, or social interaction among LLM players.
- A prompt engineer wants to run a configured multi-player interaction, such as examples/nlp-classroom-3players.json, without writing a game loop.
- A teaching or prototyping team wants to use the Chameleon social-deduction game to inspect reasoning and voting under asymmetric information.
- An experimenter wants to contrast LLM-moderated rock-paper-scissors or tic-tac-toe with PettingZoo environments driven by hard-coded rules.
- A Python developer wants to implement a new language game with custom state, observations, rewards, and step logic.
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
pip install chatarenapip install chatarena[all_backends]pip install chatarena[all_envs]pip install chatarena[all]
- Environment variables
OPENAI_API_KEY- Config files
examples/nlp-classroom-3players.json- Runtime
- Python 3.7+
How do you install or deploy this agent?
The README body lists Python >= 3.7 as the requirement, while its badge says Python 3.9+. Install the core package:
pip install chatarenaInstall all supported backend dependencies:
pip install chatarena[all_backends]Install all environment dependencies:
pip install chatarena[all_envs]Install all optional dependencies:
pip install chatarena[all]For GPT-3.5-turbo or GPT-4 agents, set the optional credential:
export OPENAI_API_KEY="your_api_key_here"How do you use this agent?
Create and run a game from the repository example configuration:
arena = Arena.from_config("examples/nlp-classroom-3players.json")
arena.run(num_steps=10)Launch the interactive CLI:
arena.launch_cli()Launch the local Web UI:
pip install chatarena[gradio]
git clone https://github.com/chatarena/chatarena.git
cd chatarena
gradio app.pyThe README says the demo server can then be accessed in a browser on port 8080.
What are this agent's strengths and limitations?
- It separates Arena, Environment, Language Backend, and Player, allowing game rules, loops, prompt formatting, and player behavior to be customized independently.
- It provides a Python API, interactive CLI, and Gradio Web UI for both configured experiments and local demonstrations.
- Its included environments span open-ended conversation, moderator-controlled games, social deduction, and PettingZoo-backed rule-based games.
- JSON configuration and the documented Environment extension path support new language games with custom state, rewards, and observations.
- The project is explicitly deprecated and no further updates or support are planned, leaving adopters responsible for maintenance and compatibility.
- Using GPT-3.5-turbo or GPT-4 requires an OpenAI API key, creating an external-service dependency and potential usage cost.
- Advanced backends and environments are not in the default installation; features involving Anthropic, Cohere, Hugging Face, or PettingZoo require optional extras.
- The local Web UI workflow requires cloning the repository and installing the Gradio extra, rather than using only the core package.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| ChatArena This agent | 55 · Major gaps | Library / SDKFree + model costs | ★ 1.6k | 1y ago | Python | OpenAI API |
| AgentVerse | 43 · Major gaps | CLIFree + model costs | ★ 5.2k | 2y ago | JavaScript | OpenAI API |
| VirtualHome | 44 · Major gaps | Library / SDKFree | ★ 645 | 2y ago | Python | — |
| IR-SIM: Lightweight Robot Simulator | 57 · Major gaps | Library / SDKFree | ★ 1.2k | 5d ago | Python | — |
How does FollowAgents rate this agent?
Why each dimension lost points
The code shows the core Agent sending its role description, global prompt, and message history through a configured backend; the CLI can save conversation history to a user-selected path. Installation also asks users to set their own API key. This makes some permissions and external effects visible, but the packet does not explain data transmission, retention, or sensitive-data handling, and shows no confirmation before saving or rollback mechanism, so those criteria lose points. README attribution, citation details, and the Apache-2.0 license provide provenance clues; publisher identity is unverified, and the maintenance notice says the project is deprecated.
Agent handles RetryError with a log entry and end signal, and the CLI displays invalid-action errors, so failures receive some handling. README says Python 3.7+ and pyproject declares the same, while the README badge says 3.9+; dependencies include old pins and open ranges, and the project is deprecated, lowering consistency and availability scores. No runtime behavior is assessed.
The README identifies multi-agent language-game research as the audience and covers conversation, social deduction, and PettingZoo games, with CLI, Web UI, Python API, and customization paths for environments, backends, and players. Component roles are described, but unsupported scenarios and capability boundaries are not clearly stated. The API also depends on configured backends, configuration, and external services, so these criteria do not receive full marks.
The README is organized around installation, concepts, usage, customization, and environment examples; it documents pip and source installation, optional dependencies, and several examples. Names vary between ChatArena and Chat Arena. Limitations are mostly conveyed by the deprecation notice and example notes; no systematic limitations list or FAQ is shown. LICENSE provides Apache License 2.0, meriting full marks. The citation still says version 0.1 and no changelog is shown. Contribution steps and contact channels exist, but the deprecation notice says updates and support have ended, limiting maintenance responsibility and the update path.
The framework separates environments, players, backends, and the Arena loop, and offers several game environments, CLI/Web UI, and customization paths, showing clear research and prototyping value. Examples support common tasks, but external LLM APIs, keys, and optional dependencies add setup and service costs. The explicit end of updates and support reduces the current cost-benefit score.
README claims about features, installation, and environments are partly traceable to example configurations, Agent implementation, CLI, and test files. Most sampled tests depend on API keys and do not establish execution or coverage quality; CI files show external API keys are configured but do not prove test results. README and pyproject disagree on the Python version, and the static packet does not systematically separate every claim from supporting evidence and limitations, reducing corroboration and verifiability.
- The README says the project was deprecated in August 2025 and will receive no further updates or support; treat it as unmaintained.
- API backends receive role prompts and message history. Check each backend's data handling and avoid placing sensitive information in conversations.
- The README's Python-version badge conflicts with its installation requirement. The sampled dependency list includes old pinned versions, and this static review cannot establish compatibility with current environments.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
ChatArena 0.1.18 This is a hotfix release, fixing a minor issue with a kwarg in the Umshini environments, which caused issues in certain use cases. Apologies for the small and frequent releases, unfortunately there's no way around it currently. Bug Fixes * Umshini: fix minor typo with player_names kwarg by @elliottower in https://github.com/Farama-Foundation/chatarena/pull/117 Full Changelog: https://github.com/Farama-Foundation/chatarena/compare/v0.1.17...v0.1.18View on GitHub ↗ -
Release notes excerpt
ChatArena 0.1.17 This is a minor release, including a minor enhancement to the Umshini environments, and adding registration functionality for all environments and intelligence backends--allowing the use of Arena.from_config with custom environments. New Features and Improvements * Umshini: add classification of vulnerability category (e.g., prompt injection) for successful attacks by @elliottower in https://github.com/Farama-Foundation/chatarena/pull/114 …View on GitHub ↗ -
Release notes excerpt
ChatArena 0.1.16 This is a very minor release fixing some issues and adding slight enhancements to the Umshini environments. Bug Fixes * Umshini: Fix bug where explanation is not initialized by @andrewtanJS in https://github.com/Farama-Foundation/chatarena/pull/111 * Umshini: add asymmetric (fixed role) versions of deception and content moderation envs by @elliottower in https://github.com/Farama-Foundation/chatarena/pull/112 Full Changelog: https://github.com/Farama-Foundation/chatarena/compare/v0.1.15...v0.1.16View on GitHub ↗
FAQ
Is an OpenAI API key required?
Can it use backends beyond OpenAI?
Can I implement my own game?
Is it a safe choice for a long-lived production dependency?
Is ChatArena free?
Is ChatArena open source?
Is ChatArena still maintained?
Who makes ChatArena?
Thanks — we use this to improve the page.