Rujukan — AI Agent Builder

Prompt Templates

Common Mistakes

SDK Cheatsheet

Advanced

Tahap

📝 AI Agent Prompt Templates

Gunakan prompt templates ini untuk mempercepatkan pembinaan agent anda. Copy-paste ke AI assistant (Claude) untuk hasilkan kod dengan pantas.

1 Setup Cloudflare Workers Project dengan Agents SDK

Guna prompt ini untuk setup projek Workers dari kosong, install dependencies, dan configure wrangler.toml untuk development agent.

Prompt

Saya nak setup projek Cloudflare Workers baru untuk bina AI Agent. Tolong berikan arahan langkah demi langkah untuk: 1. Create projek Workers dengan nama "agent-saya" 2. Install @anthropic-ai/sdk 3. Configure wrangler.toml dengan nodejs_compat 4. Set CLAUDE_API_KEY sebagai secret 5. Test worker di localhost Saya guna JavaScript, bukan TypeScript.

2 Bina Chat Agent dengan System Prompt [Personality]

Guna prompt ini untuk bina chat agent asas dengan Claude API dan tambah system prompt untuk personality dan role.

Prompt

Bina Cloudflare Worker chat agent yang menggunakan Claude API. Agent perlu: - Endpoint POST /chat yang terima JSON {message: String} - Balas JSON {reply: String} - Ada system prompt: "Anda adalah 'Si Cerdik' — pembantu coding yang mesra, guna Bahasa Melayu, suka explain dengan analogi, sentiasa beri contoh kod" Guna model claude-sonnet-4-20250514.

3 Tambah State Management — Agent Ingat [Data]

Guna prompt ini untuk tambah Durable Objects supaya agent boleh ingat perbualan dan data user secara persist.

Prompt

Tambah Durable Objects untuk persistent state dalam Cloudflare Worker chat agent saya. Saya sudah ada projek Workers dengan Claude API integration. Sekarang saya nak: 1. ChatAgent class guna Durable Objects dengan storage untuk messages array 2. Worker handler yang routing ke ChatAgent berdasarkan sessionId (dari request body) 3. Agent ingat full conversation history untuk setiap sessionId 4. wrangler.toml dengan binding dan migration Berikan kod lengkap untuk chat-agent.js, index.js, dan wrangler.toml.

4 Tambah Tool: Web Search Capability

Guna prompt ini untuk tambah keupayaan web search kepada agent menggunakan Claude's tool use feature.

Prompt

Tambah web search tool kepada AI Agent saya yang guna Claude API. Guna Anthropic tool_use / function calling. Agent perlu: - Define tool "web_search" dengan input query: string - Bila Claude panggil tool, execute web search (guna fetch atau API) - Hantar result balik ke Claude untuk final response - Handle tool_use dalam loop Saya prefer guna fetch terus ke search API (Google Custom Search atau SerpAPI). Berikan kod lengkap untuk integrate tool use dalam worker.

5 Tambah Tool: Database Query Capability

Guna prompt ini untuk benarkan agent query database (SQL) untuk mendapatkan data.

Prompt

Tambah database query tool kepada AI Agent saya. Agent saya guna Cloudflare Workers + Claude API. Saya nak tambah tool yang benarkan agent query database: 1. Tool "query_database" dengan input { query: string, params: array } 2. Bila Claude panggil tool, execute SQL query 3. Return result dalam JSON 4. Handle error dengan graceful Guna D1 (Cloudflare's SQL database) atau Neon (Postgres) sebagai database. Berikan kod connection dan tool handler.

6 Setup WebSocket untuk Real-time Chat

Guna prompt ini untuk tambah WebSocket support — agent boleh stream response dan handle real-time communication.

Prompt

Tambah WebSocket support kepada Cloudflare Worker chat agent saya. Agent perlu: 1. Endpoint /ws untuk WebSocket upgrade 2. Accept connection dan handle message events 3. Stream response word-by-word (50ms delay antara words) 4. Handle sessionId untuk memory 5. Send JSON {type: 'chunk', content: string} untuk setiap word 6. Send JSON {type: 'done'} bila selesai Saya guna JavaScript dan Claude API. Berikan kod lengkap untuk WebSocket handler.

7 Deploy Agent ke Cloudflare Workers

Guna prompt ini untuk deploy agent yang telah siap ke Cloudflare, set secrets, dan test.

Prompt

Saya nak deploy AI Agent saya ke Cloudflare Workers. Agent saya guna: - Cloudflare Workers - Claude API (@anthropic-ai/sdk) - Durable Objects untuk memory Tolong berikan arahan untuk: 1. Set CLAUDE_API_KEY sebagai wrangler secret 2. Deploy worker menggunakan wrangler deploy 3. Test agent dengan curl 4. Check logs dan troubleshoot jika ada error

8 Tambah Multiple Agents — Agent A Panggil Agent B

Guna prompt ini untuk bina multi-agent architecture — satu agent utama yang boleh delegation task ke agent lain.

Prompt

Bina multi-agent system di Cloudflare Workers dengan dua agent: Agent A (Orchestrator): - Agent utama yang interact dengan user - Bila user minta coding help, dia panggil Agent B - Bila user minta general info, dia jawab sendiri Agent B (Coding Specialist): - Pakar dalam coding questions - Boleh generate code, explain konsep, debug errors - Return response dalam format yang Agent A boleh guna Guna Claude API untuk kedua-dua agent. Agent A decide bila nak delegation ke Agent B. Berikan kod lengkap untuk multi-agent architecture dengan Durable Objects.

⚠️ 10 Kesilapan Biasa AI Agent & Penyelesaian

1. API Key tidak di-set sebagai secret

Masalah: Worker cuba baca env.CLAUDE_API_KEY tapi variable tak wujud. Return error 500.

✅ Penyelesaian: Jalankan npx wrangler secret put CLAUDE_API_KEY SEBELUM deploy. Untuk local dev, guna .dev.vars file: CLAUDE_API_KEY=sk-ant-...

2. "Module not found: @anthropic-ai/sdk"

Masalah: npm dependencies tak diinstal. Worker gagal build sebab module missing.

✅ Penyelesaian: Jalankan npm install @anthropic-ai/sdk dalam folder projek. Pastikan package.json ada dependencies yang betul. Juga pastikan nodejs_compat flag di wrangler.toml.

3. Agent tak ingat perbualan

Masalah: Setiap request baru, state bermula kosong. Agent lupa semua yang user cakap.

✅ Penyelesaian: Implement Durable Objects. Setiap request guna sessionId yang sama untuk access state yang sama. Pastikan messages array disimpan ke storage selepas setiap exchange.

4. CORS error bila panggil dari browser

Masalah: Browser block request sebab worker tak set Access-Control-Allow-Origin headers.

✅ Penyelesaian: Tambah CORS headers dalam setiap response: Access-Control-Allow-Origin: *. Handle OPTIONS (preflight) request dengan return 200. Jangan lupa Access-Control-Allow-Headers: Content-Type.

5. Response timeout — worker lambat balas

Masalah: Claude API ambil masa 5-15 saat. Cloudflare Workers ada 30 saat limit untuk HTTP fetch.

✅ Penyelesaian: Guna model lebih cepat (claude-haiku-3-5). Kurangkan max_tokens. Implement streaming response supaya user nampak progres. Atau guna WebSocket untuk elakkan HTTP timeout.

6. Agent bagi jawapan Bahasa Inggeris

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

✅ Penyelesaian: Dalam system prompt, tulis dengan explicit: "Anda MESTI menjawab dalam Bahasa Melayu sahaja. Walaupun user bertanya dalam Bahasa Inggeris, jawab dalam Bahasa Melayu." Letakkan peraturan ini di awal system prompt.

7. Durable Objects migration error

Masalah: wrangler.toml takde migration config. DO gagal di-deploy.

✅ Penyelesaian: Tambah [[migrations]] block dalam wrangler.toml. Setiap kali tambah class DO baru, kena tambah migration entry dengan new_classes. Juga pastikan [[durable_objects.bindings]] pointing ke class yang betul.

8. Token limit exceeded

Masalah: Conversation terlalu panjang, melebihi context window Claude.

✅ Penyelesaian: Implement conversation summarization — ringkaskan old messages bila panjang melebihi threshold. Atau trim oldest messages. Claude Sonnet ada 200K context, tapi untuk agent dengan memory panjang, summarization adalah penting.

9. Tool call infinite loop

Masalah: Agent panggil tool berulang kali tanpa henti, atau tool result menyebabkan agent panggil tool lagi.

✅ Penyelesaian: Set maximum tool calls per request (contoh: 5). Track number of tool calls dalam loop. Bila exceed limit, force Claude untuk give final response tanpa tools. Simpan limit dalam state.

10. Worker terlalu besar untuk deploy

Masalah: Bundle size melebihi 1MB (Cloudflare Workers limit untuk free tier).

✅ Penyelesaian: Guna wrangler deploy --dry-run untuk check bundle size. Optimize: tree-shake dependencies, jangan import semua SDK (guna REST API terus), atau upgrade ke Workers Paid Plan (bundle sehingga 10MB).

📚 Cloudflare Agents SDK Cheatsheet

📦 Setup & Konfigurasi

Command / Config	Penerangan
npx create-cloudflare@latest [name]	Create projek Workers baru
npm install @anthropic-ai/sdk	Install Claude API SDK
npm install agents-sdk	Install Cloudflare Agents SDK
compatibility_flags = ["nodejs_compat"]	Flags penting dalam wrangler.toml
npx wrangler dev	Run worker di localhost:8787
npx wrangler deploy	Deploy worker ke Cloudflare
npx wrangler secret put [KEY]	Set environment variable sebagai secret

🤖 Agent Core Concepts

Konsep	Penerangan	Code Example
Agent Class	Class utama untuk agent	export class MyAgent extends Agent {}
fetch handler	Entry point worker	async fetch(request, env) {}
State/Storage	Persistent state guna DO	this.state.storage.put(key, val)
State get	Baca state dari storage	this.state.storage.get(key)
Agent ID	Unique ID untuk setiap session	env.CHAT_AGENT.idFromName(sessionId)
Agent Stub	Reference ke agent instance	env.CHAT_AGENT.get(agentId)

💬 Claude API Integration

Code	Penerangan
new Anthropic({apiKey: env.CLAUDE_API_KEY})	Init Claude client
anthropic.messages.create({model, max_tokens, messages})	Send message ke Claude
response.content[0].text	Extract text reply dari response
model: 'claude-sonnet-4-20250514'	Model Sonnet terkini (recommended)
model: 'claude-haiku-3-5-20241022'	Model Haiku — lebih murah & cepat
system: 'Anda adalah...'	System prompt untuk personality
tools: [{name, description, input_schema}]	Define tools untuk Claude
response.stop_reason === 'tool_use'	Check jika Claude nak guna tool

🌐 WebSocket & RPC

Code	Penerangan
new WebSocketPair()	Create WebSocket connection pair
server.accept()	Accept WebSocket connection
server.addEventListener('message', fn)	Handle incoming WebSocket messages
server.send(JSON.stringify(data))	Send data melalui WebSocket
return new Response(null, { status: 101, webSocket: client })	Upgrade ke WebSocket
stub.chat(message)	Panggil method agent lain (RPC)

🛠️ Debugging & Troubleshooting

Command	Penerangan
npx wrangler tail	Stream live logs dari worker production
npx wrangler deploy --dry-run	Check bundle size tanpa deploy
npx wrangler dev --ip 0.0.0.0	Local dev accessible dari device lain
npx wrangler d1 execute [db] --command "SQL"	Execute SQL query terus di D1 database
CF_ACCOUNT_ID + CF_API_TOKEN	Environment variables untuk API access

💡 Claude API Integration Tips

1. Pilih Model yang Tepat

Model	Kelebihan	Kekurangan	Sesuai Untuk
claude-sonnet-4-20250514	Paling pintar, 200K context	Lebih mahal, lebih lambat	Agent yang perlukan reasoning mendalam
claude-haiku-3-5-20241022	Cepat, murah, masih bagus	Kurang sesuai untuk complex tasks	Chat agent ringkas, real-time apps

2. Optimal Penggunaan Token

max_tokens: Set ikut keperluan. 256-512 untuk response pendek. 1024-2048 untuk response detailed. 4096+ untuk code generation.
Context window: Claude Sonnet 200K token. Tapi jangan guna semua untuk free tier — makin panjang context, makin mahal.
Message trimming: Bila messages terlalu panjang, trim oldest messages. Simpan system prompt, recent context, dan summarization old messages.
Cache system prompt: System prompt yang panjang boleh di-cache dengan cached: true untuk jimat cost.

3. Streaming Response

// Stream response dari Claude
const stream = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: messages,
  stream: true  // Enable streaming
});

for await (const chunk of stream) {
  if (chunk.type === 'content_block_delta') {
    const text = chunk.delta.text;
    // Hantar text ke client melalui WebSocket
    server.send(JSON.stringify({ type: 'chunk', content: text }));
  }
}

4. Error Handling

try {
  const response = await anthropic.messages.create({...});
  return response.content[0].text;
} catch (error) {
  if (error.status === 429) {
    // Rate limited — tunggu dan retry
    return 'Maaf, terlalu banyak request. Cuba lagi nanti.';
  }
  if (error.status === 401) {
    // API key invalid
    return 'API key tidak sah. Sila semak CLAUDE_API_KEY.';
  }
  if (error.status === 400) {
    // Bad request — kemungkinan messages format salah
    return 'Format mesej tidak betul. Cuba lagi.';
  }
  // Generic error
  return `Ralat: ${error.message}`;
}

5. Cost Management

Model	Input (per 1M tokens)	Output (per 1M tokens)
claude-sonnet-4	$3.00	$15.00
claude-haiku-3-5	$0.80	$4.00

Untuk kelas 20 pelajar selama 4-6 jam, budget $10-20 adalah mencukupi jika guna model haiku untuk development dan sonnet untuk production.

6. Security Best Practices

API Key: Jangan simpan API key dalam kod. Guna wrangler secret atau environment variables.
Input Validation: Validate user input sebelum hantar ke Claude. Jangan bagi attacker control system prompt.
Rate Limiting: Limit requests per user per minute untuk elakkan abuse dan cost spike.
Prompt Injection: Guard agent dari prompt injection — validate user input, sanitize, dan gunakan system prompt yang kukuh.
Logging: Log semua requests tapi jangan log sensitive data (API keys, passwords).

📄 Rujukan Pantas

Tindakan	Command / Code
Create Workers project	npx create-cloudflare@latest project-name --framework=javascript
Install Claude SDK	npm install @anthropic-ai/sdk
Local dev	npx wrangler dev
Deploy	npx wrangler deploy
Set secret	npx wrangler secret put CLAUDE_API_KEY
View logs	npx wrangler tail
Init Claude	new Anthropic({apiKey: env.CLAUDE_API_KEY})
Send message	anthropic.messages.create({model, max_tokens, messages})
Get reply text	response.content[0].text
Durable Object binding	[[durable_objects.bindings]] name / class_name
DO get state	this.state.storage.get('messages')
DO set state	this.state.storage.put('messages', val)
DO agent ID	env.BINDING.idFromName(sessionId)
DO agent stub	env.BINDING.get(agentId)
WebSocket upgrade	new Response(null, {status: 101, webSocket: client})
CORS headers	Access-Control-Allow-Origin: *

🔗 Sumber & Rujukan Lain

Cloudflare Workers Docs: developers.cloudflare.com/workers
Cloudflare Durable Objects: developers.cloudflare.com/durable-objects
Anthropic Claude API Docs: docs.anthropic.com
Claude API Console: console.anthropic.com (dapatkan API key)
Cloudflare Agents SDK: github.com/cloudflare/agents-sdk
Wrangler CLI Reference: developers.cloudflare.com/workers/wrangler
Claude Prompt Engineering: docs.anthropic.com/en/docs/prompt-engineering
Cloudflare Workers Pricing: developers.cloudflare.com/workers/pricing

Nota: Semua sumber di atas adalah percuma untuk diakses. Cloudflare Workers ada free tier yang generous (100k requests/day). Claude API adalah berbayar — gunakan API key yang disediakan oleh pengajar.