Mengenal Tools pada AI Agent PHP

Terakhir diperbarui: 22 Agustus 2026

Mengenal Tools pada AI Agent PHP: Konsep & Definisi

Secara konsep, Large Language Model (LLM) seperti GPT-4 hanya memiliki pengetahuan statis sampai batas waktu pelatihannya (*knowledge cutoff*) dan tidak memiliki akses ke dunia luar. Tool pada AI Agent PHP adalah fungsi atau method PHP yang didaftarkan agar LLM dapat berinteraksi dengan lingkungan eksternal — seperti membaca database MySQL, memeriksa cuaca real-time, mengakses API pembayaran, hingga membaca sistem file server Linux.

Dengan tools, AI Agent bertransformasi dari sekadar generator teks pasif menjadi agen otonom yang mampu melakukan aksi nyata (*action-oriented AI*).

| Fitur & Karakteristik | Chatbot Standar (Text Only) | AI Agent dengan Function Calling |
| :--- | :--- | :--- |
| **Akses Data Real-Time** | ❌ Terbatas knowledge cutoff | ✅ Akses database, API, & file system |
| **Akurasi Perhitungan** | ⚠️ Rawan halusinasi numerik | ✅ Presisi 100% via eksekusi kalkulator PHP |
| **Aksi Operasional Server** | ❌ Tidak bisa melakukan mutasi | ✅ Bisa kirim email, manipulasi file, eksekusi CLI |
| **Penanganan Multi-Step** | ❌ Single-turn response | ✅ Parallel multi-tool reasoning loops |
| **Format Output** | 📝 Teks bebas (Unstructured) | ⚙️ JSON Schema terstruktur (*Strict Mode*) |

Cara Kerja Function Calling pada AI Agent PHP

Proses pemanggilan tool bekerja dalam siklus komunikasi dua arah (*handshake protocol*) yang terstruktur antara aplikasi PHP Anda dan OpenAI Chat Completions API.

Diagram Arsitektur: Alur Eksekusi Parallel Function Calling AI Agent PHP

WebP Lossless • 59 KB • Multimodal Ready

1. Mendefinisikan Interface & JSON Schema Tools AI Agent

Setiap tool wajib mengimplementasikan interface standar agar agent dapat mengekstrak metadata JSON Schema dan mengeksekusinya secara konsisten:

<?php

namespace App\Tools;

interface ToolInterface
{
    /**
     * Definisi metadata fungsi dalam format JSON Schema standar OpenAI.
     */
    public function getDefinition(): array;

    /**
     * Logika eksekusi method PHP saat dipanggil oleh model AI.
     */
    public function execute(array $args): mixed;
}

<?php

namespace App\Tools;

class WeatherTool implements ToolInterface
{
    public function getDefinition(): array
    {
        return [
            'type'     => 'function',
            'function' => [
                'name'        => 'get_weather',
                'description' => 'Mendapatkan informasi cuaca terkini dan prakiraan untuk kota tertentu.',
                'parameters'  => [
                    'type'       => 'object',
                    'properties' => [
                        'city' => [
                            'type'        => 'string',
                            'description' => 'Nama kota yang ingin dicari informasinya, misal: Jakarta, Bandung, Surabaya.',
                        ],
                        'unit' => [
                            'type'        => 'string',
                            'enum'        => ['celsius', 'fahrenheit'],
                            'description' => 'Satuan temperatur (default: celsius).',
                        ],
                    ],
                    'required' => ['city'],
                ],
            ],
        ];
    }

    public function execute(array $args): mixed
    {
        $city = $args['city'] ?? 'Jakarta';
        $unit = $args['unit'] ?? 'celsius';

        return [
            'city'        => $city,
            'temperature' => 31,
            'unit'        => $unit,
            'condition'   => 'Cerah Berawan',
            'humidity'    => '70%',
            'timestamp'   => date('Y-m-d H:i:s'),
        ];
    }
}

2. Menangani Multi-Tool Calls Array (Parallel Function Calling) di PHP

Model AI canggih seperti GPT-4o memiliki fitur Parallel Tool Calling. Ketika pengguna memberikan instruksi ganda (contoh: "Bandingkan cuaca di Jakarta dan Tokyo sekaligus"), OpenAI tidak mengembalikan satu pemanggilan, melainkan array tool_calls yang berisi beberapa objek fungsi secara simultan.

Backend PHP wajib melakukan perulangan (foreach) dan mengembalikan pesan respons untuk setiap tool_call_id sebelum melanjutkan ke iterasi berikutnya:

<?php

namespace App\Agent;

class MultiToolHandler
{
    /**
     * Memproses array tool_calls paralel dari OpenAI API.
     */
    public function handleParallelToolCalls(array $toolCalls, array $toolRegistry, array &$messages): void
    {
        echo "Ditemukan " . count($toolCalls) . " permintaan tool secara simultan:\n";

        foreach ($toolCalls as $toolCall) {
            $callId   = $toolCall['id'];
            $funcName = $toolCall['function']['name'];
            $args     = json_decode($toolCall['function']['arguments'], true) ?? [];

            echo "  [Executing ID: {$callId}] Memanggil fungsi: {$funcName}...\n";

            // 1. Cari instance tool yang cocok di registry
            if (!isset($toolRegistry[$funcName])) {
                $toolOutput = ['status' => 'error', 'message' => "Tool '{$funcName}' tidak terdaftar."];
            } else {
                try {
                    $toolOutput = $toolRegistry[$funcName]->execute($args);
                } catch (\Throwable $e) {
                    $toolOutput = ['status' => 'error', 'message' => $e->getMessage()];
                }
            }

            // 2. Wajib: Sematkan respon dengan role 'tool' dan matching 'tool_call_id'
            $messages[] = [
                'role'         => 'tool',
                'tool_call_id' => $callId,
                'content'      => json_encode($toolOutput, JSON_UNESCAPED_UNICODE),
            ];
        }

        echo "Seluruh " . count($toolCalls) . " hasil tool berhasil dirangkai ke konteks memori.\n";
    }
}

3. Studi Kasus Penanganan Error pada Tools AI Agent (Error Handling)

Salah satu kesalahan fatal pada pembuatan AI Agent adalah membiarkan aplikasi PHP mengalami fatal error atau unhandled exception saat tool gagal. Alih-alih menghentikan program, tangkap eksepsi dan kembalikan ke model AI dalam format JSON error. Model AI yang cerdas akan membaca pesan error tersebut dan mencoba strategi alternatif (*Self-Correction*):

<?php

namespace App\Agent;

use App\Tools\ToolInterface;

class SafeToolExecutor
{
    public function executeSafely(ToolInterface $tool, array $args, string $callId): array
    {
        try {
            if (empty($args)) {
                throw new \InvalidArgumentException("Argumen pemanggilan tool tidak boleh kosong.");
            }

            $result = $tool->execute($args);

            return [
                'role'         => 'tool',
                'tool_call_id' => $callId,
                'content'      => json_encode([
                    'status' => 'success',
                    'data'   => $result,
                ], JSON_UNESCAPED_UNICODE),
            ];
        } catch (\Throwable $e) {
            return [
                'role'         => 'tool',
                'tool_call_id' => $callId,
                'content'      => json_encode([
                    'status'  => 'error',
                    'message' => $e->getMessage(),
                    'hint'    => 'Coba periksa kembali parameter input atau gunakan nilai fallback.',
                ], JSON_UNESCAPED_UNICODE),
            ];
        }
    }
}

4. Praktik Implementasi Tools via Guzzle HTTP & OpenAI PHP SDK

Untuk mempraktikkan Function Calling secara langsung di ekosistem backend PHP, Anda dapat memilih antara pendekatan native menggunakan Guzzle HTTP Client atau memanfaatkan OpenAI PHP SDK:

<?php

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

use GuzzleHttp\Client;
use App\Tools\WeatherTool;

$client = new Client([
    'base_uri' => 'https://api.openai.com/v1/',
    'headers'  => [
        'Authorization' => 'Bearer ' . getenv('OPENAI_API_KEY'),
        'Content-Type'  => 'application/json',
    ],
    'timeout'  => 30.0,
]);

$weatherTool = new WeatherTool();
$tools = [$weatherTool->getDefinition()];

$response = $client->post('chat/completions', [
    'json' => [
        'model'       => 'gpt-4o-mini',
        'messages'    => [
            ['role' => 'user', 'content' => 'Berapa suhu cuaca di Bandung hari ini?'],
        ],
        'tools'       => $tools,
        'tool_choice' => 'auto',
    ],
]);

$data    = json_decode($response->getBody()->getContents(), true);
$message = $data['choices'][0]['message'];

if (!empty($message['tool_calls'])) {
    $toolCall = $message['tool_calls'][0];
    $args     = json_decode($toolCall['function']['arguments'], true);

    $toolResult = $weatherTool->execute($args);

    $finalResponse = $client->post('chat/completions', [
        'json' => [
            'model'    => 'gpt-4o-mini',
            'messages' => [
                ['role' => 'user', 'content' => 'Berapa suhu cuaca di Bandung hari ini?'],
                $message,
                [
                    'role'         => 'tool',
                    'tool_call_id' => $toolCall['id'],
                    'content'      => json_encode($toolResult),
                ],
            ],
        ],
    ]);

    $finalData = json_decode($finalResponse->getBody()->getContents(), true);
    echo "Jawaban Final:\n" . $finalData['choices'][0]['message']['content'] . "\n";
}

FAQ: Pertanyaan Umum Seputar Tools & Function Calling AI Agent PHP