Data Model

agents Table

The primary table for storing agent configurations.

CREATE TABLE agents (
  -- Identity
  id               BIGINT        PRIMARY KEY AUTO_INCREMENT,
  workspace_id     VARCHAR(255)  NOT NULL,
  created_by       VARCHAR(255)  NOT NULL,   -- user ID

  -- Core config
  name             VARCHAR(255)  NOT NULL,
  description      TEXT,
  status           VARCHAR(20)   NOT NULL DEFAULT 'draft',
                   -- draft | active | paused | error

  -- AI config
  system_prompt    TEXT          NOT NULL,
  suggested_query  TEXT,
  tools_allowed    JSON          NOT NULL,   -- string[]
  llm_model        VARCHAR(100)  DEFAULT 'deepseek-v4.1-flash',  -- the platform's single pinned model (LLM_MODEL)

  -- Scheduling
  schedule         VARCHAR(50),              -- cron expression or 'manual'
  schedule_label   VARCHAR(100),             -- human-readable label
  timezone         VARCHAR(50)   DEFAULT 'UTC',

  -- Alerting
  alert_condition  JSON,
  -- { metric: string, operator: 'gt'|'lt'|'eq', threshold: number }
  alert_channel    VARCHAR(500), -- Discord webhook URL

  -- Runtime stats
  run_count        INT           DEFAULT 0,
  success_count    INT           DEFAULT 0,
  last_run_at      TIMESTAMP,
  last_run_status  VARCHAR(20),  -- success | failed | timeout | running

  -- Timestamps
  created_at       TIMESTAMP     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at       TIMESTAMP     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Indexes
CREATE INDEX idx_agents_workspace ON agents(workspace_id);
CREATE INDEX idx_agents_status ON agents(status);
CREATE INDEX idx_agents_schedule ON agents(schedule) WHERE schedule != 'manual';

agent_execution_logs Table

Execution history for every agent run.

CREATE TABLE agent_execution_logs (
  -- Identity
  id              BIGINT       PRIMARY KEY AUTO_INCREMENT,
  agent_id        BIGINT       NOT NULL,
  workspace_id    VARCHAR(255) NOT NULL,

  -- Timing
  started_at      TIMESTAMP    NOT NULL,
  finished_at     TIMESTAMP,
  duration_ms     INT,

  -- Status
  status          VARCHAR(20)  NOT NULL,
                  -- success | failed | timeout | running

  -- Execution details
  tools_used      JSON,        -- string[] of tools actually called
  ai_response     TEXT,        -- full LLM final response
  tool_calls_json JSON,        -- detailed tool call log

  -- Alert
  alert_triggered BOOLEAN      DEFAULT FALSE,
  alert_value     FLOAT,       -- extracted metric value

  -- Error info
  error_message   TEXT,
  error_code      VARCHAR(50),

  -- Foreign key
  FOREIGN KEY (agent_id) REFERENCES agents(id) ON DELETE CASCADE
);

-- Indexes
CREATE INDEX idx_logs_agent ON agent_execution_logs(agent_id);
CREATE INDEX idx_logs_workspace ON agent_execution_logs(workspace_id);
CREATE INDEX idx_logs_started ON agent_execution_logs(started_at DESC);
CREATE INDEX idx_logs_status ON agent_execution_logs(status);

agents Table — Status Transitions

stateDiagram-v2
  [*] --> draft: Created (NLP or manual)
  draft --> active: User enables
  active --> paused: User pauses OR rate limited
  active --> error: Consecutive failures
  paused --> active: User re-enables
  error --> active: User re-enables
  active --> [*]: User deletes
  draft --> [*]: User deletes

TypeScript Types

// In Backend API
export interface Agent {
  id: number;
  workspaceId: string;
  createdBy: string;
  name: string;
  description?: string;
  status: 'draft' | 'active' | 'paused' | 'error';
  systemPrompt: string;
  suggestedQuery?: string;
  toolsAllowed: string[];
  llmModel: string;
  schedule?: string;
  scheduleLabel?: string;
  timezone: string;
  alertCondition?: AlertCondition;
  alertChannel?: string;
  runCount: number;
  successCount: number;
  lastRunAt?: Date;
  lastRunStatus?: 'success' | 'failed' | 'timeout';
  createdAt: Date;
  updatedAt: Date;
}

export interface AlertCondition {
  metric: string;
  operator: 'gt' | 'lt' | 'eq';
  threshold: number;
}

export interface AgentExecutionLog {
  id: number;
  agentId: number;
  workspaceId: string;
  startedAt: Date;
  finishedAt?: Date;
  durationMs?: number;
  status: 'success' | 'failed' | 'timeout' | 'running';
  toolsUsed?: string[];
  aiResponse?: string;
  alertTriggered: boolean;
  alertValue?: number;
  errorMessage?: string;
}

API Request/Response Types

// POST /api/v1/agents — Create agent
export interface CreateAgentRequest {
  name: string;
  description?: string;
  systemPrompt: string;
  toolsAllowed: string[];
  schedule?: string;
  alertCondition?: AlertCondition;
  alertChannel?: string;
}

// GET /api/v1/agents/:id/executions — Execution history
export interface ExecutionHistoryResponse {
  total: number;
  executions: AgentExecutionLog[];
  stats: {
    successRate: number;
    avgDurationMs: number;
    alertsTriggered: number;
  };
}