Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcprize.org/llms.txt

Use this file to discover all available pages before exploring further.

ARC-AGI-3 games are turn-based systems where agents interact with 2D grid environments through a standardized action interface. Each game maintains state through discrete action-response cycles.
  • Agents will receive a 1-N frames of JSON objects with the game state and metadata.
  • Agents will respond with an action 1-5 or a 6th action which includes x, y coordinates.

​
Available Games

To see which games are available, either go to arcprize.org/tasks or make an API call to list games. Example games include
  • ls20 - Agent reasoning
  • ft09 - Elementary Logic
  • vc33 - Orchestration

​
Game ID

Game IDs are formatted as <game_name>-<version>. game_names are stable, but version may change as games update.

​
Grid Structure

  • Dimensions: Maximum 64x64 grid size
  • Cell Values: Integer values 0-15 representing different states/colors
  • Coordinate System: (0,0) at top-left, (x,y) format

​
Game Available Actions

Each game provides an explicit set of actions that an agent can take. Actions available vary per game. Typically, the available actions include:
  • Actions 1–4: ex: move up, down, left, or right
  • Action 6: A complex action (if supported by the game)
To learn more about each action and what it does, please visit the Actions.

​
Running a Full Playtest

To run a complete playtest, you’ll need to integrate your agent with scorecard management and the game loop. This is what happens “under the hood” when you run commands like uv run main.py --agent=random --game=ls20 (from the Quick Start). Below is pseudocode for the key steps. For a ready-to-use implementation, see the Swarms guide—which can automate this for you across multiple games.

​
Game State Enumeration

StateDescription
NOT_FINISHEDGame is active and awaiting next action
WINObjective completed successfully
GAME_OVERGame terminated due to the max actions reached or other conditions

​
Full Playtest

This is a bare-bones example for (educational purposes) is also available as a notebook. 
#!/usr/bin/env python3
"""
Simple demo showing what a swarm agent does under the hood.
This is a bare-bones example for educational purposes.
"""

import json
import os
import random
import requests
from dotenv import load_dotenv

# Load environment variables
load_dotenv(dotenv_path=".env")

# Setup
ROOT_URL = "https://three.arcprize.org"
API_KEY = os.getenv("ARC_API_KEY")

# Create a session with headers
session = requests.Session()
session.headers.update({
    "X-API-Key": API_KEY,
    "Accept": "application/json"
})

print("=== MANUAL SWARM DEMO ===")
print("This shows what happens when an agent plays an ARC game.\n")

# Step 1: Get available games
print("STEP 1: Getting list of games...")
response = session.get(f"{ROOT_URL}/api/games")
games = [g["game_id"] for g in response.json()]
print(f"Found {len(games)} games")

# Pick a random game
game_id = random.choice(games)
print(f"Selected game: {game_id}\n")

# Step 2: Open a scorecard (tracks performance)
print("STEP 2: Opening scorecard...")
response = session.post(
    f"{ROOT_URL}/api/scorecard/open",
    json={"tags": ["manual_demo"]}
)
card_id = response.json()["card_id"]
print(f"Scorecard ID: {card_id}\n")

# Step 3: Start the game
print("STEP 3: Starting game with RESET action...")
url = f"{ROOT_URL}/api/cmd/RESET"
print(f"URL: {url}")
response = session.post(
    url,
    json={
        "game_id": game_id,
        "card_id": card_id
    }
)

# Check if response is valid
if response.status_code != 200:
    print(f"Error: {response.status_code} - {response.text}")
    exit()

game_data = response.json()
guid = game_data["guid"]
state = game_data["state"]
score = game_data.get("score", 0)
print(f"Game started! State: {state}, Score: {score}\n")

# Step 4: Play with random actions (max 5 actions)
print("STEP 4: Taking random actions...")
actions = ["ACTION1", "ACTION2", "ACTION3", "ACTION4", "ACTION5", "ACTION6", "ACTION7"]

for i in range(5):
    # Check if game is over
    if state in ["WIN", "GAME_OVER"]:
        print(f"\nGame ended! Final state: {state}, Score: {score}")
        break
    
    # Pick a random action
    action = random.choice(actions)
    
    # Build request data
    request_data = {
        "game_id": game_id,
        "card_id": card_id,
        "guid": guid
    }
    
    # ACTION6 needs x,y coordinates
    if action == "ACTION6":
        request_data["x"] = random.randint(0, 29)
        request_data["y"] = random.randint(0, 29)
        print(f"Action {i+1}: {action} at ({request_data['x']}, {request_data['y']})", end="")
    else:
        print(f"Action {i+1}: {action}", end="")
    
    # Take the action
    response = session.post(
        f"{ROOT_URL}/api/cmd/{action}",
        json=request_data
    )
    
    game_data = response.json()
    state = game_data["state"]
    score = game_data.get("score", 0)
    print(f" -> State: {state}, Score: {score}")

# Step 5: Close scorecard
print("\nSTEP 5: Closing scorecard...")
response = session.post(
    f"{ROOT_URL}/api/scorecard/close",
    json={"card_id": card_id}
)
scorecard = response.json()
print("Scorecard closed!")
print(f"\nView results at: {ROOT_URL}/scorecards/{card_id}")

print("\n=== DEMO COMPLETE ===")
print("\nThis is what every agent does:")
print("1. Get games list")
print("2. Open a scorecard")
print("3. Reset to start the game")
print("4. Take actions based on its strategy (we used random)")
print("5. Close the scorecard when done")
print("\nThe real agents use smarter strategies instead of random!")
This workflow ensures your plays are tracked officially. For parallel playtests across games, use a swarm to handle the orchestration automatically.