Site icon SUSANTOKUN

Mengenal Laravel AI SDK: Integrasi AI ke Laravel 13

SUSANTOKUN

Selama beberapa tahun, cara paling umum menambahkan fitur AI ke aplikasi Laravel adalah memanggil API provider lewat HTTP client, atau memasang paket komunitas seperti openai-php/laravel. Keduanya sah, tapi begitu kamu ingin berpindah provider atau menambah fitur seperti tool calling dan structured output, kodenya cepat berantakan.

Laravel akhirnya merilis solusi resmi: Laravel AI SDK (laravel/ai). Paket ini menyatukan akses ke OpenAI, Anthropic, Gemini, dan provider lain dalam satu antarmuka yang konsisten. Artikel ini membahas cara install, konfigurasi, sampai membuat agent pertama di project Laravel 13.

Kenapa Perlu SDK, Bukan HTTP Client Manual?

Memanggil endpoint AI secara manual sebenarnya hanya soal Http::withToken() lalu mengirim JSON. Masalahnya muncul setelah aplikasi berjalan:

SDK resmi menutup semua celah itu. Konsep intinya adalah agent: satu class PHP yang membungkus instruksi, konteks percakapan, daftar tool, dan skema output. Kamu mendefinisikannya sekali, lalu memanggilnya di mana pun dibutuhkan.

Apa Saja yang Bisa Dilakukan Laravel AI SDK?

Berdasarkan dokumentasi resminya, cakupan SDK ini cukup luas untuk aplikasi produksi:

Yang menarik, SDK ini juga mendukung failover antar provider. Jadi kalau provider utama sedang gangguan, request bisa dialihkan ke provider lain tanpa mengubah kode pemanggil.

Persyaratan

Kalau project kamu masih Laravel 11 ke bawah, SDK ini belum bisa dipakai. Untuk project baru, sebaiknya mulai dari Laravel 13 supaya tidak perlu upgrade di tengah jalan.

Langkah 1: Install Paket

composer require laravel/ai

Setelah paket terpasang, publish file konfigurasi dan migration-nya:

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

Lalu jalankan migration. Perintah ini akan membuat tabel agent_conversations dan agent_conversation_messages, yaitu tempat SDK menyimpan riwayat percakapan agent:

php artisan migrate

Dua tabel itu opsional secara fungsional, tapi jangan dimatikan kalau kamu berencana membuat fitur chat. Menyimpan riwayat sendiri dari nol jauh lebih merepotkan daripada memakai storage bawaan SDK.

Langkah 2: Konfigurasi Provider

Semua pengaturan ada di config/ai.php. Di sana kamu menentukan provider default dan daftar kredensialnya. Nilainya dibaca dari .env, jadi kunci API tidak pernah masuk ke repository:

ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GEMINI_API_KEY=
DEEPSEEK_API_KEY=
GROQ_API_KEY=
MISTRAL_API_KEY=
OPENROUTER_API_KEY=
XAI_API_KEY=
OLLAMA_API_KEY=

SDK ini juga menyediakan OPENAI_COMPATIBLE_URL dan OPENAI_COMPATIBLE_API_KEY. Dua variabel ini berguna kalau kamu memakai layanan yang meniru format OpenAI, misalnya gateway internal atau provider lokal. Dengan begitu kamu tidak perlu menunggu driver khusus.

Provider default ditentukan lewat key default di config. Menariknya, SDK memisahkan default per jenis operasi: default_for_images, default_for_audio, default_for_transcription, default_for_embeddings, default_for_reranking, dan default_for_classification. Jadi kamu bisa memakai model murah untuk teks dan model lain untuk gambar tanpa mengubah kode.

Langkah 3: Membuat Agent Pertama

Agent dibuat lewat Artisan. Contoh di bawah membuat agent untuk menjawab pertanyaan seputar dokumentasi produk:

php artisan make:agent ProductAssistant

# tambahkan flag --structured kalau butuh output JSON terstruktur
php artisan make:agent ProductAssistant --structured

File yang dihasilkan ada di app/Ai/Agents. Bagian terpentingnya adalah method instructions(), yang berisi peran dan aturan agent:

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;
use Stringable;

class ProductAssistant implements Agent
{
    use Promptable;

    public function instructions(): Stringable|string
    {
        return 'Kamu adalah asisten dokumentasi produk. Jawab dalam bahasa Indonesia, '
             . 'maksimal 120 kata, dan jangan mengarang fitur yang tidak ada.';
    }
}

Perhatikan dua hal. Pertama, class ini mengimplementasikan Laravel\Ai\Contracts\Agent dan memakai trait Promptable. Kedua, instructions() boleh mengembalikan string biasa maupun Stringable.

Kalau butuh konteks percakapan, tambahkan interface Conversational dan method messages(). Kalau butuh tool, tambahkan HasTools dan method tools(). Semuanya opsional — agent paling sederhana cukup punya instructions().

Langkah 4: Memanggil Agent

Memanggil agent cukup satu baris. Hasilnya bisa langsung di-cast ke string:

$response = (new ProductAssistant)->prompt('Bagaimana cara reset password?');

return (string) $response;

Di dalam controller, pola ini sudah cukup untuk fitur tanya jawab sederhana. Kamu tinggal menambahkan validasi input dan rate limiting supaya tidak diborong pengguna.

Streaming Response ke Browser

Untuk pengalaman seperti ChatGPT, gunakan method stream(). Object yang dikembalikan bisa langsung di-return dari route, dan SDK akan mengirimkannya sebagai SSE:

use App\Ai\Agents\ProductAssistant;

Route::get('/assistant', function () {
    return (new ProductAssistant)->stream('Jelaskan fitur export data');
});

Kalau perlu melakukan sesuatu setelah streaming selesai — misalnya menyimpan transkrip atau mencatat pemakaian token — gunakan method then() dengan closure. Ini lebih aman daripada menebak kapan koneksi berakhir di sisi klien.

Structured Output dengan Skema

Ini fitur yang paling sering dicari. Kalau aplikasi butuh data yang bisa diproses lebih lanjut, jangan parsing teks bebas. Definisikan skema lewat interface HasStructuredOutput:

public function schema(JsonSchema $schema): array
{
    return [
        'ringkasan' => $schema->string()->required(),
        'sentimen'  => $schema->string()->enum(['positif', 'netral', 'negatif'])->required(),
        'skor'      => $schema->integer()->min(1)->max(10)->required(),
    ];
}

Dengan skema seperti ini, hasilnya bisa langsung divalidasi dan disimpan ke kolom database tanpa regex atau json_decode manual. Untuk kasus klasifikasi tiket support atau ekstraksi data dari dokumen, pola ini menghemat banyak kode.

Catatan Sebelum Dipakai di Produksi

Beberapa hal yang sering terlewat saat integrasi AI pertama kali:

Pertanyaan yang Sering Ditanyakan

Apakah Laravel AI SDK gratis?

Paketnya open source dengan lisensi MIT, jadi bebas dipakai. Yang berbayar adalah pemakaian model dari provider AI yang kamu pilih, dan tarifnya mengikuti provider masing-masing.

Bisa dipakai tanpa OpenAI?

Bisa. SDK ini mendukung Anthropic, Gemini, DeepSeek, Groq, Mistral, OpenRouter, xAI, dan provider lain. Kamu juga bisa memakai endpoint yang kompatibel dengan format OpenAI lewat OPENAI_COMPATIBLE_URL.

Apakah data percakapan disimpan otomatis?

Tidak otomatis untuk semua agent. Riwayat baru disimpan kalau agent memakai interface Conversational, dan tabelnya dibuat oleh migration yang tadi kamu jalankan.

Kesimpulan

Laravel AI SDK mengubah integrasi AI di Laravel dari sekadar memanggil API menjadi pola yang rapi: satu class agent, satu konfigurasi provider, satu skema output. Untuk fitur chat sederhana pun pendekatannya sudah lebih terstruktur dibanding menulis request HTTP manual.

Kalau kamu baru mulai, urutan yang paling masuk akal adalah: pasang SDK, buat satu agent dengan instructions() saja, lalu tambahkan tool dan skema setelah alurnya jelas. Untuk persiapan environment, baca dulu persiapan web developer Laravel, dan kalau project kamu masih versi lama, sesuaikan dulu lewat panduan install Laravel di Linux Ubuntu.

Referensi resmi: dokumentasi Laravel AI SDK.

Exit mobile version