feat: Add presence heartbeat for Matrix online status
- 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
This commit is contained in:
Apple
622
docs/AGENT_HUB_SPEC.md
Normal file
622
docs/AGENT_HUB_SPEC.md
Normal file
@@ -0,0 +1,622 @@
|
||||
# 🤖 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** 🤖
|
||||
|
||||
Reference in New Issue
Block a user