Panduan Pengajar — AI Agent Builder

📋 Ringkasan Sesi

Sesi ini adalah kemuncak keseluruhan kursus Vibe Coding. Pelajar akan belajar membina AI Agent — aplikasi pintar yang boleh berfikir, ingat perbualan, dan melaksanakan tugas menggunakan kuasa Claude API dan Cloudflare Workers.

Ini adalah skill yang sangat bernilai: keupayaan untuk membina AI agent adalah antara kemahiran paling dicari dalam industri teknologi masa kini.

Objektif Pembelajaran

Memahami konsep AI Agent — apa bezanya dengan chatbot biasa
Mampu setup projek Cloudflare Workers dengan Agents SDK
Boleh membina chat agent dengan system prompt dan personality
Menguasai state management — agent yang ingat perbualan
Boleh tambah tools — search web, access database
Faham konsep WebSocket dan RPC untuk real-time chat
Mampu deploy agent ke Cloudflare Workers

Prasyarat Pelajar

Telah menyelesaikan Fasa 1 hingga Fasa 10
Mempunyai akaun Cloudflare yang aktif
Mempunyai akaun GitHub
Node.js telah diinstal di komputer (v18 atau lebih baru)
Faham asas JavaScript dan konsep asynchronous programming
API key Claude (dari Anthropic) — disediakan oleh pengajar

Peringatan: Modul ini adalah advanced dan memerlukan persiapan rapi. Pastikan semua prasyarat teknikal (Node.js, akaun Cloudflare, API key) telah disediakan SEBELUM sesi bermula. Kegagalan prasyarat akan menyebabkan sesi tergendala.

🔄 Aliran Sesi (4-6 Jam)

1 Pengenalan AI Agent (20 min) 2 Demo 1: Agent Pertama (30 min) 3 Hands-on 1-3 (60 min) 4 Demo 2: Agent Memory (30 min) 5 Hands-on 4-5 (60 min) 6 Project & Deploy (60 min) 7 Rumusan & Q&A (20 min)

Langkah 1: Pengenalan Konsep AI Agent (20 minit)

Terangkan apa itu AI Agent dengan analogi mudah:

Analogi: Bayangkan chatbot biasa macam mesin layan diri — awak tekan butang, dia bagi minuman. Tapi AI Agent macam pelayan restoran — dia boleh ingat pesanan awak, tanya soalan, cadangkan menu, dan kalau perlu, dia pergi dapur ambil makanan. Agent ada memory, boleh guna tools, dan boleh buat keputusan sendiri.

🤖

AI Agent vs Chatbot Biasa

Chatbot biasa: balas satu-soal-satu-jawab, tiada ingatan, tiada keupayaan bertindak. AI Agent: ada konteks perbualan, boleh ingat, boleh guna tools (cari web, query database), dan boleh execute tasks. Agent adalah evolusi chatbot — lebih pintar, lebih autonomous.

⚙️

Komponen Utama AI Agent

(1) LLM (Claude) — otak agent yang memproses dan menjana teks. (2) System Prompt — personality dan peraturan agent. (3) Memory/State — ingatan perbualan. (4) Tools — keupayaan agent untuk bertindak (search web, query database, panggil API). (5) Runtime — Cloudflare Workers sebagai persekitaran larian.

Langkah 2: Demo 1 — "Agent Pertama dalam 15 Minit" (30 minit)

Demo langsung membina agent paling asas dari kosong. Gunakan skrip di bawah:

Tip Pengajar: Demo ini sangat penting untuk membina keyakinan pelajar. Tunjukkan yang setup hanya ambil beberapa minit. Pelajar akan teruja bila nampak agent pertama mereka berfungsi!

Setup Projek Workers

# Buka terminal, create project baru
npx create-cloudflare@latest my-first-agent --framework=javascript

# Masuk folder projek
cd my-first-agent

# Install Agents SDK
npm install agents-sdk

# Install Anthropic AI SDK
npm install @anthropic-ai/sdk

Kod Agent Pertama

// src/index.js
import { Agent, createAgent } from 'agents-sdk';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: env.CLAUDE_API_KEY
});

export default createAgent({
  async chat(request, env) {
    const { message } = await request.json();

    const response = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: [{ role: 'user', content: message }]
    });

    const reply = response.content[0].text;
    return new Response(JSON.stringify({ reply }), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
});

Deploy ke Cloudflare

# Set API key
npx wrangler secret put CLAUDE_API_KEY

# Deploy
npx wrangler deploy

# Test agent
curl -X POST https://my-first-agent.your-subdomain.workers.dev/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello! Siapa awak?"}'

Demo Flow: (1) Tunjuk terminal — create project, (2) install dependencies, (3) tulis kod agent, (4) set secret, (5) deploy, (6) test dengan curl. Keseluruhan proses patut ambil kurang 15 minit.

Langkah 3: Hands-on Latihan 1-3 (60 minit)

Pelajar menjalankan Latihan 1 hingga 3 secara individu. Beredar untuk bantu pelajar yang menghadapi masalah teknikal.

Latihan 1: Setup Workers + Agents SDK project
Latihan 2: Bina chat agent basic — "Hello" response
Latihan 3: Tambah personality — agent jadi "pembantu coding"

Langkah 4: Demo 2 — Agent dengan Memory (30 minit)

Demo bagaimana agent boleh ingat perbualan menggunakan state management:

// Agent dengan Memory menggunakan Durable Objects
import { Agent, createAgent } from 'agents-sdk';
import Anthropic from '@anthropic-ai/sdk';

export class ChatAgent extends Agent {
  async initialize() {
    this.state = { messages: [] };
    await this.saveState();
  }

  async chat(request) {
    const { message } = await request.json();
    const state = await this.loadState();

    // Tambah message baru ke history
    state.messages.push({ role: 'user', content: message });

    const response = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: state.messages
    });

    const reply = response.content[0].text;
    state.messages.push({ role: 'assistant', content: reply });

    // Simpan state
    await this.saveState(state);

    return new Response(JSON.stringify({ reply }), {
      headers: { 'Content-Type': 'application/json' }
    });
  }
}

Key Concept: Durable Objects membolehkan agent mempunyai persistent state. Setiap perbualan diingati. Agent tahu konteks — apa yang disebut 10 minit lepas, preferensi pengguna, dan history perbualan penuh.

Langkah 5: Hands-on Latihan 4-5 (60 minit)

Pelajar menjalankan Latihan 4 dan 5:

Latihan 4: Tambah memory — agent ingat nama dan preference
Latihan 5: Deploy agent dan share URL dengan rakan sekelas

Langkah 6: Projek Mini (60 minit)

Pelajar diberi masa untuk memperkemas agent mereka — tambah tools, baiki personality, atau tambah WebSocket untuk real-time chat.

Langkah 7: Rumusan & Q&A (20 minit)

Review konsep utama: Agent, State, Tools, Deploy
Pelajar demo agent masing-masing
Q&A dan perkongsian pengalaman
Cadangan: baca halaman rujukan untuk prompt templates dan troubleshooting

🎯 Key Teaching Points

🤖

AI Agent vs Chatbot: Ramai pelajar fikir AI Agent sama dengan chatbot. Bezakan dengan jelas: chatbot balas soalan, agent boleh ingat, guna tools, dan buat keputusan sendiri. Agent adalah autonomous — dia boleh decide bila nak guna tool, apa nak tanya, dan bagaimana nak respond.

💾

State Management: Inilah kuasa sebenar agent. Tanpa state, agent buta — setiap response bermula dari kosong. Dengan state, agent ada konteks. Ajar konsep Durable Objects sebagai tempat simpan state. State boleh: messages history, user preferences, session data, authentication tokens.

🔧

Tools & Actions: Agent tanpa tools ibarat kereta tanpa roda. Tools memberi agent keupayaan untuk berinteraksi dengan dunia luar: search web, query database, hitung matematik, hantar email, panggil API. Tunjukkan contoh tool yang ringkas (search web) supaya mudah difahami.

🌐

WebSocket & Real-time: HTTP request-response baik untuk chat biasa, tapi WebSocket memberi pengalaman real-time. Agent boleh stream response perkata, bagi feedback masa nyata, dan handle multiple users serentak. Ini advanced — ajar hanya jika masa mengizinkan.

🏗️ Senibina AI Agent

Gambarajah senibina bagaimana AI Agent berfungsi di Cloudflare Workers:

👤 User

→

☁️ Worker

→

🤖 Agent

↔

💬 Claude API

💾 Durable Objects
(State / Memory)

↔

🛠️ Tools
(Search, DB, API)

↔

🕹️ WebSocket
(Real-time Chat)

Aliran: User hantar mesej -> Worker terima request -> Agent proses dengan Claude API -> Agent guna State untuk ingat konteks -> Agent boleh guna Tools untuk bertindak -> Response dikembalikan ke User melalui WebSocket atau HTTP.

🎬 Demo Script 1: Agent Pertama dalam 15 Minit

Demo ini adalah tunjuk cara paling penting. Ia membuktikan bahawa setup AI Agent hanya mengambil masa 15 minit dari kosong kepada live agent.

Langkah 1: Prasyarat (Sebelum Demo)

# Pastikan Node.js sudah diinstal
node --version
# Output: v18.0.0 atau lebih baru

# Pastikan akaun Cloudflare sudah sedia
# Buka https://dash.cloudflare.com dan login

# Dapatkan API key dari Claude
# Buka https://console.anthropic.com/
# Generate API key dan simpan di tempat selamat

Langkah 2: Create Workers Project

npx create-cloudflare@latest my-first-agent --framework=javascript
# Pilih: "Hello World" template
# Pilih: Yes untuk TypeScript (optional)
# Pilih: Yes untuk deploy

Langkah 3: Install Dependencies

cd my-first-agent
npm install @anthropic-ai/sdk

Langkah 4: Tulis Kod Agent

Gantikan content src/index.js dengan kod berikut:

import Anthropic from '@anthropic-ai/sdk';

export default {
  async fetch(request, env) {
    const anthropic = new Anthropic({ apiKey: env.CLAUDE_API_KEY });

    if (request.method === 'POST' && new URL(request.url).pathname === '/chat') {
      const { message } = await request.json();

      const response = await anthropic.messages.create({
        model: 'claude-sonnet-4-20250514',
        max_tokens: 1024,
        messages: [{ role: 'user', content: message }]
      });

      const reply = response.content[0].text;
      return new Response(JSON.stringify({ reply }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }

    return new Response('AI Agent is running! Send POST to /chat', {
      headers: { 'Content-Type': 'text/plain' }
    });
  }
};

Langkah 5: Set Secret & Deploy

# Set Claude API Key sebagai secret
npx wrangler secret put CLAUDE_API_KEY
# Paste API key bila diminta

# Deploy ke Cloudflare
npx wrangler deploy

# Output: https://my-first-agent.your-subdomain.workers.dev

Langkah 6: Test Agent

# Guna curl
curl -X POST https://my-first-agent.your-subdomain.workers.dev/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello! Siapa awak?"}'

# Output: {"reply":"Hello! Saya AI Agent yang dibina menggunakan Claude..."}

# Atau guna browser - buka URL worker untuk laman status

Tip Pengajar: Kalau curl nampak complicated, guna tools macam Postman atau Thunder Client (VS Code extension) untuk test. Atau bina HTML form ringkas yang POST ke endpoint agent.

Masalah Biasa: (1) CLAUDE_API_KEY tidak set — worker akan return error 500. (2) CORS — kalau nak panggil dari browser, perlu tambah CORS headers. (3) Model name — pastikan guna model name yang betul untuk Claude API.

🎬 Demo Script 2: Agent dengan Memory

Demo ini menunjukkan cara agent boleh ingat perbualan menggunakan Durable Objects untuk persistent state.

Langkah 1: Setup Durable Object

Edit wrangler.toml untuk tambah Durable Object binding:

name = "my-first-agent"
main = "src/index.js"

[[durable_objects.bindings]]
name = "CHAT_AGENT"
class_name = "ChatAgent"

[[migrations]]
tag = "v1"
new_classes = ["ChatAgent"]

Langkah 2: Install Agents SDK

npm install agents-sdk

Langkah 3: Tulis Agent dengan State

import { Agent } from 'agents-sdk';
import Anthropic from '@anthropic-ai/sdk';

export class ChatAgent extends Agent {
  static schema = {
    messages: [''] // Array of message objects
  };

  async initialize() {
    this.setState({ messages: [] });
  }

  async chat(message) {
    const state = await this.getState();
    const anthropic = new Anthropic({ apiKey: this.env.CLAUDE_API_KEY });

    // Append user message
    state.messages.push({ role: 'user', content: message });

    // Get response from Claude
    const response = await anthropic.messages.create({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: state.messages
    });

    const reply = response.content[0].text;
    state.messages.push({ role: 'assistant', content: reply });

    // Save state
    await this.setState(state);

    return reply;
  }
}

Langkah 4: Worker Handler dengan Agent Routing

import { ChatAgent } from './chat-agent';

export default {
  async fetch(request, env) {
    const url = new URL(request.url);

    if (url.pathname === '/chat' && request.method === 'POST') {
      const { message, sessionId } = await request.json();

      // Dapatkan atau cipta session agent
      const agentId = env.CHAT_AGENT.idFromName(sessionId || 'default');
      const agent = env.CHAT_AGENT.get(agentId);

      const reply = await agent.chat(message);
      return new Response(JSON.stringify({ reply }), {
        headers: { 'Content-Type': 'application/json' }
      });
    }

    return new Response('AI Agent with Memory is running!');
  }
};

Langkah 5: Deploy & Test

# Deploy
npx wrangler deploy

# Test: agent ingat nama
curl -X POST https://my-first-agent.workers.dev/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Hi! Nama saya Ali.","sessionId":"session-1"}'

# Agent akan ingat nama Ali dalam sesi yang sama
curl -X POST https://my-first-agent.workers.dev/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"Siapa nama saya?","sessionId":"session-1"}'
# Output: "Nama awak Ali!"

Kenapa ini penting? Dengan memory, agent boleh: (1) ingat nama pengguna, (2) ingat preference, (3) ingat konteks perbualan, (4) sediakan pengalaman yang personalized. Tanpa memory, agent akan lupa semuanya setiap kali user hantar message baru.

Langkah 6: Tambah System Prompt (Personality)

async chat(message) {
  const state = await this.getState();
  const anthropic = new Anthropic({ apiKey: this.env.CLAUDE_API_KEY });

  // System prompt - define personality
  const systemPrompt = `Anda adalah "Si Cerdik" — AI Agent pembantu coding yang:
- Bertutur dalam Bahasa Melayu
- Mesra dan suka membantu
- Sentiasa memberi contoh kod
- Suka explain konsep dengan analogi
- Jawab dengan ringkas dan tepat`;

  state.messages.push({ role: 'user', content: message });

  const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    system: systemPrompt,
    max_tokens: 1024,
    messages: state.messages
  });

  const reply = response.content[0].text;
  state.messages.push({ role: 'assistant', content: reply });
  await this.setState(state);
  return reply;
}

📖 Konsep Utama Yang Perlu Ditekankan

Konsep	Penerangan	Kenapa Penting
AI Agent	Program AI yang boleh berfikir, ingat, dan bertindak secara autonomous	Asas segala yang akan dibina
System Prompt	Instructions yang define personality dan peraturan agent	Menentukan cara agent berkelakuan
State Management	Menyimpan dan mengurus data perbualan agent	Agent perlu ingat untuk berguna
Tools	Keupayaan agent untuk berinteraksi dengan dunia luar	Agent tanpa tools adalah chatbot biasa
Durable Objects	Cloudflare's persistent storage untuk state	Backend yang power untuk agent memory
WebSocket	Sambungan real-time antara user dan agent	Pengalaman chat yang smooth
RPC	Remote Procedure Call — agent panggil agent lain	Multi-agent architecture
Deploy	Menyiarkan agent ke internet melalui Cloudflare Workers	Agent boleh diakses semua orang

⚠️ Kesilapan Biasa Pelajar & Penyelesaian

1. "CLAUDE_API_KEY is not defined"

Masalah: Pelajar tak set secret. Worker cuba baca env variable yang tiada.

✅ Penyelesaian: Jalankan npx wrangler secret put CLAUDE_API_KEY sebelum deploy. Boleh juga set di Cloudflare Dashboard: Workers & Pages -> pilih worker -> Settings -> Variables -> Add secret.

2. Build failed — "Module not found"

Masalah: Pelajar lupa install dependencies. @anthropic-ai/sdk atau agents-sdk tak diinstal.

✅ Penyelesaian: Jalankan npm install @anthropic-ai/sdk dan npm install agents-sdk. Pastikan package.json ada dependencies yang betul.

3. Agent lupa semua perbualan

Masalah: Pelajar tak implement state management. Setiap request baru, state bermula kosong.

✅ Penyelesaian: Guna Durable Objects atau Agents SDK state management. Pastikan messages array disimpan antara requests.

4. CORS error bila panggil dari browser

Masalah: Worker tak set CORS headers. Browser block request sebab cross-origin.

✅ Penyelesaian: Tambah CORS headers dalam response: Access-Control-Allow-Origin: *, Access-Control-Allow-Methods: POST, OPTIONS, Access-Control-Allow-Headers: Content-Type. Handle OPTIONS preflight request.

5. Response terlalu lambat

Masalah: Claude API ambil masa 5-10 saat untuk generate response. Worker mungkin timeout.

✅ Penyelesaian: Guna streaming response — agent hantar response char-by-char. Atau set max_tokens lebih rendah. Cloudflare Workers ada limit 30 saat untuk HTTP request.

6. Agent bagi jawapan dalam Bahasa Inggeris

Masalah: System prompt tak specify bahasa. Claude default kepada English.

✅ Penyelesaian: Dalam system prompt, tulis dengan jelas: "Anda mesti menjawab dalam Bahasa Melayu sahaja. Walaupun user tanya dalam English, jawab dalam Bahasa Melayu."

🎓 Panduan Fasilitasi

Strategi Pengajaran untuk Modul Advanced

Demo dulu, baru buat: Tunjukkan demo penuh sebelum suruh pelajar buat sendiri. Pelajar perlu nampak "magik" dulu untuk kekal termotivasi.
Pair programming: Suruh pelajar kerja berpasangan — satu pegang keyboard, satu guide. Tukar peranan setiap 15 minit. Agent development lebih seronok berkawan.
Gamification: Cari agent paling kreatif, personality paling menarik, atau tool paling berguna. Bagi "AI Agent Champion" award.
API Key Management: Sedikan Claude API key untuk semua pelajar. Jangan suruh pelajar guna key sendiri — confirm akan bocor atau exceed limit.
Debugging bersama: Bila agent error, jangan betulkan sendiri. Tunjuk cara debug — baca error log, check wrangler output, check Cloudflare Dashboard.

Panduan API Key

Untuk kelas: Dapatkan Claude API key dari console.anthropic.com. Dana $10-20 cukup untuk kelas 20 pelajar selama 4-6 jam (setiap request Claude API ~$0.01-0.05). Optional: guna Anthropic Batch API untuk 50% lebih murah.

Cara Bantu Pelajar Yang Ketinggalan

Sediakan starter template — repo GitHub dengan kod agent basic yang boleh clone dan deploy
Guna AI prompts dari halaman rujukan untuk bantu mereka troubleshoot
Pelajar cepat: bagi cabaran tambahan — tambah tools, WebSocket, multi-agent
Pelajar lambat: fokus pada Latihan 1-3 sahaja. 4-5 adalah bonus

Moment "Wow": Momen paling berkesan dalam modul ini adalah bila pelajar hantar message, dan agent mereka ingat nama mereka. Atau bila agent buat keputusan sendiri untuk guna tool. Tangkap momen ini — ia akan diingati pelajar sebagai titik "Saya boleh buat AI!"