AgentMesh

AgentMesh is a Kubernetes-inspired orchestration layer for AI agents: each agent runs as an isolated AgentPod, a Claude-powered LLM acts as the control plane making live scheduling decisions, and agents collaborate peer-to-peer via MCP and A2A delegation — with full state preservation across failures.

---

Architecture

┌──────────────────────────────────────────────────────────┐
│ React Dashboard (ws://) │
│ MeshView · EventLog · TaskQueue │
└────────────────────────┬─────────────────────────────────┘
│ WebSocket
┌────────────────────────▼─────────────────────────────────┐
│ FastAPI Server │
│ GET /mesh POST /tasks POST /agents/spawn WS /ws │
└──────┬──────────────┬────────────────────┬───────────────┘
│ │ │
┌────▼────┐ ┌─────▼──────┐ ┌────────▼────────┐
│ Sched- │ │ LLM │ │ A2A Comm- │
│ uler │ │ Control │ │ unicator │
│ spawn │ │ Plane │ │ discover │
│ evict │ │ (Claude) │ │ delegate │
│ reroute │ │ tick: 5s │ │ broadcast │
└────┬────┘ └────────────┘ └────────┬────────┘
│ │
┌────▼──────────────────────────────────▼────────┐
│ Agent Registry │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │AgentPod │ │AgentPod │ │AgentPod │ … │ │
│ │search │ │summarise │ │classify │ │
│ │health=1.0│ │health=0.8│ │health=0.4│ │
│ └──────────┘ └──────────┘ └──┬───────┘ │
└────────────────────────────────-│──────────────┘
│ (degraded → evict)
┌─────────────────────────────────▼──────────────┐
│ MemoryManager │
│ snapshot(agent) → Redis / in-memory dict │
│ restore(new_agent, evicted_id) │
└────────────────────────────────────────────────┘

Flow: Health loop (1s) → control plane tick (5s) → Claude reads all scores → JSON decisions → scheduler executes → events broadcast via WebSocket → dashboard updates live.

---

Quick Start

1. Clone & install

git clone https://github.com/Mu-iq/agentmesh
cd agentmesh/agentmesh
pip install -e ".[dev]"

2. Configure environment

cp .env.example .env
# Edit .env and set ANTHROPIC_API_KEY

3. (Optional) Start Redis

docker run -d -p 6379:6379 redis:7-alpine
# or: docker compose up redis -d

4. Start the API server

uvicorn api.server:app --reload
# Server starts at http://localhost:8000

5. Open the dashboard

cd dashboard
npm install
npm run dev
# Dashboard at http://localhost:5173

6. Or run everything with Docker Compose

# From agentmesh/ directory
docker compose up

---

API Reference

Agents

Method	Path	Description
GET	/mesh	Full mesh snapshot — all agent health, task queue, control plane state
GET	/agents/{id}	Single agent health
POST	/agents/spawn	Spawn a new agent
DELETE	/agents/{id}	Evict an agent (state is preserved in memory)
GET	/capabilities	Capability → agent ID map

Spawn an agent:

curl -X POST http://localhost:8000/agents/spawn \
-H "Content-Type: application/json" \
-d '{"capabilities": ["search", "summarise"], "instructions": "Be concise."}'

Tasks

Method	Path	Description
POST	/execute	Run a task synchronously — returns the agent's result immediately
POST	/tasks	Submit a task to the async queue (fire-and-forget)
GET	/tasks	List all queued/completed tasks
GET	/tasks/{id}	Get a specific task including its result

Execute a task and get the result back:

curl -X POST http://localhost:8000/execute \
-H "Content-Type: application/json" \
-d '{"capability": "summarise", "input": "Summarise the Apollo program."}'

Or queue a task asynchronously:

curl -X POST http://localhost:8000/tasks \
-H "Content-Type: application/json" \
-d '{"capability": "summarise", "input": "Summarise the Apollo program."}'

Memory

Method	Path	Description
GET	/snapshots	List all stored agent snapshots
GET	/snapshots/{id}	Get a specific snapshot

WebSocket

Connect to ws://localhost:8000/ws to receive a real-time stream of all mesh events:

Event type	Trigger
mesh_snapshot	On connect — full current state
agent_spawned	New agent added
agent_evicted	Agent removed
health_update	Per-agent health tick (every 1s)
task_submitted	New task queued
task_dispatched	Task assigned to an agent
task_completed	Task finished — agent returned a result
task_failed	Task execution threw an error
task_rerouted	Task moved to a different agent
task_delegated	Agent-to-agent delegation
control_plane_decision	Claude's scheduling decision

---

Running Examples

Research pipeline (3 agents + degradation demo)

cd agentmesh
python -m examples.research_mesh

Pipeline: researcher → A2A → summariser → A2A → fact_checker → simulate degradation → control plane evicts & replaces.

Hierarchical summarisation

python -m examples.summary_mesh

Pipeline: ingestion → parallel A2A delegation to two summarisers → merger agent produces final output.

---

Running Tests

cd agentmesh
pytest tests/ -v

Tests are pure unit tests with no LLM calls or Redis required.

---

Tech Stack

Layer	Technology
Language	Python 3.11+
Agent Framework	LangGraph / custom AgentPod
MCP	mcp Python SDK (official)
LLM — Control Plane	Anthropic Claude (claude-sonnet-4-6)
LLM — Agents	Claude (claude-sonnet-4-6, swappable)
State Storage	Redis (fallback: in-memory dict)
Health Loop	asyncio background task, 1s interval
API	FastAPI + WebSockets
Frontend	React 18, TypeScript, Tailwind CSS
Real-time	WebSocket (FastAPI → React)
CLI	Typer
Testing	pytest + pytest-asyncio
Containerisation	Docker + Docker Compose

---

Project Structure

agentmesh/
├── core/
│ ├── agent_pod.py # AgentPod base class — health, state, snapshot/restore
│ ├── llm_agent_pod.py # Claude-backed AgentPod implementation
│ ├── control_plane.py # LLM control plane (Claude) — observe & decide
│ ├── scheduler.py # Spawn / evict / reroute + 1s health loop
│ └── memory_manager.py # State snapshot and restore (Redis / in-memory)
├── comms/
│ ├── mcp_layer.py # MCP server wrapper per agent + in-process registry
│ └── a2a.py # Agent-to-agent discovery, delegation, broadcast
├── api/
│ └── server.py # FastAPI server + WebSocket event fan-out
├── dashboard/ # React frontend (Vite + TypeScript + Tailwind)
│ └── src/
│ ├── App.tsx
│ ├── components/
│ │ ├── MeshView.tsx # Live agent grid with spawn/evict actions
│ │ ├── AgentCard.tsx # Agent card — health gauge, hover actions
│ │ ├── EventLog.tsx # Terminal-style event feed, filterable
│ │ ├── Lab.tsx # Interactive playground — run tasks, see results
│ │ └── SpawnModal.tsx # Spawn agent dialog with capability picker
│ └── hooks/
│ └── useMeshSocket.ts # WebSocket hook — auto-reconnect, state sync
├── examples/
│ ├── research_mesh.py # 3-agent research + degradation demo
│ └── summary_mesh.py # Hierarchical summarisation demo
├── tests/
│ ├── test_agent_pod.py
│ ├── test_scheduler.py
│ └── test_a2a.py
├── pyproject.toml
├── docker-compose.yml
└── .env.example

---

Author

Muhammad Muzammil Tariq
github.com/Mu-iq · muzamiltariq.com