> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quinnsambal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ai agent history

<style>
  {`
    [class*="max-w-none"][class*="table"] {
      display: block !important;
      overflow-x: auto !important;
      max-width: 100% !important;
      width: 100% !important;
      flex-grow: 0 !important;
    }
    [class*="max-w-none"][class*="table"] > table {
      width: 100% !important;
      max-width: 100% !important;
      table-layout: fixed !important;
    }
    .mermaid {
      max-width: 100% !important;
      overflow-x: auto !important;
    }
    article svg[role="img"] {
      max-width: 100% !important;
      height: auto !important;
    }
    article img, .prose img {
      max-width: 100% !important;
      height: auto !important;
    }
    img[src*="LOGO"], img[src*="logo"] {
      max-width: 120px !important;
      max-height: 40px !important;
      width: auto !important;
      height: auto !important;
      object-fit: contain !important;
    }
    `}
</style>

***

title: "AI Agent History"
description: "Riwayat eksekusi agen AI dengan cost analytics, date grouping, date filter, payment filter, dan export data."
---------------------------------------------------------------------------------------------------------------------------

# AI Agent History

<img src="https://mintcdn.com/quinnofspicy/e4f_upKhVWcjsUmM/docs/mintlify/screenshots/ai/ai-agent-history.png?fit=max&auto=format&n=e4f_upKhVWcjsUmM&q=85&s=99e2b23fd483d0051883b30466e39e9c" alt="AI Agent History" width="1920" height="1080" data-path="docs/mintlify/screenshots/ai/ai-agent-history.png" />

Halaman AI Agent History mencatat semua eksekusi yang pernah dilakukan oleh setiap agen. Halaman ini penting untuk audit biaya, evaluasi performa, dan mengidentifikasi pola error yang muncul berulang.

## Arsitektur Halaman

```mermaid theme={null}
graph TD
    A[AIAgentHistory.jsx<br/>477 baris] --> B[Load AIAgentRun.list]
    B --> C[Compute Stats]
    C --> D[Stats Bar — 4 Kartu]
    C --> E[Date Groups]
    C --> F[Payment Filter]
    
    D --> D1[Total Runs]
    D --> D2[Total Cost]
    D --> D3[Total Credits]
    D --> D4[Unique Agents]
    
    E --> E1[Hari Ini]
    E --> E2[Kemarin]
    E --> E3[7 Hari Terakhir]
    E --> E4[30 Hari Terakhir]
    E --> E5[Lebih Lama]
    
    F --> F1[balance]
    F --> F2[credit]
    F --> F3[free]
```

## Data Pipeline

```mermaid theme={null}
flowchart LR
    subgraph "Source"
        DB[(AIAgentRun)] --> Fetch[Fetch all runs]
    end

    subgraph "Transform"
        Fetch --> Group[Group by date bucket]
        Fetch --> Aggregate[Compute stats]
        Fetch --> Filter[Apply payment filter]
    end

    subgraph "Display"
        Group --> Sections[Date Sections]
        Aggregate --> Stats[Stats Bar Cards]
        Filter --> List[Filtered Run List]
    end
```

## Stats Bar — 4 Kartu

| Kartu | Perhitungan | Format |
| - | - | - |
| **Total Runs** | `count(AIAgentRun)` | Angka absolut |
| **Total Cost** | `sum(cost_amount)` | Rupiah (Rp XX.XXX) |
| **Total Credits** | `sum(cost_credit)` | Angka absolut |
| **Unique Agents** | `count(distinct agent_key)` | Angka absolut |

### Stats Computation Flow

```mermaid theme={null}
flowchart TD
    A[All AIAgentRun records] --> B{Payment filter active?}
    B -->|Yes| C[Filter by payment_method]
    B -->|No| D[Use all records]
    C --> E[Compute stats]
    D --> E
    
    E --> F[COUNT(*) → Total Runs]
    E --> G[SUM cost_amount → Total Cost]
    E --> H[SUM cost_credit → Total Credits]
    E --> I[COUNT DISTINCT agent_key → Unique Agents]
    
    F & G & H & I --> J[Render Stats Cards]
```

## Date Grouping

Run dikelompokkan berdasarkan waktu eksekusi:

| Group | Aturan | Contoh |
| - | - | - |
| **Hari Ini** | `created_at` = hari ini | 2026-10-10 |
| **Kemarin** | `created_at` = hari sebelumnya | 2026-10-09 |
| **7 Hari Terakhir** | 2-7 hari lalu | 2026-10-03 s/d 2026-10-08 |
| **30 Hari Terakhir** | 8-30 hari lalu | 2026-09-10 s/d 2026-10-02 |
| **Lebih Lama** | >30 hari lalu | \< 2026-09-10 |

Setiap group ditampilkan sebagai section terpisah dengan header dan jumlah run.

### Date Grouping Algorithm

```mermaid theme={null}
flowchart TD
    A[AIAgentRun.created_at] --> B[Parse to Date]
    B --> C{Compare with today}
    C -->|Same date| D[Group: Hari Ini]
    C -->|Yesterday| E[Group: Kemarin]
    C -->|2-7 days ago| F[Group: 7 Hari Terakhir]
    C -->|8-30 days ago| G[Group: 30 Hari Terakhir]
    C -->|>30 days ago| H[Group: Lebih Lama]
    
    D & E & F & G & H --> I[Sort by created_at DESC within group]
    I --> J[Render sections]
```

## Payment Filter

Filter berdasarkan metode pembayaran:

| Metode | Deskripsi | Badge Color |
| - | - | - |
| **balance** | Dibayar dari saldo perusahaan | Blue |
| **credit** | Dibayar dari kredit AI bulanan | Purple |
| **free** | Gratis (dalam kuota atau promo) | Green |

## Detail per Run

Setiap record run menampilkan:

| Kolom | Detail |
| - | - |
| **Agent** | Nama agen (`agent_name`) |
| **User** | Email user (`user_email`) |
| **Status** | `success` (hijau) / `failed` (merah) |
| **Waktu** | Timestamp eksekusi (WIB) |
| **Biaya** | `cost_amount` dalam Rupiah |
| **Kredit** | `cost_credit` |
| **Metode** | `payment_method` badge |
| **Input** | Preview `input_data` |
| **Output** | Expandable — parsed output |

## Cost Analytics

### Distribusi Biaya per Agen

```mermaid theme={null}
pie title Distribusi Biaya AI
    "Business Analysis" : 35
    "Content Generator" : 25
    "Sales Forecaster" : 20
    "Customer Analyzer" : 12
    "Custom Agents" : 8
```

### Cost Breakdown by Model Tier

| Model Tier | Multiplier | Avg Cost/Run | Usage % |
| - | - | - | - |
| **Standard** (hermes-3-llama-3) | 1.0x | Rp 1.000 | 60% |
| **Advanced** (claude-3-5-sonnet, gpt-4o) | 1.5x | Rp 1.500 | 30% |
| **Premium** (gemini-1-5-pro) | 3.0x | Rp 3.000 | 10% |

### Tren Penggunaan

Data history bisa dianalisis untuk:

* Identifikasi agen dengan ROI tertinggi
* Deteksi lonjakan penggunaan yang tidak wajar
* Perencanaan anggaran kredit bulanan
* Evaluasi apakah model yang lebih murah cukup untuk tugas tertentu

### Cost Trend Analysis

```mermaid theme={null}
flowchart LR
    subgraph "Input"
        H[AIAgentRun history]
    end

    subgraph "Analysis"
        H --> A1[Daily cost aggregation]
        H --> A2[Per-agent cost breakdown]
        H --> A3[Model tier distribution]
        H --> A4[Payment method split]
    end

    subgraph "Insights"
        A1 --> I1[Cost trend line]
        A2 --> I2[Top expensive agents]
        A3 --> I3[Model optimization opportunities]
        A4 --> I4[Budget vs actual]
    end
```

## Error Pattern Detection

Mengidentifikasi pola error dari history:

```mermaid theme={null}
flowchart TD
    A[Failed Runs] --> B{Group by agent_key}
    B --> C{Count failures}
    C --> |1-2| D[Random Error<br/>— mungkin transient]
    C --> |3-5| E[Pattern Emerging<br/>— perlu investigasi]
    C --> |>5| F[Systematic Error<br/>— segera perbaiki]
    
    F --> G[Check system_prompt]
    F --> H[Check input_fields]
    F --> I[Check model compatibility]
```

### Error Resolution Playbook

| Error Pattern | Likely Cause | Resolution |
| - | - | - |
| **Same agent, same error** | Bad system prompt | Review and update prompt |
| **Same agent, different errors** | Input validation issue | Add input field constraints |
| **Multiple agents, same error** | Model API issue | Check model provider status |
| **Intermittent failures** | Timeout / rate limit | Increase timeout or add retry |
| **New agent failures** | Configuration error | Compare with working agent config |

## Entity: AIAgentRun

| Field | Tipe | Detail |
| - | - | - |
| `user_id` | string | ID user yang menjalankan |
| `user_email` | string | Email user |
| `company_id` | string | ID perusahaan aktif |
| `agent_key` | string | Key agen yang dijalankan |
| `agent_name` | string | Nama agen |
| `input_data` | object | Input yang diberikan user |
| `output` | string | Hasil output (max 100.000 karakter) |
| `cost_amount` | number | Biaya Rupiah (default: 0) |
| `cost_credit` | number | Kredit terpakai (default: 0) |
| `payment_method` | enum | `balance`, `credit`, `free` |
| `status` | enum | `success`, `failed` |
| `created_at` | timestamp | Waktu eksekusi |
| `model` | string | Model yang digunakan |
| `duration_ms` | number | Durasi eksekusi dalam milidetik |

## Export Data

### Export Formats

| Format | Library | Use Case |
| - | - | - |
| **CSV** | Built-in | Spreadsheet analysis |
| **JSON** | Built-in | API integration |
| **PDF** | jsPDF | Audit report |
| **Excel** | xlsx | Financial reporting |

### Export Flow

```mermaid theme={null}
flowchart LR
    A[Click Export] --> B{Select format}
    B -->|CSV| C[Generate CSV]
    B -->|JSON| D[Generate JSON]
    B -->|PDF| E[Generate PDF report]
    B -->|Excel| F[Generate XLSX]
    
    C & D & E & F --> G[Download file]
```

## Cara Akses

Dari sidebar, klik menu **AI & Analitik** > **Agent History**.

## Flow Penggunaan

```mermaid theme={null}
flowchart TD
    A[Buka halaman Agent History] --> B[Lihat 4 kartu statistik]
    B --> C[Review daftar run per tanggal]
    C --> D{Perlu filter?}
    D -->|Ya| E[Apply payment filter]
    D -->|Tidak| F[Lanjut review]
    E --> F
    F --> G{Ada anomali?}
    G -->|Ya| H[Klik run → Detail output]
    G -->|Tidak| I[Export jika perlu]
    H --> J[Investigasi error]
    I --> K[Selesai]
    J --> K
```

## Tips

* Cek history secara berkala untuk mendeteksi anomali biaya sedini mungkin
* Jika ada error berulang (>3 kali), segera investigasi dan perbaiki konfigurasi
* Bandingkan biaya agen template vs custom untuk optimasi
* Gunakan data history untuk negosiasi kuota AI dengan tim manajemen
* Export data bulanan untuk audit keuangan

***

## Entity Relationship Diagram — Agent History

```mermaid theme={null}
erDiagram
    AIAgent ||--o{ AIAgentRun : "dieksekusi menghasilkan"
    AIAgent }o--o| AIAgentTemplate : "dibuat dari template"
    AIAgent ||--o{ AIAgentSchedule : "dijadwalkan oleh"
    AIAgentRun }o--|| AIAgentModel : "menggunakan model"
    AIAgentRun }o--|| AIAgentSettings : "mengacu pengaturan biaya"
    AIAgentSchedule }o--|| AIAgent : "trigger untuk"
    Conversation ||--o{ ConversationMessage : "berisi pesan"
    Conversation }o--|| AIAgent : "percakapan dengan agen"
    AILearningData }o--|| AIAgent : "pembelajaran dari koreksi"

    AIAgent {
        string agent_key PK "Kunci unik agen"
        string company_id FK "ID perusahaan"
        string created_by "Email pembuat"
        string name "Nama agen"
        string tagline "Deskripsi singkat"
        string description "Penjelasan lengkap (max 2000)"
        string category "Kategori: business|content|writing|social|other"
        string icon "Nama icon lucide-react"
        string color "Kode warna hex"
        string system_prompt "Instruksi sistem LLM (max 4000)"
        array input_fields "Field input dinamis"
        string model "Model LLM default"
        boolean use_internet "Gunakan konteks internet"
        string status "Status: active|paused|inactive"
        string source_template_key FK "Link ke template asal"
        number run_count "Total eksekusi"
        number total_cost_amount "Total biaya Rupiah"
        number total_cost_credit "Total kredit terpakai"
        datetime created_date "Waktu pembuatan"
        datetime updated_date "Waktu pembaruan terakhir"
    }

    AIAgentRun {
        string user_id FK "ID user yang menjalankan"
        string user_email "Email user"
        string company_id FK "ID perusahaan aktif"
        string company_name "Nama perusahaan saat run"
        string agent_key FK "Kunci agen yang dijalankan"
        string agent_name "Nama agen saat run"
        string model_used "Model AI yang dipakai"
        string model_name "Nama tampilan model"
        object input_data "Input dari user"
        string output "Hasil AI (max 100.000 karakter)"
        number cost_amount "Biaya Rupiah yang dipotong"
        number cost_credit "Kredit yang dipotong"
        string payment_method "Metode: balance|credit|free"
        string status "Status: success|failed"
        datetime created_at "Waktu eksekusi"
    }

    AIAgentModel {
        string model_key PK "Kunci model untuk InvokeLLM"
        string name "Nama tampilan model"
        string description "Penjelasan kualitas/kecepatan (max 500)"
        number price_multiplier "Pengali biaya (default: 1)"
        string tier "Tingkatan: standard|advanced|premium"
        boolean supports_internet "Mendukung konteks internet"
        boolean is_active "Status aktif model"
        number order "Urutan pengurutan"
    }

    AIAgentTemplate {
        string agent_key PK "Kunci unik template"
        string name "Nama agen template"
        string tagline "Deskripsi singkat"
        string description "Penjelasan lengkap (max 2000)"
        string category "Kategori: business|content|writing|social|other"
        string icon "Nama icon lucide-react"
        string color "Kode warna hex"
        number price_per_run "Biaya per run dalam Rupiah"
        number credit_cost "Biaya alternatif dalam kredit"
        array features "Daftar fitur utama"
        array use_cases "Daftar kasus penggunaan"
        array input_fields "Field input untuk user"
        string system_prompt "Instruksi sistem LLM (max 4000)"
        string model "Model LLM default"
        boolean use_internet "Gunakan konteks internet"
        string status "Status: active|coming_soon|inactive"
        number order "Urutan pengurutan"
    }

    AIAgentSettings {
        string setting_key PK "Kunci pengaturan (default: global)"
        string description "Catatan pengaturan (max 1000)"
        number credit_to_rupiah_rate "Nilai 1 kredit dalam Rupiah (default: 10)"
        number base_price_per_run "Harga dasar per run (default: 1000)"
        boolean allow_credit_payment "Izinkan pembayaran kredit"
        boolean allow_balance_payment "Izinkan pembayaran saldo"
    }

    AIAgentSchedule {
        string agent_id FK "Referensi ke AIAgent"
        string company_id FK "ID perusahaan"
        string trigger_type "Jenis trigger"
        object trigger_config "Konfigurasi trigger"
        boolean is_active "Status aktif schedule"
        datetime last_triggered_at "Waktu trigger terakhir"
        number trigger_count "Jumlah trigger fired"
        string notification_channel "Channel: in_app|whatsapp|email|all"
        string created_by "Email pembuat schedule"
        datetime created_date "Waktu pembuatan"
    }

    Conversation {
        string user_id FK "ID pengguna"
        string title "Judul percakapan"
        string description "Ringkasan percakapan (max 1000)"
        array messages "Seluruh riwayat pesan"
        boolean pinned "Disematkan (default: false)"
        datetime created_at "Waktu pembuatan"
    }

    AILearningData {
        string scope_key PK "Kunci scope pembelajaran"
        string user_id FK "ID user pemilik scope"
        string company_id FK "ID perusahaan untuk scope business"
        object keyword_map "Peta keyword ke kategori"
        array corrections "Log koreksi dari user"
        number positive_count "Jumlah konfirmasi benar"
        number correction_count "Jumlah koreksi"
        datetime last_updated "Terakhir diperbarui"
    }
```

***

## Schema Tabel Entitas — Agent History

### AIAgentRun — Record Eksekusi Agen

Entitas inti yang merekam setiap eksekusi agen AI. Setiap baris mewakili satu kali run lengkap dengan input, output, biaya, dan status.

| Field | Tipe | Wajib | Default | Deskripsi |
| - | - | - | - | - |
| `user_id` | string | Ya | — | ID user yang menjalankan agen |
| `user_email` | string | Tidak | — | Email user yang menjalankan |
| `company_id` | string | Tidak | null | ID perusahaan aktif (null untuk personal) |
| `company_name` | string | Tidak | — | Nama perusahaan saat agen dijalankan |
| `agent_key` | string | Ya | — | Kunci unik agen yang dijalankan |
| `agent_name` | string | Tidak | — | Nama agen saat run (snapshot) |
| `model_used` | string | Tidak | — | Model AI yang dipakai pada run ini |
| `model_name` | string | Tidak | — | Nama tampilan model yang dipakai |
| `input_data` | object | Tidak | — | Input yang diberikan user (struktur dinamis) |
| `output` | string | Tidak | — | Hasil dari AI Agent (max 100.000 karakter) |
| `cost_amount` | number | Tidak | 0 | Biaya Rupiah yang dipotong |
| `cost_credit` | number | Tidak | 0 | Kredit yang dipotong |
| `payment_method` | enum | Tidak | `balance` | Metode pembayaran: `balance`, `credit`, `free` |
| `status` | enum | Tidak | `success` | Status eksekusi: `success`, `failed` |
| `created_at` | timestamp | Otomatis | now() | Waktu eksekusi berlangsung |

### AIAgent — Definisi Agen AI

Entitas yang menyimpan konfigurasi dan definisi setiap agen AI yang tersedia dalam sistem.

| Field | Tipe | Wajib | Default | Deskripsi |
| - | - | - | - | - |
| `agent_key` | string | Ya | — | Kunci unik agen (auto-generated slug dari nama) |
| `company_id` | string | Ya | — | ID perusahaan (scope company-level) |
| `created_by` | string | Ya | — | Email user yang membuat agen |
| `name` | string | Ya | — | Nama AI Agent |
| `tagline` | string | Tidak | — | Deskripsi singkat satu baris |
| `description` | string | Tidak | — | Penjelasan lengkap fungsi agen (max 2000 karakter) |
| `category` | enum | Tidak | `other` | Kategori: `business`, `content`, `writing`, `social`, `other` |
| `icon` | string | Tidak | `Sparkles` | Nama icon lucide-react |
| `color` | string | Tidak | `#4F46E5` | Kode warna hex untuk tampilan |
| `system_prompt` | string | Ya | — | Instruksi sistem utama untuk LLM (max 4000 karakter) |
| `input_fields` | array | Tidak | — | Field input dinamis untuk agen |
| `model` | string | Tidak | `automatic` | Model LLM default |
| `use_internet` | boolean | Tidak | false | Gunakan konteks internet |
| `status` | enum | Tidak | `active` | Status: `active` (jalan otomatis), `paused` (tidak otomatis tapi bisa manual), `inactive` (nonaktif) |
| `source_template_key` | string | Tidak | null | Link ke AIAgentTemplate asal jika dibuat dari template |
| `run_count` | number | Tidak | 0 | Total eksekusi agen |
| `total_cost_amount` | number | Tidak | 0 | Total biaya Rupiah semua run |
| `total_cost_credit` | number | Tidak | 0 | Total kredit yang dipakai semua run |
| `created_date` | datetime | Otomatis | now() | Waktu pembuatan agen |
| `updated_date` | datetime | Otomatis | now() | Waktu pembaruan terakhir |

### AIAgentModel — Konfigurasi Model LLM

Entitas yang mendefinisikan model-model LLM yang tersedia beserta tingkatan dan pengali biayanya.

| Field | Tipe | Wajib | Default | Deskripsi |
| - | - | - | - | - |
| `model_key` | string | Ya | — | Kunci model untuk InvokeLLM (misal: `automatic`, `gpt_5_mini`, `claude_sonnet_4_6`) |
| `name` | string | Ya | — | Nama tampilan model (misal: `Standar (Cepat & Hemat)`) |
| `description` | string | Tidak | — | Penjelasan singkat kualitas/kecepatan model (max 500 karakter) |
| `price_multiplier` | number | Tidak | 1 | Pengali biaya. Biaya akhir = harga dasar agen x multiplier |
| `tier` | enum | Tidak | `standard` | Tingkatan kualitas: `standard`, `advanced`, `premium` |
| `supports_internet` | boolean | Tidak | false | Model mendukung konteks internet |
| `is_active` | boolean | Tidak | true | Status ketersediaan model |
| `order` | number | Tidak | 0 | Urutan pengurutan tampilan |

### AIAgentSettings — Pengaturan Global AI Agent

Entitas singleton yang menyimpan konfigurasi biaya dan metode pembayaran global untuk seluruh agen.

| Field | Tipe | Wajib | Default | Deskripsi |
| - | - | - | - | - |
| `setting_key` | string | Ya | `global` | Kunci pengaturan (selalu `global` untuk pengaturan utama) |
| `description` | string | Tidak | — | Catatan pengaturan AI Agent (max 1000 karakter) |
| `credit_to_rupiah_rate` | number | Tidak | 10 | Nilai 1 kredit dalam Rupiah (misal: 10 berarti 1 kredit = Rp10) |
| `base_price_per_run` | number | Tidak | 1000 | Harga dasar default per penggunaan dalam Rupiah |
| `allow_credit_payment` | boolean | Tidak | true | Izinkan user membayar dengan kredit |
| `allow_balance_payment` | boolean | Tidak | true | Izinkan user membayar dengan saldo Rupiah |

### AIAgentTemplate — Template Agen Bawaan

Entitas yang menyimpan template agen bawaan sistem yang dapat dijadikan acuan pembuatan agen baru.

| Field | Tipe | Wajib | Default | Deskripsi |
| - | - | - | - | - |
| `agent_key` | string | Ya | — | Kunci unik template (misal: `business_analysis`) |
| `name` | string | Ya | — | Nama AI Agent |
| `tagline` | string | Tidak | — | Deskripsi singkat satu baris |
| `description` | string | Tidak | — | Penjelasan lengkap fungsi agen (max 2000 karakter) |
| `category` | enum | Tidak | `other` | Kategori: `business`, `content`, `writing`, `social`, `other` |
| `icon` | string | Tidak | `Sparkles` | Nama icon lucide-react |
| `color` | string | Tidak | `#3b82f6` | Kode warna hex |
| `price_per_run` | number | Tidak | 5000 | Biaya per penggunaan dalam Rupiah |
| `credit_cost` | number | Tidak | 1 | Biaya alternatif dalam kredit AI |
| `features` | array\[string] | Tidak | — | Daftar fitur utama |
| `use_cases` | array\[string] | Tidak | — | Daftar kasus penggunaan |
| `input_fields` | array\[object] | Tidak | — | Field input yang diminta dari user |
| `system_prompt` | string | Tidak | — | Instruksi sistem untuk LLM (max 4000 karakter) |
| `model` | string | Tidak | `automatic` | Model LLM yang dipakai |
| `use_internet` | boolean | Tidak | false | Gunakan konteks internet |
| `status` | enum | Tidak | `active` | Status: `active`, `coming_soon`, `inactive` |
| `order` | number | Tidak | 0 | Urutan pengurutan tampilan |

### AIAgentSchedule — Penjadwalan & Trigger Agen

Entitas yang menyimpan konfigurasi penjadwalan atau trigger berbasis event untuk eksekusi agen otomatis.

| Field | Tipe | Wajib | Default | Deskripsi |
| - | - | - | - | - |
| `agent_id` | string | Ya | — | Referensi ke AIAgent (agent\_key) |
| `company_id` | string | Ya | — | ID perusahaan |
| `trigger_type` | enum | Ya | — | Jenis trigger: `schedule_daily`, `schedule_weekly`, `schedule_monthly`, `event_low_stock`, `event_invoice_overdue`, `event_new_transaction`, `event_task_due`, `event_custom` |
| `trigger_config` | object | Tidak | — | Konfigurasi trigger. Schedule: `{hour, minute, day_of_week?, day_of_month?}`. Event: `{threshold?, product_category?, days_before?}` |
| `is_active` | boolean | Tidak | true | Apakah schedule/trigger aktif |
| `last_triggered_at` | datetime | Tidak | — | Waktu terakhir trigger fired |
| `trigger_count` | number | Tidak | 0 | Berapa kali trigger sudah fired |
| `notification_channel` | enum | Tidak | `in_app` | Channel notifikasi hasil: `in_app`, `whatsapp`, `email`, `all` |
| `created_by` | string | Ya | — | Email user yang membuat schedule |
| `created_date` | datetime | Otomatis | now() | Waktu pembuatan schedule |

### Conversation — Riwayat Percakapan

Entitas yang menyimpan riwayat percakapan user dengan agen AI dalam format pesan berurutan.

| Field | Tipe | Wajib | Default | Deskripsi |
| - | - | - | - | - |
| `user_id` | string | Ya | — | ID pengguna yang memulai percakapan |
| `title` | string | Ya | — | Judul percakapan, dibuat otomatis dari pesan pertama |
| `description` | string | Tidak | — | Ringkasan atau konteks singkat (max 1000 karakter) |
| `messages` | array\[object] | Ya | — | Seluruh riwayat pesan dalam percakapan |
| `messages[].role` | enum | Ya | — | Peran pengirim: `user`, `assistant` |
| `messages[].content` | string | Ya | — | Isi pesan |
| `pinned` | boolean | Tidak | false | Apakah percakapan disematkan |
| `created_at` | timestamp | Otomatis | now() | Waktu pembuatan percakapan |

### AILearningData — Data Pembelajaran AI

Entitas yang menyimpan hasil pembelajaran AI dari koreksi dan konfirmasi user, bersifat per-scope (personal atau business).

| Field | Tipe | Wajib | Default | Deskripsi |
| - | - | - | - | - |
| `scope_key` | string | Ya | — | Kunci scope (format: `ai_learn_personal_<userId>` atau `ai_learn_business_<companyId>`) |
| `user_id` | string | Tidak | — | ID user pemilik scope (untuk scope personal) |
| `company_id` | string | Tidak | — | ID perusahaan (untuk scope business) |
| `keyword_map` | object | Tidak | — | Peta keyword ke `{category, confidence, type}` hasil pembelajaran |
| `corrections` | array\[object] | Tidak | — | Log koreksi yang diberikan user |
| `corrections[].input_text` | string | — | — | Teks input asli |
| `corrections[].original_category` | string | — | — | Kategori hasil prediksi asli |
| `corrections[].correct_category` | string | — | — | Kategori koreksi yang benar |
| `corrections[].type` | string | — | — | Tipe koreksi |
| `corrections[].timestamp` | string | — | — | Waktu koreksi |
| `corrections[].record_id` | string | — | — | ID record terkait |
| `positive_count` | number | Tidak | 0 | Jumlah konfirmasi `benar` dari user |
| `correction_count` | number | Tidak | 0 | Jumlah koreksi dari user |
| `last_updated` | datetime | Otomatis | now() | Terakhir diperbarui |

***

## Diagram Siklus Hidup Riwayat Sesi

```mermaid theme={null}
stateDiagram-v2
    [*] --> AgentDibuat: User membuat agen baru
    AgentDibuat --> AgentAktif: Status = active

    AgentAktif --> MenungguInput: User membuka form agen
    MenungguInput --> EksekusiDimulai: User submit input
    EksekusiDimulai --> MemprosesLLM: Kirim ke model LLM
    MemprosesLLM --> EksekusiBerhasil: status = success
    MemprosesLLM --> EksekusiGagal: status = failed

    EksekusiBerhasil --> RunTercatat: Simpan AIAgentRun
    EksekusiGagal --> RunTercatat: Simpan AIAgentRun (failed)

    RunTercatat --> DihitungStat: Update stats agregat
    DihitungStat --> DikelompokkanTanggal: Date grouping
    DikelompokkanTanggal --> SiapDitampilkan: Masuk daftar history

    SiapDitampilkan --> DifilterPayment: Apply payment filter
    DifilterPayment --> SiapDitampilkan

    SiapDitampilkan --> Diekspor: User klik export
    Diekspor --> SiapDitampilkan

    AgentAktif --> AgentDijeda: Status = paused
    AgentDijeda --> AgentAktif: Status = active
    AgentAktif --> AgentNonaktif: Status = inactive
    AgentNonaktif --> [*]

    state EksekusiDimulai {
        [*] --> ValidasiInput
        ValidasiInput --> HitungBiaya
        HitungBiaya --> PotongPembayaran
        PotongPembayaran --> PanggilLLM
        PanggilLLM --> [*]
    }
```

***

## Diagram Sekuens — Pengambilan Riwayat

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant H as AIAgentHistory.jsx
    participant DB as Database
    participant Stats as Stats Engine
    participant Group as Date Grouper

    U->>H: Buka halaman Agent History
    H->>DB: FETCH AIAgentRun (WHERE company_id = aktif)
    DB-->>H: Return semua record run

    H->>Stats: Hitung statistik agregat
    Stats->>Stats: COUNT(*) → Total Runs
    Stats->>Stats: SUM(cost_amount) → Total Cost
    Stats->>Stats: SUM(cost_credit) → Total Credits
    Stats->>Stats: COUNT DISTINCT agent_key → Unique Agents
    Stats-->>H: Return 4 kartu statistik

    H->>Group: Kelompokkan berdasarkan tanggal
    Group->>Group: Parse created_at → Date bucket
    Group->>Group: Hari Ini | Kemarin | 7 Hari | 30 Hari | Lebih Lama
    Group-->>H: Return grouped runs

    H->>H: Render Stats Bar + Date Sections
    H-->>U: Tampilkan halaman lengkap

    U->>H: Apply payment filter (misal: credit)
    H->>H: Filter runs WHERE payment_method = credit
    H->>Stats: Hitung ulang stats (filtered)
    Stats-->>H: Return filtered stats
    H-->>U: Tampilkan hasil filter
```

## Diagram Sekuens — Replay Percakapan

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant C as Conversation UI
    participant DB as Database
    participant Agent as AI Agent Engine
    participant LLM as Model LLM

    U->>C: Buka riwayat percakapan
    C->>DB: FETCH Conversation WHERE user_id = current
    DB-->>C: Return daftar percakapan

    U->>C: Pilih percakapan tertentu
    C->>DB: FETCH Conversation.messages
    DB-->>C: Return array messages [{role, content}]

    loop Replay setiap pesan
        C->>C: Render pesan sesuai role
        alt role = user
            C->>C: Tampilkan bubble user (kanan)
        else role = assistant
            C->>C: Tampilkan bubble assistant (kiri)
        end
    end

    C-->>U: Tampilkan seluruh percakapan

    U->>C: Kirim pesan baru
    C->>DB: APPEND message {role: user, content}
    C->>Agent: Invoke agent dengan context messages[]
    Agent->>LLM: Kirim system_prompt + messages
    LLM-->>Agent: Return respons AI
    Agent->>DB: APPEND message {role: assistant, content}
    Agent->>DB: CREATE AIAgentRun (input, output, cost, status)
    Agent-->>C: Return respons
    C-->>U: Tampilkan respons AI
```

## Diagram Sekuens — Penjadwalan Trigger Otomatis

```mermaid theme={null}
sequenceDiagram
    participant CRON as Scheduler
    participant S as AIAgentSchedule
    participant A as AIAgent Engine
    participant DB as Database
    participant N as Notifikasi

    CRON->>S: Cek schedule aktif (setiap menit)
    S->>S: Evaluasi trigger_config vs waktu sekarang

    alt trigger_type = schedule_daily
        S->>S: Cocokkan hour & minute
    else trigger_type = schedule_weekly
        S->>S: Cocokkan day_of_week, hour, minute
    else trigger_type = schedule_monthly
        S->>S: Cocokkan day_of_month, hour, minute
    end

    S->>A: Fire trigger → Jalankan agen
    A->>DB: FETCH AIAgent config (agent_id)
    DB-->>A: Return agent definition
    A->>A: Eksekusi agen dengan data kontekstual
    A->>DB: CREATE AIAgentRun (auto-generated input)
    A->>S: UPDATE last_triggered_at, INCREMENT trigger_count

    A->>N: Kirim notifikasi hasil
    N->>N: Channel: in_app / whatsapp / email / all
    N-->>U: User menerima notifikasi hasil agen
```

***

## Referensi Enum

### payment\_method — Metode Pembayaran Run

| Nilai | Deskripsi | Badge Color |
| - | - | - |
| `balance` | Dibayar dari saldo perusahaan | Blue |
| `credit` | Dibayar dari kredit AI bulanan | Purple |
| `free` | Gratis (dalam kuota atau promo) | Green |

### status (AIAgentRun) — Status Eksekusi Agen

| Nilai | Deskripsi | Indikator Visual |
| - | - | - |
| `success` | Eksekusi berhasil dan output dihasilkan | Hijau |
| `failed` | Eksekusi gagal (error LLM, timeout, dll) | Merah |

### category (AIAgent / AIAgentTemplate) — Kategori Agen

| Nilai | Deskripsi | Contoh Penggunaan |
| - | - | - |
| `business` | Agen terkait analisis bisnis dan operasional | Business Analysis, Sales Forecaster |
| `content` | Agen pembuat konten | Content Generator, Social Media Writer |
| `writing` | Agen terkait penulisan umum | Email Composer, Report Writer |
| `social` | Agen untuk media sosial | Social Media Analyzer |
| `other` | Kategori lainnya / custom | Custom agents |

### status (AIAgent) — Status Ketersediaan Agen

| Nilai | Deskripsi | Behavior |
| - | - | - |
| `active` | Agen aktif dan berjalan otomatis | Muncul di dashboard, bisa dijadwalkan, bisa dijalankan manual |
| `paused` | Agen dijeda tidak otomatis | Tidak dijadwalkan otomatis, tapi masih bisa dijalankan manual |
| `inactive` | Agen nonaktif sepenuhnya | Tidak muncul di dashboard, tidak bisa dijalankan |

### status (AIAgentTemplate) — Status Template

| Nilai | Deskripsi |
| - | - |
| `active` | Template tersedia untuk digunakan |
| `coming_soon` | Template akan datang, belum bisa digunakan |
| `inactive` | Template disembunyikan |

### tier (AIAgentModel) — Tingkatan Model LLM

| Nilai | Multiplier | Deskripsi | Contoh Model |
| - | - | - | - |
| `standard` | 1.0x | Model cepat dan hemat biaya | hermes-3-llama-3 |
| `advanced` | 1.5x | Model berkualitas lebih tinggi | claude-3-5-sonnet, gpt-4o |
| `premium` | 3.0x | Model terbaik untuk tugas kompleks | gemini-1-5-pro |

### trigger\_type (AIAgentSchedule) — Jenis Trigger Penjadwalan

| Nilai | Kategori | Deskripsi |
| - | - | - |
| `schedule_daily` | Jadwal | Trigger setiap hari pada waktu tertentu |
| `schedule_weekly` | Jadwal | Trigger setiap minggu pada hari dan waktu tertentu |
| `schedule_monthly` | Jadwal | Trigger setiap bulan pada tanggal dan waktu tertentu |
| `event_low_stock` | Event | Trigger saat stok produk rendah |
| `event_invoice_overdue` | Event | Trigger saat ada faktur jatuh tempo |
| `event_new_transaction` | Event | Trigger saat ada transaksi baru |
| `event_task_due` | Event | Trigger saat tugas mendekati tenggat |
| `event_custom` | Event | Trigger event kustom yang dikonfigurasi user |

### notification\_channel (AIAgentSchedule) — Channel Notifikasi

| Nilai | Deskripsi |
| - | - |
| `in_app` | Notifikasi dalam aplikasi |
| `whatsapp` | Notifikasi melalui WhatsApp |
| `email` | Notifikasi melalui email |
| `all` | Semua channel notifikasi |

### role (Conversation.messages) — Peran Pengirim Pesan

| Nilai | Deskripsi |
| - | - |
| `user` | Pesan dari pengguna |
| `assistant` | Pesan balasan dari AI Agent |

### channel\_type (ChatChannel) — Tipe Channel Chat

| Nilai | Deskripsi |
| - | - |
| `public` | Channel publik, semua anggota perusahaan bisa melihat |
| `private` | Channel privat, hanya anggota yang diundang |
| `direct` | Chat langsung antar dua pengguna |

***

## Kontrol Akses Berbasis Peran (RBAC)

| Entitas | Operasi | Admin | Manager | Staff | Viewer | Deskripsi Akses |
| - | - | - | - | - | - | - |
| **AIAgentRun** | Create | Ya | Ya | Ya | Tidak | User yang menjalankan agen membuat record run |
| **AIAgentRun** | Read | Semua | Perusahaan | Sendiri | Sendiri | Admin lihat semua, manager lihat per perusahaan, staff lihat milik sendiri |
| **AIAgentRun** | Update | Ya | Ya | Tidak | Tidak | Hanya admin/manager yang bisa update metadata run |
| **AIAgentRun** | Delete | Ya | Tidak | Tidak | Tidak | Hanya admin yang bisa menghapus record run |
| **AIAgent** | Create | Ya | Ya | Ya | Tidak | Semua user aktif bisa membuat agen baru |
| **AIAgent** | Read | Semua | Perusahaan | Perusahaan | Perusahaan | Agen bersifat company-level, semua role dalam perusahaan bisa melihat |
| **AIAgent** | Update | Ya | Ya | Milik sendiri | Tidak | Admin/manager update semua, staff hanya update agen buat sendiri |
| **AIAgent** | Delete | Ya | Ya | Milik sendiri | Tidak | Admin/manager hapus semua, staff hanya hapus agen buat sendiri |
| **AIAgentModel** | Create | Ya | Tidak | Tidak | Tidak | Hanya admin yang bisa menambah konfigurasi model |
| **AIAgentModel** | Read | Ya | Ya | Ya | Ya | Semua role bisa melihat daftar model yang tersedia |
| **AIAgentModel** | Update | Ya | Tidak | Tidak | Tidak | Hanya admin yang bisa mengubah konfigurasi model |
| **AIAgentModel** | Delete | Ya | Tidak | Tidak | Tidak | Hanya admin yang bisa menghapus model |
| **AIAgentSettings** | Create | Ya | Tidak | Tidak | Tidak | Hanya admin yang bisa membuat pengaturan |
| **AIAgentSettings** | Read | Ya | Ya | Ya | Ya | Semua role bisa membaca pengaturan global |
| **AIAgentSettings** | Update | Ya | Tidak | Tidak | Tidak | Hanya admin yang bisa mengubah pengaturan global |
| **AIAgentSettings** | Delete | Ya | Tidak | Tidak | Tidak | Hanya admin yang bisa menghapus pengaturan |
| **AIAgentTemplate** | Create | Ya | Tidak | Tidak | Tidak | Hanya admin sistem yang bisa menambah template bawaan |
| **AIAgentTemplate** | Read | Ya | Ya | Ya | Ya | Semua role bisa melihat template yang tersedia |
| **AIAgentTemplate** | Update | Ya | Tidak | Tidak | Tidak | Hanya admin sistem yang bisa mengubah template |
| **AIAgentTemplate** | Delete | Ya | Tidak | Tidak | Tidak | Hanya admin sistem yang bisa menghapus template |
| **AIAgentSchedule** | Create | Ya | Ya | Ya | Tidak | User yang memiliki agen bisa membuat schedule |
| **AIAgentSchedule** | Read | Semua | Perusahaan | Perusahaan | Perusahaan | Schedule bersifat company-level |
| **AIAgentSchedule** | Update | Ya | Ya | Milik sendiri | Tidak | Admin/manager update semua, staff hanya milik sendiri |
| **AIAgentSchedule** | Delete | Ya | Ya | Milik sendiri | Tidak | Admin/manager hapus semua, staff hanya milik sendiri |
| **Conversation** | Create | Ya | Ya | Ya | Ya | Semua user bisa memulai percakapan |
| **Conversation** | Read | Semua | Perusahaan | Sendiri | Sendiri | Admin lihat semua, user lain hanya percakapan sendiri |
| **Conversation** | Update | Ya | Ya | Sendiri | Sendiri | Pemilik bisa update (pin, tambah pesan) |
| **Conversation** | Delete | Ya | Ya | Sendiri | Sendiri | Pemilik bisa menghapus percakapan sendiri |
| **AILearningData** | Create | Ya | Ya | Ya | Tidak | Data pembelajaran dibuat saat user memberikan koreksi |
| **AILearningData** | Read | Semua | Perusahaan | Sendiri | Sendiri | Admin lihat semua, user lain hanya scope sendiri |
| **AILearningData** | Update | Ya | Ya | Sendiri | Sendiri | Pemilik scope bisa memperbarui data pembelajaran |
| **AILearningData** | Delete | Ya | Tidak | Tidak | Tidak | Hanya admin yang bisa menghapus data pembelajaran |

***

**Related Documentation**:

* [Agent Dashboard](/docs/ai/agent-dashboard)
* [AI Agent Detail](/docs/ai/ai-agent-detail)
* [AI Agents](/docs/ai/agents)
* [AI Overview](/docs/ai/overview)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.