from haive.games.among_us import AmongUsGame, AmongUsAgent, AmongUsConfig
# Create agents with distinct personalities
agents = [
AmongUsAgent(
name="detective",
personality="analytical",
deception_skill=0.3,
trust_threshold=0.7,
social_influence=0.6
),
AmongUsAgent(
name="manipulator",
personality="deceptive",
deception_skill=0.9,
trust_threshold=0.3,
social_influence=0.8
),
AmongUsAgent(
name="follower",
personality="trusting",
deception_skill=0.2,
trust_threshold=0.9,
social_influence=0.4
),
AmongUsAgent(
name="chaos_agent",
personality="unpredictable",
deception_skill=0.6,
trust_threshold=0.5,
social_influence=0.7
)
]
# Configure advanced social dynamics
config = AmongUsConfig(
enable_psychology_tracking=True,
alliance_formation=True,
behavioral_adaptation=True,
social_influence_modeling=True
)
# Run social psychology experiment
game = AmongUsGame(players=agents, config=config)
results = await game.run()
# Analyze emergent behaviors
print(f"Alliance Networks: {results.alliance_analysis}")
print(f"Deception Success Rates: {results.deception_metrics}")
print(f"Trust Evolution: {results.trust_dynamics}")
print(f"Social Influence Patterns: {results.influence_analysis}")
Social Psychology Games¶
The Social Psychology Games represent the cutting edge of AI behavioral research - sophisticated gaming environments where AI agents demonstrate complex social psychology, deception mechanics, trust modeling, and emergent social behaviors that mirror real human interactions.
🧠 Revolutionary Capabilities¶
AI agents that lie convincingly, detect deception, form alliances, and exhibit realistic social psychology patterns
Complex group dynamics with hidden roles, asymmetric information, and emergent social behaviors
Dynamic personality profiles that evolve based on social interactions and strategic necessities
Comprehensive behavioral analysis including manipulation tactics, trust patterns, and social influence
Live tracking of alliance formation, betrayal patterns, and social hierarchy emergence
Core Social Games¶
Among Us - Advanced Social Deduction¶
Among Us social deduction game module.
Agent implementation for the Among Us game.
This class inherits state management from AmongUsStateManagerMixin and agent behavior from MultiPlayerGameAgent.
alias of
AmongUsAgentConfigInitialize the Among Us agent with configuration.
Extract structured move from engine response.
response (Any)
role (str)
dict[str, Any]
Get the appropriate engine for a player based on their role and the current. phase.
role (str) – Player role (CREWMATE or IMPOSTOR)
engine_key (str) – Engine type key (player, meeting, voting)
The appropriate engine runnable
Any | None
Prepare context for a player’s move decision.
state (AmongUsState)
player_id (str)
dict[str, Any]
Visualize the current game state using the AmongUsUI.
This method is required by the MultiPlayerGameAgent parent class.
state (dict[str, Any] | AmongUsState) – Current game state (dict or AmongUsState object)
None
Configuration for Among Us game agent.
id (str)
name (str)
engine_type (EngineType)
description (str | None)
input_schema (type[BaseModel] | dict[str, Any] | None)
output_schema (type[BaseModel] | dict[str, Any] | None)
version (str)
metadata (dict[str, Any])
engine (Engine | str | None)
engines (dict[str, dict[str, AugLLMConfig]] | None)
state_schema (type)
node_configs (dict[str, NodeConfig])
patterns (list[PatternConfig])
pattern_parameters (dict[str, dict[str, Any]])
default_patterns (list[str | dict[str, Any]])
visualize (bool)
output_dir (str)
debug (bool)
save_history (bool)
runnable_config (RunnableConfig)
add_store (bool)
agent_settings (dict[str, Any])
subagents (dict[str, AgentConfig])
persistence (CheckpointerConfig | None)
checkpoint_mode (str)
enable_analysis (bool)
player_names (list[str])
llm_config (dict[str, Any] | None)
map_name (str)
map_locations (list[str] | None)
num_impostors (int)
emergency_meetings_per_player (int)
discussion_time (int)
voting_time (int)
player_movement_speed (float)
kill_cooldown (int)
task_bar_updates (Literal['always', 'meetings', 'never'])
Create configuration for casual gameplay.
Features: - Balanced timing for relaxed discussion - Standard movement speed - Moderate kill cooldown - Visualization enabled
player_count (int) – Number of players (default: 6).
Casual game configuration.
AmongUsAgentConfig
Create configuration for educational/demonstration purposes.
Features: - Extended discussion for learning - Slower pace for observation - Higher movement speed for clarity - Always show task progress
player_count (int) – Number of players (default: 5).
Educational configuration.
AmongUsAgentConfig
Set default values based on provided values.
Create configuration for fast-paced gameplay.
Features: - Short discussion and voting times - Fast movement speed - Reduced kill cooldown - Quick decision making
player_count (int) – Number of players (default: 8).
Speed game configuration.
AmongUsAgentConfig
Create configuration for tournament play.
Features: - Extended discussion time for strategy - Longer voting time for careful decisions - Reduced kill cooldown for action - Competitive balance
player_count (int) – Number of players (default: 10).
Tournament configuration.
AmongUsAgentConfig
This function is meant to behave like a BaseModel method to initialise private attributes.
It takes context as an argument since that’s what pydantic-core passes when calling it.
self (BaseModel) – The BaseModel instance.
context (Any) – The context.
None
Calculate game balance metrics and recommendations.
Balance analysis including ratios and recommendations.
Dict[str, Any]
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
Current phase of gameplay.
Game alternates between task/action phases and discussion/voting.
TASKS: Normal gameplay with movement and actions MEETING: Discussion phase after body report or emergency VOTING: Active voting to eject a player GAME_OVER: Game concluded with winner determined
Comprehensive state model for Among Us game sessions.
This class manages all aspects of an Among Us game state, including spatial layout, player tracking, task management, and game progression. It provides methods for querying game state, updating player positions, managing events, and evaluating win conditions.
The state model supports: - Multiple map layouts (currently Skeld, with Polus/Mira HQ planned) - Real-time player position and status tracking - Task assignment and completion monitoring - Sabotage event lifecycle management - Emergency meeting and voting systems - Observation and memory tracking for deduction - Flexible win condition evaluation
data (Any)
players (list[str])
current_player_idx (int)
game_phase (AmongUsGamePhase)
game_status (str)
move_history (list[dict[str, Any]])
round_number (int)
player_data (dict[str, dict[str, Any]])
public_state (dict[str, Any])
error_message (str | None)
map_locations (list[str])
map_name (str)
rooms (dict[str, Room])
vents (dict[str, Vent])
player_states (dict[str, PlayerState])
tasks (dict[str, Task])
sabotages (list[SabotageEvent])
eliminated_players (list[str])
meeting_active (bool)
meeting_caller (str | None)
reported_body (str | None)
votes (dict[str, str])
impostor_count (int)
crewmate_count (int)
discussion_history (list[dict[str, Any]])
kill_cooldowns (dict[str, int])
List of valid room IDs for the current map. Used for movement validation and spawn points.
list[str]
Name of the current map (e.g., “skeld”, “polus”). Determines room layout and task locations.
str
Mapping of room IDs to Room objects. Defines spatial layout and connections.
dict[str, haive.games.among_us.models.Room]
Mapping of vent IDs to Vent objects. Enables impostor movement through vent network.
dict[str, haive.games.among_us.models.Vent]
Mapping of player IDs to PlayerState objects. Tracks all player information including role and position.
dict[str, haive.games.among_us.models.PlayerState]
Mapping of task IDs to Task objects. Defines available tasks and their completion status.
dict[str, haive.games.among_us.models.Task]
List of active and resolved sabotage events. Tracks sabotage history and current emergencies.
list[haive.games.among_us.models.SabotageEvent]
List of player IDs who have been eliminated. Used for ghost mechanics and win conditions.
list[str]
Whether an emergency meeting is in progress. Pauses gameplay and enables discussion/voting.
bool
Player ID who called the current meeting. None if meeting was triggered by body report.
str | None
Player ID of body that triggered meeting. None if meeting was called via emergency button.
str | None
Mapping of voter ID to target ID for current meeting. Tracks voting progress and determines ejection.
dict[str, str]
Current phase of gameplay. Controls available actions and UI state.
haive.games.among_us.models.AmongUsGamePhase
Number of living impostors. Cached for efficient win condition checks.
int
Number of living crewmates. Cached for efficient win condition checks.
int
List of discussion events and messages. Provides context for AI decision-making.
list[dict[str, Any]]
Mapping of impostor ID to remaining cooldown. Prevents rapid elimination chains.
dict[str, int]
Examples
Creating a new game state:
Checking task progress:
Managing meetings:
Validate map name is supported.
v (str) – Map name to validate.
Validated map name in lowercase.
str
ValueError – If map name is not supported.
Add an observation to a player’s memory.
Observations form the basis of deduction in Among Us. This method records what a player has witnessed for later analysis.
player_id (str) – ID of the observing player.
observation (str) – Description of what was observed.
None
Examples
Witnessing movement:
Task verification:
Add an observation to all players in a specific room.
Used for events that are visible to everyone in a location, such as sabotages, eliminations, or visual tasks.
room_id (str) – Room where the event occurred.
observation (str) – Description of the observed event.
exclude_players (list[str] | None) – Optional list of player IDs to exclude. Typically used to exclude the actor from observations.
None
Examples
Elimination witnessed:
Visual task:
Check if either side has achieved victory.
Evaluates all win conditions for both teams:
Crewmate victories: - All tasks completed - All impostors eliminated
Impostor victories: - Impostor count >= crewmate count - Critical sabotage timer expired
Winning team or None.
Optional[Literal[“crewmates”, “impostors”]]
Examples
Task victory:
Impostor majority:
Sabotage victory:
Decrement all active kill cooldowns by 1 second.
Should be called each game tick/second to update cooldowns. Automatically removes cooldowns that reach 0.
Examples
Game loop integration:
None
Get the currently active sabotage event.
Only one sabotage can be active at a time. This method returns the first unresolved sabotage found.
Active sabotage or None.
Optional[SabotageEvent]
Examples
Emergency response:
Checking if sabotage is possible:
Get list of alive player IDs.
Returns only players who have not been eliminated, useful for voting counts, task assignments, and win condition checks.
IDs of all living players.
List[str]
Examples
During meeting:
Win condition check:
Get all rooms directly connected to the given room.
Returns only accessible connections (not blocked by sabotage). Used for pathfinding and movement validation.
room_id (str) – Source room to check connections from.
IDs of all accessible connected rooms.
List[str]
Examples
Movement options:
Sabotage effects:
Get all vents connected to the given vent.
Used for impostor movement through the vent network. All vent connections are always accessible (no blocking).
vent_id (str) – Source vent to check connections from.
IDs of all connected vents.
List[str]
Examples
Vent navigation:
Get a player’s kill cooldown in seconds.
player_id (str) – ID of the player (impostor) to check.
Remaining cooldown seconds (0 if can kill).
int
Examples
Checking kill availability:
Get a room by its unique identifier.
room_id (str) – Unique room identifier (e.g., “cafeteria”).
Room object if found, None otherwise.
Optional[Room]
Examples
Checking room properties:
Calculate overall task completion percentage.
Computes the percentage of all tasks that have been completed across all crewmates. This is a primary win condition - crewmates win immediately when this reaches 100%.
Percentage of completed tasks (0-100).
float
Examples
Progress tracking:
Win condition:
Note
Returns 100.0 if no tasks exist (edge case handling).
Get a vent by its unique identifier.
vent_id (str) – Unique vent identifier (e.g., “electrical_vent”).
Vent object if found, None otherwise.
Optional[Vent]
Examples
Checking vent connections:
Get all vents located in a specific room.
Used for impostor movement options and vent camping detection.
room_id (str) – Room to search for vents.
All vents in the specified room.
List[Vent]
Examples
Impostor options:
Initialize the map with rooms and vents based on the map name.
Creates the spatial layout for the selected map, including all rooms, connections, and vent networks. Currently supports the Skeld map with plans for Polus and Mira HQ.
The initialization includes: - Room creation with connections and properties - Vent network setup with travel times - Map location list for spawn points
Examples
Default Skeld initialization:
Future map support:
Note
This method clears any existing rooms and vents before creating the new map layout.
None
Set a player’s kill cooldown.
Typically called after an impostor eliminates someone.
player_id (str) – ID of the player (impostor).
cooldown (int) – Cooldown duration in seconds.
None
Examples
After elimination:
Custom game settings:
Calculate comprehensive game statistics.
Statistics including player counts, progress, etc.
Dict[str, Any]
Examples
Displaying game stats:
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
Comprehensive state management mixin for Among Us social deduction gameplay.
This mixin class provides complete state management functionality for Among Us games, handling complex mechanics including role-based gameplay, task systems, sabotage mechanics, meeting coordination, and win condition evaluation. The class separates state management from agent behavior, allowing any inheriting class to gain full Among Us state management capabilities.
The state manager handles: - Game initialization with intelligent role assignment - Task generation and completion tracking - Complex sabotage systems with resolution mechanics - Meeting and voting coordination - Move validation and application - Win condition evaluation - Player state filtering for information hiding - Legal move generation for AI systems
Examples
Initializing a new game:
Applying player actions:
Checking game progression:
Note
This mixin is designed to be inherited by game agents, providing state management capabilities without imposing specific agent behaviors.
Advance the game to the next phase in the game cycle.
Progresses the game through its phases: TASKS -> MEETING -> VOTING -> TASKS. Updates related state variables and resets phase-specific data.
state (AmongUsState) – Current game state to advance.
Updated state in the next phase.
AmongUsState
Examples
Task to meeting transition:
Meeting to voting transition:
Voting to tasks transition:
Apply a player’s move to the game state with comprehensive validation.
Processes and validates player moves, updating the game state accordingly. Handles all move types across different game phases with proper error handling and state consistency maintenance.
state (AmongUsState) – Current game state to modify.
player_id (str) – ID of the player making the move.
move (dict[str, Any]) – Move dictionary containing action and parameters.
Updated game state after applying the move.
AmongUsState
Examples
Movement action:
Task completion:
Impostor kill:
Voting action:
Note
The method creates a deep copy of the state to avoid modifying the original, ensuring state immutability.
Check and update game status with win condition evaluation.
Evaluates the current game state to determine if any win conditions have been met and updates the game status accordingly.
state (AmongUsState) – Current game state to check.
Updated state with current game status.
AmongUsState
Examples
Ongoing game:
Crewmate victory:
Impostor victory:
Filter game state to include only information visible to a specific player.
Creates a filtered view of the game state that includes only information the specified player should have access to, implementing proper information hiding for authentic social deduction gameplay.
state (AmongUsState) – Complete game state to filter.
player_id (str) – ID of the player to create filtered state for.
Filtered state dictionary with player-visible information.
Dict[str, Any]
Examples
Crewmate filtered state:
Impostor filtered state:
Dead player filtered state:
Generate comprehensive legal moves for a player based on game state.
Analyzes the current game state and player situation to generate all valid moves available to the player, considering their role, location, game phase, and current constraints.
state (AmongUsState) – Current game state.
player_id (str) – ID of the player to generate moves for.
List of legal move dictionaries.
List[Dict[str, Any]]
Examples
Crewmate in task phase:
Impostor in task phase:
Player in voting phase:
Initialize a new Among Us game state with intelligent defaults.
Creates a complete game state with role assignments, task generation, map initialization, and all necessary game components. The initialization process follows standard Among Us rules for balanced gameplay.
player_names (list[str]) – List of player identifiers (4-15 players).
**kwargs – Additional configuration options. map_name (str): Map to use (default: “skeld”). num_impostors (int): Number of impostors (auto-calculated if None). tasks_per_player (int): Tasks per crewmate (default: 5). kill_cooldown (int): Impostor kill cooldown in seconds (default: 45). seed: Random seed for reproducible games.
Fully initialized game state ready for gameplay.
AmongUsState
Examples
Standard initialization:
Custom configuration:
Note
The initialization automatically balances impostor count based on player count following standard Among Us ratios.
Cognitive model for player observations and deductions.
Tracks what a player has observed and deduced during gameplay, forming the basis for social deduction. Memory includes direct observations, suspicion levels, alibis, and movement patterns.
data (Any)
observations (list[str])
player_suspicions (dict[str, float])
player_alibis (dict[str, str])
location_history (list[str])
Chronological list of observations.
List[str]
Suspicion levels (0-1) per player.
Dict[str, float]
Last known locations of players.
Dict[str, str]
Recent rooms visited by this player.
List[str]
Examples
Tracking suspicious behavior:
Building alibis:
Ensure suspicion levels are within valid range.
v (Dict[str, float]) – Suspicion dictionary to validate.
Validated suspicion levels.
Dict[str, float]
ValueError – If suspicion level outside 0-1 range.
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
Identify the most suspicious player.
Player ID with highest suspicion or None.
Optional[str]
List players with low suspicion (< 0.3).
IDs of trusted players.
List[str]
Player roles defining objectives and abilities.
Determines the player’s win condition and available actions: - Crewmates: Complete tasks and identify impostors - Impostors: Eliminate crew and avoid detection
CREWMATE: Innocent crew member focused on tasks IMPOSTOR: Deceptive player who can kill and sabotage
Complete state representation for a player in Among Us.
Encapsulates all information about a player including their role, location, tasks, survival status, and cognitive state. Supports both crewmate and impostor gameplay with appropriate abilities.
data (Any)
id (str)
role (PlayerRole)
location (str)
tasks (list[Task])
is_alive (bool)
last_action (str | None)
observations (list[str])
in_vent (bool)
current_vent (str | None)
memory (PlayerMemory)
Unique player identifier.
str
Crewmate or Impostor designation.
PlayerRole
Current room location.
str
Assigned tasks (empty for impostors).
List[Task]
Whether player is still active.
bool
Most recent action taken.
Optional[str]
Direct observations this turn.
List[str]
Whether currently hiding in vent.
bool
ID of occupied vent.
Optional[str]
Cognitive state and deductions.
PlayerMemory
Examples
Crewmate with tasks:
Impostor in vent:
Dead player:
Check if the player can perform a kill action.
Kill ability requires: - Impostor role - Being alive - Kill cooldown expired - Not currently in vent
kill_cooldown (int) – Remaining cooldown seconds.
True if all conditions met for killing.
bool
Examples
Check if the player can use ventilation systems.
Vent usage requires: - Impostor role - Being alive
True if player can enter/exit vents.
bool
Examples
Check if the player is a crewmate.
True if player has crewmate role.
bool
Examples
Check if the player is an impostor.
True if player has impostor role.
bool
Examples
Get list of uncompleted tasks.
Tasks that still need completion.
List[Task]
Check if player is a ghost (dead but still participating).
True if player is dead.
bool
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
Calculate percentage of tasks completed.
Completion percentage (0.0-100.0).
float
Individual task assignment for crewmates.
Tasks are the primary objective for crewmates, requiring them to visit specific locations and complete mini-games. Visual tasks can prove innocence by showing animations to nearby players.
data (Any)
id (str)
type (TaskType)
location (str)
description (str)
status (TaskStatus)
visual_indicator (bool)
Unique task identifier.
str
Category of task affecting behavior.
TaskType
Room where task must be performed.
str
Human-readable task description.
str
Current completion state.
TaskStatus
Whether task shows visible proof.
bool
Examples
Visual task proving innocence:
Common electrical task:
Calculate task completion percentage.
0.0 for not started, 0.5 for in progress, 1.0 for completed.
float
Check if task is fully completed.
True if task status is COMPLETED.
bool
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
Task completion status for tracking progress.
NOT_STARTED: Task not yet attempted IN_PROGRESS: Task partially completed COMPLETED: Task fully finished
Types of tasks with different characteristics.
Task types affect completion time and verification: - Visual tasks provide visible proof of innocence - Common tasks are shared by all crewmates - Short/Long tasks vary in completion time
VISUAL: Tasks with visible animations (proves innocence) COMMON: Tasks assigned to all crewmates SHORT: Quick tasks (1-3 seconds) LONG: Extended tasks (5-10 seconds)
The Ultimate AI Social Psychology Laboratory
Among Us provides the most sophisticated platform for studying AI deception, trust, and social reasoning. AI agents demonstrate:
Strategic Deception: Convincing lies and misdirection
Behavioral Analysis: Reading other agents’ tells and patterns
Alliance Formation: Dynamic team building and betrayal
Social Influence: Manipulating group decision-making
Quick Start: AI Social Deduction
Advanced Among Us Features
Mafia/Werewolf - Hidden Role Psychology¶
Module exports.
Classic Social Deduction with Advanced AI Psychology
The Mafia implementation features sophisticated day/night cycles, role-based psychology, and complex information asymmetry.
Key Features: * Hidden Role Psychology: Different AI behaviors for Mafia vs Townspeople * Information Asymmetry: Complex knowledge modeling and strategic information sharing * Day/Night Mechanics: Different behavioral patterns for different game phases * Social Network Analysis: Dynamic relationship tracking and influence modeling
Debate - Argumentative AI Intelligence¶
Debate game module for structured argumentation.
Intelligent agent for facilitating structured debates and discussions.
The DebateAgent orchestrates multi-participant debates with sophisticated phase management, role-based interaction, and configurable formats. It handles participant turn management, moderator functions, voting systems, and comprehensive state tracking throughout the debate lifecycle.
This agent supports various debate formats including parliamentary, Oxford-style, Lincoln-Douglas, and trial simulations. It can manage AI participants, human participants, or hybrid groups with appropriate context preparation and response extraction for each role.
config (DebateAgentConfig)
Manages all debate state transitions and rule enforcement throughout the debate process.
DebateStateManager
Configuration object containing debate format, timing, participant roles, and other behavioral settings.
DebateAgentConfig
Examples
Creating and configuring a debate agent:
Running a debate with custom topic:
Handling trial format:
Note
The agent requires appropriate engines to be configured for different participant roles. Each role (debater, moderator, judge, etc.) should have corresponding engine configurations in the agent setup.
alias of
DebateAgentConfigInitialize the debate agent with configuration.
config (DebateAgentConfig) – Configuration object containing debate format, timing rules, participant roles, and behavioral settings.
None
Note
The state_manager is set as a class reference and will be used to create instances for state management operations.
Handle the initial debate setup and configuration phase.
Configures participant roles, assigns moderator if specified, and advances the debate to the first active phase. This method applies configuration-based role assignments and sets up special roles like moderators before beginning the actual debate proceedings.
state (Dict[str, Any]) – Current state dictionary or DebateState object containing initialized participants and topic information.
LangGraph command to transition to participant turn handling with updated state including role assignments and phase advancement.
Command
Examples
Setting up debate with configured roles:
Setting up with automatic moderator:
Note
Role assignment from config takes precedence over default assignments. If moderator_role is enabled, the first player becomes moderator. Always advances to opening statements phase after setup.
Determine the next step in the debate workflow.
Analyzes the current debate state to decide whether to continue with participant turns, transition to the next phase, or end the debate. Uses phase-specific completion criteria to ensure proper debate flow and timing.
state (DebateState) – Current debate state including phase information, participant data, statements, and votes.
Next workflow step identifier: - END: Debate has concluded or game status is not ongoing - “handle_phase_transition”: Current phase is complete, advance - “handle_participant_turn”: Continue with next participant
str
Examples
Checking phase completion:
Note
Phase completion criteria: - Opening/Closing: All participants have made statements - Voting: All participants have cast votes - Other phases: Use turn-based progression
Extract and structure move data from engine response.
Processes responses from AI engines or other participants, converting them into standardized move dictionaries that can be applied to the debate state. Handles different response types based on participant role and response format.
response (Any) – Raw response from the participant’s engine. Can be a Statement object, dictionary with structured data, or raw text.
role (str) – Role of the participant (affects response interpretation). Roles like “moderator” have special handling for actions.
Structured move dictionary with standardized format.
type: “statement”
content: Text content of the statement
statement_type: Category (opening, rebuttal, etc.)
target_id: Optional target participant
references: Supporting evidence or citations
type: “vote”
vote_value: The vote decision
target_id: What/who is being voted on
reason: Explanation for the vote
type: “moderation”
action: Moderator action to take
note: Additional context or explanation
Dict[str, Any]
Examples
Extracting statement from structured response:
Extracting vote from dictionary:
Note
Fallback behavior treats any unrecognized response as a general statement to ensure debate flow continues even with unexpected responses.
Get the role of a specific player in the debate.
Retrieves the assigned role for a participant from the debate state. Roles determine how participants interact with the debate, what context they receive, and how their responses are processed.
state (DebateState) – Current debate state containing participant data.
player_id (str) – Unique identifier of the participant.
The participant’s role (e.g., “debater”, “moderator”, “judge”, “prosecutor”, “defense”, “witness”). Returns “debater” if participant not found or no role assigned.
str
Examples
Getting participant roles:
Note
Default role is “debater” for unknown participants to ensure graceful handling of edge cases during debate flow.
Handle special processing for moderator participant turns.
Processes moderator-specific actions including debate guidance, phase advancement, time management, and procedural interventions. Moderators have special privileges and different context preparation compared to regular debaters.
state (DebateState) – Current debate state with moderator information and designated moderator ID.
Updated state after moderator action, with potential phase changes, turn order adjustments, or procedural updates.
DebateState
Examples
Moderator managing debate flow:
Moderator providing guidance:
Note
If no moderator is designated or no moderator engine is available, the turn is skipped and normal turn progression continues. Moderator “advance_phase” actions trigger immediate phase transitions.
Handle individual participant turns within the debate.
Manages the core debate loop by processing each participant’s turn, including context preparation, engine invocation, move extraction, and state updates. Handles special cases for different participant roles and manages error recovery to maintain debate flow.
state (Dict[str, Any]) – Current debate state containing participant information, statements, phase data, and turn order.
LangGraph command for next step in debate flow. Can be: - END: If debate has concluded or game status is not ongoing - handle_participant_turn: Continue with next participant - handle_phase_transition: Advance to next debate phase
Command
Examples
Normal participant turn flow:
Handling moderator turn:
Note
Automatically handles error recovery by skipping problematic turns. Engine selection is based on participant role and position. State visualization occurs if configured in agent settings.
Handle transition between debate phases.
state (dict[str, Any])
Command
Initialize the debate with topic, participants, and configuration.
Sets up the initial debate state including topic validation, participant registration, role assignment, and format-specific configuration. This method handles both structured topic objects and simple string topics, creating a fully configured debate state ready for the setup phase.
state (Dict[str, Any]) – Initial state containing debate setup data. Expected keys: - topic (Union[str, Dict]): Debate topic as string or structured data - participants (Union[List[str], Dict]): List of participant IDs
LangGraph command to transition to debate_setup phase with initialized state data.
Command
Examples
Basic initialization with string topic:
Initialization with structured topic:
Note
If no topic is provided, defaults to “AI Ethics in Society”. If no participants are provided, creates 4 default participants. Participant roles are assigned during the setup phase based on config.
Prepare contextual information for a participant’s move.
Generates role-specific context that provides participants with relevant information for making their next move. Context varies significantly based on participant role (debater, moderator, judge, etc.) and current debate phase, ensuring each participant receives appropriate information.
state (DebateState) – Current debate state with all participants, statements, votes, and phase information.
player_id (str) – Unique identifier of the participant whose turn it is.
Role-specific context dictionary containing relevant information for the participant’s decision-making. Contents vary by role:
topic: Debate topic and description
debate_phase: Current phase of debate
position: Participant’s stance (pro/con/neutral)
recent_statements: Last 5 statements from all participants
your_statements: Participant’s previous statements
statement_type: Expected type for current phase
topic: Debate topic and description
debate_phase: Current phase of debate
participants: List of all participants with roles
recent_statements: Recent debate activity
current_speaker: Who is currently speaking
action_prompt: Suggested moderator action
topic: Debate topic and description
debate_phase: Current phase of debate
all_statements: Complete statement history
key_arguments: Extracted pro/con arguments
action_prompt: Evaluation guidance
Dict[str, Any]
Examples
Preparing context for debater:
Preparing context for moderator:
Note
Returns empty dict if participant not found in state. Context is optimized for AI engines but human-readable for hybrid debates.
Setup the debate workflow.
None
Visualize the current debate state.
state (dict[str, Any])
None
Comprehensive configuration for debate agents with format-specific settings.
This configuration class provides extensive customization options for debate agents, supporting various debate formats, role assignments, timing controls, and engine configurations. It includes validation for debate-specific parameters and provides factory methods for common debate formats.
The configuration system supports: - Multiple debate formats (standard, parliamentary, oxford, trial, presidential) - Flexible role assignment system for participants - Timing controls and statement limits - Interruption and voting settings - Custom engine configurations for different participant roles
id (str)
name (str)
engine_type (EngineType)
description (str | None)
input_schema (type[BaseModel] | dict[str, Any] | None)
output_schema (type[BaseModel] | dict[str, Any] | None)
version (str)
metadata (dict[str, Any])
engine (Engine | str | None)
engines (dict[str, AugLLMConfig])
state_schema (type[BaseModel])
node_configs (dict[str, NodeConfig])
patterns (list[PatternConfig])
pattern_parameters (dict[str, dict[str, Any]])
default_patterns (list[str | dict[str, Any]])
visualize (bool)
output_dir (str)
debug (bool)
save_history (bool)
runnable_config (RunnableConfig)
add_store (bool)
agent_settings (dict[str, Any])
subagents (dict[str, AgentConfig])
persistence (CheckpointerConfig | None)
checkpoint_mode (str)
debate_format (str)
time_limit (int | None)
max_statements (int | None)
allow_interruptions (bool)
voting_enabled (bool)
moderator_role (str | None)
participant_roles (dict[str, str])
Format type determining debate structure and rules. Supported formats: “standard”, “parliamentary”, “oxford”, “trial”, “presidential”, “panel”, “lincoln_douglas”.
str
Maximum time in seconds per debate phase. None means no time limit. Typical values: 60-600 seconds.
Optional[int]
Maximum statements per participant per phase. None means unlimited statements. Typical values: 1-5 statements.
Optional[int]
Whether participants can interrupt each other during their statements. Common in presidential and panel formats.
bool
Whether to include a voting phase at debate end. Typically enabled for competitive debates, disabled for discussions.
bool
Specific role identifier for the moderator. None means no dedicated moderator. Common value: “moderator”.
Optional[str]
Mapping of participant IDs to their roles. Keys are participant identifiers, values are role names like “pro”, “con”, “judge”, “moderator”, “prosecutor”, “defense”, “witness”.
Dict[str, str]
Pydantic model class for debate state. Defaults to DebateState but can be customized for specific formats.
Type[BaseModel]
Engine configurations for different roles. Automatically built by build_debate_engines but can be customized.
Dict[str, AugLLMConfig]
Examples
Basic debate configuration:
Trial simulation configuration:
Parliamentary debate configuration:
Note
The configuration automatically sets up appropriate engines for each role using the build_debate_engines factory. Custom engines can be provided to override defaults for specific use cases or to add specialized capabilities.
Create a default configuration for standard debate.
Create a configuration for a panel discussion.
Create a configuration for presidential debate.
Create a configuration for a trial format.
Validate debate format is supported.
v (str) – Debate format to validate.
Validated format string.
str
ValueError – If format is not supported.
Validate participant role assignments.
v (Dict[str, str]) – Role assignments to validate.
Validated role assignments.
Dict[str, str]
ValueError – If role assignments are invalid.
This function is meant to behave like a BaseModel method to initialise private attributes.
It takes context as an argument since that’s what pydantic-core passes when calling it.
self (BaseModel) – The BaseModel instance.
context (Any) – The context.
None
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
State model for debate-style interactions.
data (Any)
players (list[str])
current_player_idx (int)
game_phase (str)
game_status (str)
move_history (list[dict[str, Any]])
round_number (int)
player_data (dict[str, dict[str, Any]])
public_state (dict[str, Any])
error_message (str | None)
topic (Topic)
participants (dict[str, Participant])
statements (list[Statement])
current_speaker_idx (int)
debate_phase (str)
phase_time_limit (int | None)
phase_statement_limit (int | None)
votes (dict[str, list[Vote]])
scores (dict[str, float])
interruptions_allowed (bool)
moderator_id (str | None)
moderation_notes (list[str])
time_remaining (dict[str, int])
turn_order (list[str])
Get the current speaker’s ID.
str
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
Manager for debate game states.
Advance to the next debate phase.
state (DebateState) – Current debate state
State in the next phase
DebateState
Apply a player’s move to the state.
state (DebateState) – Current debate state
player_id (str) – ID of the player making the move
move (dict[str, Any]) – Move to apply (typically a statement)
Updated debate state
DebateState
Check and update game status.
state (DebateState) – Current debate state
Updated debate state with status
DebateState
Filter state information for a specific player.
state (DebateState) – Current debate state
player_id (str) – ID of the player
Filtered state visible to the player
Dict[str, Any]
Get legal moves for a player.
state (DebateState) – Current debate state
player_id (str) – ID of the player
List of legal moves
List[Dict[str, Any]]
Initialize a new debate state.
player_names (list[str]) – List of participant IDs
topic (Topic) – The debate topic
format_type (str) – Type of debate (presidential, trial, etc.)
**kwargs – Additional format-specific parameters
A new debate state
DebateState
Advanced Argumentation and Persuasion Systems
The Debate system represents sophisticated AI argumentation with real-time research, evidence evaluation, and persuasion tactics.
Revolutionary Features: * Real-Time Research: AI agents research topics during debate preparation * Evidence Evaluation: Sophisticated fact-checking and source credibility analysis * Persuasion Tactics: Advanced rhetorical strategies and audience psychology * Multi-Format Support: Parliamentary, Oxford-style, Lincoln-Douglas formats
Advanced Social Mechanics¶
Dynamic Personality Evolution¶
Adaptive Personality Systems that evolve based on social interactions:
Alliance Formation & Betrayal¶
Complex Social Network Dynamics:
Social Influence Modeling¶
Advanced Persuasion and Manipulation:
Psychological Research Features¶
Behavioral Pattern Analysis¶
Comprehensive Psychology Profiling:
Multi-Game Social Consistency¶
Cross-Game Personality Tracking:
Social Network Evolution¶
Dynamic Relationship Modeling:
Tournament Social Intelligence¶
Cross-Provider Social Comparison¶
Compare AI Provider Social Intelligence:
Emergent Behavior Research¶
Study Emergent Social Phenomena:
Performance Metrics¶
Social Intelligence Benchmarks:
Deception Success Rate: 85% for advanced manipulator personalities
Trust Calibration: ±0.1 accuracy in trust assessment
Alliance Stability: 70% alliance survival rate across game phases
Influence Propagation: <3 hops for 90% influence spread
Behavioral Adaptation: 0.2 personality shift per significant interaction
Research Applications:
Academic Research: Social psychology, game theory, multi-agent coordination
Commercial Intelligence: Negotiation training, team dynamics, leadership development
AI Safety Research: Understanding AI social manipulation and cooperation patterns
Integration with Other Systems¶
Social psychology games integrate with the main haive-agents framework for sophisticated agent orchestration.
Hot-swap personalities, strategies, and social parameters during gameplay for adaptive research.
Full integration with cross-provider tournament system for competitive social intelligence analysis.
See Also¶
Tournament System - Multi-Agent & LLM Benchmarking - Cross-provider social intelligence tournaments
multi_agent_coordination - Integration with haive-agents framework
dynamic_configuration - Real-time personality and strategy modification
benchmark_framework - Performance analysis and optimization