Managing AI Players

This guide covers the in-game commands, REST API endpoints, and monitoring tools for managing AI Players. All admin commands require ADMIN access level.

In-Game Admin Commands

Player Management

Command	Description	Example
@ai status	List all AI Players with status summary	@ai status
@ai status <name>	Detailed status of a specific AI Player	@ai status Ava
@ai spawn <preset>	Spawn a new AI Player from a personality preset	@ai spawn explorer
@ai despawn <name>	Remove an AI Player (persists memory by default)	@ai despawn Ava
@ai pause <name>	Pause an AI Player's cognitive loop	@ai pause Ava
@ai resume <name>	Resume a paused AI Player	@ai resume Ava
@ai goal <name> <goal>	Manually set a goal for an AI Player	@ai goal Ava "Explore the Dark Forest"
@ai reset <name>	Reset AI Player's memory and plans	@ai reset Ava
@ai say <name> <message>	Force AI Player to say something	@ai say Ava "Hello everyone!"

Inspection & Debugging

Command	Description	Example
@ai memory <name>	Show recent memories (all layers)	@ai memory Ava
@ai memory <name> <layer>	Show memories from a specific layer	@ai memory Ava episodic
@ai plan <name>	Show current goals and plan hierarchy	@ai plan Ava
@ai thoughts <name>	Show last N thought traces	@ai thoughts Ava
@ai thoughts <name> --live	Stream thought traces in real-time	@ai thoughts Ava --live
@ai world <name>	Show the AI Player's internal world model	@ai world Ava
@ai cost <name>	Show cost report for a specific AI Player	@ai cost Ava
@ai cost	Show global cost report across all AI Players	@ai cost

Thought Traces for Debugging

Use @ai thoughts <name> --live to watch an AI Player's decision-making in real time. Each trace shows the Thought → Action pair from the ReAct framework, making it easy to understand why the player chose a particular action.

REST API

The admin API provides programmatic access to AI Player management under /admin/ai-players/. All endpoints require admin authentication.

Player Lifecycle

Method	Path	Description
GET	/admin/ai-players/	List all AI Players
POST	/admin/ai-players/	Spawn a new AI Player
GET	/admin/ai-players/{id}	Get AI Player details
PUT	/admin/ai-players/{id}	Update configuration
DELETE	/admin/ai-players/{id}	Despawn and remove
POST	/admin/ai-players/{id}/pause	Pause cognitive loop
POST	/admin/ai-players/{id}/resume	Resume cognitive loop
POST	/admin/ai-players/{id}/reset	Reset memory and plans

Inspection

Method	Path	Description
GET	/admin/ai-players/{id}/state	Current cognitive state
GET	/admin/ai-players/{id}/memory	Memory contents (paginated)
GET	/admin/ai-players/{id}/memory/{layer}	Memories by layer
GET	/admin/ai-players/{id}/plan	Current goals and plans
GET	/admin/ai-players/{id}/thoughts	Recent thought traces
GET	/admin/ai-players/{id}/cost	Cost report

Bulk Operations

Method	Path	Description
POST	/admin/ai-players/bulk/spawn	Spawn multiple AI Players
POST	/admin/ai-players/bulk/despawn	Despawn multiple AI Players
POST	/admin/ai-players/bulk/pause	Pause all AI Players
POST	/admin/ai-players/bulk/resume	Resume all AI Players
GET	/admin/ai-players/cost/global	Global cost report

Example: Spawn an AI Player

curl -X POST http://localhost:8080/admin/ai-players/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Explorer Ava",
    "personality_preset": "explorer",
    "initial_goals": ["Explore the Dark Forest"],
    "max_cost_per_hour": 0.10,
    "auto_respawn": true
  }'

Example: Check Cost Report

curl http://localhost:8080/admin/ai-players/cost/global \
  -H "Authorization: Bearer $TOKEN"

Monitoring

Key Metrics

Metric	What to Watch	Threshold
Cognitive tick duration	Should stay under 100ms	> 200ms = investigate
LLM call latency	Per-call response time	> 2s = provider issue
Cost per hour per agent	Budget burn rate	Configurable per agent
Stuck detection counter	Repeated identical actions	Auto-triggers replan
Memory count	Total memories per agent	Soft limits trigger forgetting

When an AI Player is Stuck

An AI Player is "stuck" when it repeats the same action without progress. The system detects this automatically and triggers replanning. If that fails:

1. Check the thought traces: @ai thoughts <name>
2. Inspect the world model: @ai world <name> — is the map accurate?
3. Review the plan: @ai plan <name> — is the goal achievable?
4. Manually set a new goal: @ai goal <name> "Go to the tavern"
5. As a last resort, reset: @ai reset <name>

Bug Reports

AI Players automatically file structured bug reports when they detect game anomalies — broken exits, command errors, state inconsistencies, and more. The bug filing pipeline runs after each action:

Anomaly Detector → Classifier → Report Builder → Store
  (deterministic)    (LLM)        (deterministic)   (deduplication)

The classifier distinguishes player errors (the AI made a mistake) from genuine game bugs. Only real bugs are filed. Duplicate reports are merged automatically — each new encounter increments the vote count rather than creating a separate report.

Bug Admin Commands

Command	Description	Example
@bugs list	List open bug reports (sorted by severity × votes)	@bugs list
@bugs show <id>	Show full bug report details	@bugs show abc123
@bugs acknowledge <id>	Mark a bug as acknowledged	@bugs acknowledge abc123
@bugs fix <id> [notes]	Mark a bug as fixed with optional notes	@bugs fix abc123 "Fixed exit in cave"

Bug Report Fields

Each report includes reproduction context: the exact command sequence, expected vs actual behavior, world model snapshot, and the AI Player's goal at the time. The votes field shows how many AI Players independently encountered the same issue — higher votes indicate a more impactful bug.

Deduplication

Reports are deduplicated by fingerprint (a hash of anomaly type + location + action + error). When a second AI Player hits the same bug, the existing report's vote count increments and its last_seen timestamp updates.

For the full specification of admin interfaces, see the AI Players specification §17–18.