{"id":7785,"library":"textarena","title":"TextArena","description":"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.","status":"active","version":"0.7.4","language":"en","source_language":"en","source_url":"https://github.com/microsoft/TextArena","tags":["LLM","reinforcement-learning","text-games","evaluation","AI","multi-agent"],"install":[{"cmd":"pip install textarena","lang":"bash","label":"Install TextArena"}],"dependencies":[],"imports":[{"symbol":"Arena","correct":"from textarena.arena import Arena"},{"note":"Import path for base agent class changed in v0.7.0. Previously it was 'textarena.agent.base.Agent'.","wrong":"from textarena.agent.base import Agent","symbol":"Agent","correct":"from textarena.agent.agent import Agent"},{"note":"Import path for GPTAgent class changed in v0.7.0. Previously it was 'textarena.agent.lm_agent.GPTAgent'.","wrong":"from textarena.agent.lm_agent import GPTAgent","symbol":"GPTAgent","correct":"from textarena.agent.agent import GPTAgent"},{"symbol":"TextEnv","correct":"from textarena.env.text_env import TextEnv"}],"quickstart":{"code":"import os\nfrom textarena.arena import Arena\nfrom textarena.agent.agent import Agent, GPTAgent\nfrom textarena.env.text_env import TextEnv\nfrom textarena.game.prisoner_dilemma import PrisonerDilemmaGame\n\n# 1. TextArena comes with pre-registered games, e.g., 'prisoner_dilemma'.\n# If you define a custom game, you'd register it like this before use:\n# TextEnv.register_game(\"my_custom_game\", MyCustomGameClass)\n\n# 2. Create agents\n# For demonstration, we'll use base Agents. They generate random actions.\nagent1 = Agent(name=\"Alice\", temperature=0.7)\nagent2 = Agent(name=\"Bob\", temperature=0.7)\n\n# To use GPTAgent, ensure OPENAI_API_KEY is set in your environment.\n# The 'sk-dummy-key' is a placeholder and will not work with actual OpenAI API calls.\nopenai_api_key = os.environ.get('OPENAI_API_KEY', 'sk-dummy-key')\n# agent1 = GPTAgent(name=\"Alice\", api_key=openai_api_key, model=\"gpt-3.5-turbo\")\n# agent2 = GPTAgent(name=\"Bob\", api_key=openai_api_key, model=\"gpt-3.5-turbo\")\n\n# 3. Initialize and run the arena with a pre-registered game\narena = Arena(\n    game_name=\"prisoner_dilemma\", # Using a pre-registered game\n    agents=[agent1, agent2],\n    max_turns=3 # Number of rounds for the dilemma\n)\n\nprint(f\"Starting TextArena with {arena.game_name} for {arena.max_turns} turns...\")\nresults = arena.run()\n\nprint(\"\\nArena run complete. Final Results:\")\nfor agent_name, score in results['score'].items():\n    print(f\"- {agent_name}: {score} points\")\n\nprint(\"\\nFull game history:\")\nfor turn_idx, turn_log in enumerate(arena.game_env.get_history()):\n    print(f\"--- Turn {turn_idx + 1} ---\")\n    print(turn_log)\n","lang":"python","description":"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."},"warnings":[{"fix":"Update your import statements: `from textarena.agent.agent import Agent, GPTAgent`.","message":"Agent 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`.","severity":"breaking","affected_versions":">=0.7.0"},{"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.","message":"The 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`.","severity":"breaking","affected_versions":">=0.6.0"},{"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-...\")`.","message":"Using `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.","severity":"gotcha","affected_versions":"All versions with GPTAgent"},{"fix":"Consult the GitHub releases page (`https://github.com/microsoft/TextArena/releases`) for detailed changelogs and migration guides before upgrading.","message":"TextArena 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.","severity":"gotcha","affected_versions":"All 0.x.x versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Update your import statement: `from textarena.agent.agent import Agent`.","cause":"You are trying to import the Agent base class from an old path that was refactored in `textarena` version 0.7.0.","error":"ModuleNotFoundError: No module named 'textarena.agent.base'"},{"fix":"Ensure `OPENAI_API_KEY` environment variable is set or pass `api_key` directly to the `GPTAgent` constructor: `GPTAgent(name=\"MyGPT\", api_key=\"YOUR_KEY_HERE\")`.","cause":"The `GPTAgent` was instantiated without a valid OpenAI API key, and thus could not initialize its OpenAI client. This typically happens when `OPENAI_API_KEY` environment variable is not set.","error":"TypeError: 'NoneType' object is not callable (often seen when using GPTAgent)"},{"fix":"Before initializing `Arena`, register your custom game class using `TextEnv.register_game(\"my_custom_game\", MyCustomGameClass)`.","cause":"You are attempting to create an `Arena` instance with a `game_name` that has not been registered with TextArena's environment system.","error":"ValueError: Game 'my_custom_game' not found in registry."}]}