Agent Architecture

Engine Bot memakai hierarchical multi-agent architecture. HTTP controller menyiapkan context tenant dan customer, main orchestrator memilih specialist agent, lalu specialist menjalankan LangChain tools yang membaca atau mengubah MongoDB dan API eksternal.

WhatsApp/API client
  -> Express auth dan request buffer
  -> mainController.botFunction
  -> context loader dan intent detector
  -> main orchestrator
  -> specialist agent
  -> domain tools/service
  -> MongoDB atau external API
  -> response formatter
  -> optional BullMQ follow-up

Runtime Components

Request Lifecycle

1. verifyToken memeriksa allowlist IP atau JWT.
2. functionRouteBot memvalidasi store_id, customer_id, dan agent_id.
3. Request identik dalam 10 detik didedup memakai in-memory map.
4. Pesan cepat dari customer sama digabung berdasarkan time_reply.
5. botFunction memuat customer, agent, store, dan maksimal 10 history messages.
6. Audio ditranskripsi; gambar dideskripsikan dan dapat masuk proof-of-payment flow.
7. Active order dan followup_step dibaca untuk menentukan context dan routing.
8. Saat konfirmasi alamat memenuhi fast path, checkShippingCost dipanggil tanpa main orchestrator.
9. Di luar order follow-up, katalog, QnA, dan intent dimuat.
10. Main orchestrator memanggil satu specialist tool berdasarkan prompt.
11. Output JSON dibersihkan, gambar Markdown dipisahkan, token main orchestrator dicatat.
12. Follow-up job dijadwalkan bila aturan order/intent terpenuhi.

Specialist Agents

Customer Service

Tool wrapper: customer_service_department.

Fungsi: FAQ dan informasi toko, katalog dan stok produk, complaint, constraint customer.

Admin

Tool wrapper: admin_department.

Fungsi: tambah/hapus cart, tampilkan context cart, checkout cart menjadi order, perubahan produk/varian/quantity melalui order tools.

Logistics

Tool wrapper aktual: logistics_departemen.

Fungsi: parse dan validasi alamat, hitung ongkir, simpan pilihan kurir/service, tracking resi.

Payment

Tool wrapper: payment_department.

Fungsi: tampilkan dan simpan metode pembayaran, konfirmasi order, buat checkout instant payment, cek status instant payment.

Booking

Tool wrapper aktual: booking_departement.

Agent dan prompt tersedia, tetapi seluruh fungsi di tools/booking/tools.js mengembalikan pesan belum diimplementasikan. Jangan menganggap booking production-ready.

Model Mapping

Main Orchestrator Settings

• parallel_tool_calls: false
• response_format: { type: "json_object" }
• History maksimal 10 messages
• Tool wrappers dibangun per request
• Active order hint ditambahkan untuk routing logistics/payment

Main Orchestrator Prompt

prompt/main-agent.md — aturan routing:

ATURAN ROUTING (PANGGIL SALAH SATU):
- customer_service_department : Sapaan, cari produk, FAQ, komplain
- admin_department             : Keranjang, pilih varian/jumlah, checkout
- logistics_departemen         : Alamat, cek ongkir, pilih kurir, lacak resi
- payment_department           : Metode pembayaran, konfirmasi pesanan
- booking_departement          : Reservasi event (stub)

Orchestrator adalah router — dilarang menjawab dengan pengetahuan bawaan. Setelah specialist agent selesai, orchestrator format output ke JSON:

{
  "answer": "String balasan natural tanpa markdown (100% isi dari sub-agent).",
  "images": [
    { "caption": "Nama Produk", "image": ["URL"] }
  ]
}

Context Strategy

Data selalu dimuat:

• Customer, agent, store
• Kategori dan tipe produk
• Rekening bank
• Nama customer service
• Active order

Data berat hanya dimuat di luar order follow-up:

• Katalog produk penuh
• QnA agent
• OpenAI intent detection
• Produk promo dan termurah

Order follow-up yang memicu lightweight context

Context Controls

• QnA dipotong maksimal 3.500 karakter.
• Katalog penuh dilewati selama active order follow-up.
• Intent detection dilewati selama active order follow-up.
• Product special/cheapest hanya dimuat bila intent memiliki entity.

Conversation State

Persistent business state berada di MongoDB melalui order, cart, dan followup_step. History percakapan berasal dari request client dan dipotong menjadi 10 messages. thread_id diberikan ke LangChain, tetapi code tidak memasang persistent checkpointer.

In-memory state:

• userBuffer: message batching
• lastRequestPerCustomer: duplicate guard

Keduanya hilang saat restart dan tidak dibagi antar multiple instances.

Prompt Loading

Prompt Markdown dibaca dari filesystem melalui readMdPromptFile/promptWithContext saat agent dibangun. Perubahan prompt berlaku pada request berikutnya; restart tidak diwajibkan oleh loader saat ini.

Response Formatting

Main orchestrator diminta menghasilkan JSON dengan answer dan images. Controller tetap memiliki fallback untuk raw text dan ekstraksi syntax gambar Markdown. Hanya URL gambar yang lolos aturan extractAndCleanImages yang dipindahkan ke response images.

Cost Tracking

Main orchestrator memasang callback token dan menyimpan hasil ke log_request_openai. Welcome generator juga mencatat token/cost.

Belum tercakup penuh:

• Specialist agents
• Intent detection
• Vision
• Audio transcription
• Follow-up AI refinement

Karena itu, log_request_openai bukan total biaya OpenAI end-to-end.

Perubahan Model

Saat mengganti model:

1. Uji tool calling untuk seluruh specialist agent.
2. Uji JSON output main orchestrator.
3. Uji address extraction dan variant matching.
4. Uji payment confirmation tanpa mengandalkan output model sebagai sumber kebenaran finansial.
5. Perbarui tabel di atas dan pricing callback bila masih dipakai.

Langkah berikutnya

• Cara order mengalir? Baca Order Flow.
• Cara follow-up mengirim? Baca Follow-up Scheduler.
• Known issues agent? Baca Tech Debt.