managarten/docs/reports/ai-agent-architecture-comparison.md

AI-Agent-Architektur: Mana vs. Industrie-Frameworks

Stand: 2026-04-16
Zweck: Vergleich der Mana AI-Workbench-Architektur mit Google A2A, MCP, OpenAI Agents SDK, LangGraph, CrewAI und Microsoft Agent Framework. Stärken identifizieren, Verbesserungspotenzial aufzeigen.

---

1. Zusammenfassung der Mana-Architektur

Was wir haben

Mana implementiert ein Dual-Runtime AI-Agent-System:

Komponente	Beschreibung
Foreground Runner (Browser)	runner.ts — Reasoning-Loop mit bis zu 5 Planner-Iterationen, direkte Dexie-Writes, E2E-verschlüsselt
Background Runner (mana-ai, Port 3067)	tick.ts — 60s Cron-Tick, scannt fällige Missions, plant via mana-llm, schreibt über sync_changes zurück
Planner	Shared Prompt-Template (@mana/shared-ai/src/planner/) → OpenAI-kompatible API auf mana-llm
Tool-System	29 Tools (11 Module), AI_TOOL_CATALOG + MCP-Server, policy-gated (auto/propose/deny)
Agents	Named Personas mit eigener systemPrompt, memory, policy, Budget, Concurrency-Limits
Proposals	Mutationen unter propose-Policy erzeugen Proposals → User muss approven
Actor-System	Jeder Write trägt einen immutablen Actor (user/ai/system) mit frozen displayName
Encryption	Mission Key-Grants für serverseitige Entschlüsselung, AES-GCM-256, HKDF-scoped

Execution Flow

Mission (title, objective, inputs, cadence)
    → Input Resolution (Dexie oder DB + optionale Grant-Entschlüsselung)
    → Planner Call (system prompt + tools + inputs → JSON plan)
    → Policy Gate pro Step (auto → execute, propose → Proposal, deny → reject)
    → Iteration Write-back (LWW sync via mana-sync)
    → Optional: Chained Reasoning (tool output → nächster Planner Call)

---

2. Industrie-Frameworks im Überblick

2.1 Google A2A (Agent-to-Agent Protocol)

Was es ist: Offenes Protokoll für Inter-Agent-Kommunikation. Linux Foundation, 150+ Organisationen, v1.0 seit 2026.

Kernkonzepte:

• Agent Cards (/.well-known/a2a/agent-card) — JSON-Selbstbeschreibung: Capabilities, Skills (mit Input/Output JSON-Schemas), Security, Protocol Bindings. Signiert für dezentrales Trust.
• Tasks — Kern-Arbeitseinheit: SUBMITTED → WORKING → COMPLETED/FAILED. Plus INPUT_REQUIRED und AUTH_REQUIRED für HITL-Flows.
• Messages & Parts — Modalitätsagnostisch: text, raw (binary), url (Datei), data (strukturiertes JSON).
• Artifacts — Task-Outputs, getrennt von Konversation. Streambar (append: true, lastChunk: true).

Kommunikationsmuster:

• Blocking (Request/Response)
• Streaming (SSE, gRPC, JSON-RPC)
• Push Notifications (Webhooks für long-running Tasks)

Protocol Bindings: JSON-RPC 2.0, HTTP/REST, gRPC.

2.2 Anthropic MCP (Model Context Protocol)

Was es ist: Offenes Protokoll für die Verbindung von LLM-Anwendungen mit externen Tools/Daten. Linux Foundation, 10.000+ Server, 97M monatliche SDK-Downloads.

Architektur (Host → Client → Server):

• Host = LLM-Anwendung, managed Security
• Client = 1:1 zu Server, JSON-RPC 2.0 Session
• Server = Lightweight Adapter, exponiert drei Primitives:

Primitive	Gesteuert von	Zweck
Resources	Application	Kontextdaten (Dateien, DB-Einträge)
Tools	Model	Ausführbare Funktionen
Prompts	User	Vordefinierte Templates

Entscheidende Design-Regel: Server sehen nie die volle Konversation oder andere Server. Host kontrolliert alle Cross-Server-Interaktionen.

2.3 OpenAI Agents SDK

Kernprimitive:

• Agent — LLM + instructions + tools + handoffs
• Runner — Orchestriert den Execution Loop
• Handoffs — First-class Primitive für Multi-Agent-Delegation (kein separater Orchestrator nötig)
• Guardrails — Input/Output-Validierung parallel zur Ausführung
• Sessions — Persistente Memory (SQLite, Redis, verschlüsselt)
• Tracing — Built-in Observability (LLM calls, tool calls, handoffs, OpenTelemetry)

2.4 LangGraph

Kernarchitektur — StateGraph:

• Nodes = Funktionen (Agents, Tools, Logik)
• Edges = Kontrollfluss (statisch oder conditional)
• State = Zentraler TypedDict, immutable Updates
• Checkpointing = State-Persistenz mit Time-Travel-Debugging

Multi-Agent-Patterns: Subagents, Handoffs, Router, Supervisor, Scatter-Gather, Subgraphs.

2.5 CrewAI

Kernarchitektur:

• Agent = role + goal + backstory + tools + LLM
• Task = Beschreibung + erwartetes Output-Format + Guardrails + HITL
• Crew = Agents + Tasks + Prozesstyp (sequential, hierarchical, consensual)
• Flows = Event-driven Orchestrierung für Produktion
• Memory = 4 Typen: Short-term, Long-term (Embeddings), Entity, Contextual

2.6 Microsoft Agent Framework

Vereinigung von AutoGen + Semantic Kernel:

• Agents = LLM + Tools + MCP-Server + Middleware
• Workflows = Graph-basiert mit Type-safe Routing, Checkpointing, HITL
• Sessions = Enterprise-grade State Management
• Multi-Provider (Anthropic, Azure OpenAI, OpenAI, Ollama)

---

3. Vergleichsmatrix

Dimension	Mana	A2A	MCP	OpenAI SDK	LangGraph	CrewAI
Agent-Definition	Agent(name, role, systemPrompt, memory, policy)	Agent Card (JSON, signiert)	N/A (Protokoll)	Agent(instructions, tools, handoffs)	Node-Funktionen	Agent(role, goal, backstory)
Tool-Registration	AI_TOOL_CATALOG (29 Tools) + MCP-Server	Skills in Agent Card	tools/list + tools/call	@function_tool + MCP	Node context	tools= Parameter
Agent↔Agent	❌ Nicht vorhanden	✅ Kernzweck	❌ Nicht designed dafür	Handoffs	Edges/Routing	Delegation + Hierarchie
Agent↔Tool	Policy-gated Executor	Via MCP	✅ Kernzweck	Function calls + MCP	Node-Aufrufe	Direkte Zuweisung
State/Memory	LWW Sync + encrypted IndexedDB	Task contextId	Stateful Sessions	Sessions (SQLite/Redis)	StateGraph + Checkpoints	4 Memory-Typen
Orchestrierung	Dual-Runtime (Browser + Server Cron)	Task Lifecycle	Host koordiniert	Runner Loop	DAG Engine	Sequential/Hierarchical
Streaming	✅ SSE Token-Streaming	SSE, gRPC, JSON-RPC	JSON-RPC Notifications	Built-in	Native Token-Stream	Log-basiert
Observability	Prometheus Metrics + Debug Logs	Agent Cards Metadata	Server Logging	Built-in Tracing (OTel)	LangSmith	Built-in Logging
HITL	Proposal-System (approve/reject)	INPUT_REQUIRED State	Elicitation	Guardrails	Interrupt/Resume	Task-Guardrails
Encryption	✅ AES-GCM + Key-Grants	❌	❌	❌	❌	❌
Local-First	✅ Dexie + Offline	❌ Server-to-Server	❌	❌	❌	❌
Multi-Device	✅ LWW Sync	❌	❌	❌	❌	❌

---

4. Was Mana gut macht

4.1 Privacy-First Architektur (einzigartig in der Industrie)

Kein einziges der verglichenen Frameworks hat ein vergleichbares Verschlüsselungskonzept:

• AES-GCM-256 at rest für 27 Tabellen
• Mission Key-Grants mit HKDF-Scoping, Audit Trail, TTL
• Zero-Knowledge-Modus optional
• Server sieht nie Klartext ohne expliziten Grant

Bewertung: Das ist ein echter Wettbewerbsvorteil. A2A, MCP, OpenAI SDK — alle gehen davon aus, dass der Server alles sehen darf.

4.2 Dual-Runtime mit Graceful Degradation

• Browser-Runner funktioniert offline und hat Zugriff auf alle verschlüsselten Daten
• Server-Runner läuft scheduled auch wenn kein Browser offen ist
• Bei fehlendem Key-Grant degradiert Server gracefully → Browser übernimmt

Bewertung: Kein anderes Framework hat diese Browser/Server-Dualität. LangGraph und CrewAI sind rein serverseitig. OpenAI SDK hat keinen Offline-Modus.

4.3 Immutable Actor Attribution

Jeder Write trägt einen eingefrorenen Actor mit kind, principalId, displayName, missionId, iterationId, rationale. Das ist besser als jedes der verglichenen Frameworks:

• OpenAI SDK hat Tracing, aber keine Write-Level Attribution
• LangGraph hat State-Checkpoints, aber keine Actor-Zuordnung pro Mutation
• CrewAI hat keine per-Write-Attribution

Bewertung: Exzellent für Audit, Undo, und Vertrauen. Ermöglicht "Wer hat was warum geändert?" auf Feldebene.

4.4 Proposal-System (Human-in-the-Loop)

Das dreistufige Policy-System (auto/propose/deny) mit dem Proposal-Lifecycle ist durchdacht:

• Granular pro Tool konfigurierbar
• User-Feedback bei Rejection fließt zurück in den Planner
• Pro-Agent Policies (Phase 3)

Vergleich: OpenAI hat Guardrails (aber binär: pass/fail). A2A hat INPUT_REQUIRED (aber kein propose/approve-Workflow). LangGraph hat Interrupt/Resume (ähnlich, aber weniger formalisiert).

4.5 Local-First + Multi-Device Sync

Field-Level LWW über mana-sync ist einzigartig unter AI-Agent-Frameworks. Missions, Agents und ihre Ergebnisse synchen automatisch über Geräte.

---

5. Was Mana verbessern könnte

5.1 🔴 Kein Agent-to-Agent-Protokoll

Problem: Agents können nicht miteinander kommunizieren. Jeder Agent ist eine isolierte Insel. Ein "Cashflow Watcher" kann keinen "Todo Manager" bitten, eine Aufgabe zu erstellen.

Was die Industrie macht:

• A2A: Agents discovern sich über Agent Cards und delegieren Tasks
• OpenAI SDK: Handoffs als First-class Primitive
• LangGraph: Edges zwischen Agent-Nodes
• CrewAI: Hierarchical delegation + shared context

Empfehlung: Ein leichtgewichtiges internes Agent-to-Agent-Protokoll einführen:

interface AgentDelegation {
  fromAgentId: string;
  toAgentId: string;
  intent: ToolCallIntent;   // Was soll der andere Agent tun?
  context: string;           // Warum?
  policy: 'auto' | 'propose'; // User muss bestätigen?
}

Langfristig: A2A-kompatible Agent Cards für externe Integration (z.B. Mana-Agents mit Google Agents kommunizieren lassen).

5.2 🔴 Kein Streaming

Problem: Der aktuelle Flow ist Request/Response. User sieht nichts, bis die gesamte Iteration fertig ist.

Was die Industrie macht:

• A2A: SSE + gRPC Streaming mit TaskStatusUpdateEvent und TaskArtifactUpdateEvent
• OpenAI SDK: Built-in Token-Streaming
• LangGraph: Native Token-by-Token Streaming
• MCP: JSON-RPC Notifications

Empfehlung: SSE-basiertes Streaming für den Foreground Runner:

1. Planner-Response streamen (Token für Token)
2. Step-Ausführung live anzeigen ("Erstelle Task... ✓", "Tagge Note... ⏳")
3. Server-Runner: SSE-Events an verbundene Clients pushen

5.3 🟡 Statisches Tool-System

Problem: 13 hardcoded Tools in einer Allow-List. Neue Tools erfordern Code-Änderungen an mindestens 3 Stellen (server tools.ts, shared-ai proposable-tools, executor).

Was die Industrie macht:

• MCP: Dynamische Tool-Discovery via tools/list, Hot-Reload via notifications/tools/list_changed
• OpenAI SDK: @function_tool Decorator, automatische Schema-Generierung
• LangGraph: Tools als Node-Funktionen, dynamisch registrierbar
• A2A: Skills in Agent Cards mit JSON-Schema

Empfehlung: MCP-kompatibles Tool-Registry einführen:

// Jedes Modul registriert seine Tools deklarativ
// apps/mana/apps/web/src/lib/modules/todo/ai-tools.ts
export const todoTools: AiToolDefinition[] = [
  {
    name: 'create_task',
    description: 'Create a new task',
    inputSchema: { /* JSON Schema */ },
    module: 'todo',
    annotations: { destructiveHint: false, idempotentHint: false }
  }
];

Module registrieren Tools via Registry → Planner bekommt dynamische Tool-Liste → Server synchronisiert über shared-ai Package. Bonus: MCP-Server-Export ermöglicht externe Tool-Nutzung.

5.4 🟡 Kein Graph-basierter Workflow

Problem: Der Reasoning Loop ist linear (Planner → Steps → optional Loop). Komplexe Workflows (Branching, Parallelisierung, Conditional Logic) sind nicht möglich.

Was die Industrie macht:

• LangGraph: DAG mit Conditional Edges, Parallel Nodes, Subgraphs
• CrewAI: Sequential + Hierarchical + Consensual Prozesse
• Microsoft Agent Framework: Type-safe Graph Workflows

Empfehlung: Für die meisten Mana-Usecases ist der lineare Loop ausreichend. Aber für komplexere Missions (z.B. "Analysiere meine Finanzen, erstelle einen Bericht, und plane Aufgaben basierend auf dem Ergebnis") wäre ein einfacher DAG sinnvoll:

interface MissionGraph {
  nodes: MissionStep[];     // Jeder Node = ein Planner-Call oder Tool-Execution
  edges: MissionEdge[];     // Conditional routing
  parallelGroups?: string[][]; // Steps die parallel laufen können
}

Priorität: Niedrig. Der aktuelle Loop deckt 90% der Usecases ab.

5.5 🟡 Keine Agent-Discovery

Problem: Agents sind nur ihrem Ersteller bekannt. Kein Mechanismus für:

• "Welche Agents gibt es?"
• "Welcher Agent kann X?"
• Automatische Delegation basierend auf Capabilities

Was die Industrie macht:

• A2A: Agent Cards mit Skills + JSON-Schemas → automatische Discovery
• MCP: Resource Discovery via URI-Schemes

Empfehlung: Agent Capabilities als strukturierte Metadaten:

interface AgentCapability {
  module: string;          // 'todo', 'notes', 'calendar'
  actions: string[];       // ['create', 'update', 'query']
  inputTypes: string[];    // Welche Inputs kann der Agent verarbeiten?
}

Ermöglicht: "Finde den Agent, der Kalender-Events erstellen kann" → automatisches Routing.

5.6 🟡 Kein Guardrail-System

Problem: Policy (auto/propose/deny) ist ein Gating-Mechanismus, aber kein Guardrail. Es gibt keine:

• Input-Validierung (ist der Prompt safe?)
• Output-Validierung (ist das Ergebnis korrekt/sicher?)
• Budget-Enforcement serverseitig (nur client-seitig)

Was die Industrie macht:

• OpenAI SDK: Input + Output Guardrails parallel zur Execution
• CrewAI: Task-Level Guardrails
• LangGraph: Custom Validation Nodes

Empfehlung: Guardrails als separate Schicht:

interface Guardrail {
  name: string;
  phase: 'pre-plan' | 'post-plan' | 'pre-execute' | 'post-execute';
  check: (context: GuardrailContext) => GuardrailResult;
}
// Beispiele:
// - PII-Detection vor Planner-Call
// - Budget-Check vor Execution
// - Output-Schema-Validierung nach Tool-Call

5.7 🟢 Tracing & Debugging verbessern

Problem: Debug-Info ist in _aiDebugLog (localStorage, nie gesynct) + Prometheus Metrics. Kein zusammenhängendes Tracing einer Mission über Browser + Server.

Was die Industrie macht:

• OpenAI SDK: Built-in Tracing mit visuellen DAGs, OpenTelemetry Export
• LangGraph: LangSmith Integration, Step-by-Step Debugging, Time-Travel
• Microsoft: Semantic Kernel Telemetry

Empfehlung: OpenTelemetry-Spans für den gesamten Mission-Lifecycle:

Mission.run (span)
  ├── Input.resolve (span, per input)
  ├── Planner.call (span, mit prompt + response)
  ├── Step[0].execute (span, tool name + params + result)
  ├── Step[1].propose (span, proposal created)
  └── Iteration.write (span, sync write)

Exportierbar nach Grafana Tempo oder ähnlichem.

---

6. Strategische Empfehlungen (priorisiert)

Kurzfristig (nächste 2-4 Wochen)

#	Maßnahme	Aufwand	Impact
1	Streaming für Foreground Runner — ERLEDIGT be81d11dc	Mittel	Hoch
2	Dynamisches Tool-Registry — ERLEDIGT d40a61119	Mittel	Hoch
3	Budget-Enforcement serverseitig — ERLEDIGT ce57e1195 (rolling 24h, token_usage Tabelle)	Klein	Mittel

Mittelfristig (1-3 Monate)

#	Maßnahme	Aufwand	Impact
4	Agent-to-Agent Delegation — Internes Protokoll, ein Agent kann einen anderen beauftragen	Groß	Hoch — Multi-Agent
5	MCP-Server-Export — ERLEDIGT db4dd437b + e969324cc (29 Tools, 27 mit echten DB-Ops)	Mittel	Hoch
6	Guardrail-Layer — ERLEDIGT fad7f4bea (4 built-in checks)	Mittel	Mittel
7	OpenTelemetry Tracing — ERLEDIGT 76577869e (Tempo + mana-ai spans)	Mittel	Mittel

Langfristig (3-6 Monate)

#	Maßnahme	Aufwand	Impact
8	A2A-kompatible Agent Cards — Mana-Agents extern discoverable machen	Groß	Hoch — Interop
9	Graph-basierte Workflows — DAG für komplexe Missions	Groß	Mittel — Power-User
10	Agent Memory (Embeddings) — Long-term Memory à la CrewAI	Groß	Mittel — Intelligenz

---

7. Architektur-Diagramm: Ist vs. Soll

Ist-Zustand

┌──────────────────────────────────────────────────────┐
│ Browser (Foreground Runner)                          │
│  Mission → Planner → Policy Gate → Execute/Propose   │
│  ↕ Dexie (encrypted) ↕ mana-sync (LWW)             │
└──────────────────┬───────────────────────────────────┘
                   │ sync_changes
┌──────────────────▼───────────────────────────────────┐
│ mana-ai (Background Runner)                          │
│  Tick → Due Missions → Planner → Write Iteration     │
│  ↕ PostgreSQL (RLS) ↕ mana-llm                      │
└──────────────────────────────────────────────────────┘

Soll-Zustand (mittelfristig)

┌──────────────────────────────────────────────────────────────┐
│ Browser                                                       │
│  Mission → [Guardrails] → Planner (streaming) → Policy Gate  │
│  Agent A ←→ Agent B (delegation)                              │
│  ↕ Dexie (encrypted) ↕ mana-sync (LWW + SSE)               │
└──────────────────┬───────────────────────────────────────────┘
                   │ sync_changes + OTel spans
┌──────────────────▼───────────────────────────────────────────┐
│ mana-ai (Background Runner)                                   │
│  Tick → [Budget Check] → Due Missions → Planner → Write      │
│  Tool Registry (dynamic, MCP-compatible)                      │
│  ↕ PostgreSQL (RLS) ↕ mana-llm ↕ Grafana Tempo              │
└──────────────────┬───────────────────────────────────────────┘
                   │ A2A Agent Cards (langfristig)
┌──────────────────▼───────────────────────────────────────────┐
│ Externe Agents (Google ADK, OpenAI, etc.)                     │
│  Discovery via /.well-known/a2a/agent-card                    │
└──────────────────────────────────────────────────────────────┘

---

8. Fazit

Mana's AI-Agent-Architektur ist in drei Bereichen führend:

1. Privacy/Encryption — Kein vergleichbares Framework hat Key-Grants, Zero-Knowledge, oder at-rest Encryption für Agent-Daten
2. Local-First + Multi-Device — Einzigartige Dual-Runtime mit Offline-Fähigkeit
3. Actor Attribution — Bestes Audit-Trail-System unter allen verglichenen Frameworks

Die größten Lücken gegenüber der Industrie:

1. Kein Agent-to-Agent — Die wichtigste fehlende Capability für echte Multi-Agent-Systeme
2. Kein Streaming — ERLEDIGT (be81d11dc)
3. Statisches Tool-System — ERLEDIGT (d40a61119)

Die Kernempfehlung: Mana sollte nicht versuchen, ein General-Purpose-Agent-Framework zu werden (das machen LangGraph/CrewAI besser). Stattdessen die einzigartigen Stärken (Privacy, Local-First, Attribution) ausbauen und den größten verbleibenden Architektur-Sprung angehen: Agent-to-Agent Delegation.

Stand 2026-04-16: 7 von 10 Roadmap-Punkten in einer Session umgesetzt:

• #1 Streaming ✅ · #2 Dynamic Tools ✅ · #3 Budget ✅ · #5 MCP Server ✅ · #6 Guardrails ✅ · #7 OTel ✅ · Tool-Drift-Fix (Bonus)

Verbleibend (langfristig):

• #4 Agent-to-Agent Delegation — Internes Protokoll für Agent-Kommunikation. Nächster architektureller Meilenstein.
• #8 A2A Agent Cards — Mana-Agents extern discoverable machen (setzt #4 voraus)
• #9 Graph-Workflows — DAG für komplexe Missions (niedrige Priorität, linearer Loop reicht für 90% der Usecases)
• #10 Agent Memory (Embeddings) — Long-term Memory à la CrewAI (abhängig von Infra-Entscheidung: eigener Vector-Store vs. externe Integration)