microdao-daarion/docs/AGENT_HUB_SPEC.md

🤖 Agent Hub UI — Technical Specification

Version: 1.0
Phase: 5
Status: ✅ Complete
Date: 2025-11-24

---

📋 Overview

Agent Hub — це центральний UI для управління агентами DAARION. Надає візуальний інтерфейс для перегляду, моніторингу та налаштування агентів.

Features:

• ✅ Gallery view — перегляд усіх агентів в grid layout
• ✅ Agent Cabinet — детальна сторінка агента з табами
• ✅ Metrics Dashboard — статистика використання LLM/tools
• ✅ Context Viewer — перегляд пам'яті агента (short/mid/long-term)
• ✅ Settings Panel — налаштування моделі та інструментів
• ✅ Real-time status indicators
• ✅ Search & filters

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Agent Hub UI                            │
│  (React + TypeScript + Tailwind CSS)                        │
└─────────────────────────────────────────────────────────────┘
                             │
                             │ HTTP/REST
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                   agents-service                             │
│                   Port: 7014                                 │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  • GET /agents             — List agents             │  │
│  │  • GET /agents/{id}        — Agent details           │  │
│  │  • GET /agents/{id}/metrics — Usage stats            │  │
│  │  • GET /agents/{id}/context — Memory                 │  │
│  │  • POST /agents/{id}/settings/model — Update model   │  │
│  │  • POST /agents/{id}/settings/tools — Update tools   │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
          │                │                    │
          │                │                    │
          ▼                ▼                    ▼
   ┌───────────┐   ┌───────────────┐   ┌──────────────┐
   │  memory-  │   │ usage-engine  │   │     PDP      │
   │orchestrator│   │   (metrics)   │   │  (authz)     │
   │   :7008   │   │     :7013     │   │    :7012     │
   └───────────┘   └───────────────┘   └──────────────┘

---

📁 File Structure

src/
├── api/
│   └── agents.ts                       ✅ API client (11 functions)
│
├── features/
│   └── agentHub/
│       ├── hooks/
│       │   ├── useAgents.ts           ✅ List agents hook
│       │   ├── useAgent.ts            ✅ Single agent hook
│       │   ├── useAgentMetrics.ts     ✅ Metrics hook
│       │   └── useAgentContext.ts     ✅ Context hook
│       │
│       ├── AgentHubPage.tsx           ✅ Main page (/agent-hub)
│       ├── AgentGallery.tsx           ✅ Grid view
│       ├── AgentCard.tsx              ✅ Single card
│       ├── AgentCabinet.tsx           ✅ Agent detail page (/agent/:id)
│       ├── AgentMetricsPanel.tsx      ✅ Metrics tab
│       └── AgentSettingsPanel.tsx     ✅ Settings tab
│
└── App.tsx                             ✅ Updated with routes

Total: 14 files created/updated

---

🎨 UI Components

1. AgentHubPage (/agent-hub)

Purpose: Головна сторінка — перегляд усіх агентів

Features:

• Search bar (по імені/опису)
• Filter by MicroDAO
• Stats cards (total, active, your microDAOs)
• Agent gallery grid
• Refresh button

Layout:

┌────────────────────────────────────────────────────┐
│  🤖 Agent Hub                       [🔄 Оновити]   │
│  Керуйте агентами вашого MicroDAO                  │
│                                                     │
│  [🔍 Пошук агентів...]  [▼ Всі MicroDAO]          │
│                                                     │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
│  │   42    │  │   15    │  │    3    │            │
│  │ Знайдено│  │Активних │  │Ваших DAO│            │
│  └─────────┘  └─────────┘  └─────────┘            │
│                                                     │
│  ┌──────┐  ┌──────┐  ┌──────┐                     │
│  │Sofia │  │ Alex │  │Guard.│                     │
│  │🟢 Act│  │🟡 Idle│  │🟢 Act│                     │
│  └──────┘  └──────┘  └──────┘                     │
└────────────────────────────────────────────────────┘

---

2. AgentCard

Purpose: Одна карточка агента в gallery

Features:

• Avatar (gradient circle з першою літерою)
• Name + Kind badge
• Status indicator (green/yellow/gray/red)
• Model name
• Last active timestamp
• Click → navigate to /agent/{id}

Visual:

┌────────────────────────────────┐
│              🟢 Активний       │
│  ┌──┐                          │
│  │S │ Sofia                    │
│  └──┘ [Асистент]               │
│                                 │
│  Допомагає з проєктами...      │
│                                 │
│  Модель: gpt-4.1-mini          │
│  Остання активність: 10:30     │
└────────────────────────────────┘

---

3. AgentCabinet (/agent/:agentId)

Purpose: Детальна сторінка агента з табами

Tabs:

1. 📊 Метрики — usage stats
2. 🧠 Контекст — memory (short/mid/knowledge)
3. ⚙️ Налаштування — model, tools, system prompt

Header:

• Back button (← Назад до Agent Hub)
• Large avatar
• Name + status + description
• Model + MicroDAO + Tools count
• Actions: [🔄 Оновити] [💬 Чат]

Layout:

┌────────────────────────────────────────────────────┐
│ ← Назад до Agent Hub                               │
│                                                     │
│  ┌───┐ Sofia                 🟢 Активний           │
│  │ S │ Допомагає з проєктами                       │
│  └───┘ 🤖 gpt-4.1-mini | 🏢 daarion | 🔧 6 tools  │
│                                                     │
│  [📊 Метрики] [🧠 Контекст] [⚙️ Налаштування]     │
│  ─────────────                                      │
│  (tab content here)                                │
└────────────────────────────────────────────────────┘

---

4. AgentMetricsPanel

Purpose: Відображення статистики використання

Metrics:

• LLM Calls Total
• Tokens Total (formatted as K/M)
• Tool Calls Total
• Messages Sent
• Average Latency (ms)
• Tool Success Rate (%)
• Errors Count

Period selector: 24 год | 7 днів | 30 днів

Charts:

• Time-series bar charts for tokens
• Time-series bar charts for tool calls

Visual:

┌────────────────────────────────────────────────────┐
│ 📊 Метрики                [24год][7днів][30днів]  │
│                                                     │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│  │  1,234  │ │  45.2K  │ │   156   │ │   423   │ │
│  │LLM Calls│ │ Токени  │ │  Tools  │ │Messages │ │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│                                                     │
│  Середня затримка: 320 мс                          │
│  Успішність інструментів: 98.5%                    │
│  Помилки: 3                                        │
│                                                     │
│  Активність в часі:                                │
│  [bar chart for tokens]                            │
│  [bar chart for tool calls]                        │
└────────────────────────────────────────────────────┘

---

5. AgentSettingsPanel

Purpose: Налаштування агента

Settings:

🤖 LLM Модель:

• Radio buttons для вибору моделі
• List: gpt-4.1-mini, gpt-4-turbo, deepseek-r1, claude-3.7-sonnet, llama-3.3-70b
• [Зберегти модель] button

🔧 Інструменти:

• Checkboxes для кожного інструмента
• Categories: Projects, Tasks, Memory, Files, Web
• [Зберегти інструменти] button

ℹ️ Інформація:

• Agent ID
• MicroDAO ID
• Created at
• Updated at

Visual:

┌────────────────────────────────────────────────────┐
│ ⚙️ Налаштування                                    │
│                                                     │
│ 🤖 LLM Модель                                      │
│  ○ GPT-4.1 Mini      (OpenAI) ← Поточна           │
│  ○ GPT-4 Turbo       (OpenAI)                      │
│  ○ DeepSeek R1       (DeepSeek)                    │
│  [Зберегти модель]                                  │
│                                                     │
│ 🔧 Інструменти                                     │
│  ☑ Список проєктів   (Projects)                    │
│  ☑ Створити задачу   (Tasks)                       │
│  ☐ Пошук в пам'яті   (Memory)                      │
│  [Зберегти інструменти]                             │
└────────────────────────────────────────────────────┘

---

🔌 API Client (src/api/agents.ts)

Types

type AgentKind = 'assistant' | 'node' | 'system' | 'guardian' | 'analyst';
type AgentStatus = 'active' | 'idle' | 'offline' | 'error';

interface AgentListItem {
  id: string;
  name: string;
  kind: AgentKind;
  status: AgentStatus;
  model: string;
  microdao_id: string;
  description?: string;
  avatar_url?: string;
  last_active_at?: string;
}

interface AgentDetail extends AgentListItem {
  owner_user_id: string;
  tools: string[];
  system_prompt?: string;
  created_at: string;
  updated_at: string;
}

interface AgentMetrics {
  agent_id: string;
  period_hours: number;
  llm_calls_total: number;
  llm_tokens_total: number;
  llm_latency_avg_ms: number;
  tool_calls_total: number;
  tool_success_rate: number;
  invocations_total: number;
  messages_sent: number;
  errors_count: number;
}

interface AgentContext {
  agent_id: string;
  short_term: MemoryItem[];
  mid_term: MemoryItem[];
  knowledge_items: MemoryItem[];
}

Functions

// Agent CRUD
getAgents(microdaoId?: string): Promise<AgentListItem[]>
getAgent(agentId: string): Promise<AgentDetail>

// Metrics
getAgentMetrics(agentId: string, periodHours?: number): Promise<AgentMetrics>
getAgentMetricsSeries(agentId: string, periodHours?: number): Promise<AgentMetricsSeries>

// Context
getAgentContext(agentId: string): Promise<AgentContext>

// Events
getAgentEvents(agentId: string, limit?: number): Promise<AgentEvent[]>

// Settings
updateAgentModel(agentId: string, model: string): Promise<{success: boolean}>
updateAgentTools(agentId: string, toolsEnabled: string[]): Promise<{success: boolean}>
updateAgentSystemPrompt(agentId: string, systemPrompt: string): Promise<{success: boolean}>

// Health
checkAgentsServiceHealth(): Promise<{service: string; status: string}>

Base URL

const AGENTS_API_URL = import.meta.env.VITE_AGENTS_API_URL || 'http://localhost:7014';

Authentication

Всі запити автоматично додають Authorization: Bearer {token} header, використовуючи token з localStorage (ключ: daarion_session_token).

---

🪝 React Hooks

1. useAgents

function useAgents(microdaoId?: string): {
  agents: AgentListItem[];
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}

Usage:

const { agents, loading, error, refetch } = useAgents('microdao:daarion');

---

2. useAgent

function useAgent(agentId: string): {
  agent: AgentDetail | null;
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}

Usage:

const { agent, loading } = useAgent('agent:sofia');

---

3. useAgentMetrics

function useAgentMetrics(agentId: string, periodHours?: number): {
  metrics: AgentMetrics | null;
  series: AgentMetricsSeries | null;
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}

Usage:

const { metrics, series } = useAgentMetrics('agent:sofia', 168);

---

4. useAgentContext

function useAgentContext(agentId: string): {
  context: AgentContext | null;
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
}

Usage:

const { context } = useAgentContext('agent:sofia');

---

🚀 Deployment

1. Start Backend

cd /Users/apple/github-projects/microdao-daarion

# Start all services (Phase 5)
docker-compose -f docker-compose.phase5.yml up -d

# Or start agents-service manually
cd services/agents-service
pip install -r requirements.txt
python main.py  # Port 7014

2. Start Frontend

# Install dependencies
npm install

# Start dev server
npm run dev

# Open: http://localhost:3000

3. Navigate to Agent Hub

http://localhost:3000/agent-hub

---

🧪 Testing

Manual Testing Flow:

1. Start services (docker-compose.phase5.yml)
2. Open frontend (http://localhost:3000)
3. Navigate to /agent-hub
4. Verify gallery loads (should show Sofia, Alex, Guardian)
5. Click on an agent card → should open /agent/{id}
6. Check all tabs:
   • Metrics: stats load, charts render
   • Context: memory items display
   • Settings: can change model/tools
7. Test search (type "sofia")
8. Test filter (select "DAARION")
9. Test refresh button

API Testing:

# Health check
curl http://localhost:7014/health

# List agents
curl http://localhost:7014/agents

# Get agent details
curl http://localhost:7014/agents/agent:sofia

# Get metrics
curl http://localhost:7014/agents/agent:sofia/metrics

# Get context
curl http://localhost:7014/agents/agent:sofia/context

---

📊 Mock Data

Current mock agents (from backend):

[
  {
    "id": "agent:sofia",
    "name": "Sofia",
    "kind": "assistant",
    "model": "gpt-4.1-mini",
    "microdao_id": "microdao:daarion",
    "tools": ["projects.list", "task.create"],
    "status": "active"
  },
  {
    "id": "agent:alex",
    "name": "Alex",
    "kind": "analyst",
    "model": "deepseek-r1",
    "microdao_id": "microdao:7",
    "status": "idle"
  },
  {
    "id": "agent:guardian",
    "name": "Guardian",
    "kind": "guardian",
    "model": "gpt-4.1-mini",
    "microdao_id": "microdao:daarion",
    "status": "active"
  }
]

Note: Phase 6 буде додано database persistence і можливість створювати нових агентів.

---

🔮 Future Enhancements (Phase 6+)

Phase 6: Agent CRUD

• ✨ Create new agents via UI
• ✨ Delete agents
• ✨ Agent templates
• ✨ Bulk operations

Phase 6.5: Real-time Updates

• ✨ WebSocket integration
• ✨ Live activity feed
• ✨ Real-time status updates
• ✨ Event stream

Phase 7: Advanced Features

• ✨ Agent chat (inline chat with agent)
• ✨ Agent cloning
• ✨ Usage analytics dashboard
• ✨ Cost tracking
• ✨ Agent marketplace

---

📝 Notes

Known Limitations:

1. Mock data only — agents-service використовує hardcoded mock data (Phase 6 додасть database)
2. No WebSocket — статус оновлюється тільки при refetch (Phase 6.5 додасть live updates)
3. Limited events — events endpoint пустий (Phase 6 додасть event store)
4. Basic context — контекст не повністю інтегрований з memory-orchestrator (Phase 6 покращить)

Performance:

• All API calls cached in React state
• Lazy loading for metrics/context
• Optimistic UI updates for settings

Accessibility:

• Semantic HTML
• Keyboard navigation
• ARIA labels (planned)
• Screen reader support (planned)

---

🎯 Acceptance Criteria

• /agent-hub shows all agents in gallery
• AgentCard displays: name, kind, model, status
• Click agent → opens AgentCabinet
• AgentCabinet shows: metrics, context, settings
• Metrics load from usage-engine
• Context loads from memory-orchestrator
• Model switching works (updates via API)
• Tools enable/disable works
• Search by name works
• Filter by MicroDAO works
• Routes protected by auth (planned)
• PDP enforces permissions (planned)

---

📚 Related Documents

• HANDOFF_DOCUMENT.md — повний проєктний контекст
• START_PHASE5_FRONTEND.md — швидкий старт
• PHASE4_READY.md — Security Layer
• PHASE45_READY.md — Passkey Auth
• services/agents-service/README.md — Backend API docs
• INFRASTRUCTURE.md — повна інфраструктура

---

Status: ✅ Phase 5 Frontend Complete (100%)
Next Phase: Phase 6 — Agent CRUD & Database Integration
Last Updated: 2025-11-24

---

END OF AGENT HUB SPEC 🤖