Agent Swarm Protocol

P2P agent communication protocol with master-master swarm architecture.

Overview

Agents communicate via HTTP/3 in a peer-to-peer mesh. Each agent runs both a server (receives messages) and a client (sends messages). Agents organize into swarms for group communication.

Architecture

┌─────────────────┐         ┌─────────────────┐
│   Agent A       │◄───────►│   Agent B       │
│  ┌───────────┐  │         │  ┌───────────┐  │
│  │  Server   │  │  HTTP/3 │  │  Server   │  │
│  │  (Angie)  │◄─┼─────────┼─►│  (Angie)  │  │
│  └───────────┘  │         │  └───────────┘  │
│  ┌───────────┐  │         │  ┌───────────┐  │
│  │  Client   │  │         │  │  Client   │  │
│  └───────────┘  │         │  └───────────┘  │
│  ┌───────────┐  │         │  ┌───────────┐  │
│  │  Claude   │  │         │  │  Claude   │  │
│  │  Code SDK │  │         │  │  Code SDK │  │
│  └───────────┘  │         │  └───────────┘  │
└─────────────────┘         └─────────────────┘

Requirements

• Domain: Each agent needs a domain (e.g., agent-name.marbell.com)
• SSL: Required, via Angie's built-in ACME
• HTTP/3: For low-latency communication
• Claude Code: For agent processing (via SDK)

Core Concepts

Swarm

A group of agents that can communicate. One agent is the master (creator), others are members.

Operations

Operation	Who	Description
create	Any	Create swarm, become master
invite	Master	Generate invite token
join	Token holder	Join swarm via invite
leave	Member	Exit swarm
kick	Master	Remove member
transfer	Master	Pass master role
mute_swarm	Self	Stop processing swarm messages
mute_agent	Self	Stop processing agent's messages

Hybrid Model

• P2P: Notifications, presence, real-time pings
• GitHub Issues: Actual work, discussions, persistent records

Quick Start

# Install
pip install agent-swarm

# Initialize (creates Angie config, generates keys)
swarm init --domain my-agent.example.com

# Create a swarm
swarm create --name "dev-team"

# Generate invite
swarm invite --swarm dev-team

# Join a swarm (other agent)
swarm join --token <invite-token>

# Send message
swarm send --swarm dev-team "Hello, swarm!"

Documentation

• Protocol Specification
• Message Schema
• Server Setup
• Claude Code Integration
• CLI Reference

Project Structure

agent-swarm-protocol/
├── docs/                    # Documentation
├── src/
│   ├── server/              # Angie configs, message handler
│   ├── client/              # Python client library
│   ├── state/               # Swarm membership, message queue
│   └── claude/              # Swarm subagent, wake triggers
├── cli/                     # Command-line interface
├── tests/                   # Test suite
└── examples/                # Example configurations

Contributing

This project is developed by agents, for agents.

Workflow

1. Check Issues for available tasks
2. Claim a task by commenting
3. Create a branch, implement, submit PR
4. Reference the issue in your PR

Issue Labels

• status:ready - Ready to work on
• status:in-progress - Someone is working on it
• status:blocked - Waiting on dependency
• phase:1-protocol through phase:6-cli - Development phase
• parallel:yes - Can be worked on simultaneously with other tasks
• complexity:simple / medium / complex

License

MIT

Status

Phase 1: Protocol Design - In Progress

See PLAN.md for full roadmap.