Panduan praktis membuat tool pertama untuk AI Agent PHP: merancang JSON Schema, mengimplementasikan class tool, mengujinya secara unit, dan mengintegrasikannya ke dalam Agent.
Daftar Isi
- TL;DR — Ringkasan Membuat Tool Pertama AI Agent PHP
- Membuat Tool Kalkulator Pertama untuk AI Agent PHP
- Implementasi ToolInterface: Kontrak Standar Tool AI Agent PHP
- Implementasi Lengkap Class CalculatorTool di PHP
- Mengintegrasikan Tool Kalkulator ke dalam Loop AI Agent
- Pengujian Otomatis CalculatorTool Menggunakan PHPUnit
- Best Practices Pengembangan Tool AI Agent PHP
- FAQ: Pertanyaan Umum Seputar Pembuatan Tool AI Agent PHP
- 1. Bagaimana cara membuat tool pertama untuk AI Agent PHP?
- 2. Mengapa AI Agent PHP membutuhkan tool kalkulator eksternal?
- 3. Apa fungsi array required pada definisi JSON Schema tool?
- 4. Bagaimana jika tool PHP mengalami error saat dieksekusi?
Terakhir diperbarui:
TL;DR — Ringkasan Membuat Tool Pertama AI Agent PHP
- ToolInterface: Kontrak OOP wajib dengan dua method kunci:
getDefinition()untuk mengekspos skema JSON danexecute()untuk menjalankan kalkulasi PHP lokal. - Flow Komunikasi: LLM bertindak sebagai otak yang memilih tool dan merumuskan argumen JSON, sedangkan PHP Runtime bertindak sebagai eksekutor fungsi nyata.
- Deskripsi Presisi: Kualitas deskripsi pada skema
parametersmenentukan tingkat akurasi LLM dalam memanggil tool tanpa halusinasi numerik. - Defensive Execution: Selalu validasi tipe data input dan lindungi operasi matematika berisiko (seperti pembagian atau modulo dengan nol).
Membuat Tool Kalkulator Pertama untuk AI Agent PHP
Model AI seperti GPT-4 sangat handal dalam memahami bahasa alami, namun sering mengalami halusinasi (*calculation error*) saat dihadapkan pada perhitungan numerik kompleks, persentase multi-langkah, atau manipulasi data presisi. Dalam ekosistem AI Agent PHP, kita mengatasi keterbatasan ini dengan memberikan Tool Pertama berupa kalkulator matematika deterministik berbasis PHP native.
+-----------------------------------------------------------------------------------+
| PENGGUNA / USER PROMPT |
| "Hitung berapa 15% dari 2.450.000 + 350.000" |
+-----------------------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------------------+
| OPENAI LLM (Decision & Argument Synthesis) |
| - Menganalisis kebutuhan aritmatika |
| - Memilih tool: "calculate" |
| - Menghasilkan tool_calls: { operation: "add", a: 367500, b: 350000 } |
+-----------------------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------------------+
| PHP AGENT CORE (ToolInterface Dispatcher) |
| - getDefinition(): Validasi JSON Schema |
| - execute(args): Panggil App\Tools\CalculatorTool |
+-----------------------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------------------+
| RUNTIME PHP EKSEKUSI (Deterministic Math Evaluation) |
| - (float) $a = 367500; (float) $b = 350000; |
| - match ($operation) => $result = 717500; |
| - JSON Response: {"status":"success","result":717500,"expression":"..."} |
+-----------------------------------------------------------------------------------+
|
v
+-----------------------------------------------------------------------------------+
| LLM FINAL RESPONSE SYNTHESIS |
| "Hasil 15% dari 2.450.000 (367.500) ditambah 350.000 adalah 717.500." |
+-----------------------------------------------------------------------------------+One-line Takeaway: Diagram teks ASCII memudahkan ekstraksi struktural oleh LLM scraper dan memperkaya konteks semantik halaman.
Implementasi ToolInterface: Kontrak Standar Tool AI Agent PHP
Untuk memastikan modularitas dan kemudahan penambahan (*pluggability*) berbagai tools di masa depan, seluruh tool wajib tunduk pada sebuah interface kontrak standar. Interface ini memisahkan dua tanggung jawab utama: Discovery (skema fungsi untuk LLM) dan Execution (pemrosesan logika PHP):
<?php
namespace App\Tools;
interface ToolInterface
{
/**
* Mengembalikan spesifikasi JSON Schema fungsi yang dipahami OpenAI API.
*
* @return array{type: string, function: array{name: string, description: string, parameters: array}}
*/
public function getDefinition(): array;
/**
* Mengeksekusi logika komputasi PHP asli saat dipanggil oleh model AI.
*
* @param array<string, mixed> $args Argumen terurai dari payload tool_calls
* @return mixed Hasil evaluasi fungsi yang siap di-serialize ke JSON
*/
public function execute(array $args): mixed;
}Implementasi Lengkap Class CalculatorTool di PHP
Berikut adalah implementasi konkrit class CalculatorTool yang mendukung 6 jenis operasi aritmatika dengan proteksi validasi pembagian/modulo nol secara anggun (*graceful error handling*):
<?php
namespace App\Tools;
class CalculatorTool implements ToolInterface
{
public function getDefinition(): array
{
return [
'type' => 'function',
'function' => [
'name' => 'calculate',
'description' => 'Melakukan operasi matematika presisi: penjumlahan, pengurangan, perkalian, pembagian, perpangkatan, dan modulo. Gunakan tool ini untuk setiap kalkulasi numerik agar hasil 100% akurat.',
'parameters' => [
'type' => 'object',
'properties' => [
'operation' => [
'type' => 'string',
'enum' => ['add', 'subtract', 'multiply', 'divide', 'power', 'modulo'],
'description' => 'Jenis operasi: add (+), subtract (-), multiply (*), divide (/), power (^), modulo (%)',
],
'a' => [
'type' => 'number',
'description' => 'Operand pertama (angka kiri)',
],
'b' => [
'type' => 'number',
'description' => 'Operand kedua (angka kanan)',
],
],
'required' => ['operation', 'a', 'b'],
],
],
];
}
public function execute(array $args): mixed
{
// 1. Validasi & normalisasi tipe data input
$operation = $args['operation'] ?? '';
$a = (float) ($args['a'] ?? 0);
$b = (float) ($args['b'] ?? 0);
// 2. Evaluasi aritmatika deterministik
return match ($operation) {
'add' => ['status' => 'success', 'result' => $a + $b, 'expression' => "$a + $b = " . ($a + $b)],
'subtract' => ['status' => 'success', 'result' => $a - $b, 'expression' => "$a - $b = " . ($a - $b)],
'multiply' => ['status' => 'success', 'result' => $a * $b, 'expression' => "$a × $b = " . ($a * $b)],
'divide' => $b !== 0.0
? ['status' => 'success', 'result' => $a / $b, 'expression' => "$a ÷ $b = " . ($a / $b)]
: ['status' => 'error', 'message' => 'Pembagian dengan nol (division by zero) tidak diperbolehkan.'],
'power' => ['status' => 'success', 'result' => $a ** $b, 'expression' => "$a ^ $b = " . ($a ** $b)],
'modulo' => $b !== 0.0
? ['status' => 'success', 'result' => fmod($a, $b), 'expression' => "$a % $b = " . fmod($a, $b)]
: ['status' => 'error', 'message' => 'Modulo dengan nol tidak diperbolehkan.'],
default => ['status' => 'error', 'message' => "Operasi matematika '{$operation}' tidak dikenali."],
};
}
}Salin skema JSON mentah berikut untuk didaftarkan langsung ke parameter tools pada payload OpenAI Chat Completions API atau System Prompt agent Anda:
{
"type": "function",
"function": {
"name": "calculate",
"description": "Melakukan operasi matematika presisi: penjumlahan, pengurangan, perkalian, pembagian, perpangkatan, dan modulo. Gunakan tool ini untuk setiap kalkulasi numerik agar hasil 100% akurat.",
"parameters": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"enum": ["add", "subtract", "multiply", "divide", "power", "modulo"],
"description": "Jenis operasi aritmatika yang akan dieksekusi: add (+), subtract (-), multiply (*), divide (/), power (^), modulo (%)"
},
"a": {
"type": "number",
"description": "Operand pertama (angka kiri)"
},
"b": {
"type": "number",
"description": "Operand kedua (angka kanan)"
}
},
"required": ["operation", "a", "b"],
"additionalProperties": false
},
"strict": true
}
}Schema Takeaway: Penggunaan "strict": true dan "additionalProperties": false menjamin model AI menghasilkan payload argumen yang patuh 100% pada tipe data skema (*Structured Outputs*).
Mengintegrasikan Tool Kalkulator ke dalam Loop AI Agent
Berikut adalah skrip eksekusi run-agent-calculator.php yang mendemonstrasikan bagaimana agent secara cerdas mendeteksi kebutuhan kalkulasi, memanggil CalculatorTool, dan menyusun jawaban komprehensif:
<?php
// run-agent-calculator.php
require_once __DIR__ . '/vendor/autoload.php';
use App\OpenAIClient;
use App\Agent\Agent;
use App\Tools\CalculatorTool;
$client = new OpenAIClient(getenv('OPENAI_API_KEY'));
$agent = new Agent($client, maxIterations: 5);
// Langkah 1: Daftarkan CalculatorTool ke Agent
$agent->registerTool(new CalculatorTool());
// Langkah 2: Berikan prompt yang membutuhkan kalkulasi presisi
$task = 'Hitung berapa 15% dari 2.450.000 kemudian tambahkan hasilnya dengan 350.000.';
echo "Task Pengguna: {$task}\n\n";
$result = $agent->run($task);
echo "=== JAWABAN FINAL AI AGENT ===\n";
echo $result . "\n";Pengujian Otomatis CalculatorTool Menggunakan PHPUnit
Dalam standar rekayasa perangkat lunak enterprise (E-E-A-T), setiap tool yang berinteraksi dengan AI Agent wajib diuji secara terisolasi via Automated Unit Testing. Hal ini memastikan tool tidak pernah menghasilkan kalkulasi salah atau memicu fatal exception tak terduga:
<?php
namespace Tests\Unit;
use PHPUnit\Framework\TestCase;
use App\Tools\CalculatorTool;
class CalculatorToolTest extends TestCase
{
private CalculatorTool $calculator;
protected function setUp(): void
{
parent::setUp();
$this->calculator = new CalculatorTool();
}
public function test_get_definition_returns_valid_openai_schema(): void
{
$schema = $this->calculator->getDefinition();
$this->assertSame('function', $schema['type']);
$this->assertSame('calculate', $schema['function']['name']);
$this->assertContains('operation', $schema['function']['parameters']['required']);
$this->assertContains('a', $schema['function']['parameters']['required']);
$this->assertContains('b', $schema['function']['parameters']['required']);
}
public function test_addition_calculation_success(): void
{
$result = $this->calculator->execute([
'operation' => 'add',
'a' => 367500,
'b' => 350000,
]);
$this->assertSame('success', $result['status']);
$this->assertSame(717500.0, (float) $result['result']);
}
public function test_division_by_zero_returns_graceful_error_payload(): void
{
$result = $this->calculator->execute([
'operation' => 'divide',
'a' => 5000,
'b' => 0,
]);
$this->assertSame('error', $result['status']);
$this->assertStringContainsString('tidak diperbolehkan', $result['message']);
}
}Menjalankan Test Suite via CLI:
./vendor/bin/phpunit tests/Unit/CalculatorToolTest.php --testdoxBest Practices Pengembangan Tool AI Agent PHP
1. Deskripsi Fungsi yang Kaya Semantik: LLM memilih tool murni berdasarkan description. Jelaskan secara eksplisit kapan fungsi harus digunakan dan format angka yang diharapkan.
2. Validasi & Type Casting Ketat: Selalu konversi tipe data (seperti (float) atau (int)) dan validasi batasan nilai argumen sebelum eksekusi.
3. Payload Error Terstruktur: Hindari mematikan script via die() atau melempar fatal exception tak tertangkap. Kembalikan array berisi status: error dan message agar AI dapat melakukan refleksi.
4. Prinsip Single Responsibility: Desain satu class tool untuk satu kapabilitas spesifik guna mencegah ambiguitas pemilihan fungsi pada AI.
FAQ: Pertanyaan Umum Seputar Pembuatan Tool AI Agent PHP
1. Bagaimana cara membuat tool pertama untuk AI Agent PHP?
Ringkasan Jawaban:Buat class PHP yang mengimplementasikanToolInterface, definisikan skema JSON parameter pada methodgetDefinition(), dan tulis logika komputasi lokal pada methodexecute().
Setelah class dibuat, cukup daftarkan instance objek tersebut ke agent menggunakan $agent->registerTool(new CalculatorTool()).
2. Mengapa AI Agent PHP membutuhkan tool kalkulator eksternal?
Ringkasan Jawaban:Large Language Model (LLM) adalah model probabilistik prediksi kata yang rawan mengalami halusinasi aritmatika pada angka besar atau persentase bertingkat.
Dengan mengeksekusi perhitungan pada runtime PHP asli, akurasi perhitungan matematis dijamin 100% presisi dan deterministik.
3. Apa fungsi array required pada definisi JSON Schema tool?
Ringkasan Jawaban:Arrayrequiredmemberitahu model AI argumen mana saja yang wajib diisi sebelum permintaan pemanggilan fungsi (tool_calls) diizinkan.
Jika pengguna belum memberikan parameter yang wajib, model AI akan meminta klarifikasi terlebih dahulu kepada pengguna alih-alih memanggil fungsi dengan data kosong.
4. Bagaimana jika tool PHP mengalami error saat dieksekusi?
Ringkasan Jawaban:Kembalikan payload JSON berupa array dengan status: error dan pesan penjelasan masalah agar model AI dapat membaca kendala tersebut dan melakukan perbaikan mandiri (Self-Correction).Jangan biarkan script PHP mengeluarkan fatal error atau melempar eksepsi mentah yang dapat menghentikan loop eksekusi otonom agent.
Rusmawan Abdullah Sani
Lead Software Engineer & System Architect
Praktisi pengembangan backend PHP modern, arsitektur AI Agent, microservices, dan otomasi server Linux. Terhubung melalui profil LinkedIn.