AI Agents Architecture

System Architecture

graph TB
  subgraph Frontend["Frontend :3000"]
    AB[AgentBuilder UI\n/agents/new]
    AL[Agent List\n/agents]
    AD[Agent Detail\n/agents/:id]
    TB[Tool Browser]
  end

  subgraph Backend["Backend :8080"]
    AGAPI[Agent API\n/api/v1/agents]
    EXAPI[Execution API\n/api/v1/agents/:id/executions]
    DB[(Agents DB\nPostgres/H2)]
  end

  subgraph AIService["AI Service :9300"]
    CE[ChatEngine]
    AGLP[AgentLoop]
    PARSE[/agent-builder/parse\nNEW endpoint]
    TE[ToolExecutor]
  end

  subgraph AgentRunner["Agent Runner :9400 NEW"]
    SCHED[Scheduler\ncron-based]
    EXEC[Executor]
    LOG[Result Logger]
    ALERT[Alert Engine]
  end

  subgraph Tools["Tool Layer"]
    SEM[semantic_search]
    OSQ[opensearch_query]
    BKND[backend_api]
    ANA[analyze_logs]
    REG[Tool Registry\nregistry.ts]
  end

  AB -->|NLP text| PARSE
  PARSE -->|structured JSON| AB
  AB -->|confirm| AGAPI
  AGAPI --> DB
  AL --> AGAPI
  AD --> AGAPI
  AD --> EXAPI

  AgentRunner -->|poll agents| AGAPI
  SCHED -->|on schedule| EXEC
  EXEC -->|POST /chat/sync| AIService
  EXEC --> LOG
  LOG --> EXAPI
  ALERT -->|Discord webhook| DC[Discord]

  AIService --> REG
  REG --> SEM
  REG --> OSQ
  REG --> BKND
  REG --> ANA

Component Breakdown

Frontend Components (New/Extended)

Component	Route	Purpose
AgentBuilder	/agents/new	NLP-based agent creation flow
AgentList	/agents	Table of all workspace agents
AgentDetail	/agents/:id	Config + execution history
ToolBrowser	(modal)	Browse available tools by category
Metrics row	(in AgentDetail)	Success rate, last run, avg duration

Backend Extensions (Existing Service)

New DB table: agents (extended with 12 new columns):

CREATE TABLE agents (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  workspace_id VARCHAR(255) NOT NULL,
  name VARCHAR(255) NOT NULL,
  description TEXT,
  system_prompt TEXT,
  tools_allowed JSON,           -- ["semantic_search", "opensearch_query"]
  schedule VARCHAR(50),         -- cron expression or "manual"
  status VARCHAR(20),           -- active, paused, draft
  alert_condition JSON,         -- {metric, operator, threshold}
  alert_channel VARCHAR(255),   -- discord webhook URL
  created_by VARCHAR(255),
  created_at TIMESTAMP,
  updated_at TIMESTAMP,
  last_run_at TIMESTAMP,
  last_run_status VARCHAR(20),  -- success, failed, running
  run_count INT DEFAULT 0,
  success_count INT DEFAULT 0
);

New DB table: agent_execution_logs:

CREATE TABLE agent_execution_logs (
  id BIGINT PRIMARY KEY AUTO_INCREMENT,
  agent_id BIGINT NOT NULL,
  workspace_id VARCHAR(255) NOT NULL,
  started_at TIMESTAMP,
  finished_at TIMESTAMP,
  status VARCHAR(20),           -- success, failed, timeout
  duration_ms INT,
  tools_used JSON,              -- list of tools actually called
  ai_response TEXT,             -- full LLM response
  alert_triggered BOOLEAN,
  alert_value FLOAT,
  error_message TEXT,
  FOREIGN KEY (agent_id) REFERENCES agents(id)
);

New API endpoints on Backend:

Method	Path	Description
GET	/api/v1/agents	List workspace agents
POST	/api/v1/agents	Create agent
GET	/api/v1/agents/:id	Get agent details
PUT	/api/v1/agents/:id	Update agent config
DELETE	/api/v1/agents/:id	Delete agent
GET	/api/v1/agents/:id/executions	Execution history
POST	/api/v1/agents/:id/trigger	Manual trigger

AI Service Extensions (Existing Service)

New endpoint: POST /api/v1/agent-builder/parse

Accepts a natural language description and returns a structured agent config:

// Request
{
  "description": "Monitor payment errors and alert me if error rate exceeds 5%"
}

// Response
{
  "name": "Payment Error Monitor",
  "description": "Monitors payment error rates and alerts on threshold breach",
  "systemPrompt": "You are a monitoring agent for payment errors...",
  "toolsAllowed": ["semantic_search", "opensearch_query"],
  "schedule": "0 * * * *",    // hourly
  "scheduleLabel": "Every hour",
  "alertCondition": {
    "metric": "error_rate",
    "operator": "gt",
    "threshold": 5.0
  },
  "suggestedQuery": "Check payment error rate in the last hour"
}

AgentLoop extension — toolsAllowed filter:

// Existing AgentLoop accepts all tools
const loop = new AgentLoop(tools);

// Extended: filter to agent's allowed tools
const loop = new AgentLoop(tools, { toolsAllowed: agent.toolsAllowed });

Tool Registry (New File)

New file: src/tools/registry.ts

export const TOOL_REGISTRY = {
  semantic_search: {
    category: 'read_only',
    permissionLevel: 'basic',
    description: 'Search logs using natural language',
    handler: semanticSearchTool
  },
  opensearch_query: {
    category: 'read_only',
    permissionLevel: 'standard',
    description: 'Execute OpenSearch queries and aggregations',
    handler: opensearchQueryTool
  },
  get_scan_results: {
    category: 'read_only',
    permissionLevel: 'standard',
    description: 'Read compliance scan results',
    handler: getScanResultsTool
  },
  analyze_logs: {
    category: 'read_only',
    permissionLevel: 'standard',
    description: 'AI-powered log analysis',
    handler: analyzeLogsTool
  }
  // write, external, admin categories: planned Phase 3+
};