Teams API

Team management for multi-agent collaboration. Spawn teams of persistent agents that communicate and coordinate on shared tasks.

Overview

Teams are groups of persistent Luna agents that share a work queue and can communicate via the agent mailbox system. Each team has a configurable size (default 3, max 10). Teammates persist across multiple tasks until stop_team() is called. Teams use ACP for inter-agent messaging.

Authentication

Requires Authorization: Bearer <token>. Team operations are scoped to the authenticated user.

Endpoints

Create Team

POST /api/v1/teams

Request Body:

{
  "name": "research-team",
  "size": 3,
  "model": "claude-sonnet-4-20250514",
  "mode": "coordinate",
  "system_prompt": "You are a research team. Collaborate on literature review."
}

Response:

{
  "ok": true,
  "data": {
    "id": "team-abc123",
    "name": "research-team",
    "size": 3,
    "agents": ["agent-1", "agent-2", "agent-3"],
    "status": "active"
  }
}

List Teams

GET /api/v1/teams

Returns all teams owned by the authenticated user.

Get Team Details

GET /api/v1/teams/:id

Returns team status, member agents, and queue depth.

Dispatch Task to Team

POST /api/v1/teams/:id/dispatch

Request Body:

{
  "task": "Find all papers on quantum error correction from 2025-2026",
  "tools": ["web_search", "web_fetch", "read_file"],
  "parallel": true
}

Stop Team

DELETE /api/v1/teams/:id

Stops all team members and cleans up resources.

Background Tasks

POST /api/v1/teams/:id/background

Dispatch a fire-and-forget sub-agent task:

{
  "task": "Monitor logs for error patterns",
  "max_runtime_seconds": 3600
}

Team Communication:

Agents within a team communicate through the agent mailbox system (agent_mailbox.lua). Messages are routed via ACP:

Agent A  ──send──►  Mailbox A  ──►  TeamQueue  ──►  Agent B
                                                    Agent C

The team queue (team_queue.lua) provides FIFO work distribution with get_idle/mark_busy/mark_idle states. Teammates poll for work every 500ms.

Error Codes:

Code	Description
400	Invalid team parameters
401	Authentication required
404	Team not found
409	Team already at max size

Examples:

curl -X POST http://127.0.0.1:11434/api/v1/teams \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "research", "size": 3, "model": "claude-sonnet-4-20250514"}'

curl -X POST http://127.0.0.1:11434/api/v1/teams/team-abc123/dispatch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task": "Research topic", "parallel": true}'