1~
2Claude Agent SDK memberi Anda akses programatik ke agent loop yang sama yang menggerakkan Claude Code. Agents Anda dapat membaca file, mengeksekusi perintah shell, mencari di web, mengedit kode, memanggil API eksternal melalui MCP servers, dan mengatur sub-agents  -  semuanya hanya dari beberapa baris TypeScript atau Python.
3~
4Tidak seperti Anthropic Client SDK standar di mana Anda membangun tool loop sendiri, Agent SDK menangani tool execution, context management, retries, dan orchestration secara internal. Anda menggambarkan apa yang Anda inginkan, menyediakan tools, dan agent akan mencari tahu sisanya.
5~
6## Arsitektur
7~
8SDK mengikuti loop sederhana: **kumpulkan context, lakukan tindakan, verifikasi, ulangi**.
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 pesan saat agent bekerja. Setiap pesan memberi tahu Anda apa yang sedang dilakukan agent: bernalar, memanggil tool, menerima hasil, atau mengirimkan output akhir.
37~
38## Memulai
39~
40### Instalasi
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 diatur sebagai `ANTHROPIC_API_KEY` di 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 saja. Agent akan menggunakan Glob untuk menemukan file, Grep untuk mencari pola TODO, Read untuk memeriksa kecocokan, dan mengembalikan ringkasan terstruktur. Anda tidak menulis logika 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 dikirim dengan tools yang sama yang tersedia di Claude Code:
94~
95| Tool | Description |
96|------|-------------|
97| **Read** | Membaca konten file |
98| **Write** | Membuat file baru |
99| **Edit** | Melakukan edit tertarget pada file yang ada |
100| **Bash** | Menjalankan perintah shell |
101| **Glob** | Menemukan file berdasarkan pola |
102| **Grep** | Mencari konten file dengan regex |
103| **WebSearch** | Mencari di web |
104| **WebFetch** | Mengambil URL dan mengembalikan kontennya |
105| **AskUserQuestion** | Meminta input dari user |
106~
107Anda mengontrol tools mana yang dapat digunakan agent melalui `allowedTools`. Jika sebuah tool tidak ada dalam daftar, agent tidak dapat memanggilnya.
108~
109## Permission Modes
110~
111Karena agents mengeksekusi perintah nyata pada sistem nyata, permissions itu penting.
112~
113| Mode | Behavior | Use Case |
114|------|----------|----------|
115| `default` | Custom `canUseTool` callback memutuskan per-panggilan | Kontrol halus |
116| `acceptEdits` | Auto-approve operasi file, meminta untuk Bash | Development workflows |
117| `dontAsk` | Menolak apapun yang tidak ada di allowedTools | Restricted agents |
118| `bypassPermissions` | Menyetujui semuanya secara otomatis | Trusted sandboxed environments |
119| `auto` | Model classifier memutuskan keamanan | 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, selalu jalankan agents di sandboxed environments (containers, VMs) dan gunakan permission mode yang paling ketat yang masih memungkinkan agent melakukan tugasnya.
132~
133## Membangun Custom Tools dengan MCP
134~
135Kekuatan sebenarnya dari SDK datang dari memperluas agents dengan tools Anda sendiri. Custom tools didefinisikan sebagai in-process MCP servers  -  tanpa manajemen subprocess, tanpa overhead jaringan.
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 mengikuti konvensi penamaan `mcp__{server_name}__{tool_name}`. Anda dapat menggunakan wildcard di `allowedTools`: `"mcp__weather__*"` mengizinkan semua tools dari 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## Menghubungkan MCP Servers Eksternal
218~
219Selain tools in-process, Anda dapat terhubung ke MCP server yang sudah ada  -  server yang sama yang bekerja dengan Claude Desktop, Cursor, dan MCP clients lainnya.
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 dapat menggabungkan beberapa MCP servers. Agent melihat semua tools dari semua server yang terhubung dan menggunakannya sesuai kebutuhan.
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 dapat mendefinisikan sub-agents khusus yang didelegasikan oleh parent agent. Setiap sub-agent memiliki prompt, tools, dan area 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"` di `allowedTools` parent untuk mengaktifkan delegasi. Sub-agents berjalan dengan tools mereka sendiri dan tidak dapat mengakses tools parent kecuali 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 Kontinuitas
297~
298Agents dapat mempertahankan context di beberapa query menggunakan sessions. Tangkap `session_id` dari interaksi pertama dan teruskan di `resume` untuk query berikutnya.
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 ingin meng-host infrastruktur agent sendiri, **Claude Managed Agents** (diluncurkan April 2026) menyediakan layanan cloud yang dikelola sepenuhnya. Anthropic menjalankan containers, menangani 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~
343Perbedaan utama: dengan Agent SDK, Anda menjalankan agent loop di infrastruktur Anda sendiri. Dengan Managed Agents, Anthropic meng-host dan menjalankan agent untuk Anda. Anda berinteraksi melalui API berbasis session dan menerima event melalui Server-Sent Events.
344~
345**Harga:**
346- **Agent SDK**: hanya tarif token Claude API standar. Anda menangani hosting.
347- **Managed Agents**: tarif token ditambah $0,08 per session-hour (ditagih per millisecond).
348~
349## Best Practices Production
350~
351### 1. Selalu Gunakan Sandbox
352~
353Jangan pernah menjalankan agents dengan permissions tak terbatas pada mesin production. Gunakan containers (Docker, Fly.io, Modal) atau sandboxed environments (E2B, Vercel Sandbox).
354~
355### 2. Batasi Akses Tool
356~
357Ikuti prinsip privilege paling sedikit. Agent yang menghasilkan 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 memungkinkan Anda mencegat tool calls sebelum dan sesudah eksekusi. Gunakan untuk logging, validasi, 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. Tangani Error dengan Baik
391~
392Agent loop dapat menghasilkan error  -  kegagalan tool, batas rate API, context window overflow. Selalu periksa tipe pesan.
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 dapat mengonsumsi token yang signifikan, terutama dengan codebase besar. SDK mencakup context compaction otomatis, tetapi Anda tetap harus memantau penggunaan.
415~
416## Kesimpulan
417~
418Claude Agent SDK mengubah LLM dari mesin penjawab pertanyaan menjadi sesuatu yang lebih mirip developer junior. Agents Anda dapat membaca, menulis, mengeksekusi, memverifikasi, dan beriterasi  -  alur kerja yang sama yang diikuti manusia.
419~
420Mulai dari kecil: bangun agent dengan beberapa built-in tools. Kemudian tambahkan custom MCP tools untuk domain spesifik Anda. Tingkatkan ke multi-agent orchestration ketika workflow Anda memerlukan spesialisasi.
421~
422Agent loop adalah yang sama dengan yang menggerakkan Claude Code. Jika ia dapat membangun perangkat lunak, agents Anda juga bisa.
423~
424> **Getting Started Checklist:**
425>
426> - [x] Instal SDK (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] Atur `ANTHROPIC_API_KEY` di environment Anda
428> - [x] Bangun agent sederhana dengan built-in tools (Read, Glob, Grep)
429> - [x] Tambahkan custom tool melalui in-process MCP server
430> - [x] Hubungkan MCP server eksternal (GitHub, PostgreSQL, dll.)
431> - [x] Implementasikan multi-agent orchestration dengan sub-agents
432> - [x] Siapkan sandboxed environment untuk production
433> - [x] Tambahkan hooks untuk logging dan guardrails
434~