Belajar AI Agent PHP: Pengertian, Cara Kerja & Komponen

Terakhir diperbarui: 29 Jul 2026

Pengertian AI Agent

Pengertian AI Agent adalah entitas perangkat lunak otonom yang mampu merasakan kondisi lingkungan (environment) di sekitarnya, memproses informasi dengan kecerdasan buatan, serta mengambil serangkaian keputusan dan tindakan (actions) secara mandiri untuk mencapai tujuan (goal) tertentu. Jika Anda ingin belajar AI Agent dengan PHP dari dasar hingga tingkat produksi, panduan ini dirancang untuk membantu Anda memahami arsitektur dan cara praktis belajar AI Agent di PHP secara mendalam.

Berbeda dengan program konvensional yang mengikuti instruksi yang ditentukan secara kaku oleh programmer, AI Agent memiliki kemampuan untuk beradaptasi, merencanakan, dan menggunakan alat-alat (tools) yang tersedia untuk menyelesaikan tugas yang diberikan kepadanya.

Perbedaan AI Agent dan Chatbot

Ini adalah salah satu pertanyaan paling sering ditanyakan oleh pemula. Meskipun sama-sama berbasis bahasa, AI Agent dan Chatbot memiliki perbedaan fundamental yang sangat signifikan.

Alasan Utama Belajar AI Agent & PHP

Banyak pengembang mengasosiasikan pengembangan AI dengan Python. Namun, PHP adalah bahasa yang sangat tangguh dan ideal untuk membangun AI Agent tingkat produksi karena beberapa alasan strategis:

• Dominasi Web & Integration: Lebih dari 75% website di internet menggunakan PHP. Membangun AI Agent dengan PHP memudahkan integrasi langsung dengan aplikasi web, database MySQL/PostgreSQL, dan REST API yang sudah ada tanpa perlu membangun microservice terpisah.
• Ekosistem Modern PHP 8.3+: Fitur modern seperti strict typing, Enums, Readonly Classes, Fibers (Asynchronous), dan cURL HTTP client membuat pengembangan AI Agent menjadi sangat rapi, aman, dan berperforma tinggi.
• Kemudahan Deployment: Aplikasi PHP sangat mudah di-deploy di berbagai lingkungan hosting, mulai dari Shared Hosting, VPS Ubuntu dengan Nginx/Apache, hingga Container Docker.
• Manajemen Sesi & State: PHP memiliki dukungan native yang sangat baik untuk Session management dan ORM yang memudahkan pengelolaan Memory dan State AI Agent.

Framework & SDK AI Agent Modern di PHP

Selain membangun dari nol, ekosistem PHP modern saat ini didukung oleh berbagai SDK dan framework AI kelas produksi yang sangat mumpuni:

• openai-php/client: SDK PHP resmi komunitas yang dikembangkan oleh Nuno Maduro & Sandro Gehri dengan dukungan penuh untuk PHP 8.1+, typed request/response, dan streaming response.
• LLPhant: Framework AI paling populer untuk PHP yang terinspirasi dari LangChain. Menyediakan fitur RAG (Vector Search), Memory management, Function Calling, dan dukungan multi-LLM (OpenAI, Anthropic, Mistral, Ollama).
• Prism (EchoLabs): Abstraksi AI modern untuk PHP & Laravel yang menyediakan API fluent untuk teks generation, structured JSON output, dan pemanggilan tool secara otomatis.

Pencegahan Prompt Injection & Sanitasi Input User di PHP

Salah satu ancaman keamanan siber terbesar pada aplikasi berbasis AI Agent adalah Prompt Injection — kondisi di mana pengguna yang tidak bertanggung jawab menyelipkan instruksi berbahaya untuk memanipulasi logika System Prompt atau memicu tindakan eksekusi Tool yang tidak diizinkan.

Untuk mengamankan AI Agent dalam ekosistem PHP, selalu terapkan 3 pilar sanitasi input berikut sebelum mengirimkan payload ke API LLM:

• Validasi Tipe Data & Batas Karakter (Length Limit): Gunakan fitur strict typing PHP 8.3 dan mb_substr() untuk membatasi panjang input pengguna (misal maksimal 1000 karakter) agar mencegah serangan Resource Exhaustion.
• Filtering Karakter & Delimiter Escaping: Bersihkan kontrol karakter atau delimiter prompt yang berpotensi membingungkan pembacaan LLM dengan fungsi sanitasi kustom atau htmlspecialchars() / preg_replace().
• Pemisahan Peran System vs User Prompt: Jangan pernah menggabungkan input mentah pengguna langsung ke dalam string System Message. Selalu pisahkan input pengguna dalam objek berlabel "role" => "user".

Berikut adalah contoh fungsi helper sanitasi input sederhana di PHP untuk mencegah Prompt Injection:

<?php

// Helper Sanitasi Input User Mencegah Prompt Injection pada AI Agent PHP
function sanitizeAgentPrompt(string $input, int $maxLength = 1000): string
{
    // 1. Trim whitespace & strip HTML tags
    $clean = trim(strip_tags($input));
    
    // 2. Batasi panjang input (Length Limiting)
    $clean = mb_substr($clean, 0, $maxLength, "UTF-8");
    
    // 3. Filter karakter kontrol tersembunyi
    $clean = preg_replace("/[\x00-\x1F\x7F]/u", "", $clean);
    
    return $clean;
}

<?php

// Skrip AI Agent Loop PHP 8.3 dengan Estimasi & Manajemen Kuota Token cURL

readonly class StockTool
{
    public function __construct(private PDO $pdo) {}

    public function getDefinition(): array
    {
        return [
            "type" => "function",
            "function" => [
                "name" => "check_stock",
                "description" => "Mengecek stok dan harga barang di database MySQL berdasarkan nama produk.",
                "parameters" => [
                    "type" => "object",
                    "properties" => [
                        "product_name" => [
                            "type" => "string",
                            "description" => "Nama produk barang yang dicari"
                        ]
                    ],
                    "required" => ["product_name"]
                ]
            ]
        ];
    }

    public function execute(string $productName): array
    {
        $stmt = $this->pdo->prepare("SELECT name, stock, price FROM products WHERE name LIKE ? LIMIT 1");
        $stmt->execute(["%" . $productName . "%"]);
        $row = $stmt->fetch(PDO::FETCH_ASSOC);

        return $row ?: ["error" => "Produk " . $productName . " tidak ditemukan di database."];
    }
}

class AgentLoop
{
    private int $totalTokensUsed = 0;

    public function __construct(
        private string $apiKey,
        private StockTool $stockTool,
        private int $maxIterations = 5,
        private int $maxTokenBudget = 8000 // Guardrail pencegah pembengkakan kuota cURL
    ) {}

    // Helper estimasi token sederhana (1 token ~ 3.5 karakter teks Bahasa Indonesia / Kode)
    private function estimateTokens(string $text): int
    {
        return (int) ceil(mb_strlen($text, "UTF-8") / 3.5);
    }

    public function run(string $goal): string
    {
        $messages = [
            ["role" => "system", "content" => "Kamu adalah AI Agent asisten toko. Gunakan tool check_stock untuk mencari data barang."],
            ["role" => "user", "content" => $goal]
        ];

        $tools = [$this->stockTool->getDefinition()];

        // Cycle: Agent Loop
        for ($i = 0; $i < $this->maxIterations; $i++) {
            // Guardrail 1: Pre-flight check estimasi token sebelum panggil HTTP cURL
            $estimatedPromptTokens = $this->estimateTokens(json_encode($messages));
            if ($this->totalTokensUsed + $estimatedPromptTokens > $this->maxTokenBudget) {
                return "PERINGATAN: Loop dihentikan otomatis untuk mencegah pembengkakan kuota. Estimasi token (" 
                       . ($this->totalTokensUsed + $estimatedPromptTokens) . ") melebihi batas budget (" . $this->maxTokenBudget . " token).";
            }

            $ch = curl_init("https://api.openai.com/v1/chat/completions");
            curl_setopt_array($ch, [
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_POST => true,
                CURLOPT_POSTFIELDS => json_encode([
                    "model" => "gpt-4o-mini",
                    "messages" => $messages,
                    "tools" => $tools,
                    "tool_choice" => "auto",
                    "max_tokens" => 1000 // Batasi token completion per respons API
                ]),
                CURLOPT_HTTPHEADER => [
                    "Content-Type: application/json",
                    "Authorization: Bearer " . $this->apiKey
                ]
            ]);

            $rawResponse = curl_exec($ch);
            curl_close($ch);

            $response = json_decode($rawResponse, true);

            // Guardrail 2: Catat akumulasi pemakaian token real dari objek usage LLM API
            if (isset($response["usage"]["total_tokens"])) {
                $this->totalTokensUsed += (int) $response["usage"]["total_tokens"];
            }

            $message = $response["choices"][0]["message"] ?? [];
            $messages[] = $message;

            // FASE ACT: Cek apakah LLM memutuskan memanggil Tool
            if (!empty($message["tool_calls"])) {
                foreach ($message["tool_calls"] as $toolCall) {
                    $args = json_decode($toolCall["function"]["arguments"], true);
                    $result = $this->stockTool->execute($args["product_name"] ?? "");

                    // Guardrail 3: Truncate output hasil tool agar tidak membengkakkan prompt iterasi berikutnya
                    $cleanResultJson = mb_substr(json_encode($result), 0, 1500, "UTF-8");

                    // FASE REFLECT: Kirim hasil eksekusi tool kembali ke LLM
                    $messages[] = [
                        "role" => "tool",
                        "tool_call_id" => $toolCall["id"],
                        "content" => $cleanResultJson
                    ];
                }
                continue; // Lanjutkan ke iterasi berikutnya (Loop)
            }

            // Jika tidak ada tool call, goal tercapai dan kembalikan jawaban akhir + laporan token
            $finalAnswer = $message["content"] ?? "Selesai.";
            return $finalAnswer . "\n\n[Total Akumulasi Token Terpakai: " . $this->totalTokensUsed . " token]";
        }

        return "Batas maksimum iterasi tercapai. Total token terpakai: " . $this->totalTokensUsed;
    }
}

Unit Testing AI Agent & Sanitasi Input dengan PHPUnit

Untuk memastikan fungsi sanitasi input sanitizeAgentPrompt() dan komponen AgentLoop berjalan deterministik di lingkungan produksi, Anda dapat membuat pengujian otomatis (Unit Testing) menggunakan PHPUnit secara terisolasi menggunakan Mock Objects tanpa perlu melakukan pemanggilan API cURL atau database nyata:

<?php

namespace Tests\Unit;

use PHPUnit\Framework\TestCase;

// 1. Unit Test untuk Fungsi Sanitasi Input Mencegah Prompt Injection
class AgentSanitizationTest extends TestCase
{
    public function test_sanitize_agent_prompt_strips_html_and_script_tags(): void
    {
        $rawInput = "<script>alert(\"xss\")</script> Halo AI Agent";
        $clean = sanitizeAgentPrompt($rawInput);

        $this->assertEquals("alert(\"xss\") Halo AI Agent", $clean);
        $this->assertStringNotContainsString("<script>", $clean);
    }

    public function test_sanitize_agent_prompt_enforces_length_limit(): void
    {
        $longInput = str_repeat("A", 1500);
        $clean = sanitizeAgentPrompt($longInput, 1000);

        $this->assertEquals(1000, mb_strlen($clean, "UTF-8"));
    }

    public function test_sanitize_agent_prompt_removes_control_characters(): void
    {
        $inputWithControlChar = "Halo\x00World\x1F!";
        $clean = sanitizeAgentPrompt($inputWithControlChar);

        $this->assertEquals("HaloWorld!", $clean);
    }
}

// 2. Unit Test Terisolasi untuk Tool & Guardrail AgentLoop dengan Mock Object PHPUnit
class AgentLoopTest extends TestCase
{
    public function test_stock_tool_execution_returns_product_data(): void
    {
        // Mocking PDO Statement dan PDO Database Connection
        $stmtMock = $this->createMock(\PDOStatement::class);
        $stmtMock->expects($this->once())
            ->method("execute")
            ->with(["%Laptop%"]);
        $stmtMock->expects($this->once())
            ->method("fetch")
            ->willReturn([
                "name" => "Laptop Asus ROG",
                "stock" => 5,
                "price" => 15000000
            ]);

        $pdoMock = $this->createMock(\PDO::class);
        $pdoMock->expects($this->once())
            ->method("prepare")
            ->willReturn($stmtMock);

        $tool = new \StockTool($pdoMock);
        $result = $tool->execute("Laptop");

        $this->assertArrayHasKey("stock", $result);
        $this->assertEquals(5, $result["stock"]);
        $this->assertEquals("Laptop Asus ROG", $result["name"]);
    }

    public function test_agent_loop_stops_when_token_budget_exceeded(): void
    {
        $stockToolMock = $this->createMock(\StockTool::class);
        
        // Inisialisasi AgentLoop dengan budget token minimal (10 token) untuk memicu guardrail
        $agent = new \AgentLoop("fake-api-key", $stockToolMock, maxIterations: 5, maxTokenBudget: 10);
        
        $output = $agent->run("Cari stok Laptop");

        $this->assertStringContainsString("PERINGATAN: Loop dihentikan otomatis", $output);
    }
}

Cara Kerja AI Agent (Agent Loop)

AI Agent modern bekerja dalam sebuah siklus iteratif yang disebut Agent Loop. Loop ini terus berputar hingga goal tercapai atau batas iterasi terlampaui.

1. Observe (Amati): Agent menerima input dari user dan mengumpulkan informasi dari lingkungan (memory, hasil tool sebelumnya).
2. Think (Pikir): LLM memproses semua konteks dan memutuskan langkah terbaik selanjutnya.
3. Plan (Rencanakan): Agent merancang urutan aksi yang diperlukan untuk mencapai goal.
4. Act (Bertindak): Agent mengeksekusi aksi — memanggil tool, mengakses database, atau menghasilkan respons.
5. Reflect (Refleksi): Agent mengevaluasi hasil dari aksi dan memutuskan apakah perlu iterasi lagi atau tujuan sudah tercapai.

Estimasi Pemakaian Token & Pencegahan Pembengkakan Kuota cURL API

Pada setiap iterasi Agent Loop, seluruh riwayat pesan sebelumnya (System Message, User Message, Tool Calls, dan Tool Response) dikirimkan kembali secara eksponensial ke API LLM. Jika hasil eksekusi Tool mengembalikan data berukuran besar (misalnya respons JSON database ratusan baris), pemakaian token prompt (prompt_tokens) akan membengkak drastis yang berpotensi menghabiskan kuota API cURL secara tak terkendali.

Untuk mengendalikan pemakaian kuota token dan mencegah error Context Length Exceeded dalam ekosistem PHP, terapkan 4 pilar pembatasan token (Token Budgeting & Truncation Guardrails) berikut:

• Akumulasi Token Real-time (Usage Object): Ambil data \$response["usage"]["total_tokens"] dari payload balasan API cURL pada setiap iterasi untuk memantau konsumsi token secara presisi.
• Estimasi Token Heuristik (Pre-flight Check): Sebelum mengirim request cURL, perkirakan jumlah token prompt dengan rumus sederhana ceil(mb_strlen(\$jsonText) / 3.5) sebagai guardrail awal.
• Max Token Budgeting: Tentukan batas maksimum konsumsi token per alur kerja Agent (misal 8.000 token). Hentikan iterasi secara aman jika akumulasi mendekati batas budget.
• Sanitasi & Output Truncation Tool: Batasi panjang respons JSON dari fungsi database/tool (misal mb_substr(\$json, 0, 1500)) sebelum disuntikkan ke dalam array \$messages.

Penanganan cURL Timeout & Eksekusi Asynchronous di PHP

Proses eksekusi Agent Loop sering kali melibatkan pemanggilan LLM API dan Tool eksternal yang membutuhkan waktu (*long-running requests*). Untuk menjaga kestabilan aplikasi PHP di lingkungan produksi, Anda harus mengonfigurasi batas waktu HTTP cURL secara tepat:

• CURLOPT_TIMEOUT: Batas maksimum total waktu eksekusi cURL dalam detik (disarankan 30 hingga 60 detik untuk pemanggilan LLM kompleks).
• CURLOPT_CONNECTTIMEOUT: Batas waktu maksimal saat mencoba melakukan handshaking jaringan ke server API (disarankan 5 hingga 10 detik).

Untuk aplikasi web berskala besar dengan ribuan pengguna simultan, mengeksekusi Agent Loop secara synchronous (blocking) dapat menghabiskan *worker process* web server. PHP modern menawarkan beberapa alternatif arsitektur Asynchronous & Non-blocking:

• PHP Fibers (Native PHP 8.1+): Mendukung arsitektur *cooperative concurrency* bawaan tanpa dependensi ekstensi C tambahan, sangat cocok digunakan bersama HTTP Client async seperti Guzzle Promises atau ReactPHP.
• Swoole / OpenSwoole: Ekstensi C berperforma sangat tinggi yang mengubah PHP menjadi event-driven async server (mirip Node.js), mampu menangani puluhan ribu Agent Loop secara bersamaan dengan memori minimal.
• RoadRunner: Application server berbasis Go (*Golang-powered*) yang menjaga skrip PHP tetap resident di memori (*long-lived workers*), menghapus overhead inisialisasi framework pada setiap iterasi Agent Loop.

Komponen Utama AI Agent dalam Ekosistem PHP

Setiap AI Agent yang fungsional dalam lingkungan PHP dibangun dari empat komponen inti:

• LLM (Large Language Model): "Otak" agent. Bertanggung jawab untuk memahami instruksi, bernalar, dan memutuskan aksi. Contoh: GPT-4o, Claude, Gemini via API call.
• Tools: "Tangan" agent. Fungsi PHP, PDO query, atau REST API client yang dapat dipanggil agent untuk berinteraksi dengan dunia nyata.
• Memory: "Ingatan" agent. Menyimpan riwayat percakapan dalam Session PHP (short-term) atau Vector Database (long-term).
• Planning Module: "Strategi" agent. Kemampuan untuk memecah goal besar menjadi sub-task yang dapat dieksekusi oleh skrip PHP.

Arsitektur Integrasi RAG (Retrieval-Augmented Generation) & Vector Database

Untuk memberikan daya ingat jangka panjang (*long-term memory*) dan pemahaman dokumen bisnis internal kepada AI Agent tanpa melampaui batas *context window* LLM, Anda dapat menerapkan arsitektur RAG (Retrieval-Augmented Generation) terintegrasi dengan Vector Database:

Dalam ekosistem PHP, Anda dapat menggunakan extension pgvector pada PostgreSQL atau REST API Client untuk Qdrant / Pinecone untuk melakukan pencarian kemiripan vektor (*vector similarity search*) dengan latensi rendah di bawah 50ms.

Berikut adalah 3 langkah teknis utama dalam mengimplementasikan RAG pada skrip PHP:

1. Chunking & Vector Embedding: Teks dokumen dipotong menjadi potongan kecil (misal 500 karakter per chunk), kemudian dikonversi menjadi array vektor angka numerik 1536-dimensi menggunakan API text-embedding-3-small OpenAI.
2. Cosine Similarity Retrieval: Saat user mengirimkan pertanyaan, pertanyaan tersebut di-embed menjadi vektor dan dibandingkan dengan ribuan vektor dokumen di database menggunakan algoritma kemiripan jarak kosinus (Cosine Similarity).
3. Prompt Context Augmentation: Top-K potongan teks yang paling relevan (misal 3 chunk terbaik) disuntikkan ke dalam array $messages sebagai *System Context* sebelum memanggil Agent Loop.

Contoh Penggunaan AI Agent di Dunia Nyata

AI Agent bukan sekadar teori — saat ini sudah banyak implementasi nyata yang mengubah cara kerja industri:

• GitHub Copilot Agent: Membaca codebase, memahami bug, membuat pull request perbaikan secara otomatis.
• Customer Support Agent: Membaca tiket keluhan, mengecek riwayat pesanan di database, memberikan solusi, dan mengekskalasi jika perlu.
• Research Agent: Mencari informasi dari berbagai sumber web, merangkum, dan menyusun laporan penelitian.
• DevOps Agent: Memonitor server, mendeteksi anomali, dan menjalankan tindakan pemulihan secara otomatis.
• E-commerce Agent: Menganalisis tren penjualan, menyesuaikan harga, dan mengirim notifikasi restock secara otomatis.