README.md

---
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>