mycelium-agents 0.3.1

The networking protocol for AI agents. Discover, communicate, and collaborate.

🍄 Mycelium Agents

The Semantic Networking Protocol for AI Swarms

▶ See Live Demo • Technical Report

Stop hardcoding tool selection. Scale your AI product from 5 to 5,000 tools without rewriting your orchestration logic.

📖 The "Tool Routing" Bottleneck

As AI products grow, they transition from single-prompt wrappers to complex multi-tool systems. Developers today rely on hardcoded if/else logic, expensive LLM-based routing, or keyword matching that breaks when a user's intent doesn't exactly match a function name.

Mycelium provides a drop-in semantic discovery layer. It allows your AI system to dynamically find and route requests to the right internal tool or agent based on meaning, not just exact keywords.

📊 Performance Moat (v0.3.0 Benchmark)

We refuse to trade accuracy for speed. In our latest fair-benchmark against traditional Information Retrieval (IR) methods on a corpus of 100,000 agents:

• 70.7% Family-Level Top-1 Accuracy (A +30 percentage point advantage over the strongest lexical baseline, BM25).
• <11ms Cold Discovery Latency (Running 20x faster than BM25 on commodity hardware).
• Zero-Cost Local Infrastructure (Embedding runs locally via all-MiniLM-L6-v2; no OpenAI API bills for routing).

See the full reproduction steps and methodology in our Benchmarks Ledger.

📢 Latest Updates

• May 2024: ✅ v0.2.0 Live! Added Semantic Discovery & 100k agent benchmark.
• May 2024: 🚀 CrewAI Integration Bridge released. See Example
• Next Up: 🛠️ Authentication Layer & JS SDK (Working on it...)

---

The Problem

AI agents are everywhere. But they're all isolated.

Your Coding Agent ──── cannot talk to ──── Research Agent
Your Email Agent  ──── cannot find   ──── Translation Agent
Your Data Agent   ──── cannot hire   ──── Visualization Agent

There are thousands of AI agents being built. None of them can discover, communicate with, or collaborate with each other.

It's like having millions of phones with no telephone network.

---

The Solution

Mycelium is the networking protocol that connects AI agents.

Your Agent ←→ [MYCELIUM NETWORK] ←→ Any Agent, Anywhere

Any agent can:

• 🔍 Discover other agents by natural language
• 📨 Communicate using a standard protocol
• 🤝 Collaborate in multi-agent chains
• ⭐ Build trust through successful interactions

---

🛠️ Quick Start

Mycelium is language-agnostic and supports both Python and JavaScript ecosystems natively.

For Python Developers (Backend & AI Frameworks)

pip install mycelium-agents

For JavaScript/Web Developers (Node.js & Browsers)

npm install mycelium-js

1. Start the Registry (Server)

import uvicorn
from mycelium.server.app import app

uvicorn.run(app, host="0.0.0.0", port=8000)

2. Discover Semantically

No more hardcoded routing. Just describe what you need.

Python Example:

import httpx
# Query: "I need to change some dollars into euros"
response = httpx.get("http://localhost:8000/api/v1/agents/discover?q=change+dollars+into+euros&semantic=true")

JavaScript Example (mycelium-js):

import { MyceliumClient } from 'mycelium-js';

const client = new MyceliumClient();
// Finds the ForexAgent with 0 keyword overlap in <15ms
const bestTool = await client.discoverTool("I need to change some dollars into euros");

---

🧠 v0.2.0 — Semantic Search

Agents are now found by MEANING, not just keywords.

# Before (v0.1 — keyword only)
network.discover("weather")
# Only finds agents with "weather" in name

# Now (v0.2 — semantic)
network.discover("I need temperature data for my city")
# Automatically finds WeatherAgent ✅

network.discover("Speak Hindi please")
# Automatically finds TranslatorAgent ✅

network.discover("What is the value of digital currency?")
# Automatically finds CryptoAgent ✅

Powered by ChromaDB + sentence-transformers. Runs locally. No API key needed.

---

📊 Enterprise-Grade Benchmarks (v0.2.0)

Mycelium is stress-tested for production-scale AI swarms.

1. Discovery Accuracy at Scale (100,000 Agents) Semantic search completely outperforms traditional methods at massive scale.

Method	Top-1 Accuracy	Avg Latency
Naive Keyword	75.6%	136 ms
BM25 Lexical	83.4%	71 ms
Semantic (Mycelium)	87.4%	14 ms

2. Network Load & Cache (100 Concurrent Users) The built-in Query Cache Layer provides a 20x speedup under heavy load.

• 10 Users: 970 Requests/sec | 0% error
• 50 Users: 879 Requests/sec | 0% error
• 100 Users: 753 Requests/sec | 0.1% error (p95 = 122ms)

3. Multi-Agent Workflow Chaining Reliability Routing sequential payloads (Agent A → Agent B → Agent C) is flawlessly reliable.

Chain Depth	Success Rate	Per-Hop Latency
2 Agents	100.0%	124.27 ms
3 Agents	100.0%	90.04 ms
5 Agents	100.0%	83.41 ms
(Note: Per-hop latency decreases as chain depth grows due to dynamic path caching)

→ Read the full arXiv Technical Report Draft
→ Reproduce benchmarks

🎬 Watch the Demo

https://github.com/user-attachments/assets/2a228337-80f5-479d-8b03-02597ccdc5ef

---

🎨 Spatial Dashboard

A visual control center for your Mycelium network. Built with vanilla JS and glassmorphism design.

🌐 Live Demo → mycelium-agents.netlify.app

Watch AI agents orbit the registry core in real-time. Click any agent to inspect capabilities and send requests.

Features:

• 🌌 Floating agent pills orbiting the registry core
• ⛓️ Canvas filament lines showing live connections
• 📊 Real-time network stats (Agents, Latency, Messages)
• 🔍 Natural language agent search (Ctrl+K)
• 📡 Send requests directly from the dashboard
• 🖱️ Right-click context menu on any agent
• 🎯 macOS-style dock controls
• 📋 Real-time network logs panel
• ⛓️ Multi-agent chain builder
• 🌗 Dark / Light theme toggle

Run Locally

# Step 1: Start the registry
python -m server.app

# Step 2: Start some agents
python examples/real_agents/real_weather_agent.py
python examples/real_agents/real_crypto_agent.py

# Step 3: Open the dashboard
cd antigrav_dashboard
npm install
npm run dev

Open: http://localhost:5173

---

🏗️ Architecture

┌────────────────────────────────────────────────────┐
│                  MYCELIUM NETWORK                  │
│                                                    │
│  ┌──────────┐    ┌──────────────┐    ┌──────────┐  │
│  │ Agent A  │───▶│   REGISTRY   │◀───│ Agent B │  │
│  │ (Travel) │    │              │    │ (Payment)│  │
│  └────┬─────┘    │ • Discovery  │    └────┬─────┘  │
│       │          │ • Semantic   │         │        │
│       │          │ • Trust      │         │        │
│       │          │ • Relay      │         │        │
│       │          └──────────────┘         │        │
│       │                                   │        │
│       └────── DIRECT COMMUNICATION ───────┘        │
│                                                    │
└────────────────────────────────────────────────────┘

---

🛡️ Security & Reliability (OWASP ASI06 Compliance)

As AI agents move towards autonomy, security risks like OWASP ASI06 (AI Agent Over-Permissioning) become critical. Mycelium is engineered to mitigate these risks at the protocol level.

🔒 Mitigating AI Agent Over-Permissioning

Mycelium enforces a Least Privilege Routing (LPR) model:

• Granular Capability Mapping: Agents only register specific atomic capabilities (e.g., get_weather), preventing broad system access.
• Discovery Sandboxing: The registry only reveals agents that exactly match the semantic intent, preventing unauthorized "agent-to-agent" scanning.
• Encapsulated Payloads: All communication is strictly validated via Pydantic schemas, ensuring no malicious execution code is injected into the routing layer.

🛠️ Hardened Infrastructure

• Dependency Guard: Continuous scanning via CodeQL to prevent supply chain vulnerabilities.
• Payload Integrity: (Alpha) Support for signed message envelopes to ensure data hasn't been tampered with during relay.
• Rate Limiting: Built-in protection against "Agent Storms" where recursive agent calls could lead to Denial of Service (DoS).

---

🌍 Real-World Agents (Included)

5 production-ready agents using live APIs:

Agent	Capability	API Used
🌤️ RealWeather	Live weather for any city	OpenWeatherMap
💰 CryptoTracker	Live Bitcoin & crypto prices	CoinGecko (free)
🌍 RealTranslator	Translate to 50+ languages	MyMemory (free)
📖 WikiBrain	Wikipedia knowledge & search	Wikipedia (free)
💱 CurrencyMaster	Live exchange rates (150+)	ExchangeRate API

Multi-Agent Chain Demo

python scripts/real_world_demo.py

⛓️  CHAIN: Crypto Price Translation
→ CryptoTracker:   Bitcoin = $67,432
→ CurrencyMaster:  $67,432 = ₹56,30,613
→ RealTranslator:  67432.5 अमेरिकी डॉलर = 5630613.75 भारतीय रुपया

✅ 3 agents. 3 live APIs. 1 automated chain. (1122ms)

---

🧪 System Diagnostics

python scripts/system_check.py

✅ Registry Server Health      PASS
✅ Agent Registration          PASS
✅ Natural Language Discovery  PASS
✅ Agent-to-Agent Comms        PASS
✅ Multi-Agent Chains          PASS
✅ Error Handling              PASS
✅ SDK Imports                 PASS

📈 Pass Rate: 32/32 (100%)
🟢 ALL SYSTEMS OPERATIONAL

---

📚 Documentation

Document	Description
Getting Started	First steps with Mycelium
Protocol Spec	Full protocol specification
Architecture	System design & decisions
Technical Report (arXiv)	Official whitepaper draft with full benchmark data
Knowledge Base	Complete postmortem
API Reference	REST API docs
FAQ	Frequently asked questions

---

🎯 Examples

Example	Description
01 — First Agent	Create your first agent
02 — Discover Agents	Find and use agents
Weather Agent	Live weather data
Translator Agent	50+ languages
Crypto Agent	Live crypto prices
Wikipedia Agent	Knowledge base
Currency Agent	Exchange rates

---

🗺️ Roadmap

v0.1.1 ✅ Done

• Core protocol
• Python SDK (pip install mycelium-agents)
• Registry server (FastAPI)
• Agent discovery (keyword-based)
• Agent-to-agent communication
• 5 real-world agents with live APIs
• Multi-agent chain demo
• Spatial dashboard (live on Netlify)
• 32/32 diagnostic tests passing

v0.2.0 ✅ Done

• Semantic search (ChromaDB + sentence-transformers)
• Agents found by MEANING not keywords
• 8/8 semantic tests passing
• Enterprise Benchmarks (100k agents scale testing)
• Workflow Chain Benchmarks (100% routing reliability)
• arXiv Technical Report draft completed

v0.3.0 📋 Next

• Authentication (HMAC + API keys)
• CLI tool (mycelium discover "translator")
• JavaScript/TypeScript SDK
• WebSocket support
• Agent Marketplace (web UI)
• LangChain + CrewAI plugins
• Docker deployment

v1.0.0 🏆 2027

• Stable protocol specification
• Multi-language SDKs
• Hosted registry (SaaS)
• Enterprise features
• Protocol governance council

---

🤝 Contributing

We love contributions! Mycelium is community-driven.

git clone https://github.com/udaysaai/mycelium.git
cd mycelium
pip install -e ".[dev,server]"
pytest
python -m server.app

See CONTRIBUTING.md for guidelines.

Good first issues:

• Add a new example agent
• Improve documentation
• Write more tests
• Add language translations

---

📜 License

MIT — use it, build on it, make it yours.

---

Built with ❤️ from India 🇮🇳

If AI agents are the future, they need a way to find each other.

⭐ Star this repo if you believe in open agent infrastructure.

🎨 Live Dashboard • 📦 PyPI • 📖 Docs