microdao-daarion/docs/tasks/AGENT_HUB_UI_TASK.md

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:

{
  "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:

{
  "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:

{
  "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):

{
  "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:

{
  "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:

{
  "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:

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:

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:

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)

# 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! 🚀