daarion-admin/microdao-daarion

Fork 0

Files

Apple 083a622817 docs: expand lint scope batch7 (2 files)

2026-02-16 04:05:40 -08:00

20 KiB

Raw Permalink Blame History

🤖 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     │
   └───────────┘   └───────────────┘   └──────────────┘
```text

---

## 📁 File Structure

```text
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:

📊 Метрики — usage stats
🧠 Контекст — memory (short/mid/knowledge)
⚙️ Налаштування — 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)                      │
│  [Зберегти інструменти]                             │
└────────────────────────────────────────────────────┘
```text

---

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

### Types

```typescript
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

/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)

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 🤖

20 KiB Raw Permalink Blame History Unescape Escape

🤖 Agent Hub UI — Technical Specification

📋 Overview

Features

🏗️ Architecture

🎨 UI Components

1. AgentHubPage (/agent-hub)

2. AgentCard

3. AgentCabinet (/agent/:agentId)

4. AgentMetricsPanel

5. AgentSettingsPanel

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

20 KiB

Raw Permalink Blame History

1. AgentHubPage (`/agent-hub`)

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