Agent Launcher Architecture Design

Executive Summary

This document outlines the design and implementation of an Agent Launcher system for MIZ OKI 3.5, enabling users to discover, configure, launch, and monitor autonomous AI agents through a frontend marketplace interface.

Problem Statement

Current State: - ✅ Chat interface (request-response model) - ✅ MCP Tools UI (individual tool execution) - ✅ MOA/MOE templates (pre-defined workflows) - ❌ No agent marketplace/discovery - ❌ No agent launching mechanism - ❌ No real-time agent monitoring - ❌ No agent lifecycle management

Desired State: - ✅ Browse available agents in a marketplace - ✅ View agent capabilities, requirements, and examples - ✅ Configure agent parameters before launch - ✅ Launch agents with custom configurations - ✅ Monitor running agents in real-time - ✅ View agent execution logs and outputs - ✅ Pause/resume/stop agents - ✅ View agent execution history

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Agent Launcher System                         │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────┐
│   Frontend Layer    │
├─────────────────────┤
│ Agent Marketplace   │ ← Browse/search agents
│ Agent Config UI     │ ← Configure parameters
│ Agent Dashboard     │ ← Monitor running agents
│ Agent Details       │ ← View agent info
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   API Gateway       │
├─────────────────────┤
│ /api/agents/*       │ ← Agent CRUD endpoints
└──────────┬──────────┘
           │
           ▼
┌──────────────────────────────────────────────────────────────┐
│                    Backend Services                           │
├──────────────────────────────────────────────────────────────┤
│                                                                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │ Agent Registry  │  │ Agent Executor  │  │   Agent      │ │
│  │                 │  │                 │  │  Monitoring  │ │
│  │ - Metadata DB   │  │ - Launch queue  │  │ - Status API │ │
│  │ - Discovery API │  │ - Session mgmt  │  │ - Logs API   │ │
│  │ - Search        │  │ - Orchestrator  │  │ - Metrics    │ │
│  └────────┬────────┘  └────────┬────────┘  └──────┬───────┘ │
│           │                    │                   │         │
│           └────────────────────┼───────────────────┘         │
│                                │                             │
└────────────────────────────────┼─────────────────────────────┘
                                 │
                                 ▼
┌──────────────────────────────────────────────────────────────┐
│                    Agent Instances                            │
├──────────────────────────────────────────────────────────────┤
│  - SRPVDAL Agents (Cell 3, 7, 11, 15, 19, 24, 27)              │
│  - MOA/MOE Orchestrators                                      │
│  - Specialist Agents (Budget, Performance, Creative, etc.)    │
│  - Coding MOA (5 specialist agents)                          │
│  - Custom User Agents (future)                               │
└──────────────────────────────────────────────────────────────┘

Core Components

1. Agent Registry Service

Purpose: Central repository of available agents with metadata

Data Model:

interface Agent {
  id: string;                    // Unique identifier
  name: string;                  // Display name
  description: string;           // What the agent does
  category: AgentCategory;       // Marketing, Analytics, Development, etc.
  version: string;               // Semantic version
  status: 'active' | 'beta' | 'deprecated';

  // Capabilities
  capabilities: {
    srpvdal_stages: string[];      // SENSE, REASON, DECIDE, ACT, LEARN
    tools: string[];             // MCP tools this agent can use
    models: string[];            // AI models (Claude, Gemini, GPT-4, etc.)
    specializations: string[];   // Budget optimization, causal analysis, etc.
  };

  // Configuration
  parameters: AgentParameter[];  // Required/optional parameters
  defaults: Record<string, any>; // Default parameter values

  // Execution
  endpoint: string;              // API endpoint to launch agent
  execution_mode: 'sync' | 'async' | 'streaming';
  timeout_seconds: number;       // Max execution time

  // Metadata
  created_at: string;
  updated_at: string;
  created_by: string;
  tags: string[];
  icon: string;                  // Icon URL or emoji

  // Usage stats
  stats: {
    total_launches: number;
    successful_runs: number;
    avg_execution_time_seconds: number;
    last_launched_at: string;
  };

  // Documentation
  documentation_url: string;
  examples: AgentExample[];
}

interface AgentParameter {
  name: string;
  type: 'string' | 'number' | 'boolean' | 'array' | 'object';
  required: boolean;
  description: string;
  default?: any;
  validation?: {
    min?: number;
    max?: number;
    pattern?: string;
    enum?: any[];
  };
}

interface AgentExample {
  title: string;
  description: string;
  parameters: Record<string, any>;
  expected_output: string;
}

enum AgentCategory {
  MARKETING = 'marketing',
  ANALYTICS = 'analytics',
  DEVELOPMENT = 'development',
  OPERATIONS = 'operations',
  CUSTOMER_SUCCESS = 'customer_success',
  FINANCE = 'finance',
  GENERAL = 'general'
}

API Endpoints:

// List all agents
GET /api/agents
  ?category=marketing
  &status=active
  &search=budget
  &tags=optimization,causal

// Get agent details
GET /api/agents/:agentId

// Get agent examples
GET /api/agents/:agentId/examples

// Get agent documentation
GET /api/agents/:agentId/docs

// Search agents
GET /api/agents/search?q=budget+allocation

// Get agent stats
GET /api/agents/:agentId/stats

2. Agent Execution Service

Purpose: Launch and manage agent execution sessions

Data Model:

interface AgentSession {
  session_id: string;
  agent_id: string;
  user_id: string;

  // Configuration
  parameters: Record<string, any>;

  // Status
  status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
  progress: number;              // 0-100
  current_stage: string;         // Current SRPVDAL stage

  // Execution
  started_at: string;
  completed_at?: string;
  duration_seconds?: number;

  // Results
  output?: any;
  error?: string;
  logs: AgentLog[];

  // Metadata
  created_at: string;
  updated_at: string;
}

interface AgentLog {
  timestamp: string;
  level: 'debug' | 'info' | 'warning' | 'error';
  message: string;
  stage?: string;
  metadata?: Record<string, any>;
}

API Endpoints:

// Launch agent
POST /api/agents/:agentId/launch
Body: {
  parameters: {
    campaign_id: "campaign_123",
    optimization_goal: "maximize_roas",
    constraints: {...}
  }
}
Response: {
  session_id: "session_abc123",
  status: "queued"
}

// Get session status
GET /api/agents/sessions/:sessionId

// Get session logs (streaming)
GET /api/agents/sessions/:sessionId/logs
  ?follow=true  // Stream new logs as they arrive

// Cancel session
POST /api/agents/sessions/:sessionId/cancel

// Get user's sessions
GET /api/agents/sessions
  ?user_id=user_123
  &status=running
  &limit=20

3. Agent Monitoring Service

Purpose: Real-time monitoring and observability

Features: - Live status updates via Server-Sent Events (SSE) - Execution metrics (latency, throughput, error rate) - Agent health checks - Resource usage tracking

API Endpoints:

// Stream real-time updates for a session
GET /api/agents/sessions/:sessionId/stream
Event-Stream:
  - status_update: { status, progress, current_stage }
  - log_entry: { timestamp, level, message }
  - stage_complete: { stage, duration_ms }
  - output_ready: { output }
  - error: { error }

// Get session metrics
GET /api/agents/sessions/:sessionId/metrics

// Get global agent metrics
GET /api/agents/metrics
  ?agent_id=agent_123
  &timeframe=24h

Frontend Components

1. Agent Marketplace (`/agents`)

Features: - Grid/list view of available agents - Category filters (Marketing, Analytics, etc.) - Search with autocomplete - Agent cards with: - Icon, name, description - Category badge - Status badge (Active/Beta/Deprecated) - Launch count - Average execution time - Quick launch button

Wireframe:

┌─────────────────────────────────────────────────────────┐
│  Agent Marketplace                          [Search...] │
├─────────────────────────────────────────────────────────┤
│  Filters: [All] [Marketing] [Analytics] [Development]  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ 📊           │  │ 💰          │  │ 🎨           │ │
│  │ Budget       │  │ Performance │  │ Creative     │ │
│  │ Allocator    │  │ Analyzer    │  │ Generator    │ │
│  │              │  │             │  │              │ │
│  │ Optimizes... │  │ Analyzes... │  │ Generates... │ │
│  │              │  │             │  │              │ │
│  │ 1,234 runs   │  │ 567 runs    │  │ 890 runs     │ │
│  │ [Launch] [+] │  │ [Launch] [+]│  │ [Launch] [+] │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│                                                         │
└─────────────────────────────────────────────────────────┘

Features: - Dynamic form based on agent's parameters schema - Input validation - Parameter descriptions with tooltips - Example values - Preview of configuration - Launch button

Wireframe:

┌─────────────────────────────────────────────────────────┐
│  Launch Agent: Budget Allocator                    [X]  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Campaign ID *                                          │
│  [campaign_123_______________]                          │
│  📝 The campaign to optimize                            │
│                                                         │
│  Optimization Goal *                                    │
│  [⌄ Maximize ROAS ▼]                                   │
│                                                         │
│  Budget Constraint                                      │
│  [$_10000____________]                                  │
│                                                         │
│  Time Horizon                                           │
│  [⌄ 30 days ▼]                                         │
│                                                         │
│  Advanced Options  [▼]                                  │
│                                                         │
├─────────────────────────────────────────────────────────┤
│                               [Cancel]  [🚀 Launch]     │
└─────────────────────────────────────────────────────────┘

3. Agent Dashboard (`/agents/sessions`)

Features: - List of user's agent sessions - Status badges (Running/Completed/Failed) - Progress bars for running agents - Live log streaming - Action buttons (View, Cancel, Re-run)

Wireframe:

┌─────────────────────────────────────────────────────────────────┐
│  My Agent Sessions                    [All] [Running] [Recent]  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  🔄 Budget Allocator - campaign_123              [View Details] │
│     Running for 2m 34s                                          │
│     Current: DECIDE stage                                       │
│     [████████████████░░░░░░░░] 75%                             │
│     Started: 2025-11-04 10:23 AM                               │
│                                                                 │
│  ✅ Performance Analyzer - last_30_days          [View Results] │
│     Completed in 1m 12s                                         │
│     Output: 47 insights, 12 recommendations                     │
│     Finished: 2025-11-04 09:45 AM                              │
│                                                                 │
│  ❌ Creative Generator - holiday_campaign        [View Logs]    │
│     Failed after 45s                                            │
│     Error: Insufficient budget for image generation             │
│     Failed: 2025-11-03 04:12 PM                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

4. Agent Execution Detail View (`/agents/sessions/:id`)

Features: - Real-time status and progress - Live log streaming - Stage-by-stage execution timeline - Output/results display - Execution metrics - Re-run with same config button

Wireframe:

┌─────────────────────────────────────────────────────────────────┐
│  ← Back to Sessions                                             │
│  Budget Allocator - Session abc123                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Status: 🔄 Running                   Progress: 75%             │
│  Duration: 2m 34s                     Stage: DECIDE             │
│                                                                 │
│  ┌─ Execution Timeline ──────────────────────────────────────┐ │
│  │  ✅ SENSE     [██████] 12s                                 │ │
│  │  ✅ REASON    [██████] 45s                                 │ │
│  │  🔄 DECIDE    [████░░] 67s (in progress)                   │ │
│  │  ⏳ ACT       [░░░░░░]                                     │ │
│  │  ⏳ LEARN     [░░░░░░]                                     │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌─ Live Logs ────────────────────────────────────────────────┐ │
│  │  [INFO ] 10:23:45 - Analyzing campaign performance...     │ │
│  │  [INFO ] 10:24:12 - Fetched 1,234 data points             │ │
│  │  [INFO ] 10:25:30 - Running causal inference...           │ │
│  │  [DEBUG] 10:25:45 - Cell 7 responded in 234ms             │ │
│  │  [INFO ] 10:26:12 - Optimization in progress...           │ │
│  │  ▌ (live)                                                  │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌─ Configuration ────────────────────────────────────────────┐ │
│  │  Campaign ID: campaign_123                                 │ │
│  │  Goal: Maximize ROAS                                       │ │
│  │  Budget: $10,000                                           │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  [⏸️ Pause]  [⛔ Cancel]  [🔄 Re-run]                          │
└─────────────────────────────────────────────────────────────────┘

Implementation Plan

Phase 1: Backend Foundation (Week 1)

Agent Registry Service - Create BigQuery tables for agent metadata - Implement Agent Registry API endpoints - Seed database with existing agents (SRPVDAL cells, MOA/MOE, specialists) - Create admin UI for agent management
Agent Execution Service - Create BigQuery tables for agent sessions - Implement session management - Create launch queue with Pub/Sub - Implement session API endpoints
Integration with Existing Services - Connect to Boss Agent ADK for SRPVDAL agents - Connect to MOA/MOE controllers - Connect to specialist agents - Connect to Coding MOA

Phase 2: Frontend Marketplace (Week 2)

Agent Marketplace UI - Build agent card component - Implement grid/list view - Add search and filters - Create category navigation
Agent Configuration Modal - Build dynamic form generator - Implement parameter validation - Add examples and documentation links - Create launch confirmation
Agent Dashboard - Build session list view - Implement status badges and progress bars - Add action buttons (view, cancel, re-run) - Create pagination and filtering

Phase 3: Monitoring & Details (Week 3)

Real-Time Monitoring - Implement SSE for live updates - Create log streaming - Add stage-by-stage timeline - Show execution metrics
Agent Execution Detail View - Build detail page layout - Implement live log viewer - Add execution timeline visualization - Display output/results
Agent Management - Pause/resume functionality - Cancel functionality - Re-run with same config - Export results

Phase 4: Advanced Features (Week 4)

Agent Chains - Link multiple agents in sequence - Pass output from one agent to another - Create reusable workflows
Agent Scheduling - Schedule agents to run at specific times - Recurring agent execution - Cron-like syntax
Agent Marketplace Enhancements - Agent ratings and reviews - Usage analytics - Cost estimation - Performance benchmarks

Technology Stack

Backend

Language: Python (FastAPI)
Database: BigQuery (agent metadata, sessions, logs)
Queue: Cloud Pub/Sub (launch queue, async execution)
Cache: Redis (session state, real-time updates)
Deployment: Cloud Run

Frontend

Framework: Next.js 14 (App Router)
UI: Tailwind CSS + shadcn/ui components
State: Zustand (existing store)
Real-time: Server-Sent Events (SSE)
Deployment: Cloud Run

Integration

A2A Gateway: WebSocket for bidirectional communication
Boss Agent ADK: SRPVDAL orchestration
MOA/MOE: Mixture of Agents/Experts
Coding MOA: Specialized coding agents
MCP Tools: 14 tools from Boss Agent MCP

Security Considerations

Authentication: IAM-based authentication for API endpoints
Authorization: User-level permissions for agent access
Rate Limiting: Prevent abuse (max 10 concurrent sessions per user)
Input Validation: Validate all agent parameters
Output Sanitization: Sanitize agent outputs before display
Audit Logging: Track all agent launches and actions

Success Metrics

Adoption: Number of agents launched per day
Engagement: Average sessions per user per week
Success Rate: % of successful agent executions
Performance: Average agent execution time
User Satisfaction: NPS score for agent launcher feature

Migration Path

Existing Features → Agent Launcher

Chat Interface → Agent: "Conversational Assistant" - Type: General - Mode: Streaming - Tools: All MCP tools
MCP Tools → Individual tool agents - Each tool becomes a standalone agent - Parameters map to agent configuration
MOA/MOE Templates → Multi-agent workflows - Each template becomes a composite agent - Sub-agents are linked in sequence/parallel
SRPVDAL Cells → Specialized agents - Cell 3: Knowledge Graph Agent - Cell 7: Causal Inference Agent - Cell 11: Attribution Agent - Cell 15: Campaign Executor - Cell 19: Learning Agent - Cell 24: Graph Updater - Cell 27: Uplift Analyzer

Documentation

Agent Developer Guide: How to create and register new agents
Agent User Guide: How to discover, configure, and launch agents
API Reference: Complete API documentation
Examples: 10+ real-world agent configurations

Next Steps

✅ Review and approve architecture design
⏳ Create BigQuery schema for agent registry
⏳ Implement Agent Registry Service (Python/FastAPI)
⏳ Seed database with existing agents
⏳ Implement Agent Execution Service
⏳ Build frontend Agent Marketplace UI
⏳ Test end-to-end agent launching workflow
⏳ Deploy to production

Created: 2025-11-04 Version: 1.0 Status: Design Phase

Agent Launcher Architecture Design

Executive Summary

Problem Statement

System Architecture

Core Components

1. Agent Registry Service

2. Agent Execution Service

3. Agent Monitoring Service

Frontend Components

1. Agent Marketplace (/agents)

2. Agent Configuration Modal

3. Agent Dashboard (/agents/sessions)

4. Agent Execution Detail View (/agents/sessions/:id)

Implementation Plan

Phase 1: Backend Foundation (Week 1)

Phase 2: Frontend Marketplace (Week 2)

Phase 3: Monitoring & Details (Week 3)

Phase 4: Advanced Features (Week 4)

Technology Stack

Backend

Frontend

Integration

Security Considerations

Success Metrics

Migration Path

Existing Features → Agent Launcher

Documentation

Next Steps

1. Agent Marketplace (`/agents`)

3. Agent Dashboard (`/agents/sessions`)

4. Agent Execution Detail View (`/agents/sessions/:id`)