Blog

Cara Menggunakan Vercel AI SDK: Panduan Pemula

Rebecca Kovács

Rebecca Kovács

10 June 2025

Cara Menggunakan Vercel AI SDK: Panduan Pemula

Selamat datang di panduan pemula definitif untuk Vercel AI SDK. Di dunia di mana kecerdasan buatan dengan cepat mengubah lanskap digital, kemampuan untuk mengintegrasikan AI ke dalam aplikasi web telah bergeser dari spesialisasi khusus menjadi kompetensi inti bagi pengembang modern. Panduan ini dirancang untuk membawa Anda dari pemula yang penasaran menjadi pengembang aplikasi AI yang cakap.

Untuk waktu yang lama, menjembatani kesenjangan antara Large Language Model (LLM) yang kuat dan antarmuka web yang ramah pengguna adalah upaya yang kompleks. Pengembang harus bergulat dengan API penyedia yang berbeda, mengelola status yang rumit, dan secara manual mengimplementasikan fitur-fitur seperti streaming respons. Vercel AI SDK diciptakan untuk menyelesaikan masalah-masalah persis ini. Ini adalah toolkit yang mengutamakan TypeScript yang menyediakan lapisan abstraksi yang terpadu dan elegan di atas kerumitan membangun pengalaman berbasis AI.

Ini bukan sekadar panduan singkat. Sepanjang tutorial ini, kita akan membangun chatbot AI yang lengkap dan kaya fitur dari awal menggunakan Next.js dan model Gemini dari Google. Kita akan melangkah jauh melampaui contoh "hello world" sederhana. Anda akan mempelajari:

Pada akhir panduan komprehensif ini, Anda tidak hanya akan memiliki chatbot canggih yang berfungsi, tetapi juga pengetahuan konseptual mendalam yang dibutuhkan untuk dengan percaya diri membangun aplikasi berbasis AI Anda sendiri yang unik dan kuat dengan Vercel AI SDK.

💡
Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terpadu, All-in-One untuk Tim Pengembang Anda agar dapat bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua kebutuhan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Bab 1: Fondasi dan Pengaturan

Setiap struktur hebat membutuhkan fondasi yang kokoh. Dalam bab ini, kita akan menyiapkan lingkungan pengembangan kita, menginstal alat yang diperlukan, dan mengatur kunci API kita. Kita juga akan meluangkan waktu sejenak untuk memahami "mengapa" di balik setiap pilihan yang kita buat.

Prasyarat

Sebelum kita menulis satu baris kode pun, mari pastikan kotak peralatan Anda siap.

  1. Navigasi ke Google AI Studio.
  2. Masuk dengan akun Google Anda.
  3. Klik "Get API key" (Dapatkan kunci API) lalu "Create API key in new project" (Buat kunci API di proyek baru).
  4. Salin kunci yang dihasilkan dan simpan di tempat yang aman untuk saat ini. Perlakukan kunci ini seperti kata sandi; jangan pernah mengeksposnya secara publik.

Langkah 1: Menginisialisasi Proyek Next.js

Kita akan menggunakan Next.js, framework React utama untuk membangun aplikasi siap produksi. Paradigma App Router-nya terintegrasi sempurna dengan sifat aplikasi AI yang berpusat pada server.

Buka terminal Anda dan jalankan perintah ini untuk membuat proyek baru:

npx create-next-app@latest vercel-ai-tutorial

Installer akan meminta Anda dengan beberapa pertanyaan. Gunakan pengaturan ini untuk mengikuti dengan lancar:

Setelah instalasi selesai, navigasi ke direktori proyek yang baru saja Anda buat:

cd vercel-ai-tutorial

Langkah 2: Menginstal Vercel AI SDK

Sekarang, mari tambahkan paket AI SDK ke proyek kita.

npm install ai @ai-sdk/react @ai-sdk/google zod

Mari kita uraikan apa yang dilakukan setiap paket ini:

Langkah 3: Mengamankan Kunci API Anda

Jangan pernah menulis kunci API secara langsung (hardcode) dalam kode aplikasi Anda. Ini adalah risiko keamanan utama. Standar profesional adalah menggunakan variabel lingkungan. Next.js memiliki dukungan bawaan untuk ini dengan file .env.local.

Buat file di root proyek Anda:

touch .env.local

Sekarang, buka file baru ini dan tambahkan kunci AI Google Anda:

# .env.local
# This file is for local development and should NOT be committed to git.
GOOGLE_GENERATIVE_AI_API_KEY=YOUR_GOOGLE_AI_API_KEY

Ganti YOUR_GOOGLE_AI_API_KEY dengan kunci yang Anda salin sebelumnya. Next.js secara otomatis memuat file ini dan membuat kunci tersedia di server, yang persis di tempat kita membutuhkannya.

Bab 2: Membangun Inti Chatbot

Setelah proyek kita siap, saatnya membangun komponen inti aplikasi kita: endpoint API sisi server yang berkomunikasi dengan AI, dan UI sisi klien tempat pengguna akan berinteraksi.

Arsitektur Klien-Server Aplikasi AI

Chatbot kita akan memiliki dua bagian utama:

  1. Rute API Sisi Server (/api/chat/route.ts): Ini adalah lingkungan aman yang berjalan di server. Tugas utamanya adalah menerima riwayat obrolan dari browser pengguna, menambahkan kunci API rahasia kita, meneruskan permintaan ke layanan Google AI, lalu melakukan streaming respons kembali ke pengguna. Menjaga logika ini di server sangat penting untuk keamanan—ini memastikan kunci API kita tidak pernah terekspos ke publik.
  2. UI Sisi Klien (page.tsx): Ini adalah komponen React yang berjalan di browser pengguna. Ini bertanggung jawab untuk merender riwayat obrolan, menangkap input pengguna, dan mengirim input tersebut ke rute API kita.

Pemisahan ini mendasar untuk membangun aplikasi web yang aman dan berperforma tinggi.

Langkah 4: Membuat Handler Rute API

Mari kita buat endpoint sisi server. Di direktori src/app Anda, buat folder baru api, dan di dalamnya, folder lain chat. Terakhir, buat file bernama route.ts di dalam folder chat.

Jalur akhirnya seharusnya src/app/api/chat/route.ts.

Isi file ini dengan kode berikut:

// src/app/api/chat/route.ts

import { google } from '@ai-sdk/google';
import { streamText } from 'ai';

// Vercel-specific configuration to allow streaming responses for up to 30 seconds
export const maxDuration = 30;

// The main API route handler
export async function POST(req: Request) {
  try {
    // Extract the `messages` array from the request body
    const { messages } = await req.json();

    // Call the AI provider with the conversation history
    const result = await streamText({
      model: google('models/gemini-1.5-pro-latest'),
      // The `messages` array provides the model with context for the conversation
      messages,
    });

    // Respond with a streaming response
    return result.toDataStreamResponse();
  } catch (error) {
    // It's a good practice to handle potential errors
    if (error instanceof Error) {
      return new Response(JSON.stringify({ error: error.message }), { status: 500 });
    }
    return new Response(JSON.stringify({ error: 'An unknown error occurred' }), { status: 500 });
  }
}

Mari kita bedah file penting ini:

Langkah 5: Membuat Antarmuka Pengguna

Sekarang bagian yang menyenangkan: membangun UI. Berkat paket @ai-sdk/react, ini sangat sederhana. Buka file halaman utama di src/app/page.tsx dan ganti seluruh isinya dengan berikut ini:

// src/app/page.tsx

'use client';

import { useChat } from '@ai-sdk/react';
import { useRef, useEffect } from 'react';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat();

  // A ref to the scrollable container of messages
  const messagesContainerRef = useRef<HTMLDivElement>(null);

  // Effect to scroll to the bottom of the messages container whenever messages change
  useEffect(() => {
    if (messagesContainerRef.current) {
      messagesContainerRef.current.scrollTop = messagesContainerRef.current.scrollHeight;
    }
  }, [messages]);

  return (
    <div className="flex flex-col h-screen bg-gray-50">
      {/* Messages container */}
      <div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
        {messages.map(m => (
          <div
            key={m.id}
            className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
          >
            {/* Display user's avatar */}
            {m.role === 'user' && (
              <div className="w-10 h-10 rounded-full bg-blue-500 flex items-center justify-center text-white font-bold">U</div>
            )}

            {/* Message bubble */}
            <div
              className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
                m.role === 'user'
                  ? 'bg-blue-500 text-white rounded-br-none'
                  : 'bg-white text-black rounded-bl-none'
              }`}
            >
              <span className="font-bold block">{m.role === 'user' ? 'You' : 'AI Assistant'}</span>
              {m.content}
            </div>

            {/* Display AI's avatar */}
            {m.role !== 'user' && (
              <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">AI</div>
            )}
          </div>
        ))}
      </div>

      {/* Input form */}
      <div className="p-4 bg-white border-t">
        <form onSubmit={handleSubmit} className="flex items-center gap-4 max-w-4xl mx-auto">
          <input
            className="flex-1 p-3 border rounded-full focus:outline-none focus:ring-2 focus:ring-blue-500"
            value={input}
            placeholder="Ask me anything..."
            onChange={handleInputChange}
            disabled={isLoading}
          />
          <button
            type="submit"
            className="px-6 py-3 bg-blue-500 text-white rounded-full font-semibold hover:bg-blue-600 disabled:bg-blue-300 disabled:cursor-not-allowed"
            disabled={isLoading}
          >
            Send
          </button>
        </form>
        {error && (
          <p className="text-red-500 mt-2 text-center">{error.message}</p>
        )}
      </div>
    </div>
  );
}

Ini adalah jumlah kode yang signifikan, tetapi sebagian besar untuk membuat UI yang rapi dengan Tailwind CSS. Mari kita fokus pada logikanya:

Langkah 6: Menjalankan Aplikasi Anda

Anda sekarang telah membangun chatbot AI yang lengkap dan terstruktur dengan baik. Mari kita jalankan!

npm run dev

Navigasi ke http://localhost:3000 di browser Anda. Anda akan disambut oleh antarmuka obrolan yang rapi. Ajukan pertanyaan kepadanya. Anda akan melihat pesan Anda muncul seketika, dan respons AI akan mengalir token demi token.

Bab 3: Kemampuan Tingkat Lanjut - Memberikan Kekuatan Super pada Chatbot Anda

Chatbot kita pintar, tetapi pengetahuannya terbatas pada data pelatihannya. Ia tidak dapat mengakses informasi langsung atau melakukan tindakan di dunia nyata. Dalam bab ini, kita akan memberikannya "Alat" (Tools) untuk mengatasi keterbatasan ini.

Apa Itu Alat (Tools)?

Alat (Tool) adalah fungsi yang Anda definisikan yang dapat dipilih oleh LLM untuk dieksekusi. Anda menjelaskan alat tersebut kepada model, dan ketika model berpikir bahwa alat tersebut diperlukan untuk menjawab pertanyaan pengguna, model akan menjeda pembuatan teksnya dan malah mengeluarkan objek "pemanggilan alat" (tool call) khusus. Kode Anda kemudian mengeksekusi fungsi dengan argumen yang disediakan oleh model, dan hasilnya dikirim kembali ke model. Model kemudian menggunakan informasi baru ini untuk menghasilkan respons akhirnya yang lebih akurat.

Mari kita berdayakan chatbot kita dengan dua alat:

  1. Alat untuk mendapatkan cuaca terkini untuk suatu lokasi.
  2. Alat untuk mengonversi suhu dari Fahrenheit ke Celsius.

Ini akan memungkinkan bot kita menjawab pertanyaan seperti, "Bagaimana cuaca di London dalam Celsius?"—tugas yang membutuhkan beberapa langkah dan data eksternal.

Langkah 7: Meningkatkan API untuk Mendukung Alat (Tools)

Kita perlu mendefinisikan alat kita dalam panggilan streamText di server. Buka src/app/api/chat/route.ts dan modifikasi untuk menyertakan definisi tools yang baru.

// src/app/api/chat/route.ts
import { google } from '@ai-sdk/google';
import { streamText, tool } from 'ai';
import { z } from 'zod';

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: google('models/gemini-1.5-pro-latest'),
    messages,
    // Define the tools the model can use
    tools: {
      getWeather: tool({
        description: 'Get the current weather for a specific location. Always returns temperature in Fahrenheit.',
        parameters: z.object({
          location: z.string().describe('The city and state, e.g., San Francisco, CA'),
        }),
        execute: async ({ location }) => {
          // In a real app, you would fetch from a real weather API
          console.log(`Fetching weather for ${location}`);
          return {
            temperature: Math.floor(Math.random() * (100 - 30 + 1) + 30),
            high: Math.floor(Math.random() * (100 - 80 + 1) + 80),
            low: Math.floor(Math.random() * (50 - 30 + 1) + 30),
            conditions: ['Sunny', 'Cloudy', 'Rainy'][Math.floor(Math.random() * 3)],
          };
        },
      }),
      convertFahrenheitToCelsius: tool({
        description: 'Convert a temperature from Fahrenheit to Celsius.',
        parameters: z.object({
          temperature: z.number().describe('The temperature in Fahrenheit'),
        }),
        execute: async ({ temperature }) => {
          console.log(`Converting ${temperature}°F to Celsius`);
          return {
            celsius: Math.round((temperature - 32) * (5 / 9)),
          };
        },
      }),
    },
  });

  return result.toDataStreamResponse();
}

Mari kita analisis objek tools:

Langkah 8: Mengaktifkan Pemanggilan Alat Multi-Langkah di UI

Hanya mendefinisikan alat di server tidak cukup. Secara default, ketika model melakukan pemanggilan alat, percakapan berhenti. Kita perlu memberi tahu hook useChat kita untuk secara otomatis mengirim hasil pemanggilan alat tersebut kembali ke model agar model dapat melanjutkan penalaran dan merumuskan jawaban akhir.

Ini sangat sederhana. Di src/app/page.tsx, perbarui inisialisasi hook useChat:

// src/app/page.tsx

// ...
export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, isLoading, error } = useChat({
    // Tell the hook to automatically send tool results back to the model
    experimental_sendExtraToolMessages: true,
  });
  // ... rest of the component
}

Itu saja. Properti experimental_sendExtraToolMessages: true mengaktifkan alur penggunaan alat multi-langkah.

Langkah 9: UI yang Lebih Baik untuk Pemanggilan Alat

UI kita saat ini hanya menampilkan m.content. Ketika alat dipanggil, informasi yang menarik ada di properti yang berbeda pada objek pesan. Mari kita buat komponen khusus untuk merender pemanggilan alat dengan baik.

Pertama, mari kita perbarui loop pesan utama di src/app/page.tsx untuk merender pemanggilan ini.

// src/app/page.tsx

// ... inside the Chat component's return statement
<div ref={messagesContainerRef} className="flex-1 overflow-y-auto p-8 space-y-4">
  {messages.map(m => (
    <div
      key={m.id}
      className={`flex gap-3 ${m.role === 'user' ? 'justify-end' : 'justify-start'}`}
    >
      {/* ... avatars ... */}
      <div
        className={`max-w-xl p-3 rounded-2xl shadow-md whitespace-pre-wrap ${
          m.role === 'user'
            ? 'bg-blue-500 text-white rounded-br-none'
            : 'bg-white text-black rounded-bl-none'
        }`}
      >
        <span className="font-bold block">{m.role === 'user' ? 'You' : 'AI Assistant'}</span>

        {/* Render tool invocations */}
        {m.toolInvocations?.map(tool => (
          <div key={tool.toolCallId} className="my-2 p-2 bg-gray-100 rounded text-sm text-gray-700">
            <p className="font-semibold">Tool Call: `{tool.toolName}`</p>
            <pre className="mt-1 p-1 bg-gray-200 rounded text-xs">
              {JSON.stringify(tool.args, null, 2)}
            </pre>
          </div>
        ))}

        {m.content}
      </div>
      {/* ... avatars ... */}
    </div>
  ))}
  {isLoading && messages[messages.length - 1]?.role === 'assistant' && (
      <div className="flex justify-start p-8 space-x-3">
          <div className="w-10 h-10 rounded-full bg-gray-700 flex items-center justify-center text-white font-bold">AI</div>
          <div className="p-3 rounded-2xl shadow-md bg-white">
              <div className="typing-indicator">
                  <span></span><span></span><span></span>
              </div>
          </div>
      </div>
  )}
</div>
// ...

Saya juga telah menambahkan indikator pengetikan sederhana yang muncul saat asisten sedang berpikir. Anda perlu menambahkan sedikit CSS untuk itu. Di file src/app/globals.css Anda, tambahkan:

/* src/app/globals.css */

.typing-indicator span {
  height: 8px;
  width: 8px;
  background-color: #9E9EA1;
  border-radius: 50%;
  display: inline-block;
  animation: a 1.2s infinite ease-in-out;
}
.typing-indicator span:nth-child(1) { animation-delay: -0.4s; }
.typing-indicator span:nth-child(2) { animation-delay: -0.2s; }
@keyframes a {
  0%, 60%, 100% { transform: scale(0.2); }
  30% { transform: scale(1); }
}

Sekarang, jalankan kembali aplikasinya. Tanyakan kepadanya, "Berapa cuaca di New York dalam Celsius?" Anda akan melihat rangkaian peristiwa menarik terungkap di UI Anda:

  1. Model pertama-tama akan memanggil alat getWeather. Anda akan melihat pemanggilan alat yang dirender di UI.
  2. Hasilnya (suhu acak dalam Fahrenheit) dikirim kembali ke model.
  3. Model, mengetahui bahwa ia membutuhkan Celsius, kemudian akan memanggil alat convertFahrenheitToCelsius, menggunakan suhu dari hasil alat pertama sebagai inputnya.
  4. Terakhir, dengan suhu Celsius di tangan, model akan menghasilkan respons bahasa alami yang menjawab pertanyaan asli Anda.

Inilah kekuatan membangun Agen AI, dan Vercel AI SDK membuat orkestrasi kompleks ini menjadi sangat mudah.

Bab 4: Ke Mana Selanjutnya?

Anda telah berhasil membangun chatbot canggih berbasis AI. Anda telah beralih dari kanvas kosong menjadi aplikasi kaya fitur yang dapat melakukan streaming respons, menangani status loading dan error, serta memanfaatkan alat untuk berinteraksi dengan data eksternal secara multi-langkah.

Panduan ini telah memberi Anda fondasi yang kuat, tetapi ini hanyalah permulaan. Vercel AI SDK memiliki lebih banyak lagi yang ditawarkan. Berikut adalah beberapa jalur untuk eksplorasi lanjutan Anda:

Masa depan pengembangan web adalah cerdas, interaktif, dan personal. Dengan Vercel AI SDK, Anda sekarang memiliki alat dan pengetahuan untuk berada di garis depan revolusi ini. Selamat membangun!

💡
Ingin alat Pengujian API hebat yang menghasilkan Dokumentasi API yang indah?

Ingin platform Terpadu, All-in-One untuk Tim Pengembang Anda agar dapat bekerja sama dengan produktivitas maksimum?

Apidog memenuhi semua kebutuhan Anda, dan menggantikan Postman dengan harga yang jauh lebih terjangkau!
button

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh