Spaces:

MCP-1st-Birthday
/

AgentMask

Sleeping

App Files Files Community

AgentMask / README.md

ym452

Update README.md

ee9b4cc verified 3 months ago

preview code

raw

history blame contribute delete

15.1 kB

	---
	title: AgentMask - Secure Multi-Agent System
	emoji: 🛡️
	colorFrom: green
	colorTo: red
	sdk: gradio
	sdk_version: 5.0.0
	app_file: app.py
	pinned: false
	tags:
	- mcp-in-action-track-enterprise
	- agent
	- security
	- langgraph
	- merkle-tree
	- multi-agent
	- ecdsa
	---

	# 🛡️ AgentMask - Secure Multi-Agent System

	> "Don't Trust, Verify." — Transparent, Auditable, and Immutable Reasoning Layer for AI Agents.

	[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-green.svg)](https://python.org)
	[![FastAPI](https://img.shields.io/badge/FastAPI-0.104+-009688.svg)](https://fastapi.tiangolo.com)
	[![Tests](https://img.shields.io/badge/Tests-44%20Passed-brightgreen.svg)]()
	[![License](https://img.shields.io/badge/License-MIT-yellow.svg)]()

	## 🎬 Demo & Submission

	Watch the system in action and check out our official submission post:

	[![Watch the Video](https://img.shields.io/badge/YouTube-Watch%20Demo-red?style=for-the-badge&logo=youtube)](https://youtu.be/d5VVxeBY1Ak)
	[![View on X](https://img.shields.io/badge/X%20(Twitter)-View%20Post-black?style=for-the-badge&logo=x)](https://x.com/SDogan_n/status/1995246903232246076?s=20)

	---

	## 🏆 Hackathon Track

	This project was developed for the MCP 1st Birthday Hackathon.

	- Track: `Track 2: MCP in Action`
	- Category Tag: `mcp-in-action-track-enterprise`

	---

	## 💡 Problem: The Black Box Issue

	Autonomous AI agents are performing increasingly complex tasks. However, there is a critical problem:

	> How can you prove why an agent made a decision or if it was manipulated during the process?

	In current systems, logs can be deleted or altered, and the agent's thought process remains a black box.

	---

	## 🚀 Solution: Cryptographic "Chain-of-Checks"

	AgentMask provides not just a "Chain-of-Thought," but a "Chain-of-Checks" (Audit Chain).

	### Key Features

	\| Feature \| Description \|
	\|---------\|-------------\|
	\| 🤖 Multi-Agent Orchestration \| Modular agent architecture with parallel and sequential execution \|
	\| 🔐 Merkle Tree Audit Trail \| Every step is hashed with SHA-256, immutable \|
	\| ✍️ ECDSA Block Signing \| Blocks are cryptographically signed (secp256k1) \|
	\| 🌐 Real Web Search \| DuckDuckGo/Serper integration with fallback support \|
	\| 📊 Developer Console \| Monitoring with real-time graph visualization \|
	\| ⚡ Parallel Execution \| Concurrent agent execution with asyncio.gather \|
	\| 💾 Append-Only Ledger \| WORM (Write-Once-Read-Many) JSON storage \|

	---

	## 🏗️ Architecture

	```
	┌─────────────────────────────────────────────────────────────────┐
	│ 🖥️ Developer Console (FastAPI) │
	│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
	│ │ POST /run │ │ GET / │ │ GET /health │ │
	│ │ Task Execute │ │ Console UI │ │ Health Check │ │
	│ └──────────────┘ └──────────────┘ └──────────────────────┘ │
	└─────────────────────────────────────────────────────────────────┘
	│
	▼
	┌─────────────────────────────────────────────────────────────────┐
	│ 🧠 Orchestrator (The Brain) │
	│ ┌────────────────────────────────────────────────────────────┐ │
	│ │ Task → ResearchAgent → SummarizerAgent → Final Output │ │
	│ │ (parallel execution support) │ │
	│ └────────────────────────────────────────────────────────────┘ │
	└─────────────────────────────────────────────────────────────────┘
	│
	┌───────────────────┼───────────────────┐
	▼ ▼ ▼
	┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
	│ 📚 ResearchAgent │ │ 📝 SummarizerAgent│ │ 🔧 Future Agents │
	│ - Web Search │ │ - Text Summary │ │ - Critic │
	│ - DuckDuckGo │ │ - Doc Analysis │ │ - Validator │
	│ - Serper API │ │ │ │ - Planner │
	└──────────────────┘ └──────────────────┘ └──────────────────┘
	│
	▼
	┌─────────────────────────────────────────────────────────────────┐
	│ 🔒 Ledger (The Vault) │
	│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
	│ │ LedgerStore│ │ Merkle Tree│ │ ECDSA Sign │ │ JSON │ │
	│ │ Entries │→ │ Root Hash │→ │ Blocks │→ │ Storage │ │
	│ └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
	└─────────────────────────────────────────────────────────────────┘
	```

	---

	## 📁 Proje Tructure

	```
	AgentMask/
	├── pyproject.toml # Proje konfigürasyonu & bağımlılıklar
	├── README.md # this file
	│
	├── src/ # Ana kaynak kod
	│ ├── __init__.py
	│ ├── orchestrator.py # Multi-agent koordinasyonu
	│ │
	│ ├── agents/ # Agent modülleri
	│ │ ├── __init__.py
	│ │ ├── base.py # BaseAgent abstract class
	│ │ ├── research_agent.py # Web search agent
	│ │ ├── summarizer_agent.py # Text summarization agent
	│ │ └── parallel.py # Parallel execution utilities
	│ │
	│ ├── ledger/ # Kriptografik denetim katmanı
	│ │ ├── __init__.py
	│ │ ├── merkle.py # Merkle tree calculation
	│ │ ├── store.py # Append-only ledger storage
	│ │ └── signing.py # ECDSA imzalama
	│ │
	│ ├── tools/ # Harici araçlar
	│ │ ├── __init__.py
	│ │ └── searcher.py # Web search abstraction
	│ │
	│ └── web/ # Web arayüzü
	│ ├── __init__.py
	│ └── app.py # FastAPI application
	│
	└── tests/ # Test dosyaları
	├── __init__.py
	├── test_agents.py # Agent testleri
	├── test_ledger.py # Ledger & signing testleri
	├── test_search_integration.py # Search entegrasyon testleri
	└── test_web_console.py # Web API testleri
	```

	---

	## 🚀 Installation

	### Requirements

	- Python 3.10+
	- pip

	### Steps

	```bash
	# 1. Clone the repo
	git clone [https://github.com/yourusername/AgentMask.git](https://github.com/yourusername/AgentMask.git)
	cd AgentMask

	# 2. Create virtual environment
	python -m venv .venv

	# 3. Activate
	# Windows:
	.\.venv\Scripts\activate
	# Linux/Mac:
	source .venv/bin/activate

	# 4. Install dependencies
	pip install -e ".[dev]"
	```

	---

	## 🧪 Running Tests

	Bash
	# Run all tests
	.\.venv\Scripts\python.exe -m pytest -v

	# Run a specific test file
	.\.venv\Scripts\python.exe -m pytest tests/test_agents.py -v

	# Run with coverage
	.\.venv\Scripts\python.exe -m pytest --cov=src -v
	Test Results: ✅ 44 tests passed

	---

	## 🖥️ Running Developer Console
	Bash

	# Start the web server
	cd src/web
	uvicorn app:app --reload --port 8000

	# Open in browser
	# http://localhost:8000
	🎨 Terminal-Style Hacker UI
	The Developer Console features a terminal-style interface that emphasizes security and transparency:

	┌─────────────────────────────────────────────────────────────────┐
	│ ⌘ AgentMask Terminal █ │
	├─────────────────────────────────────────────────────────────────┤
	│ │
	│ [root@agentmask]$ Enter query... █ [► EXECUTE] │
	│ │
	├────────────────────────────┬────────────────────────────────────┤
	│ > EXECUTION LOG_ │ > AGENT PIPELINE GRAPH_ │
	│ ┌──────────────────────┐ │ ┌──────────────────────────────┐ │
	│ │ 🔐 MERKLE ROOT HASH: │ │ │ [Flow] [Sequence] [Merkle] │ │
	│ │ a7f3b2c1d4e5f6... │ │ │ │ │
	│ └──────────────────────┘ │ │ 📥 → 📚 → 📝 → ✅ │
	│ │ │ │ │
	│ ┌─ STEP 1 ─────────────┐ │ │ Mermaid.js ile interaktif │ │
	│ │ [RESEARCH] │ │ │ graph visualization │ │
	│ │ SHA256: 8a4f2b... │ │ └──────────────────────────────┘ │
	│ │ > View I/O Data_ │ │ │
	│ └──────────────────────┘ │ │
	│ │ │
	│ ┌─ STEP 2 ─────────────┐ │ │
	│ │ [SUMMARIZER] │ │ │
	│ │ SHA256: c3d7e1... │ │ │
	│ └──────────────────────┘ │ │
	└────────────────────────────┴────────────────────────────────────┘
	```

	### Console Features
	Feature Description
	🖥️ Terminal Aesthetic Neon green (#00ff41) + red (#ff0040) hacker theme
	📊 Flow Graph Agent pipeline visualization (Mermaid.js)
	🔄 Sequence Diagram Agent communication sequence
	🌳 Merkle Tree View Interactive hash tree visualization
	📋 Execution Log Detailed I/O log for each step
	🔐 Merkle Root Cryptographic verification hash
	⚡ Real-time Real-time result display
	📱 Responsive Mobile responsive design

	---

	## 🔧 API Endpoints

	\| Endpoint \| Method \| Description \|
	\|----------\|--------\|----------\|
	\| `/` \| GET \| Developer Console UI \|
	\| `/run` \| POST \| Execute task, get results \|
	\| `/health` \| GET \| Health check \|

	### POST /run Example

	```bash
	curl -X POST http://localhost:8000/run \
	-H "Content-Type: application/json" \
	-d '{"query": "AI in healthcare diagnosis"}'
	```

	Response:
	```json
	{
	"success": true,
	"task": {"query": "AI in healthcare diagnosis"},
	"steps": [
	{
	"step": 1,
	"agent": "research",
	"hash": "a1b2c3...",
	"output": {"results": [...]}
	},
	{
	"step": 2,
	"agent": "summarizer",
	"hash": "d4e5f6...",
	"output": {"summary": "..."}
	}
	],
	"merkle_root": "abc123...",
	"total_steps": 2
	}
	```

	---

	## 🔐 Security Features

	### Merkle Tree Audit Trail

	Every agent step is hashed with SHA-256 and added to a Merkle tree:

	```python
	from ledger.merkle import compute_merkle_root, hash_leaf

	# Hash a single leaf
	leaf_hash = hash_leaf("agent action data")

	# Compute Merkle root
	leaves = ["step1", "step2", "step3"]
	root = compute_merkle_root(leaves)
	```

	### ECDSA Block Signing

	Blocks are signed using the secp256k1 curve:

	```python
	from ledger.signing import ECDSASigner

	# Generate key pair
	signer = ECDSASigner()

	# Sign
	signature = signer.sign(block_hash)

	# Verify
	is_valid = signer.verify(block_hash, signature)
	```

	### Append-Only Ledger

	```python
	from ledger.store import LedgerStore

	# Create Ledger
	store = LedgerStore(storage_path="ledger.json")

	# Add Entry
	store.add_entry("search", "research", input_data, output_data)

	# Create and sign block
	block = store.create_block(signer=signer)

	# Verify chain
	is_valid, message = store.verify_chain()
	```

	---

	## 🔮 Roadmap

	- [x] Stage 1: Multi-Agent core implementation
	- [x] Stage 2: Developer Console (FastAPI + UI)
	- [x] Stage 3: Gerçek Web Search integration
	- [x] Stage 4: Ledger, ECDSA Signing, Parallel Agents
	- [ ] Stage 5: LLM integration (OpenAI/Anthropic)
	- [ ] Stage 6: Critic & Validator agents
	- [ ] Stage 7: WebSocket real-time streaming
	- [ ] Stage 8: Distributed ledger (multi-node)

	---

	## 📄 License

	MIT License - See the LICENSE file for details.

	---

	<p align="center">
	<b>🛡️ AgentMask - Trust Through Transparency</b><br>
	<i>"Every decision, every step, cryptographically verifiable."</i>
	</p>