1 
2Claude Agent SDK memberikan anda akses programatik kepada agent loop yang sama yang menjalankan Claude Code. Agents anda boleh membaca fail, melaksanakan perintah shell, mencari di web, mengedit kod, memanggil API luaran melalui MCP servers, dan mengurus sub-agents  -  semuanya hanya daripada beberapa baris TypeScript atau Python.
3 
4Tidak seperti Anthropic Client SDK standard di mana anda membina tool loop sendiri, Agent SDK mengendalikan tool execution, context management, retries, dan orchestration secara dalaman. Anda menerangkan apa yang anda mahu, menyediakan tools, dan agent akan memikirkan selebihnya.
5 
6## Seni Bina
7 
8SDK mengikut loop yang mudah: **kumpul context, ambil tindakan, sahkan, ulang**.
9 
10```mermaid
11graph TD
12    Input[User Prompt] --> Loop[Agent Loop]
13    Loop --> Reason[Claude Reasons]
14    Reason --> Tool[Call Tool]
15    Tool --> Result[Tool Result]
16    Result --> Loop
17    Reason --> Done[Final Response]
18 
19    subgraph "Built-in Tools"
20        T1[Read / Write / Edit]
21        T2[Bash / Terminal]
22        T3[Glob / Grep]
23        T4[WebSearch / WebFetch]
24    end
25 
26    subgraph "Custom Tools via MCP"
27        M1[Your API]
28        M2[Database]
29        M3[Slack / GitHub / etc.]
30    end
31 
32    Tool --> T1
33    Tool --> M1
34```
35 
36Titik masuk utama adalah `query()`, yang mengembalikan async iterator yang men-stream mesej semasa agent bekerja. Setiap mesej memberitahu anda apa yang sedang dilakukan agent: menaakul, memanggil tool, menerima hasil, atau menyampaikan output akhir.
37 
38## Memulakan
39 
40### Pemasangan
41 
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45 
46# Python
47pip install claude-agent-sdk
48```
49 
50Anda memerlukan Anthropic API key yang ditetapkan sebagai `ANTHROPIC_API_KEY` dalam environment anda.
51 
52### Agent Pertama Anda
53 
54```typescript
55import { query } from "@anthropic-ai/claude-agent-sdk";
56 
57const conversation = query({
58  prompt: "Find all TODO comments in the codebase and create a summary",
59  options: {
60    allowedTools: ["Read", "Glob", "Grep"],
61  },
62});
63 
64for await (const message of conversation) {
65  if (message.type === "assistant") {
66    process.stdout.write(message.content);
67  }
68  if (message.type === "result" && message.subtype === "success") {
69    console.log("\nDone:", message.result);
70  }
71}
72```
73 
74Itu sahaja. Agent akan menggunakan Glob untuk mencari fail, Grep untuk mencari corak TODO, Read untuk memeriksa padanan, dan mengembalikan ringkasan berstruktur. Anda tidak menulis logik orchestration  -  SDK yang menanganinya.
75 
76### Versi Python
77 
78```python
79from claude_agent_sdk import query
80 
81async for message in query(
82    prompt="Find all TODO comments in the codebase and create a summary",
83    options={"allowed_tools": ["Read", "Glob", "Grep"]},
84):
85    if message.type == "assistant":
86        print(message.content, end="")
87    if message.type == "result" and message.subtype == "success":
88        print(f"\nDone: {message.result}")
89```
90 
91## Built-in Tools
92 
93SDK dihantar dengan tools yang sama yang tersedia dalam Claude Code:
94 
95| Tool | Description |
96|------|-------------|
97| **Read** | Membaca kandungan fail |
98| **Write** | Mencipta fail baru |
99| **Edit** | Membuat suntingan bersasar pada fail sedia ada |
100| **Bash** | Melaksanakan perintah shell |
101| **Glob** | Mencari fail mengikut corak |
102| **Grep** | Mencari kandungan fail dengan regex |
103| **WebSearch** | Mencari di web |
104| **WebFetch** | Mengambil URL dan mengembalikan kandungannya |
105| **AskUserQuestion** | Meminta input daripada user |
106 
107Anda mengawal tools mana yang boleh digunakan agent melalui `allowedTools`. Jika sesuatu tool tiada dalam senarai, agent tidak boleh memanggilnya.
108 
109## Permission Modes
110 
111Oleh kerana agents melaksanakan perintah sebenar pada sistem sebenar, permissions adalah penting.
112 
113| Mode | Behavior | Use Case |
114|------|----------|----------|
115| `default` | Custom `canUseTool` callback memutuskan setiap panggilan | Kawalan terperinci |
116| `acceptEdits` | Lulus automatik operasi fail, minta untuk Bash | Development workflows |
117| `dontAsk` | Menolak apa-apa yang tiada dalam allowedTools | Restricted agents |
118| `bypassPermissions` | Meluluskan semuanya secara automatik | Trusted sandboxed environments |
119| `auto` | Pengelas model memutuskan keselamatan | Automasi seimbang |
120 
121```typescript
122const conversation = query({
123  prompt: "Refactor the auth module to use JWT",
124  options: {
125    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
126    permissionMode: "acceptEdits",
127  },
128});
129```
130 
131Untuk penggunaan production, sentiasa jalankan agents dalam sandboxed environments (containers, VMs) dan gunakan permission mode yang paling ketat yang masih membenarkan agent melakukan tugasnya.
132 
133## Membina Custom Tools dengan MCP
134 
135Kekuatan sebenar SDK datang daripada mengembangkan agents dengan tools anda sendiri. Custom tools ditakrifkan sebagai in-process MCP servers  -  tiada pengurusan subprocess, tiada overhead rangkaian.
136 
137### Contoh: Weather Tool
138 
139```typescript
140import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
141import { z } from "zod";
142 
143const getTemperature = tool(
144  "get_temperature",
145  "Get the current temperature at a location",
146  {
147    latitude: z.number().describe("Latitude"),
148    longitude: z.number().describe("Longitude"),
149  },
150  async ({ latitude, longitude }) => {
151    const res = await fetch(
152      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
153    );
154    const data = await res.json();
155    return {
156      content: [
157        {
158          type: "text",
159          text: `Current temperature: ${data.current.temperature_2m}C`,
160        },
161      ],
162    };
163  }
164);
165 
166const weatherServer = createSdkMcpServer({
167  name: "weather",
168  version: "1.0.0",
169  tools: [getTemperature],
170});
171 
172for await (const message of query({
173  prompt: "What's the weather like in Rome?",
174  options: {
175    mcpServers: { weather: weatherServer },
176    allowedTools: ["mcp__weather__get_temperature"],
177  },
178})) {
179  if (message.type === "result" && message.subtype === "success") {
180    console.log(message.result);
181  }
182}
183```
184 
185Custom tools mengikut konvensyen penamaan `mcp__{server_name}__{tool_name}`. Anda boleh menggunakan wildcard dalam `allowedTools`: `"mcp__weather__*"` membenarkan semua tools daripada weather server.
186 
187### Contoh: Database Query Tool
188 
189```typescript
190const queryDb = tool(
191  "query_database",
192  "Run a read-only SQL query against the application database",
193  {
194    sql: z.string().describe("SQL SELECT query to execute"),
195  },
196  async ({ sql }) => {
197    // Validate: only allow SELECT queries
198    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
199      return {
200        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
201      };
202    }
203 
204    const result = await pool.query(sql);
205    return {
206      content: [
207        {
208          type: "text",
209          text: JSON.stringify(result.rows, null, 2),
210        },
211      ],
212    };
213  }
214);
215```
216 
217## Menyambung ke MCP Servers Luaran
218 
219Selain tools in-process, anda boleh menyambung ke mana-mana MCP server sedia ada  -  server yang sama yang berfungsi dengan Claude Desktop, Cursor, dan MCP clients lain.
220 
221```typescript
222for await (const message of query({
223  prompt: "Check the latest issues in the frontend repo and summarize them",
224  options: {
225    mcpServers: {
226      github: {
227        command: "npx",
228        args: ["-y", "@modelcontextprotocol/server-github"],
229        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
230      },
231    },
232    allowedTools: ["mcp__github__*"],
233  },
234})) {
235  // ...
236}
237```
238 
239Anda boleh menggabungkan beberapa MCP servers. Agent melihat semua tools daripada semua server yang disambungkan dan menggunakannya mengikut keperluan.
240 
241```mermaid
242graph LR
243    Agent[Your Agent] --> SDK[Agent SDK]
244    SDK --> InProcess[In-process MCP\nCustom Tools]
245    SDK --> GitHub[GitHub MCP Server]
246    SDK --> Postgres[PostgreSQL MCP Server]
247    SDK --> Slack[Slack MCP Server]
248```
249 
250## Multi-Agent Orchestration
251 
252Untuk workflow yang kompleks, anda boleh menentukan sub-agents khusus yang diwakilkan oleh parent agent. Setiap sub-agent mempunyai prompt, tools, dan bidang fokus sendiri.
253 
254```typescript
255for await (const message of query({
256  prompt: "Review the PR, check for security issues, and update the changelog",
257  options: {
258    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
259    agents: [
260      {
261        name: "security-reviewer",
262        description: "Reviews code for security vulnerabilities",
263        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
264        allowedTools: ["Read", "Glob", "Grep"],
265      },
266      {
267        name: "changelog-writer",
268        description: "Updates the CHANGELOG.md file based on recent changes",
269        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
270        allowedTools: ["Read", "Edit", "Bash"],
271      },
272    ],
273  },
274})) {
275  // The parent agent will:
276  // 1. Read the PR diff
277  // 2. Delegate security review to security-reviewer
278  // 3. Delegate changelog update to changelog-writer
279  // 4. Synthesize results
280}
281```
282 
283Sertakan `"Agent"` dalam `allowedTools` parent untuk mengaktifkan delegasi. Sub-agents berjalan dengan tools mereka sendiri dan tidak boleh mengakses tools parent melainkan diberikan secara eksplisit.
284 
285```mermaid
286graph TD
287    Parent[Parent Agent] --> SR[Security Reviewer\nRead, Glob, Grep]
288    Parent --> CW[Changelog Writer\nRead, Edit, Bash]
289    SR --> Report[Security Report]
290    CW --> Updated[Updated CHANGELOG]
291    Report --> Parent
292    Updated --> Parent
293    Parent --> Final[Final Summary]
294```
295 
296## Sessions dan Kesinambungan
297 
298Agents boleh mengekalkan context merentas beberapa queries menggunakan sessions. Tangkap `session_id` daripada interaksi pertama dan hantarkannya dalam `resume` untuk queries seterusnya.
299 
300```typescript
301let sessionId: string | undefined;
302 
303// First query
304for await (const message of query({
305  prompt: "Read the project structure and understand the architecture",
306  options: { allowedTools: ["Read", "Glob", "Grep"] },
307})) {
308  if (message.type === "init") {
309    sessionId = message.session_id;
310  }
311}
312 
313// Follow-up query (same session, full context preserved)
314for await (const message of query({
315  prompt: "Now refactor the auth module based on what you learned",
316  resume: sessionId,
317  options: { allowedTools: ["Read", "Edit", "Bash"] },
318})) {
319  // Agent remembers the full project context from the first query
320}
321```
322 
323## Claude Managed Agents
324 
325Jika anda tidak mahu meng-host infrastruktur agent sendiri, **Claude Managed Agents** (dilancarkan pada April 2026) menyediakan perkhidmatan cloud yang diurus sepenuhnya. Anthropic menjalankan containers, mengendalikan scaling, dan menyediakan streaming API.
326 
327```mermaid
328graph LR
329    subgraph "Self-hosted (Agent SDK)"
330        Code[Your Code] --> SDK2[Agent SDK]
331        SDK2 --> API[Claude API]
332        SDK2 --> Tools[Your Tools]
333    end
334 
335    subgraph "Managed Agents"
336        App[Your App] --> MAPI[Managed Agents API]
337        MAPI --> Container[Anthropic-hosted Container]
338        Container --> API2[Claude API]
339        Container --> Tools2[Tools in Container]
340    end
341```
342 
343Perbezaan utama: dengan Agent SDK, anda menjalankan agent loop dalam infrastruktur anda sendiri. Dengan Managed Agents, Anthropic meng-host dan menjalankan agent untuk anda. Anda berinteraksi melalui API berasaskan session dan menerima event melalui Server-Sent Events.
344 
345**Harga:**
346- **Agent SDK**: kadar token Claude API standard sahaja. Anda mengendalikan hosting.
347- **Managed Agents**: kadar token ditambah $0.08 setiap session-hour (dibilkan setiap millisecond).
348 
349## Production Best Practices
350 
351### 1. Sentiasa Sandbox
352 
353Jangan sekali-kali menjalankan agents dengan permissions tanpa had pada mesin production. Gunakan containers (Docker, Fly.io, Modal) atau sandboxed environments (E2B, Vercel Sandbox).
354 
355### 2. Hadkan Akses Tool
356 
357Ikuti prinsip privilege paling sedikit. Agent yang menjana laporan tidak memerlukan `Bash` atau `Write`.
358 
359```typescript
360// Too permissive
361allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
362 
363// Better: only what's needed
364allowedTools: ["Read", "Glob", "Grep"]
365```
366 
367### 3. Gunakan Hooks untuk Guardrails
368 
369Hooks membolehkan anda memintas tool calls sebelum dan selepas pelaksanaan. Gunakannya untuk logging, pengesahan, dan rate limiting.
370 
371```typescript
372const conversation = query({
373  prompt: "Analyze the codebase",
374  options: {
375    allowedTools: ["Read", "Glob", "Grep"],
376    hooks: {
377      PreToolUse: async (toolName, input) => {
378        console.log(`Tool call: ${toolName}`, input);
379        // Return false to block the call
380        if (toolName === "Bash" && input.command.includes("rm")) {
381          return false;
382        }
383        return true;
384      },
385    },
386  },
387});
388```
389 
390### 4. Kendalikan Ralat dengan Baik
391 
392Agent loop boleh menghasilkan ralat  -  kegagalan tool, had kadar API, limpahan context window. Sentiasa semak jenis mesej.
393 
394```typescript
395for await (const message of conversation) {
396  switch (message.type) {
397    case "assistant":
398      // Agent reasoning
399      break;
400    case "tool_use":
401      // Agent is calling a tool
402      break;
403    case "result":
404      if (message.subtype === "error") {
405        console.error("Agent failed:", message.error);
406      }
407      break;
408  }
409}
410```
411 
412### 5. Pantau Penggunaan Token
413 
414Agent loops boleh menggunakan token yang ketara, terutamanya dengan codebase yang besar. SDK merangkumi context compaction automatik, tetapi anda masih perlu memantau penggunaan.
415 
416## Kesimpulan
417 
418Claude Agent SDK mengubah LLM daripada mesin menjawab soalan kepada sesuatu yang lebih mirip developer junior. Agents anda boleh membaca, menulis, melaksanakan, mengesahkan, dan mengulang  -  workflow yang sama yang diikuti oleh manusia.
419 
420Mulakan dari kecil: bina agent dengan beberapa built-in tools. Kemudian tambah custom MCP tools untuk domain khusus anda. Skalakan ke multi-agent orchestration apabila workflow anda memerlukan kepakaran.
421 
422Agent loop adalah yang sama dengan yang menjalankan Claude Code. Jika ia boleh membina perisian, agents anda juga boleh.
423 
424> **Getting Started Checklist:**
425>
426> - [x] Pasang SDK (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] Tetapkan `ANTHROPIC_API_KEY` dalam environment anda
428> - [x] Bina agent mudah dengan built-in tools (Read, Glob, Grep)
429> - [x] Tambah custom tool melalui in-process MCP server
430> - [x] Sambungkan MCP server luaran (GitHub, PostgreSQL, dll.)
431> - [x] Laksanakan multi-agent orchestration dengan sub-agents
432> - [x] Sediakan sandboxed environment untuk production
433> - [x] Tambah hooks untuk logging dan guardrails
434