Membangun AI Agents dengan Claude Agent SDK: Panduan Praktis

Claude 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.

Tidak 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.

Arsitektur

SDK mengikuti loop sederhana: kumpulkan context, lakukan tindakan, verifikasi, ulangi.

Titik 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.

Memulai

Instalasi

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

Anda memerlukan Anthropic API key yang diatur sebagai ANTHROPIC_API_KEY di environment Anda.

Agent Pertama Anda

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

Itu 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.

Versi Python

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

Built-in Tools

SDK dikirim dengan tools yang sama yang tersedia di Claude Code:

Anda mengontrol tools mana yang dapat digunakan agent melalui allowedTools. Jika sebuah tool tidak ada dalam daftar, agent tidak dapat memanggilnya.

Permission Modes

Karena agents mengeksekusi perintah nyata pada sistem nyata, permissions itu penting.

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

Untuk penggunaan production, selalu jalankan agents di sandboxed environments (containers, VMs) dan gunakan permission mode yang paling ketat yang masih memungkinkan agent melakukan tugasnya.

Membangun Custom Tools dengan MCP

Kekuatan 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.

Contoh: Weather Tool

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Custom tools mengikuti konvensi penamaan mcp__{server_name}__{tool_name}. Anda dapat menggunakan wildcard di allowedTools: "mcp__weather__*" mengizinkan semua tools dari weather server.

Contoh: Database Query Tool

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

Menghubungkan MCP Servers Eksternal

Selain 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.

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

Anda dapat menggabungkan beberapa MCP servers. Agent melihat semua tools dari semua server yang terhubung dan menggunakannya sesuai kebutuhan.

Multi-Agent Orchestration

Untuk workflow yang kompleks, Anda dapat mendefinisikan sub-agents khusus yang didelegasikan oleh parent agent. Setiap sub-agent memiliki prompt, tools, dan area fokus sendiri.

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

Sertakan "Agent" di allowedTools parent untuk mengaktifkan delegasi. Sub-agents berjalan dengan tools mereka sendiri dan tidak dapat mengakses tools parent kecuali diberikan secara eksplisit.

Sessions dan Kontinuitas

Agents dapat mempertahankan context di beberapa query menggunakan sessions. Tangkap session_id dari interaksi pertama dan teruskan di resume untuk query berikutnya.

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

Jika 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.

Perbedaan 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.

Harga:

• Agent SDK: hanya tarif token Claude API standar. Anda menangani hosting.
• Managed Agents: tarif token ditambah $0,08 per session-hour (ditagih per millisecond).

Best Practices Production

1. Selalu Gunakan Sandbox

Jangan pernah menjalankan agents dengan permissions tak terbatas pada mesin production. Gunakan containers (Docker, Fly.io, Modal) atau sandboxed environments (E2B, Vercel Sandbox).

2. Batasi Akses Tool

Ikuti prinsip privilege paling sedikit. Agent yang menghasilkan laporan tidak memerlukan Bash atau Write.

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. Gunakan Hooks untuk Guardrails

Hooks memungkinkan Anda mencegat tool calls sebelum dan sesudah eksekusi. Gunakan untuk logging, validasi, dan rate limiting.

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. Tangani Error dengan Baik

Agent loop dapat menghasilkan error - kegagalan tool, batas rate API, context window overflow. Selalu periksa tipe pesan.

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. Pantau Penggunaan Token

Agent loops dapat mengonsumsi token yang signifikan, terutama dengan codebase besar. SDK mencakup context compaction otomatis, tetapi Anda tetap harus memantau penggunaan.

Kesimpulan

Claude 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.

Mulai 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.

Agent loop adalah yang sama dengan yang menggerakkan Claude Code. Jika ia dapat membangun perangkat lunak, agents Anda juga bisa.

Getting Started Checklist:

• Instal SDK (npm install @anthropic-ai/claude-agent-sdk)
• Atur ANTHROPIC_API_KEY di environment Anda
• Bangun agent sederhana dengan built-in tools (Read, Glob, Grep)
• Tambahkan custom tool melalui in-process MCP server
• Hubungkan MCP server eksternal (GitHub, PostgreSQL, dll.)
• Implementasikan multi-agent orchestration dengan sub-agents
• Siapkan sandboxed environment untuk production
• Tambahkan hooks untuk logging dan guardrails