3de3c8cb36
- matrix-gateway: POST /internal/matrix/presence/online endpoint - usePresenceHeartbeat hook with activity tracking - Auto away after 5 min inactivity - Offline on page close/visibility change - Integrated in MatrixChatRoom component
623 lines
20 KiB
Markdown
623 lines
20 KiB
Markdown
# 🤖 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
|
||
|
||
```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
|
||
|
||
```typescript
|
||
// 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
|
||
|
||
```typescript
|
||
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
|
||
|
||
```typescript
|
||
function useAgents(microdaoId?: string): {
|
||
agents: AgentListItem[];
|
||
loading: boolean;
|
||
error: Error | null;
|
||
refetch: () => Promise<void>;
|
||
}
|
||
```
|
||
|
||
**Usage:**
|
||
```typescript
|
||
const { agents, loading, error, refetch } = useAgents('microdao:daarion');
|
||
```
|
||
|
||
---
|
||
|
||
### 2. useAgent
|
||
|
||
```typescript
|
||
function useAgent(agentId: string): {
|
||
agent: AgentDetail | null;
|
||
loading: boolean;
|
||
error: Error | null;
|
||
refetch: () => Promise<void>;
|
||
}
|
||
```
|
||
|
||
**Usage:**
|
||
```typescript
|
||
const { agent, loading } = useAgent('agent:sofia');
|
||
```
|
||
|
||
---
|
||
|
||
### 3. useAgentMetrics
|
||
|
||
```typescript
|
||
function useAgentMetrics(agentId: string, periodHours?: number): {
|
||
metrics: AgentMetrics | null;
|
||
series: AgentMetricsSeries | null;
|
||
loading: boolean;
|
||
error: Error | null;
|
||
refetch: () => Promise<void>;
|
||
}
|
||
```
|
||
|
||
**Usage:**
|
||
```typescript
|
||
const { metrics, series } = useAgentMetrics('agent:sofia', 168);
|
||
```
|
||
|
||
---
|
||
|
||
### 4. useAgentContext
|
||
|
||
```typescript
|
||
function useAgentContext(agentId: string): {
|
||
context: AgentContext | null;
|
||
loading: boolean;
|
||
error: Error | null;
|
||
refetch: () => Promise<void>;
|
||
}
|
||
```
|
||
|
||
**Usage:**
|
||
```typescript
|
||
const { context } = useAgentContext('agent:sofia');
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 Deployment
|
||
|
||
### 1. Start Backend
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
# 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):
|
||
|
||
```json
|
||
[
|
||
{
|
||
"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** 🤖
|
||
|