744c149300
Some checks failed
Build and Deploy Docs / build-and-deploy (push) Has been cancelled
- Created logs/ structure (sessions, operations, incidents) - Added session-start/log/end scripts - Installed Git hooks for auto-logging commits/pushes - Added shell integration for zsh - Created CHANGELOG.md - Documented today's session (2026-01-10)
555 lines
13 KiB
Markdown
555 lines
13 KiB
Markdown
# TASK: Agent Hub UI — Agent Monitoring & Management Dashboard
|
|
|
|
**Priority:** High (Parallel to Phase 3)
|
|
**Estimated Time:** 3-4 weeks
|
|
**Dependencies:** Phase 2 complete
|
|
|
|
---
|
|
|
|
## Goal
|
|
|
|
Створити централізований UI для моніторингу та управління агентами в DAARION:
|
|
- **Agent Gallery** — список всіх агентів з їх статусами
|
|
- **Agent Cabinet** — детальна інформація про агента
|
|
- **Real-time monitoring** — активність, метрики, логи
|
|
- **Agent Configuration** — налаштування, інструкції, tools
|
|
- **Conversational Interface** — прямий чат з агентом
|
|
|
|
---
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
Agent Hub UI (React)
|
|
↓
|
|
├─ Agent Gallery (список агентів)
|
|
├─ Agent Cabinet (детальний dashboard)
|
|
├─ Agent Chat (direct conversation)
|
|
├─ Agent Metrics (real-time stats)
|
|
└─ Agent Configuration (edit settings)
|
|
↓
|
|
Backend:
|
|
├─ agents-service (агенти + blueprints)
|
|
├─ agent-runtime (execution stats)
|
|
├─ messaging-service (direct chat)
|
|
└─ NATS (real-time events)
|
|
```
|
|
|
|
---
|
|
|
|
## Deliverables
|
|
|
|
### 1. Frontend Components (src/features/agent-hub/)
|
|
|
|
**Structure:**
|
|
```
|
|
src/features/agent-hub/
|
|
components/
|
|
AgentGallery.tsx # Grid of agent cards
|
|
AgentCard.tsx # Single agent preview
|
|
AgentCabinet.tsx # Full agent dashboard
|
|
AgentMetrics.tsx # Real-time metrics panel
|
|
AgentLogs.tsx # Activity log stream
|
|
AgentConfiguration.tsx # Edit agent settings
|
|
AgentChat.tsx # Direct chat interface
|
|
AgentToolsPanel.tsx # List of agent tools
|
|
hooks/
|
|
useAgents.ts # Fetch agents list
|
|
useAgentDetails.ts # Fetch single agent
|
|
useAgentMetrics.ts # Real-time metrics
|
|
useAgentLogs.ts # Activity stream
|
|
useDirectChat.ts # Direct chat with agent
|
|
types/
|
|
agent.ts # TypeScript types
|
|
AgentHubPage.tsx # Main hub page
|
|
```
|
|
|
|
---
|
|
|
|
### 2. Backend: agents-service (NEW)
|
|
|
|
**Port:** 7010
|
|
**Purpose:** Agent blueprints, configuration, metadata
|
|
|
|
**Structure:**
|
|
```
|
|
services/agents-service/
|
|
main.py
|
|
models.py
|
|
blueprints.py
|
|
config.yaml
|
|
requirements.txt
|
|
Dockerfile
|
|
README.md
|
|
```
|
|
|
|
**API:**
|
|
|
|
#### GET /api/agents
|
|
List all agents:
|
|
```json
|
|
{
|
|
"agents": [
|
|
{
|
|
"id": "agent:sofia",
|
|
"name": "Sofia-Prime",
|
|
"kind": "assistant",
|
|
"status": "active",
|
|
"avatar": "https://...",
|
|
"description": "Project manager & task organizer",
|
|
"capabilities": ["task_mgmt", "summarization"],
|
|
"microdao_id": "microdao:daarion",
|
|
"created_at": "2025-01-01T00:00:00Z",
|
|
"last_active": "2025-11-24T12:00:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
#### GET /api/agents/{agent_id}
|
|
Get agent details:
|
|
```json
|
|
{
|
|
"id": "agent:sofia",
|
|
"name": "Sofia-Prime",
|
|
"kind": "assistant",
|
|
"status": "active",
|
|
"avatar": "https://...",
|
|
"description": "...",
|
|
"instructions": "You are Sofia, a helpful assistant...",
|
|
"model": "gpt-4.1-mini",
|
|
"tools": ["projects.list", "task.create", "followup.create"],
|
|
"capabilities": {...},
|
|
"metrics": {
|
|
"total_messages": 1234,
|
|
"total_invocations": 567,
|
|
"avg_response_time_ms": 2345,
|
|
"success_rate": 0.98
|
|
},
|
|
"config": {
|
|
"temperature": 0.7,
|
|
"max_tokens": 1000,
|
|
"quiet_hours": "22:00-08:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
#### PUT /api/agents/{agent_id}
|
|
Update agent configuration:
|
|
```json
|
|
{
|
|
"instructions": "Updated instructions...",
|
|
"model": "gpt-4",
|
|
"tools": ["projects.list", "task.create"],
|
|
"config": {
|
|
"temperature": 0.8,
|
|
"max_tokens": 2000
|
|
}
|
|
}
|
|
```
|
|
|
|
#### GET /api/agents/{agent_id}/metrics/realtime
|
|
Real-time metrics (WebSocket or SSE):
|
|
```json
|
|
{
|
|
"agent_id": "agent:sofia",
|
|
"timestamp": "2025-11-24T12:34:56Z",
|
|
"active_conversations": 3,
|
|
"messages_last_hour": 15,
|
|
"avg_response_time_ms": 2100,
|
|
"current_load": "normal"
|
|
}
|
|
```
|
|
|
|
#### GET /api/agents/{agent_id}/logs?limit=50
|
|
Activity logs:
|
|
```json
|
|
{
|
|
"logs": [
|
|
{
|
|
"id": "log-123",
|
|
"timestamp": "2025-11-24T12:34:56Z",
|
|
"event_type": "message.sent",
|
|
"channel_id": "channel-uuid",
|
|
"content_preview": "Створила задачу 'Phase 3 testing'",
|
|
"metadata": {
|
|
"latency_ms": 2345,
|
|
"tokens_used": 567
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 3. UI Components Detail
|
|
|
|
#### AgentGallery.tsx
|
|
- Grid layout (3-4 columns)
|
|
- Agent cards with:
|
|
- Avatar
|
|
- Name + status badge
|
|
- Short description
|
|
- Last active time
|
|
- Quick stats (messages, response time)
|
|
- Filter by:
|
|
- Status (active, paused, error)
|
|
- Kind (assistant, coordinator, specialist)
|
|
- MicroDAO
|
|
- Search by name
|
|
|
|
**Wireframe:**
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ Agent Hub [+ New] │
|
|
├─────────────────────────────────────────┤
|
|
│ [Filter: All] [Search: ...] │
|
|
├─────────────────────────────────────────┤
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
|
│ │ 👤 Sofia │ │ 👤 Alex │ │ 👤 Eva │
|
|
│ │ ● Active │ │ ● Active │ │ ⏸ Paused │
|
|
│ │ PM & Org │ │ Tech │ │ Research │
|
|
│ │ 234 msgs │ │ 156 msgs │ │ 89 msgs │
|
|
│ └──────────┘ └──────────┘ └──────────┘
|
|
```
|
|
|
|
#### AgentCabinet.tsx
|
|
- Header:
|
|
- Avatar, name, status
|
|
- Quick actions (pause, edit, chat)
|
|
- Tabs:
|
|
- **Overview**: Key stats + recent activity
|
|
- **Metrics**: Real-time charts
|
|
- **Logs**: Activity stream
|
|
- **Configuration**: Edit settings
|
|
- **Chat**: Direct conversation
|
|
|
|
**Wireframe:**
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ 👤 Sofia-Prime [Edit] [Chat]│
|
|
│ ● Active | Last seen: 2m ago │
|
|
├─────────────────────────────────────────┤
|
|
│ [Overview] [Metrics] [Logs] [Config] │
|
|
├─────────────────────────────────────────┤
|
|
│ 📊 Statistics (24h) │
|
|
│ Messages: 45 | Invocations: 23 │
|
|
│ Avg Response: 2.3s | Success: 98% │
|
|
│ │
|
|
│ 📝 Recent Activity │
|
|
│ • 12:34 - Replied in #general │
|
|
│ • 12:30 - Created task "Phase 3 test" │
|
|
│ • 12:25 - Summarized meeting notes │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
#### AgentChat.tsx
|
|
- Direct 1-on-1 chat with agent
|
|
- Similar to Messenger UI
|
|
- Shows agent thinking/tools usage
|
|
- Context: "Direct conversation (not in channel)"
|
|
|
|
---
|
|
|
|
### 4. Real-time Updates
|
|
|
|
**WebSocket endpoint:** `ws://localhost:7010/ws/agents/{agent_id}`
|
|
|
|
**Events:**
|
|
```json
|
|
{
|
|
"type": "agent.message.sent",
|
|
"agent_id": "agent:sofia",
|
|
"channel_id": "channel-uuid",
|
|
"timestamp": "2025-11-24T12:34:56Z",
|
|
"content_preview": "Created task..."
|
|
}
|
|
|
|
{
|
|
"type": "agent.metrics.update",
|
|
"agent_id": "agent:sofia",
|
|
"metrics": {
|
|
"active_conversations": 3,
|
|
"messages_last_hour": 15
|
|
}
|
|
}
|
|
|
|
{
|
|
"type": "agent.status.changed",
|
|
"agent_id": "agent:sofia",
|
|
"old_status": "active",
|
|
"new_status": "paused"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 5. Integration Points
|
|
|
|
**With Phase 2:**
|
|
- Uses existing `messaging-service` for direct chat
|
|
- Displays logs from `agent-runtime` invocations
|
|
- Shows agent status from `agent-filter`
|
|
|
|
**With Phase 3:**
|
|
- Shows LLM usage (tokens, cost) from `llm-proxy`
|
|
- Displays memory stats from `memory-orchestrator`
|
|
- Lists available tools from `toolcore`
|
|
|
|
**With NATS:**
|
|
- Subscribes to `agent.*` events for real-time updates
|
|
- Publishes `agent.config.updated` on changes
|
|
|
|
---
|
|
|
|
### 6. Mock Data (Development)
|
|
|
|
**agents.mock.ts:**
|
|
```typescript
|
|
export const mockAgents: Agent[] = [
|
|
{
|
|
id: "agent:sofia",
|
|
name: "Sofia-Prime",
|
|
kind: "assistant",
|
|
status: "active",
|
|
avatar: "/avatars/sofia.png",
|
|
description: "Project manager & task organizer",
|
|
capabilities: ["task_mgmt", "summarization", "planning"],
|
|
microdao_id: "microdao:daarion",
|
|
created_at: "2025-01-01T00:00:00Z",
|
|
last_active: "2025-11-24T12:00:00Z",
|
|
metrics: {
|
|
total_messages: 1234,
|
|
total_invocations: 567,
|
|
avg_response_time_ms: 2345,
|
|
success_rate: 0.98
|
|
}
|
|
},
|
|
{
|
|
id: "agent:alex",
|
|
name: "Alex-Tech",
|
|
kind: "specialist",
|
|
status: "active",
|
|
avatar: "/avatars/alex.png",
|
|
description: "Technical specialist for development tasks",
|
|
capabilities: ["code_review", "debugging", "documentation"],
|
|
microdao_id: "microdao:daarion",
|
|
created_at: "2025-01-15T00:00:00Z",
|
|
last_active: "2025-11-24T11:45:00Z",
|
|
metrics: {
|
|
total_messages: 856,
|
|
total_invocations: 423,
|
|
avg_response_time_ms: 3100,
|
|
success_rate: 0.96
|
|
}
|
|
}
|
|
];
|
|
```
|
|
|
|
---
|
|
|
|
### 7. Tech Stack
|
|
|
|
**Frontend:**
|
|
- React 18 + TypeScript
|
|
- Tailwind CSS
|
|
- React Query (TanStack Query)
|
|
- React Router
|
|
- WebSocket (for real-time)
|
|
|
|
**Backend:**
|
|
- Python 3.11 + FastAPI
|
|
- PostgreSQL (agents DB)
|
|
- NATS (events)
|
|
- Docker
|
|
|
|
---
|
|
|
|
### 8. Database Schema
|
|
|
|
**agents table:**
|
|
```sql
|
|
CREATE TABLE agents (
|
|
id TEXT PRIMARY KEY,
|
|
name TEXT NOT NULL,
|
|
kind TEXT NOT NULL, -- assistant, coordinator, specialist
|
|
status TEXT NOT NULL DEFAULT 'active', -- active, paused, error
|
|
avatar TEXT,
|
|
description TEXT,
|
|
instructions TEXT NOT NULL,
|
|
model TEXT NOT NULL,
|
|
tools JSONB DEFAULT '[]',
|
|
capabilities JSONB DEFAULT '{}',
|
|
config JSONB DEFAULT '{}',
|
|
microdao_id TEXT NOT NULL,
|
|
created_at TIMESTAMPTZ DEFAULT NOW(),
|
|
updated_at TIMESTAMPTZ DEFAULT NOW(),
|
|
last_active TIMESTAMPTZ
|
|
);
|
|
|
|
CREATE INDEX idx_agents_microdao ON agents(microdao_id);
|
|
CREATE INDEX idx_agents_status ON agents(status);
|
|
```
|
|
|
|
**agent_metrics table:**
|
|
```sql
|
|
CREATE TABLE agent_metrics (
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
agent_id TEXT NOT NULL REFERENCES agents(id),
|
|
timestamp TIMESTAMPTZ DEFAULT NOW(),
|
|
event_type TEXT NOT NULL, -- message.sent, invocation, error
|
|
channel_id TEXT,
|
|
latency_ms FLOAT,
|
|
tokens_used INT,
|
|
success BOOLEAN,
|
|
metadata JSONB
|
|
);
|
|
|
|
CREATE INDEX idx_metrics_agent_time ON agent_metrics(agent_id, timestamp DESC);
|
|
```
|
|
|
|
---
|
|
|
|
### 9. Routes
|
|
|
|
**Frontend routes:**
|
|
```
|
|
/agents → AgentGallery (list)
|
|
/agents/:agentId → AgentCabinet (dashboard)
|
|
/agents/:agentId/chat → AgentChat (direct conversation)
|
|
/agents/:agentId/config → AgentConfiguration (edit)
|
|
```
|
|
|
|
---
|
|
|
|
### 10. Acceptance Criteria
|
|
|
|
✅ **Agent Gallery:**
|
|
- Shows all agents with status badges
|
|
- Filter by status, kind, microDAO
|
|
- Search by name
|
|
- Responsive grid layout
|
|
|
|
✅ **Agent Cabinet:**
|
|
- Displays all agent details
|
|
- Shows real-time metrics
|
|
- Activity log stream
|
|
- Configuration editor
|
|
|
|
✅ **Agent Chat:**
|
|
- Direct 1-on-1 conversation
|
|
- Shows agent thinking/tools
|
|
- Message history
|
|
|
|
✅ **Real-time Updates:**
|
|
- Metrics auto-refresh (WebSocket)
|
|
- Activity log auto-updates
|
|
- Status changes reflected immediately
|
|
|
|
✅ **Integration:**
|
|
- Works with Phase 2 (messaging, runtime)
|
|
- Works with Phase 3 (LLM, memory, tools)
|
|
- Uses NATS for events
|
|
|
|
---
|
|
|
|
### 11. Implementation Steps
|
|
|
|
#### Week 1: Backend Foundation
|
|
1. Create `agents-service` (FastAPI)
|
|
2. Database schema + migrations
|
|
3. Basic CRUD endpoints
|
|
4. Mock agent blueprints
|
|
|
|
#### Week 2: Frontend Components
|
|
1. AgentGallery + AgentCard
|
|
2. AgentCabinet (layout + tabs)
|
|
3. AgentMetrics panel
|
|
4. AgentLogs stream
|
|
|
|
#### Week 3: Real-time & Integration
|
|
1. WebSocket for real-time updates
|
|
2. Direct chat integration
|
|
3. Configuration editor
|
|
4. NATS events
|
|
|
|
#### Week 4: Polish & Testing
|
|
1. UI polish (animations, UX)
|
|
2. Error handling
|
|
3. E2E testing
|
|
4. Documentation
|
|
|
|
---
|
|
|
|
### 12. Future Enhancements (Phase 3.5+)
|
|
|
|
🔜 **Agent creation wizard**
|
|
- GUI for creating new agents
|
|
- Template selection
|
|
- Tool assignment
|
|
|
|
🔜 **Agent analytics**
|
|
- Charts (messages over time)
|
|
- Cost tracking
|
|
- Performance insights
|
|
|
|
🔜 **Agent marketplace**
|
|
- Browse community agents
|
|
- Install/deploy agents
|
|
- Agent templates
|
|
|
|
🔜 **Multi-agent orchestration**
|
|
- Agent chains
|
|
- Workflow builder
|
|
- Agent collaboration
|
|
|
|
---
|
|
|
|
## Quick Start (After Implementation)
|
|
|
|
```bash
|
|
# Start agents-service
|
|
docker-compose -f docker-compose.agents.yml up -d
|
|
|
|
# Frontend dev
|
|
cd node-network-app
|
|
npm run dev
|
|
|
|
# Open
|
|
open http://localhost:8899/agents
|
|
```
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
**After implementation, create:**
|
|
- `/docs/AGENT_HUB_SPEC.md` — Full specification
|
|
- `/docs/AGENT_SERVICE_API.md` — API documentation
|
|
- `/services/agents-service/README.md` — Service setup
|
|
|
|
---
|
|
|
|
**Status:** 📋 Spec Ready
|
|
**Version:** 1.0.0
|
|
**Last Updated:** 2025-11-24
|
|
|
|
**READY TO BUILD!** 🚀
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|