Panduan Lengkap Membangun AI Agent dengan Laravel Tool Calling

Chatbot tradisional punya keterbatasan besar. Mereka hanya bisa memberikan respons tekstual tanpa kemampuan mengeksekusi aksi nyata. Pengguna bertanya tentang stok produk, chatbot menjawab dengan teks. Pengguna ingin melakukan booking, chatbot kembali memberikan instruksi manual. Padahal di era AI modern, bot seharusnya bisa melakukan tindakan langsung seperti mengecek database, mengirim email, atau memproses transaksi.

Di sinilah konsep AI agent dengan tool calling menjadi game changer. AI tidak lagi sekadar berbicara, tapi juga bertindak. Artikel ini akan membahas cara membangun AI agent dengan Laravel yang mampu mengeksekusi aksi nyata melalui tool calling. Cocok untuk developer PHP yang ingin membawa aplikasi mereka ke level berikutnya.

Apa Itu Tool Calling dalam AI Agent

Tool calling adalah mekanisme yang memungkinkan AI model untuk memanggil fungsi eksternal secara terstruktur. Alih-alih menghasilkan teks bebas, AI menghasilkan JSON yang berisi nama fungsi dan parameter yang diperlukan. Aplikasi kemudian mengeksekusi fungsi tersebut dan mengembalikan hasilnya ke AI.

Bayangkan skenario sederhana. Pengguna bertanya "Berapa stok laptop ASUS Rog saat ini?" Tanpa tool calling, AI hanya bisa menjawab berdasarkan knowledge base yang sudah outdated. Dengan tool calling, AI memanggil fungsi check_stock('laptop', 'ASUS Rog') yang query database secara real-time dan memberikan jawaban akurat.

Prosesnya terdiri dari beberapa langkah yang saling terhubung. Pertama, pengguna mengirim pesan ke AI. Kedua, AI memutuskan apakah perlu memanggil tool tertentu. Ketiga, jika ya, AI menghasilkan structured output berisi nama fungsi dan parameter. Keempat, aplikasi mengeksekusi fungsi tersebut. Kelima, hasil eksekusi dikirim kembali ke AI untuk diproses menjadi respons natural language.

Mengapa Laravel Ideal untuk AI Agent

Laravel memiliki ekosistem yang matang untuk membangun AI agent. Fitur HTTP client yang elegant memudahkan integrasi dengan berbagai AI provider seperti OpenAI, Anthropic, atau Groq. Sistem queue yang robust cocok untuk menangani operasi tool calling yang membutuhkan waktu lebih lama.

Architecture Laravel yang modular memungkinkan separation of concerns yang jelas. Tool definitions bisa ditempatkan di dedicated classes, business logic tetap di services, dan routing tetap bersih. Tidak lupa dokumentasi yang komprehensif dan komunitas yang aktif di Indonesia menjadikan learning curve lebih landai.

Kesulitan dengan tugas programming atau butuh bantuan coding? KerjaKode siap membantu menyelesaikan tugas IT dan teknik informatika Anda. Dapatkan bantuan profesional di jasa tugas IT KerjaKode.

Setup Environment Laravel untuk AI Agent

Persiapan dimulai dengan instalasi Laravel fresh project. Pastikan PHP versi 8.2 atau lebih tinggi sudah terinstall bersama Composer. Buka terminal dan jalankan command untuk membuat project baru.

composer create-project laravel/laravel ai-agent-laravel
cd ai-agent-laravel

Selanjutnya install package OpenAI PHP SDK yang akan menjadi jembatan komunikasi dengan AI model. Package ini official dari OpenAI dan sangat well-maintained.

composer require openai-php/client

Konfigurasi API key di file environment. Tambahkan credential OpenAI atau provider AI pilihan Anda. Jika menggunakan provider lain seperti Groq atau Anthropic, sesuaikan base URL dan parameter autentikasi.

OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1

Struktur Direktori untuk AI Agent

Organisasi folder yang rapi akan memudahkan pengembangan AI agent yang kompleks. Buat direktori khusus untuk menampung tools dan services terkait AI.

app/
├── AI/
│   ├── Tools/
│   │   ├── CheckStockTool.php
│   │   ├── SendEmailTool.php
│   │   └── ToolInterface.php
│   └── AgentService.php
├── Http/
│   └── Controllers/
│       └── ChatController.php

Interface ToolInterface menjadi kontrak yang harus dipenuhi setiap tool. Ini memastikan konsistensi dalam pendefinisian tool dan memudahkan tool discovery otomatis.

Implementasi Tool Calling Sederhana

Mulai dengan mendefinisikan interface untuk semua tools. Interface ini memastikan setiap tool memiliki method yang diperlukan oleh AI agent.

<?php

namespace App\AI\Tools;

interface ToolInterface
{
    public function getName(): string;
    public function getDescription(): string;
    public function getParameters(): array;
    public function execute(array $arguments): mixed;
}

Implementasi tool pertama adalah CheckStockTool. Tool ini akan mengecek ketersediaan stok produk dari database.

<?php

namespace App\AI\Tools;

use App\Models\Product;
use Illuminate\Support\Facades\Log;

class CheckStockTool implements ToolInterface
{
    public function getName(): string
    {
        return 'check_stock';
    }

    public function getDescription(): string
    {
        return 'Mengecek ketersediaan stok produk berdasarkan nama atau SKU';
    }

    public function getParameters(): array
    {
        return [
            'type' => 'object',
            'properties' => [
                'product_name' => [
                    'type' => 'string',
                    'description' => 'Nama produk yang ingin dicek stoknya',
                ],
                'sku' => [
                    'type' => 'string',
                    'description' => 'SKU produk (opsional jika nama sudah cukup)',
                ],
            ],
            'required' => ['product_name'],
        ];
    }

    public function execute(array $arguments): mixed
    {
        $productName = $arguments['product_name'] ?? '';
        $sku = $arguments['sku'] ?? null;

        $query = Product::query();

        if ($sku) {
            $product = $query->where('sku', $sku)->first();
        } else {
            $product = $query->where('name', 'LIKE', "%{$productName}%")->first();
        }

        if (!$product) {
            return ['error' => 'Produk tidak ditemukan'];
        }

        return [
            'product_name' => $product->name,
            'stock' => $product->stock,
            'price' => $product->price,
            'status' => $product->stock > 0 ? 'Tersedia' : 'Habis',
        ];
    }
}

Membuat Agent Service

AgentService menjadi otak yang mengkoordinasi komunikasi dengan AI dan eksekusi tools. Class ini bertanggung jawab mengirim message ke AI, m parsing tool calls, dan mengeksekusi tools yang diperlukan.

<?php

namespace App\AI;

use App\AI\Tools\ToolInterface;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class AgentService
{
    private array $tools = [];
    private string $systemPrompt;

    public function __construct()
    {
        $this->systemPrompt = "Anda adalah asisten AI yang membantu pelanggan. 
            Gunakan tool yang tersedia untuk memberikan informasi akurat dan real-time.
            Jawab dalam Bahasa Indonesia yang sopan dan informatif.";
    }

    public function registerTool(ToolInterface $tool): self
    {
        $this->tools[$tool->getName()] = $tool;
        return $this;
    }

    public function getToolSchemas(): array
    {
        $schemas = [];
        foreach ($this->tools as $tool) {
            $schemas[] = [
                'type' => 'function',
                'function' => [
                    'name' => $tool->getName(),
                    'description' => $tool->getDescription(),
                    'parameters' => $tool->getParameters(),
                ],
            ];
        }
        return $schemas;
    }

    public function chat(string $userMessage): string
    {
        $messages = [
            ['role' => 'system', 'content' => $this->systemPrompt],
            ['role' => 'user', 'content' => $userMessage],
        ];

        $response = $this->callAI($messages, $this->getToolSchemas());
        $assistantMessage = $response['choices'][0]['message'];

        if (isset($assistantMessage['tool_calls'])) {
            $messages[] = $assistantMessage;

            foreach ($assistantMessage['tool_calls'] as $toolCall) {
                $toolName = $toolCall['function']['name'];
                $arguments = json_decode($toolCall['function']['arguments'], true);

                if (isset($this->tools[$toolName])) {
                    $result = $this->tools[$toolName]->execute($arguments);
                    
                    $messages[] = [
                        'role' => 'tool',
                        'tool_call_id' => $toolCall['id'],
                        'content' => json_encode($result),
                    ];
                }
            }

            $finalResponse = $this->callAI($messages, $this->getToolSchemas());
            return $finalResponse['choices'][0]['message']['content'] ?? 'Maaf, terjadi kesalahan.';
        }

        return $assistantMessage['content'] ?? 'Maaf, saya tidak dapat memproses permintaan Anda.';
    }

    private function callAI(array $messages, array $tools): array
    {
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . env('OPENAI_API_KEY'),
            'Content-Type' => 'application/json',
        ])->post(env('OPENAI_BASE_URL') . '/chat/completions', [
            'model' => 'gpt-4o-mini',
            'messages' => $messages,
            'tools' => $tools,
            'tool_choice' => 'auto',
        ]);

        return $response->json();
    }
}

Controller untuk Chat Endpoint

Buat controller yang menangani request dari frontend dan mengembalikan respons AI agent.

<?php

namespace App\Http\Controllers;

use App\AI\AgentService;
use App\AI\Tools\CheckStockTool;
use Illuminate\Http\Request;

class ChatController extends Controller
{
    public function chat(Request $request)
    {
        $request->validate([
            'message' => 'required|string|max:1000',
        ]);

        $agent = new AgentService();
        $agent->registerTool(new CheckStockTool());

        $response = $agent->chat($request->message);

        return response()->json([
            'response' => $response,
        ]);
    }
}

Route untuk endpoint chat didefinisikan di file routes/web.php atau routes/api.php sesuai kebutuhan.

use App\Http\Controllers\ChatController;

Route::post('/chat', [ChatController::class, 'chat']);

Best Practices untuk Production

Security harus menjadi prioritas utama saat mengeksekusi tool calls. Selalu validasi dan sanitasi semua parameter yang diterima dari AI. Jangan pernah trust input secara langsung meskipun berasal dari AI model. Implementasi rate limiting untuk mencegah abuse dan logging untuk audit trail.

Error handling yang robust sangat penting. Tool bisa gagal karena berbagai alasan seperti database connection timeout, invalid parameters, atau external service down. Tangani semua skenario error dengan graceful degradation dan berikan feedback yang informatif ke AI untuk respons yang lebih baik ke pengguna.

Monitoring dan observability tidak boleh diabaikan. Setiap tool call harus di-logging dengan informasi lengkap termasuk execution time, parameters, dan hasilnya. Ini membantu debugging dan optimasi performa. Gunakan Laravel Telescope atau custom logging solution untuk visibility yang lebih baik.

Optimasi Performa

Latency adalah musuh utama AI agent. Setiap tool call menambah waktu respons secara keseluruhan. Cache hasil tool call yang sering diakses dan jarang berubah. Misalnya, informasi produk yang stoknya tidak berubah setiap detik bisa di-cache selama beberapa menit.

Untuk tool yang membutuhkan waktu lama, pertimbangkan asynchronous execution menggunakan Laravel Queue. Pengguna mendapat respons sementara bahwa permintaan sedang diproses, dan notifikasi dikirim ketika hasil sudah siap. Ini meningkatkan user experience secara signifikan.

Choice of AI model juga berpengaruh pada performa dan cost. Model seperti GPT-4o-mini menawarkan balance yang baik antara kemampuan tool calling, kecepatan, dan harga. Untuk use case sederhana, model yang lebih ringan sudah cukup. Untuk reasoning yang kompleks, model yang lebih powerful mungkin diperlukan.

Testing Tool Calling

Testing adalah bagian kritis dari development AI agent. Setiap tool harus memiliki unit test yang memverifikasi behavior dalam berbagai skenario termasuk edge cases dan error conditions.

<?php

namespace Tests\Unit\AI\Tools;

use App\AI\Tools\CheckStockTool;
use App\Models\Product;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class CheckStockToolTest extends TestCase
{
    use RefreshDatabase;

    private CheckStockTool $tool;

    protected function setUp(): void
    {
        parent::setUp();
        $this->tool = new CheckStockTool();
    }

    public function test_execute_returns_product_info_when_found()
    {
        $product = Product::factory()->create([
            'name' => 'Laptop ASUS ROG',
            'stock' => 10,
            'price' => 15000000,
        ]);

        $result = $this->tool->execute(['product_name' => 'ASUS ROG']);

        $this->assertEquals('Laptop ASUS ROG', $result['product_name']);
        $this->assertEquals(10, $result['stock']);
        $this->assertEquals('Tersedia', $result['status']);
    }

    public function test_execute_returns_error_when_not_found()
    {
        $result = $this->tool->execute(['product_name' => 'Produk Tidak Ada']);

        $this->assertArrayHasKey('error', $result);
        $this->assertEquals('Produk tidak ditemukan', $result['error']);
    }
}

Expanding Tool Capabilities

Keindahan arsitektur tool calling adalah skalabilitasnya. Menambah kemampuan baru semudah membuat class baru yang mengimplementasi ToolInterface. Ingin menambah kemampuan mengirim email? Buat SendEmailTool. Perlu integrasi dengan payment gateway? Buat ProcessPaymentTool.

Setiap tool sebaiknya focused pada satu responsibility. Tool yang melakukan terlalu banyak hal akan sulit di-test dan di-maintain. Jika sebuah tool perlu melakukan multiple operations, pertimbangkan untuk memecahnya menjadi beberapa tool yang lebih kecil.

Tool discovery bisa di-automasi dengan reflection atau configuration file. Ini memudahkan penambahan tool baru tanpa perlu mengubah AgentService secara manual. Laravel's service container bisa dimanfaatkan untuk dependency injection ke dalam tools.

Kesimpulan

Tool calling membuka dimensi baru dalam pengembangan aplikasi berbasis AI. Laravel dengan ekosistemnya yang matang menjadi pilihan solid untuk mengimplementasikan konsep ini. Arsitektur yang modular memudahkan pengembangan dan maintenance AI agent yang complex.

Dari chatbot pasif yang hanya bisa berbicara, kini aplikasi bisa memiliki AI agent proaktif yang mampu mengeksekusi aksi nyata. Mulai dari mengecek stok, memproses transaksi, hingga mengirim notifikasi. Kemungkinannya terbatas hanya oleh imajinasi dan kebutuhan bisnis Anda.

Langkah selanjutnya adalah bereksperimen dengan tools yang lebih complex. Coba integrasikan dengan third-party APIs, implementasi multi-step tool calls, atau bahkan biarkan AI memilih tool yang optimal dari kandidat yang tersedia. Era AI agent yang actionable sudah dimulai, dan Laravel developer di Indonesia sudah siap untuk menjadi bagian darinya.