README.md

metadata

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.

🎬 Demo & Submission

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

---

🏆 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

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

{
  "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:

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:

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

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

• Stage 1: Multi-Agent core implementation
• Stage 2: Developer Console (FastAPI + UI)
• Stage 3: Gerçek Web Search integration
• 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.

---

🛡️ AgentMask - Trust Through Transparency
"Every decision, every step, cryptographically verifiable."