arc-agi-3

Python SDK for building ARC-AGI-3 agents.

ARC-AGI-3 is an Interactive Reasoning Benchmark designed to measure an AI Agent's ability to generalize in novel, unseen environments. By building agents that can play ARC-AGI-3, you're directly contributing to the frontier of AI research.

Installation

# Core installation (Random agent only)
pip install arc-agi-3

# With OpenAI support (LLM-based agents)
pip install arc-agi-3[openai]

# With LangGraph support
pip install arc-agi-3[langgraph]

# With SmolAgents support
pip install arc-agi-3[smolagents]

# With AgentOps observability
pip install arc-agi-3[agentops]

# Everything
pip install arc-agi-3[all]

Quick Start

1. Get an API Key

1. Go to three.arcprize.org
2. Create an account and get your API key
3. Set it as an environment variable:

export ARC_API_KEY="your-api-key-here"

Or create a .env file:

ARC_API_KEY=your-api-key-here

2. Run an Agent

Using the CLI:

# Run a random agent on the ls20 game
arc-agi-3 --agent=random --game=ls20

# Run with tags for tracking
arc-agi-3 --agent=random --game=ls20 --tags=experiment,v1.0

# List available agents
arc-agi-3 --list-agents

Or programmatically:

from arc_agi_3 import Swarm, AVAILABLE_AGENTS

# Run a swarm of agents
swarm = Swarm(
    agent="random",
    ROOT_URL="https://three.arcprize.org",
    games=["ls20"],
    tags=["my-experiment"],
)
scorecard = swarm.main()
print(f"Final score: {scorecard.score}")

Available Agents

Building Your Own Agent

Subclass the Agent base class:

from arc_agi_3 import Agent
from arc_agi_3._structs import FrameData, GameAction, GameState

class MyAgent(Agent):
    MAX_ACTIONS = 80

    def is_done(self, frames: list[FrameData], latest_frame: FrameData) -> bool:
        return latest_frame.state is GameState.WIN

    def choose_action(
        self,
        frames: list[FrameData],
        latest_frame: FrameData,
    ) -> GameAction:
        # Your logic here
        if latest_frame.state in [GameState.NOT_PLAYED, GameState.GAME_OVER]:
            return GameAction.RESET

        # Choose an action based on the frame data
        action = GameAction.ACTION1
        action.reasoning = "My reasoning for this action"
        return action

Environment Variables

Data Structures

GameAction

Available actions:

• RESET - Start or restart a game
• ACTION1 - Simple action (typically Up/W)
• ACTION2 - Simple action (typically Down/S)
• ACTION3 - Simple action (typically Left/A)
• ACTION4 - Simple action (typically Right/D)
• ACTION5 - Simple action (typically Enter/Space)
• ACTION6 - Complex action with x,y coordinates (Click/Point)
• ACTION7 - Simple action

GameState

• NOT_PLAYED - Game hasn't started
• NOT_FINISHED - Game in progress
• WIN - Game won
• GAME_OVER - Game lost

FrameData

Each frame contains:

• game_id - The game identifier
• frame - 3D list of grid data (list of 2D grids)
• state - Current GameState
• score - Current score (0-254)
• available_actions - List of valid actions for this state

Links

• ARC Prize
• ARC-AGI-3 Preview
• Documentation
• GitHub Repository

License

MIT License - see the original ARC-AGI-3-Agents repository.