9. Agent Teams

The Problem

Subagents are disposable: spawn, work, return summary, die. No identity, no memory between invocations. Background tasks run shell commands but can’t make LLM-guided decisions.

Real teamwork needs: (1) persistent agents that outlive a single prompt, (2) identity and lifecycle management, (3) a communication channel between agents.

The Solution

Teammate lifecycle:
  spawn -> WORKING -> IDLE -> WORKING -> ... -> SHUTDOWN

Communication:
  .team/
    config.json           <- team roster + statuses
    inbox/
      alice.jsonl         <- append-only, drain-on-read
      bob.jsonl
      lead.jsonl

          +--------+    send("alice","bob","...")    +--------+
          | lead   | -----------------------------> |  bob   |
          +--------+                                +--------+
               ^                                        |
               |           inbox/lead.jsonl             |
               +----------------------------------------+

How It Works

1. The team config stores roster and statuses.

import json, threading
from pathlib import Path

TEAM_DIR = Path(".team")
INBOX_DIR = TEAM_DIR / "inbox"
TEAM_DIR.mkdir(exist_ok=True)
INBOX_DIR.mkdir(exist_ok=True)

def init_team(teammates: list) -> None:
    config = {
        "teammates": [
            {"name": t["name"], "role": t["role"], "status": "IDLE"}
            for t in teammates
        ]
    }
    (TEAM_DIR / "config.json").write_text(json.dumps(config, indent=2))
    for t in teammates:
        (INBOX_DIR / f"{t['name']}.jsonl").touch()

def get_roster() -> list:
    config = json.loads((TEAM_DIR / "config.json").read_text())
    return config["teammates"]

2. Mailboxes are append-only JSONL files. Drain means read-and-truncate.

def send_message(to: str, from_: str, content: str) -> str:
    inbox = INBOX_DIR / f"{to}.jsonl"
    msg = {"from": from_, "content": content}
    with open(inbox, "a") as f:
        f.write(json.dumps(msg) + "\n")
    return f"Message sent to {to}."

def drain_inbox(name: str) -> list:
    inbox = INBOX_DIR / f"{name}.jsonl"
    if not inbox.exists() or inbox.stat().st_size == 0:
        return []
    lines = inbox.read_text().strip().split("\n")
    inbox.write_text("")  # truncate after reading
    return [json.loads(l) for l in lines if l]

3. Each teammate runs its own agent loop in a thread.

def teammate_loop(name: str, role: str) -> None:
    system = f"You are {name}, a {role}. Check your inbox for tasks."
    while True:
        inbox_messages = drain_inbox(name)
        if not inbox_messages:
            # IDLE: wait for work
            threading.Event().wait(timeout=2)
            continue

        update_status(name, "WORKING")
        history = [{"role": "user", "content":
            "\n".join(m["content"] for m in inbox_messages)}]
        # run agent loop with history
        result = run_agent(history, system)
        send_message("lead", name, result)
        update_status(name, "IDLE")

What Changed From Background Tasks

Key Takeaway

The mailbox pattern is what makes agent teams work. Each teammate has a private inbox on disk — durable, concurrent-safe, and transparent. The lead delegates by sending a message; the teammate drains its inbox and responds. No shared memory, no locks needed — just files.