🤖 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:¶

Start services (docker-compose.phase5.yml)
Open frontend (http://localhost:3000)
Navigate to /agent-hub
Verify gallery loads (should show Sofia, Alex, Guardian)
Click on an agent card → should open /agent/{id}
Check all tabs:
Metrics: stats load, charts render
Context: memory items display
Settings: can change model/tools
Test search (type "sofia")
Test filter (select "DAARION")
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:¶

Mock data only — agents-service використовує hardcoded mock data (Phase 6 додасть database)
No WebSocket — статус оновлюється тільки при refetch (Phase 6.5 додасть live updates)
Limited events — events endpoint пустий (Phase 6 додасть event store)
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)

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 🤖

🤖 Agent Hub UI — Technical Specification¶

📋 Overview¶

Features:¶

🏗️ Architecture¶

📁 File Structure¶

🎨 UI Components¶

1. AgentHubPage (/agent-hub)¶

2. AgentCard¶

3. AgentCabinet (/agent/:agentId)¶

4. AgentMetricsPanel¶

5. AgentSettingsPanel¶

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

Types¶

Functions¶

Base URL¶

Authentication¶

🪝 React Hooks¶

1. useAgents¶

2. useAgent¶

3. useAgentMetrics¶

4. useAgentContext¶

🚀 Deployment¶

1. Start Backend¶

2. Start Frontend¶

3. Navigate to Agent Hub¶

🧪 Testing¶

Manual Testing Flow:¶

API Testing:¶

📊 Mock Data¶

Current mock agents (from backend):¶

🔮 Future Enhancements (Phase 6+)¶

Phase 6: Agent CRUD¶

Phase 6.5: Real-time Updates¶

Phase 7: Advanced Features¶

📝 Notes¶

Known Limitations:¶

Performance:¶

Accessibility:¶

🎯 Acceptance Criteria¶

📚 Related Documents¶

1. AgentHubPage (`/agent-hub`)¶

3. AgentCabinet (`/agent/:agentId`)¶

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