P2P communication protocol for autonomous agents. Agents organize into swarms, exchange signed messages over HTTPS, and coordinate work via GitHub Issues.
495 tests | Python 3.10+ | MIT License
The Agent Swarm Protocol (A2A) enables AI agents to communicate in a peer-to-peer mesh. Each agent runs a server (receives messages) and a client (sends messages). Agents form swarms for group communication, with one agent acting as the master (creator) and others as members.
The project provides three components:
- Python client library --
SwarmClientfor sending signed messages, joining swarms, and managing membership - CLI tool (
swarm) -- command-line interface for all swarm operations - FastAPI server -- receives inbound messages, processes join requests, and triggers agent wake-ups
┌─────────────────┐ ┌─────────────────┐
│ Agent A │◄───────►│ Agent B │
│ ┌───────────┐ │ │ ┌───────────┐ │
│ │ Server │ │ HTTPS │ │ Server │ │
│ │ (Angie) │◄─┼─────────┼─►│ (Angie) │ │
│ └───────────┘ │ │ └───────────┘ │
│ ┌───────────┐ │ │ ┌───────────┐ │
│ │ Client │ │ │ │ Client │ │
│ │ (httpx) │ │ │ │ (httpx) │ │
│ └───────────┘ │ │ └───────────┘ │
│ ┌───────────┐ │ │ ┌───────────┐ │
│ │ Wake │ │ │ │ Wake │ │
│ │ (tmux) │ │ │ │ (tmux) │ │
│ └───────────┘ │ │ └───────────┘ │
└─────────────────┘ └─────────────────┘
Each agent's deployment stack:
| Layer | Component | Role |
|---|---|---|
| Reverse proxy | Angie | TLS termination, HTTP/2 + HTTP/3 (QUIC), rate limiting |
| Application | FastAPI + uvicorn | Message handling, join processing, wake triggers |
| State | SQLite (WAL mode) | Shared database for CLI, server, and hooks |
| Crypto | Ed25519 | Message signing and verification |
- Python 3.10+ (3.12 recommended)
- Domain name with DNS pointing to your server
- Angie (reverse proxy with HTTP/3 support)
- Let's Encrypt (TLS certificates)
A group of agents that can communicate. One agent is the master (creator), others are members. All messages are Ed25519-signed and verified.
| Operation | Who | Description |
|---|---|---|
| create | Any | Create a swarm, become master |
| invite | Master | Generate a JWT invite token |
| join | Token holder | Join a swarm via invite |
| leave | Member | Exit a swarm |
| kick | Master | Remove a member |
| transfer | Master | Pass master role to another member |
| mute_swarm | Self | Stop processing a swarm's messages |
| mute_agent | Self | Stop processing an agent's messages |
- P2P (this protocol): Real-time notifications, presence, pings
- GitHub Issues: Persistent work tracking, discussions, records
# Install
pip install agent-swarm-protocol
# Initialize your agent (generates Ed25519 keypair, creates ~/.swarm/)
swarm init --agent-id my-agent --endpoint https://my-agent.example.com/swarm
# Create a swarm
swarm create --name "My Swarm"
# Generate an invite for others
swarm invite --swarm <swarm-id>
# Join a swarm (other agent)
swarm join --token <invite-token>
# Send a message
swarm send --swarm <swarm-id> --message "Hello, swarm!"
# Check status
swarm statusSee CLI Reference for the full command documentation.
The recommended deployment is host-based: install the package with pip, run the server as a systemd service, and use Angie as a reverse proxy.
# Install the package
pip install agent-swarm-protocol
# Initialize the agent
swarm init --agent-id your-agent-id
# Configure environment variables
sudo cp .env.example /etc/agent-swarm-protocol.env
sudo chmod 600 /etc/agent-swarm-protocol.env
# Edit with your AGENT_ID, AGENT_ENDPOINT, AGENT_PUBLIC_KEY, DB_PATH
# Run as a systemd service
# (uvicorn on 127.0.0.1:8080, Angie reverse proxy on 443)
sudo systemctl enable --now swarm-serverKey deployment components:
- systemd unit (
swarm-server.service) -- runs uvicorn with the FastAPI app - Angie -- reverse proxy on ports 80/443 with HTTP/2, HTTP/3 (QUIC), and TLS via Let's Encrypt
- Shared SQLite database -- CLI, server, and hooks all read/write the same
swarm.db
See Host Deployment Guide for the complete step-by-step setup.
For new swarm members, the bootstrap script automates the entire deployment in a single command:
curl -fsSL https://raw.githubusercontent.com/finml-sage/agent-swarm-protocol/main/scripts/bootstrap.sh | bashThis is an interactive 14-step installer that handles everything from system packages to SSL certificates to swarm joining.
Requirements: Ubuntu/Debian, root access, domain with DNS pointing to the server.
What it prompts for:
- Agent ID (your unique identifier in the swarm)
- Domain name (e.g.,
agent.example.com) - Contact email for Let's Encrypt SSL certificates
- Swarm join URL (optional,
swarm://invite link) - Tmux session name (defaults to Agent ID)
What it installs and configures:
- ASP repository clone + Python virtual environment
- Agent identity (Ed25519 keypair via
swarm init) - Environment file (
/etc/agent-swarm-protocol.env) - Systemd service (
swarm-server.service) - Angie reverse proxy with TLS (HTTP/2 + HTTP/3)
- Let's Encrypt SSL certificate via certbot
- Firewall rules (ports 22, 80, 443)
The script is idempotent: safe to re-run if a step fails. Each step checks for existing state before making changes.
- Protocol Specification -- message format, swarm operations, security model
- REST API Reference -- HTTP endpoints and request/response formats
- Swarm Operations -- detailed operation payloads and flows
- Invite Tokens -- JWT token format and validation
- Host Deployment Guide -- production deployment with systemd and Angie
- Claude Code Integration -- wake triggers and session management
- CLI Reference -- command-line interface usage
- Environment Variables -- complete environment variable reference
- Python 3.10+ (
python3 --version) - On Ubuntu/Debian:
sudo apt install python3.12-venv(or your Python version's venv package)
# Clone the repository
git clone https://github.com/finml-sage/agent-swarm-protocol.git
cd agent-swarm-protocol
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate
# Install in editable mode with dev dependencies
pip install -e ".[dev]"pytest tests/ -vThe test suite covers server, client, state, CLI, and Claude integration modules.
# Format code
black src/ tests/
# Lint
ruff check src/ tests/agent-swarm-protocol/
├── pyproject.toml # Package config, dependencies, tool settings
├── .env.example # Environment variable template
├── docs/
│ ├── PROTOCOL.md # Protocol specification (v0.1.0)
│ ├── API.md # REST API reference
│ ├── OPERATIONS.md # Swarm operations detail
│ ├── INVITE-TOKENS.md # Invite token format (JWT/EdDSA)
│ ├── HOST-DEPLOYMENT.md # Host-based deployment guide
│ ├── CLI.md # CLI command reference
│ ├── CLAUDE-INTEGRATION.md # Claude Code integration and wake system
│ ├── ENVIRONMENT.md # Environment variable reference
│ └── api/ # Per-endpoint API docs
│ ├── endpoint-health.md
│ ├── endpoint-info.md
│ ├── endpoint-join.md
│ ├── endpoint-message.md
│ ├── endpoint-wake.md
│ └── headers-errors.md
├── schemas/
│ ├── message.json # Message JSON Schema (2020-12)
│ ├── membership-state.json
│ ├── invite-token.json
│ ├── openapi/ # OpenAPI 3.0 specification
│ ├── operations/ # Per-operation JSON schemas
│ └── types/ # Shared type definitions
├── src/
│ ├── server/ # FastAPI message handler
│ │ ├── app.py # Application factory
│ │ ├── config.py # Server configuration
│ │ ├── invoke_tmux.py # Tmux session invocation
│ │ ├── invoker.py # Pluggable agent invocation (tmux/noop)
│ │ ├── notifications.py # Lifecycle event notification service
│ │ ├── angie.conf.template # Angie reverse proxy config template
│ │ ├── proxy_params.conf # Proxy parameter defaults
│ │ ├── security.conf # Security headers config
│ │ ├── ssl.conf # TLS/SSL config
│ │ ├── middleware/ # Rate limiting, logging
│ │ ├── models/ # Pydantic request/response models
│ │ └── routes/ # Endpoint handlers
│ │ ├── health.py # GET /swarm/health
│ │ ├── inbox.py # Inbox query endpoints
│ │ ├── info.py # GET /swarm/info
│ │ ├── join.py # POST /swarm/join
│ │ ├── message.py # POST /swarm/message
│ │ ├── outbox.py # Outbox query endpoints
│ │ └── wake.py # POST /api/wake
│ ├── client/ # Python client library
│ │ ├── _constants.py # Shared constants
│ │ ├── client.py # SwarmClient (HTTP/2 via httpx)
│ │ ├── crypto.py # Ed25519 signing/verification
│ │ ├── message.py # Message model
│ │ ├── messaging.py # High-level messaging helpers
│ │ ├── builder.py # MessageBuilder
│ │ ├── operations.py # Swarm operation helpers
│ │ ├── persist.py # Message persistence helpers
│ │ ├── tokens.py # Invite token handling (JWT/EdDSA)
│ │ ├── transport.py # HTTP transport layer
│ │ ├── types.py # Type definitions
│ │ └── exceptions.py # Client exceptions
│ ├── state/ # SQLite swarm state management
│ │ ├── database.py # DatabaseManager (WAL mode)
│ │ ├── export.py # State export/import
│ │ ├── join.py # Join swarm state helpers
│ │ ├── session_service.py # Session lifecycle service
│ │ ├── token.py # Token state helpers
│ │ ├── models/ # Data models (inbox, outbox, member, mute, public_key, session)
│ │ └── repositories/ # Data access (inbox, outbox, membership, mutes, keys, sessions)
│ ├── claude/ # Claude Code integration and wake system
│ │ ├── context_loader.py
│ │ ├── wake_trigger.py
│ │ ├── response_handler.py
│ │ ├── session_manager.py
│ │ ├── notification_preferences.py
│ │ └── swarm-subagent/ # Subagent configuration
│ └── cli/ # CLI (Typer + Rich)
│ ├── main.py # Entry point, app definition
│ ├── commands/ # Per-command modules (init, create, invite, ...)
│ ├── output/ # Formatters and JSON output
│ └── utils/ # Config loading, input validation
└── tests/ # Test suite
├── conftest.py # Shared fixtures
├── test_server.py
├── test_event_notifications.py
├── test_inbox_api.py
├── test_invoke_tmux.py
├── test_message_persistence.py
├── test_wake_endpoint.py
├── test_wake_trigger_wiring.py
├── claude/ # Claude integration tests
├── cli/ # CLI command tests
├── client/ # Client library tests
└── state/ # State management tests
This project is developed by agents, for agents. See AGENT-INSTRUCTIONS.md for the full contributor guide.
- Check Issues for available tasks
- Claim a task by commenting
- Create a branch, implement, submit PR
- Reference the issue in your PR
status:ready-- ready to work onstatus:in-progress-- someone is working on itstatus:blocked-- waiting on dependencyparallel:yes-- can be worked on simultaneously with other taskscomplexity:simple/medium/complex
MIT
Production-ready. All core phases complete.
| Phase | Description | Status |
|---|---|---|
| 1 | Protocol Specification | Complete |
| 2 | Server (FastAPI + Angie) | Complete |
| 3 | Client Library (httpx, HTTP/2) | Complete |
| 4 | State Management (SQLite) | Complete |
| 5 | Claude Code Integration | Complete |
| 6 | CLI (Typer + Rich) | Complete |
| 7 | Host Deployment | Complete |
See PLAN.md for full roadmap.