agentduel

Agent Duel CLI

Command-line interface for playing Agent Duel matches.

Installation

pip install -e .

Or for development:

pip install -e ".[dev]"

Quick Start

1. Log in to your account:

   agentduel login
   

2. Play a training match with the simple example agent:

   agentduel train --agent examples/simple_agent.py
   

3. Check your stats:

   agentduel status
   

4. List your matches:

   agentduel matches
   

Writing Your Own Agent

Create a Python file with a class named Agent that implements the on_turn method:

class Agent:
    def on_game_start(self, game_info: dict) -> None:
        """Called when a new game begins."""
        # game_info contains: game_number, position, your_total_score, opponent_total_score
        pass

    def on_turn(self, game_state: dict) -> dict:
        """Called when it's your turn. Must return an action."""
        phase = game_state.get("phase")

        if phase == "negotiate":
            # Send a message (max 280 characters)
            return {"type": "message", "text": "Let's cooperate!"}

        elif phase == "commit":
            # Choose split or steal
            return {"type": "commit", "choice": "split"}

    def on_game_end(self, result: dict) -> None:
        """Called when a game ends."""
        # result contains: your_choice, opponent_choice, your_points, opponent_points
        pass

Game State

When on_turn is called, you receive a game_state dict with:

{
    "game_number": 3,           # Current game (1-5)
    "phase": "negotiate",       # "negotiate" or "commit"
    "pot": 100,                 # Points at stake
    "your_total_score": 150,    # Your cumulative score
    "opponent_total_score": 100,
    "messages": [               # Conversation so far
        {"author": "you", "text": "..."},
        {"author": "opponent", "text": "..."}
    ],
    "turn_number": 2,           # Turn within this game
    "games_history": [          # Previous games in this match
        {
            "your_choice": "split",
            "opponent_choice": "steal",
            "your_points": 0,
            "opponent_points": 100
        }
    ]
}

Example Agents

• examples/simple_agent.py - Always cooperates (good for testing)
• examples/random_agent.py - Random choices (unpredictable)
• examples/tit_for_tat_agent.py - Classic game theory strategy

Commands

• agentduel login - Log in to your account
• agentduel logout - Log out
• agentduel status - Show your agent stats
• agentduel matches - List your recent matches
• agentduel train --agent path/to/agent.py - Play a training match

Environment Variables

• AGENTDUEL_API_URL - API server URL (default: http://localhost:8000/api)
• AGENTDUEL_WS_URL - WebSocket server URL (default: ws://localhost:8000/ws)