AI Groups - Holding Pool Pattern v2.1

Overview

The Holding Pool pattern provides a persistent queue where AI agents register and wait for assignment by an Ops manager. This simplifies the user experience - they just run /agent and an agent appears in the pool.

Architecture

┌─────────────────┐     ┌─────────────────┐
│   User runs     │     │   Agent Pool    │
│   /agent x4     │────▶│    (g_pool)     │
│                 │     │ a_1, a_2, a_3..│
└─────────────────┘     └────────┬────────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
                    ▼            ▼            ▼
              ┌──────────┐ ┌──────────┐ ┌──────────┐
              │ Work Grp │ │ Work Grp │ │ Work Grp │
              │ g_tcrn   │ │ g_xyz1   │ │ g_abc2   │
              │ (Recall) │ │ (Tests)  │ │ (Docs)   │
              └──────────┘ └──────────┘ └──────────┘

Key Concepts

Agent Pool (g_pool)

• Persistent holding group that always exists
• Agents register via aimsg.pool_register
• Agents wait via aimsg.wait(g_pool, agent_id)
• FIFO ordering - oldest available agent claimed first

Agent States

• available: Waiting in pool for assignment
• claimed: Ops has claimed but task not started
• working: Actively executing a task

Ops Claims

• aimsg.pool_claim(ops_id, target_group, task) claims an agent
• Agent wakes from wait() with assignment details
• Agent can be assigned to any work group

MCP Tools

For Agents

# Register in pool
aimsg.pool_register(agent_name='agent-term-1')
# Returns: {pool_id:'g_pool', agent_id:'a_xxxx', ...}

# Wait for assignment (blocks)
aimsg.wait(group_id='g_pool', my_id='a_xxxx', timeout=600)
# Returns: assignment message when claimed

For Ops

# List agents in pool
aimsg.pool_list(status='available')
# Returns: {total, available, claimed, working, agents:[]}

# Claim an agent
aimsg.pool_claim(ops_id='o_mhx8', target_group_id='g_tcrn', task='Build X')
# Returns: {agent_id, agent_name, next_steps}

# Release agent back to pool
aimsg.pool_release(agent_id='a_xxxx')
# Returns: {status:'available'}

# Remove agent from pool
aimsg.pool_release(agent_id='a_xxxx', remove=True)

Workflow Example

1. User opens 4 terminals, runs /agent in each
2. 4 agents register in pool: a_1, a_2, a_3, a_4
3. Main Claude (Ops o_mhx8) sees 4 available agents
4. Ops claims a_1 for "Build Recall server"
5. a_1 wakes up, receives task, starts working
6. Ops claims a_2 for "Write tests"
7. a_2 wakes up, receives task, starts working
8. When a_1 finishes, ops releases back to pool
9. a_1 available again for next task

Redis Keys

• aigroup:group:g_pool - Pool metadata
• aigroup:group:g_pool:agents - Hash of agent records
• aigroup:pool:queue - Sorted set for FIFO ordering
• aigroup:wait:g_pool:{agent_id} - BLPOP key for blocking

Version History

• v2.1.0 (2026-01-05): Initial holding pool implementation
• v2.0.0: Terminology overhaul (Group/Ops/Agent)
• v1.x: Original AI Groups with direct join