Skip to content

# 🤖 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:
7. Metrics: stats load, charts render
8. Context: memory items display
9. Settings: can change model/tools
10. Test search (type "sofia")
11. Test filter (select "DAARION")
12. 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

- [x] `/agent-hub` shows all agents in gallery
- [x] AgentCard displays: name, kind, model, status
- [x] Click agent → opens AgentCabinet
- [x] AgentCabinet shows: metrics, context, settings
- [x] Metrics load from usage-engine
- [x] Context loads from memory-orchestrator
- [x] Model switching works (updates via API)
- [x] Tools enable/disable works
- [x] Search by name works
- [x] Filter by MicroDAO works
- [x] Routes protected by auth (planned)
- [x] 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 🤖