Managing AI Players¶

This guide covers the REST API endpoints, CLI reporting, and monitoring tools for managing AI Players. Lifecycle mutations and takeover require the panel ADMIN role; read-only endpoints require VIEWER.

Management Surface¶

AI Players are managed through the admin REST API (documented below) and a read-only reporting CLI — there is no dedicated family of in-game @ai chat commands. The primary entry points are:

REST API under /admin/ai-players/ — create, update, delete, pause, resume, take over, inject commands, and inspect metrics for durable AI-player definitions.
CLI: maid dev ai-player-report — prints an aggregate summary, or per-player metrics when given --player <id> (add --violations for the violation history). It reads the admin API of a running server (--host/--port, defaulting to localhost:8080).
Programmatic: AIPlayerManager (maid_engine.ai_players.manager) exposes spawn, despawn, pause, resume, takeover, release_takeover, and related coroutines for embedding in custom tooling.

REST API¶

The admin API provides programmatic access to AI Player management under /admin/ai-players/. Read operations require VIEWER; lifecycle mutations and takeover require the panel ADMIN role.

Player Lifecycle¶

Method	Path	Description
`GET`	`/admin/ai-players/`	List durable definitions and live status
`POST`	`/admin/ai-players/`	Create a durable definition and start it
`PUT`	`/admin/ai-players/{id}`	Update persistent configuration
`DELETE`	`/admin/ai-players/{id}`	Despawn and permanently remove
`POST`	`/admin/ai-players/{id}/pause`	Pause cognitive loop
`POST`	`/admin/ai-players/{id}/resume`	Resume cognitive loop

Enabled definitions are loaded from data/ai_players/definitions.json and started automatically with stable AI-player IDs after an engine restart. Disabling a definition despawns its runtime character without deleting the configuration.

Administrative Takeover¶

The AI Players tab includes an embedded game console. Taking over a player:

Pauses the cognitive loop.
Rejects new AI-generated commands and clears commands queued before the takeover boundary.
Gives one administrator exclusive command injection through the player's existing game session.
Exposes a separate, non-destructive output transcript so observation does not consume the AI perception buffer.
Restores the player's previous active or paused state when control returns to the AI.

Method	Path	Description
`POST`	`/admin/ai-players/{id}/takeover`	Acquire exclusive control
`POST`	`/admin/ai-players/{id}/control/commands`	Queue a game command
`GET`	`/admin/ai-players/{id}/control/output?after=N`	Read incremental output
`POST`	`/admin/ai-players/{id}/release`	Return control to the AI

Another administrator receives 409 Conflict while a takeover is active. SUPERADMIN can force control or release for recovery. Creation, edits, deletion, takeover, release, and injected commands are audit logged.

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 Aggregate Status¶

curl http://localhost:8080/admin/ai-players/summary \
  -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 (via the stuck_detection_threshold setting) and triggers replanning. If that fails:

Review recent violations: GET /admin/ai-players/{id}/violations (or maid dev ai-player-report --player <id> --violations) to see what commands are failing.
Inspect per-player metrics: GET /admin/ai-players/{id}/metrics — check action counts, cost, and recent bug reports.
Take over the player: POST /admin/ai-players/{id}/takeover, then drive it manually with POST /admin/ai-players/{id}/control/commands to unstick it.
Update its configuration (goals, model tier) via PUT /admin/ai-players/{id}.
As a last resort, pause (/pause) or delete (DELETE /admin/ai-players/{id}) the definition.

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.

Reviewing Bug Reports¶

Filed bug reports are surfaced through the admin API rather than an in-game command:

GET /admin/ai-players/{id}/metrics returns a recent_bug_reports list for a single player (each entry has id, title, category, severity, and status).
GET /admin/ai-players/summary includes aggregate bug activity across all players.
maid dev ai-player-report --player <id> prints the per-player bug-report count.

When GitHub issue filing is enabled (MAID_AI_PLAYERS__GITHUB_ISSUES_ENABLED=true, with MAID_AI_PLAYERS__GITHUB_ISSUES_REPO and MAID_AI_PLAYERS__GITHUB_ISSUES_LABELS), deduplicated reports are also drained to GitHub Issues automatically.

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.