Registry / ai-ml / textarena

textarena

JSON →
library0.7.4pypypi✓ verified 81d ago

TextArena is a Python library that provides a collection of competitive text-based games designed for evaluating language models and developing reinforcement learning agents. It offers a framework for defining games, creating agents (including human and GPT agents), and running competitive battles. As of version 0.7.4, it's under active development with a somewhat irregular release cadence, often introducing significant changes between minor versions.

pip install textarena
INSTALL
IMPORT
SIG · TEXTARENA
T
textarena
ai-mlpythonv0.7.4
Install
11.7s avg
Import
Disk
130MB
Pass rate
9/ 10
Env Coverage9 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.7.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✓ —
✓ 10.93s
py 3.11
✓ —
✓ 9.6s
py 3.12
✓ —
✓ 9.83s
py 3.13
✓ —
✓ 9.6s
py 3.9
✕ build_error
✓ 18.48s
130MB installed
● package 130MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Env
from textarena import Env
from textarena.arena import Arena

This quickstart demonstrates how to set up and run a simple game (Prisoner's Dilemma) using two base agents in TextArena. It initializes agents, configures an Arena instance with a specified game, and then executes the game, printing the final scores and full game history. For GPT-powered agents, ensure your OpenAI API key is set as an environment variable.

import os from textarena.arena import Arena from textarena.agent.agent import Agent, GPTAgent from textarena.env.text_env import TextEnv from textarena.game.prisoner_dilemma import PrisonerDilemmaGame # 1. TextArena comes with pre-registered games, e.g., 'prisoner_dilemma'. # If you define a custom game, you'd register it like this before use: # TextEnv.register_game("my_custom_game", MyCustomGameClass) # 2. Create agents # For demonstration, we'll use base Agents. They generate random actions. agent1 = Agent(name="Alice", temperature=0.7) agent2 = Agent(name="Bob", temperature=0.7) # To use GPTAgent, ensure OPENAI_API_KEY is set in your environment. # The 'sk-dummy-key' is a placeholder and will not work with actual OpenAI API calls. openai_api_key = os.environ.get('OPENAI_API_KEY', 'sk-dummy-key') # agent1 = GPTAgent(name="Alice", api_key=openai_api_key, model="gpt-3.5-turbo") # agent2 = GPTAgent(name="Bob", api_key=openai_api_key, model="gpt-3.5-turbo") # 3. Initialize and run the arena with a pre-registered game arena = Arena( game_name="prisoner_dilemma", # Using a pre-registered game agents=[agent1, agent2], max_turns=3 # Number of rounds for the dilemma ) print(f"Starting TextArena with {arena.game_name} for {arena.max_turns} turns...") results = arena.run() print("\nArena run complete. Final Results:") for agent_name, score in results['score'].items(): print(f"- {agent_name}: {score} points") print("\nFull game history:") for turn_idx, turn_log in enumerate(arena.game_env.get_history()): print(f"--- Turn {turn_idx + 1} ---") print(turn_log)
textarena --version
Debug
Known issues
breakingAgent import paths were refactored in version 0.7.0. Classes like `Agent` and `GPTAgent` moved from `textarena.agent.base` and `textarena.agent.lm_agent` respectively to `textarena.agent.agent`.
fix
Update your import statements: `from textarena.agent.agent import Agent, GPTAgent`.
affects: >=0.7.0
breakingThe system for registering Agents and Environments was significantly refactored in version 0.6.0. Global registration via a central registry was removed and moved to a factory-like pattern, primarily `TextEnv.register_game`.
fix
For custom games, ensure you use `TextEnv.register_game("game_name", GameClass)` before creating an `Arena` instance. Agent registration is less explicit, typically agents are instantiated directly.
affects: >=0.6.0
gotchaUsing `GPTAgent` requires a valid OpenAI API key. If not provided via an environment variable (`OPENAI_API_KEY`) or the `api_key` parameter, the agent will not be able to interact with the OpenAI API, leading to errors or dummy behavior.
fix
Set the `OPENAI_API_KEY` environment variable (e.g., `export OPENAI_API_KEY="sk-..."`) or pass it directly: `GPTAgent(name="Agent", api_key="sk-...")`.
affects: All versions with GPTAgent
gotchaTextArena is in active `0.x.x` development, meaning minor version updates (e.g., `0.7.0` to `0.8.0`) can and do introduce breaking API changes. Always review the release notes when upgrading to a new minor version.
fix
Consult the GitHub releases page (`https://github.com/microsoft/TextArena/releases`) for detailed changelogs and migration guides before upgrading.
affects: All 0.x.x versions
Upgrade
Version history
0.7.4latest on PyPI · released Oct 16, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
30 hits · last 30 days
node
26
OpenAI (training)
1
Resources
textarena — pip install textarena · libregistry