SwarmMind-AI: Decentralized AI Agent Swarm

A peer-to-peer network of AI agents that demonstrate libp2p's universal connectivity through seamless discovery, NAT traversal, and collaborative intelligence. Agents autonomously discover each other, advertise capabilities, and collaborate on complex tasks that require distributed problem-solving.

Features

Decentralized Discovery: Agents discover each other via Kademlia DHT
Secure Communication: Noise encryption and Yamux multiplexing
Pub/Sub Messaging: Gossipsub for topic-based communication
AI Task Execution: Execute tasks using Anthropic Claude API
Multi-Agent Collaboration: Decompose complex tasks and distribute across agents
Universal Connectivity: NAT traversal and peer-to-peer networking

Prerequisites

Python 3.10 or higher
libp2p 0.4.0+ (installed from local repository)
Anthropic API key (for AI task execution)

Installation

Clone and setup the repository:

git clone https://github.com/bomanaps/SwarmMind-AI.git
cd SwarmMind-AI

Create a virtual environment:

python3 -m venv venv
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Install libp2p from local repository:

# Make sure you have py-libp2p cloned at ../py-libp2p or update the path
pip install -e /path/to/py-libp2p

Set up Anthropic API key:

export ANTHROPIC_API_KEY="sk-ant-api03-..."

Quick Start

Using the Demo Helper Script (Recommended for First-Time Users)

The easiest way to get started is using the interactive demo helper script:

./run_demo.sh

This script will:

Check your environment setup (virtual environment, API key)
Provide you with pre-configured demo scenarios
Show you the exact commands to run in each terminal window

Available demo scenarios:

Quick Test - Basic connectivity (2 agents)
Discovery Test - DHT discovery (3 agents)
AI Task Execution - Single task execution (2 agents with API key)
Full Demo - Multi-agent collaboration (4+ agents with API key)
Manual - Run commands manually (for advanced users)

Note: Make sure you have exported your ANTHROPIC_API_KEY before running AI task demos (scenarios 3 and 4). The script will check for this and warn you if it's missing.

Manual Quick Start

Running Your First Agent

Terminal 1 - Start an executor agent:

python swarm_demo.py \
  --agent-id executor1 \
  --port 8000 \
  --capabilities problem_solving code_generation

This will start an agent that can execute AI tasks. Note the peer ID from the output - you'll need it for other agents to connect.

Connecting Multiple Agents

Terminal 2 - Start another executor agent:

python swarm_demo.py \
  --agent-id executor2 \
  --port 8001 \
  --capabilities data_analysis research \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/<PEER_ID_FROM_TERMINAL1>

Replace <PEER_ID_FROM_TERMINAL1> with the actual peer ID shown in Terminal 1.

Terminal 3 - Search for agents:

python swarm_demo.py \
  --agent-id searcher \
  --port 8002 \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/<PEER_ID_FROM_TERMINAL1> \
  --search-capability problem_solving

This agent will search for and discover agents with the problem_solving capability.

Usage Examples

Basic Executor Agent

Start an agent that can execute AI tasks:

ANTHROPIC_API_KEY="sk-ant-api03-..." python swarm_demo.py \
  --agent-id executor \
  --port 8000 \
  --capabilities problem_solving code_generation data_analysis

Output will show:

Peer ID (needed for other agents to connect)
Listening addresses
DHT routing table size
Agent is ready to receive tasks

Search for Agents

Find agents with specific capabilities:

python swarm_demo.py \
  --agent-id searcher \
  --port 8001 \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/<PEER_ID> \
  --search-capability problem_solving

This will:

Connect to the bootstrap node
Search the DHT for agents with problem_solving capability
Display found agents
Broadcast a test task request via Gossipsub

Send a Task to an Agent

Send a task request to an executor agent:

python swarm_demo.py \
  --agent-id requester \
  --port 8002 \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/<PEER_ID> \
  --send-task problem_solving "Solve: What is 2+2?"

This will:

Connect to the bootstrap node
Find an agent with problem_solving capability
Send the task request
Wait for the result

Distribute Complex Tasks (Multi-Agent Collaboration)

Distribute a complex task across multiple agents:

python swarm_demo.py \
  --agent-id coordinator \
  --port 8003 \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/<PEER_ID> \
  --distribute-task problem_solving "Solve: What is 2+2? and What is 5*3?" \
  --decomposition-strategy parallel

This will:

Decompose the task into sub-tasks
Find multiple agents with required capabilities
Distribute sub-tasks to different agents
Aggregate results from all agents

Basic Peer Connection (Testing Connectivity)

Test basic peer-to-peer connectivity:

# Terminal 1
python swarm_demo.py --agent-id agent1 --port 8000

# Terminal 2 (after noting peer ID from Terminal 1)
python swarm_demo.py \
  --agent-id agent2 \
  --port 8001 \
  --connect /ip4/127.0.0.1/tcp/8000/p2p/<PEER_ID_FROM_TERMINAL1>

Command-Line Options

Required Arguments

--agent-id: Unique identifier for the agent

Optional Arguments

--port PORT: Port to listen on (default: auto-find free port)
--dht-mode {client,server}: DHT mode (default: server)
--capabilities CAP1 CAP2 ...: Agent capabilities
--bootstrap ADDR [ADDR ...]: Bootstrap node multiaddresses
--api-key KEY: Anthropic API key (or use ANTHROPIC_API_KEY env var)
--max-concurrent-tasks N: Max concurrent tasks (default: 3)
--connect ADDR: Connect to a specific peer (basic connectivity test)
--search-capability CAP: Search for agents with capability
--send-task TYPE "DESCRIPTION": Send a single task
--distribute-task TYPE "DESCRIPTION": Distribute a complex task
--decomposition-strategy {parallel,sequential,hierarchical,auto}: Task decomposition strategy
-v, --verbose: Enable verbose logging

Agent Capabilities

Available capability types:

problem_solving: General problem-solving and reasoning
code_generation: Generate code solutions
code_review: Review and improve code
data_analysis: Analyze data and generate insights
research: Research and information gathering
translation: Language translation
summarization: Text summarization

Architecture

┌─────────────────────────────────────────────────────────┐
│                    SwarmMind-AI Agent                    │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   Identity   │  │  Transport   │  │   Protocol   │  │
│  │  (Ed25519)   │  │ (TCP/QUIC)   │  │   Handler    │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│                                                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │         libp2p Host (py-libp2p)                  │   │
│  │  • Noise Encryption  • Yamux Multiplexing        │   │
│  │  • Universal Connectivity (NAT Traversal)        │   │
│  └──────────────────────────────────────────────────┘   │
│                                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   Kademlia   │  │  Gossipsub   │  │   Custom     │  │
│  │     DHT      │  │   Pub/Sub    │  │  Protocols   │  │
│  │ (Discovery)  │  │ (Broadcast)  │  │ (Task Exec)  │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│                                                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │            AI Agent Core                         │   │
│  │  • Capability Registry  • Task Queue             │   │
│  │  • AI Integration  • Result Aggregation          │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Multi-Agent Demo Scenario

Here's a complete demo scenario with multiple agents:

Step 1: Start Bootstrap Agent (Executor 1)

ANTHROPIC_API_KEY="sk-ant-api03-..." python swarm_demo.py \
  --agent-id executor1 \
  --port 8000 \
  --capabilities problem_solving

Note the Peer ID from output, e.g., 12D3KooW...

Step 2: Start Executor Agent 2

ANTHROPIC_API_KEY="sk-ant-api03-..." python swarm_demo.py \
  --agent-id executor2 \
  --port 8001 \
  --capabilities code_generation data_analysis \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/12D3KooW...

Step 3: Start Executor Agent 3

ANTHROPIC_API_KEY="sk-ant-api03-..." python swarm_demo.py \
  --agent-id executor3 \
  --port 8002 \
  --capabilities problem_solving research \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/12D3KooW...

Step 4: Search for Agents

python swarm_demo.py \
  --agent-id searcher \
  --port 8003 \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/12D3KooW... \
  --search-capability problem_solving

You should see executor1 and executor3 discovered.

Step 5: Send a Task

python swarm_demo.py \
  --agent-id requester \
  --port 8004 \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/12D3KooW... \
  --send-task problem_solving "Solve: What is 2+2?"

The task will be executed by one of the agents with problem_solving capability.

Step 6: Distribute Complex Task

python swarm_demo.py \
  --agent-id coordinator \
  --port 8005 \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/12D3KooW... \
  --distribute-task problem_solving "Solve: What is 2+2? and What is 5*3? and What is 10/2?" \
  --decomposition-strategy parallel

This will decompose the task and distribute it across multiple agents.

Troubleshooting

Agent won't start

Check if port is already in use
Verify libp2p is installed correctly
Check Python version (3.10+ required)

Can't find other agents

Ensure bootstrap node is running and accessible
Check network connectivity
Wait a few seconds for DHT to propagate
Try using --search-capability to trigger discovery

Task execution fails

Verify ANTHROPIC_API_KEY is set correctly
Check API key has sufficient credits - Important: Anthropic API requires credits to be purchased/added to your account. If you see "Your credit balance is too low to access the Anthropic API", you need to add credits to your Anthropic account at https://console.anthropic.com/
Ensure executor agent has required capability
Check executor agent logs for errors

Note about API Credits: The SwarmMind-AI system architecture is fully functional end-to-end. Tasks are properly accepted, queued, and distributed. However, to execute actual AI tasks, your Anthropic API key must have credits available. If credits are exhausted, you'll see HTTP 400 errors in the executor logs. This is a billing/account issue with Anthropic, not a code issue - the distributed architecture and agent communication work correctly regardless of API availability.

Connection issues

Verify peer ID is correct in multiaddress
Check firewall settings
For NAT traversal, ensure UPnP is enabled
Try using --verbose flag for detailed logs

Project Structure

SwarmMind-AI/
├── src/
│   ├── __init__.py
│   ├── agent.py              # Main agent class
│   ├── identity.py           # Agent identity management
│   ├── transport.py          # Transport layer (TCP/QUIC)
│   ├── discovery.py          # DHT discovery
│   ├── capability_registry.py # Capability management
│   ├── broadcast.py          # Gossipsub pub/sub
│   ├── messaging.py          # Message serialization
│   ├── task_protocol.py      # Custom task protocol
│   ├── ai_provider.py        # AI provider abstraction
│   ├── task_queue.py         # Task queue management
│   ├── task_executor.py      # Task execution engine
│   ├── task_decomposition.py # Task decomposition
│   ├── result_aggregator.py  # Result aggregation
│   └── collaboration.py      # Multi-agent collaboration
├── swarm_demo.py             # Unified demo script
├── run_demo.sh               # Interactive demo helper script
├── requirements.txt          # Python dependencies
└── README.md                 # This file

Development

Running Tests

Use the unified demo script with different modes:

# Basic connectivity test
python swarm_demo.py --agent-id test1 --port 8000
python swarm_demo.py --agent-id test2 --port 8001 \
  --connect /ip4/127.0.0.1/tcp/8000/p2p/<PEER_ID>

# Discovery test
python swarm_demo.py --agent-id test1 --port 8000 --capabilities test
python swarm_demo.py --agent-id test2 --port 8001 \
  --bootstrap /ip4/127.0.0.1/tcp/8000/p2p/<PEER_ID> \
  --search-capability test

Logging

Enable verbose logging for debugging:

python swarm_demo.py --agent-id test --port 8000 -v

License

This project is open source. Please check the repository for license information.

Contributing

Contributions are welcome! This project was built for the libp2p Universal Connectivity Hackathon. For contributions:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

Acknowledgments

Built for the libp2p Universal Connectivity Hackathon
Uses py-libp2p for peer-to-peer networking
AI capabilities powered by Anthropic Claude

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
src		src
.gitignore		.gitignore
README.md		README.md
requirements.txt		requirements.txt
run_demo.sh		run_demo.sh
swarm_demo.py		swarm_demo.py

Folders and files

Latest commit

History

Repository files navigation

SwarmMind-AI: Decentralized AI Agent Swarm

Features

Prerequisites

Installation

Quick Start

Using the Demo Helper Script (Recommended for First-Time Users)

Manual Quick Start

Running Your First Agent

Connecting Multiple Agents

Usage Examples

Basic Executor Agent

Search for Agents

Send a Task to an Agent

Distribute Complex Tasks (Multi-Agent Collaboration)

Basic Peer Connection (Testing Connectivity)

Command-Line Options

Required Arguments

Optional Arguments

Agent Capabilities

Architecture

Multi-Agent Demo Scenario

Step 1: Start Bootstrap Agent (Executor 1)

Step 2: Start Executor Agent 2

Step 3: Start Executor Agent 3

Step 4: Search for Agents

Step 5: Send a Task

Step 6: Distribute Complex Task

Troubleshooting

Agent won't start

Can't find other agents

Task execution fails

Connection issues

Project Structure

Development

Running Tests

Logging

License

Contributing

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages