Studi Kasus AI Agent PHP: Customer Support & Database Memory

Terakhir diperbarui: 22 Agustus 2026

Diagram Arsitektur: Production-Ready Enterprise Customer Support AI Agent (PHP Architecture)

WebP Lossless • 82 KB • Schema Ready

Arsitektur Solusi Customer Support Agent PHP & Database Memory

Direct Answer:Strategi membangun AI Agent lengkap di PHP mengandalkan arsitektur agen AI berpusat pada orkestrator backend yang menerima query browser, memuat riwayat percakapan dari state persistence MySQL, lalu mengeksekusi siklus Reasoning & Acting (ReAct) berulang bersama McpClient hingga jawaban final terbentuk.

Dalam proses membangun AI Agent lengkap untuk skala produksi, arsitektur ini memisahkan layer presentasi web, logika agen otonom, dan antarmuka alat (tools) agar sistem mudah diuji dan dikembangkan:

+-------------------------------------------------------------------------+
|                           User Browser Client                           |
+-------------------------------------------------------------------------+
                                     │ (HTTPS POST /api/chat.php)
                                     ▼
+-------------------------------------------------------------------------+
|                  API Gateway & Rate Limiter Middleware                  |
+-------------------------------------------------------------------------+
                                     │
                                     ▼
+-------------------------------------------------------------------------+
|                 Customer Support Agent PHP (Orchestrator)               |
|  - System Prompt (Aria Persona)                                         |
|  - ReAct Engine Loop (maxIterations = 8)                                 |
+-------------------------------------------------------------------------+
        │                                    │                      │
        ▼                                    ▼                      ▼
+-------------------+              +-------------------+   +--------------------+
|  DatabaseMemory   |              |    McpClient      |   |   OpenAI Client    |
| (Database Memory) |              | (Tool Dispatcher) |   |  (GPT-4o mini API) |
+-------------------+              +-------------------+   +--------------------+
                                             │
             ┌───────────────────────────────┼──────────────────────────────┐
             ▼                               ▼                              ▼
    [DatabaseTool: MySQL]          [PdfReaderTool: PDF]          [ShippingApiTool]

Implementasi Kode: 4 Langkah Membangun CustomerSupportAgent PHP

Direct Answer:Tahap inti membangun AI Agent lengkap diwujudkan lewat class CustomerSupportAgent melalui 4 langkah sekuensial: Step 1 Inisialisasi dependensi & state, Step 2 Komposisi prompt & context history, Step 3 Eksekusi ReAct reasoning loop, dan Step 4 Evaluasi tool call dispatcher.

Berikut adalah daftar langkah terstruktur dan kode lengkap implementasi orkestrator backend agen:

1. Step 1: Registrasi Dependensi & Client: Menghubungkan client LLM OpenAI, dispatcher MCP, dan Monolog logger ke dalam constructor agen.
2. Step 2: Penyusunan Payload Konteks Dialog: Menggabungkan System Prompt (persona Aria), riwayat sesi dari state persistence MySQL, dan input pengguna terbaru.
3. Step 3: Eksekusi ReAct Reasoning Loop: Menjalankan inferensi model dengan batas maxIterations = 8 untuk mencegah *infinite tool call loop*.
4. Step 4: Dispatching & Handling Hasil Tool: Mengeksekusi driver tool secara otomatis jika LLM meminta data tambahan (SQL/PDF/Shipping API) lalu mengembalikan observasi ke model.

<?php

namespace App\Agent;

use App\OpenAIClient;
use App\MCP\McpClient;
use App\Logger\Logger;
use Throwable;

/**
 * Class CustomerSupportAgent
 * Orkestrator backend Customer Support Agent PHP berbasis ReAct Loop & Model Context Protocol.
 */
class CustomerSupportAgent
{
    private OpenAIClient $client;
    private McpClient $mcpClient;
    private Logger $logger;
    private array $messages = [];
    private int $maxIterations;

    // =========================================================================
    // Step 1: Inisialisasi Dependensi Orkestrator Agen
    // =========================================================================
    public function __construct(
        OpenAIClient $client,
        McpClient $mcpClient,
        Logger $logger,
        int $maxIterations = 8
    ) {
        $this->client        = $client;
        $this->mcpClient     = $mcpClient;
        $this->logger        = $logger;
        $this->maxIterations = $maxIterations;
    }

    /**
     * Memproses pesan masuk dari pengguna dan mengeksekusi rantai penalaran agen.
     */
    public function handle(string $userId, string $userMessage, array $history = []): array
    {
        $startTime = microtime(true);
        $toolsUsed = [];

        // =========================================================================
        // Step 2: Komposisi Payload Pesan & State Persistence Context History
        // =========================================================================
        $this->messages = array_merge(
            [['role' => 'system', 'content' => $this->getSystemPrompt()]],
            $history,
            [['role' => 'user', 'content' => $userMessage]]
        );

        $toolDefs    = $this->mcpClient->getToolDefinitions();
        $finalAnswer = '';
        $tokenUsage  = [];

        // =========================================================================
        // Step 3: Memulai Siklus Reasoning & Acting (ReAct Loop)
        // =========================================================================
        for ($i = 0; $i < $this->maxIterations; $i++) {
            $response = $this->client->chat($this->messages, $toolDefs);
            $message  = $response['choices'][0]['message'] ?? [];
            $tokenUsage = $response['usage'] ?? $tokenUsage;

            $this->messages[] = $message;

            // =========================================================================
            // Step 4: Dispatching & Eksekusi Tool Call (DatabaseTool / PdfTool / Shipping)
            // =========================================================================
            if (!empty($message['tool_calls'])) {
                foreach ($message['tool_calls'] as $toolCall) {
                    $toolName    = $toolCall['function']['name'];
                    $toolsUsed[] = $toolName;

                    $this->logger->info("Eksekusi Tool Dimulai", [
                        'tool'    => $toolName,
                        'user_id' => $userId,
                        'args'    => $toolCall['function']['arguments'] ?? '',
                    ]);

                    try {
                        // Eksekusi tool melalui dispatcher MCP Client
                        $toolResult       = $this->mcpClient->executeToolCall($toolCall);
                        $this->messages[] = $toolResult;
                    } catch (Throwable $e) {
                        $this->logger->error("Gagal Eksekusi Tool", ['error' => $e->getMessage()]);
                        $this->messages[] = [
                            'role'         => 'tool',
                            'tool_call_id' => $toolCall['id'],
                            'content'      => json_encode(['error' => 'Gagal memproses alat: ' . $e->getMessage()]),
                        ];
                    }
                }
                // Lanjutkan loop ke iterasi berikutnya untuk observasi hasil tool
                continue;
            }

            // Jawaban final tercapai jika model tidak meminta pemanggilan tool lagi
            $finalAnswer = $message['content'] ?? '';
            break;
        }

        $durationMs = (int) round((microtime(true) - $startTime) * 1000);

        return [
            'answer'       => $finalAnswer,
            'tools_used'   => array_values(array_unique($toolsUsed)),
            'duration_ms'  => $durationMs,
            'token_usage'  => $tokenUsage,
        ];
    }

    /**
     * Persona & Instruksi Pengarah Agen Aria.
     */
    private function getSystemPrompt(): string
    {
        return <<<PROMPT
Kamu adalah Aria, asisten AI Customer Support resmi untuk toko online ShopKita.

KEPRIBADIAN: Ramah, profesional, sabar, dan berorientasi solusi praktis.

KEMAMPUAN TOOLS:
1. database_query: Mencari data pesanan (order_id), status transaksi, dan profil user di database MySQL.
2. read_pdf_manual: Membaca syarat & ketentuan garansi, retur barang, dan buku panduan produk dari file PDF.
3. track_shipping: Mengecek status pelacakan resi ekspedisi kurir pengiriman terkini.
4. calculate_discount: Menghitung simulasi diskon kupon promo, pajak, dan ongkos kirim.

ATURAN PERILAKU:
- Jika user menanyakan status pesanan tanpa menyebutkan Order ID, mintalah nomor pesanan secara sopan.
- Gunakan data faktual yang didapat dari tool output, jangan pernah mengarang informasi (anti-halusinasi).
- Jika komplain tidak terselesaikan dalam batas wewenang, tawarkan eskalasi tiket ke tim Human Support.
- Berikan respons dalam Bahasa Indonesia yang santun dan mudah dipahami.
PROMPT;
    }
}

Setup Tools, State Persistence MySQL & Entry Point API

Direct Answer:Entry point api/chat.php menghubungkan incoming HTTP request dari browser ke CustomerSupportAgent setelah melewati validasi payload, rate limiter, serta manajemen state persistence MySQLDatabaseMemory.

Berikut adalah file entry point lengkap yang menyatukan seluruh dependensi modul:

<?php
// =========================================================================
// api/chat.php - Production-Ready API Endpoint for AI Customer Support
// =========================================================================

require_once __DIR__ . '/../vendor/autoload.php';

header('Content-Type: application/json; charset=UTF-8');
header('X-Content-Type-Options: nosniff');

$config = require __DIR__ . '/../config/config.php';
$rawInput = file_get_contents('php://input');
$input    = json_decode($rawInput, true);

// 1. Validasi Ketat Payload Masukan Pengguna
$userMessage = htmlspecialchars(trim($input['message'] ?? ''), ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
$sessionId   = preg_replace('/[^a-zA-Z0-9_-]/', '', $input['session_id'] ?? session_id());

if (empty($userMessage) || mb_strlen($userMessage) > 3000) {
    http_response_code(400);
    echo json_encode(['error' => 'Pesan masukan tidak valid atau melebihi batas 3.000 karakter.']);
    exit;
}

// 2. Inisialisasi Database Connection Pool & State Persistence Manager
$pdo = new PDO(
    "mysql:host={$config['db']['host']};dbname={$config['db']['name']};charset=utf8mb4",
    $config['db']['user'],
    $config['db']['pass'],
    [
        PDO::ATTR_PERSISTENT         => true,
        PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
    ]
);

$memory   = new App\Memory\DatabaseMemory($pdo, $sessionId);
$history  = $memory->getAll(limit: 10);

// 3. Registrasi Tools ke Server MCP
$mcpServer = new App\MCP\McpServer();
$mcpServer
    ->register('database_query', new App\Tools\DatabaseTool($pdo))
    ->register('read_pdf_manual', new App\Tools\PdfReaderTool(__DIR__ . '/../storage/documents'))
    ->register('track_shipping', new App\Tools\ShippingApiTool($config['shipping_api_key']))
    ->register('calculate_discount', new App\Tools\CalculatorTool());

$mcpClient = new App\MCP\McpClient($mcpServer);
$client    = new App\OpenAIClient($config['openai_api_key']);
$logger    = new App\Logger\Logger(__DIR__ . '/../logs/customer_support.log', 'info');

// 4. Inisialisasi dan Eksekusi Agen
$agent  = new App\Agent\CustomerSupportAgent($client, $mcpClient, $logger);
$result = $agent->handle($sessionId, $userMessage, $history);

// 5. Simpan Hasil Dialog ke State Persistence MySQL
$memory->add('user', $userMessage);
$memory->add('assistant', $result['answer']);

// 6. Kembalikan Respon JSON ke Klien
echo json_encode([
    'status'      => 'success',
    'session_id'  => $sessionId,
    'answer'      => $result['answer'],
    'tools_used'  => $result['tools_used'],
    'duration_ms' => $result['duration_ms'],
    'token_usage' => $result['token_usage'],
]);

Repositori Kode Sumber GitHub CustomerSupportAgent

FAQ: Tanya Jawab Teknis Studi Kasus AI Agent PHP