What You’ll Learn

• Why unstructured messages break at scale
• How to design a request-response protocol with IDs
• How protocols enable negotiation, voting, and coordination

The Problem

When 5 teammates send messages like “done”, “looks good”, “failing”, the lead agent can’t parse who said what about which task. Messages need structure.

The Solution

A protocol: every request has an ID, type, sender, and payload. Every response references the request ID.

{
  "id": "req-001",
  "type": "code_review",
  "sender": "lead",
  "recipient": "reviewer",
  "payload": {"file": "src/main.py", "context": "Refactored auth module"},
  "timestamp": "2024-01-15T10:30:00Z"
}

Response:

{
  "id": "resp-001",
  "ref": "req-001",
  "sender": "reviewer",
  "status": "approved",
  "payload": {"issues": [], "suggestions": ["Add docstring to top"]}
}

How It Works

1. A ProtocolHandler wraps mailbox I/O with structured message parsing.

2. Requests can have types: code_review, run_tests, approve_plan, shutdown.

3. The lead coordinates through typed requests and tracks responses by ID.

class ProtocolMessage:
    def __init__(self, id: str, type: str, sender: str,
                 recipient: str, payload: dict):
        self.id = id
        self.type = type
        self.sender = sender
        # ...

What Changed From s15

Component	Before (s15)	After (s16)
Messages	Plain text	Structured with ID, type
Coordination	Ad-hoc	Typed request-response
Debugging	Trace by reading	Track by request ID

Try It

cd learn-claude-code
python agents/s16_team_protocols.py

1. Send a code review request to teammate "reviewer"
2. Request a plan approval from all teammates (voting)
3. Send a shutdown signal to all active teammates

Key Takeaway

A protocol request is a structured message with an ID. The response must reference the same ID. Typed messages make team coordination comprehensible, debuggable, and scalable.