Membina AI Agents dengan Claude Agent SDK: Panduan Praktikal

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

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

Seni Bina

SDK mengikut loop yang mudah: kumpul context, ambil tindakan, sahkan, ulang.

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

Memulakan

Pemasangan

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

# Python
pip install claude-agent-sdk

Anda memerlukan Anthropic API key yang ditetapkan sebagai ANTHROPIC_API_KEY dalam 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 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.

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 dihantar dengan tools yang sama yang tersedia dalam Claude Code:

Anda mengawal tools mana yang boleh digunakan agent melalui allowedTools. Jika sesuatu tool tiada dalam senarai, agent tidak boleh memanggilnya.

Permission Modes

Oleh kerana agents melaksanakan perintah sebenar pada sistem sebenar, permissions adalah penting.

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

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

Membina Custom Tools dengan MCP

Kekuatan sebenar SDK datang daripada mengembangkan agents dengan tools anda sendiri. Custom tools ditakrifkan sebagai in-process MCP servers - tiada pengurusan subprocess, tiada overhead rangkaian.

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 mengikut konvensyen penamaan mcp__{server_name}__{tool_name}. Anda boleh menggunakan wildcard dalam allowedTools: "mcp__weather__*" membenarkan semua tools daripada 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),
        },
      ],
    };
  }
);

Menyambung ke MCP Servers Luaran

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

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 boleh menggabungkan beberapa MCP servers. Agent melihat semua tools daripada semua server yang disambungkan dan menggunakannya mengikut keperluan.

Multi-Agent Orchestration

Untuk workflow yang kompleks, anda boleh menentukan sub-agents khusus yang diwakilkan oleh parent agent. Setiap sub-agent mempunyai prompt, tools, dan bidang 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" dalam allowedTools parent untuk mengaktifkan delegasi. Sub-agents berjalan dengan tools mereka sendiri dan tidak boleh mengakses tools parent melainkan diberikan secara eksplisit.

Sessions dan Kesinambungan

Agents boleh mengekalkan context merentas beberapa queries menggunakan sessions. Tangkap session_id daripada interaksi pertama dan hantarkannya dalam resume untuk queries seterusnya.

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

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

Harga:

• Agent SDK: kadar token Claude API standard sahaja. Anda mengendalikan hosting.
• Managed Agents: kadar token ditambah $0.08 setiap session-hour (dibilkan setiap millisecond).

Production Best Practices

1. Sentiasa Sandbox

Jangan sekali-kali menjalankan agents dengan permissions tanpa had pada mesin production. Gunakan containers (Docker, Fly.io, Modal) atau sandboxed environments (E2B, Vercel Sandbox).

2. Hadkan Akses Tool

Ikuti prinsip privilege paling sedikit. Agent yang menjana 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 membolehkan anda memintas tool calls sebelum dan selepas pelaksanaan. Gunakannya untuk logging, pengesahan, 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. Kendalikan Ralat dengan Baik

Agent loop boleh menghasilkan ralat - kegagalan tool, had kadar API, limpahan context window. Sentiasa semak jenis mesej.

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 boleh menggunakan token yang ketara, terutamanya dengan codebase yang besar. SDK merangkumi context compaction automatik, tetapi anda masih perlu memantau penggunaan.

Kesimpulan

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

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

Agent loop adalah yang sama dengan yang menjalankan Claude Code. Jika ia boleh membina perisian, agents anda juga boleh.

Getting Started Checklist:

• Pasang SDK (npm install @anthropic-ai/claude-agent-sdk)
• Tetapkan ANTHROPIC_API_KEY dalam environment anda
• Bina agent mudah dengan built-in tools (Read, Glob, Grep)
• Tambah custom tool melalui in-process MCP server
• Sambungkan MCP server luaran (GitHub, PostgreSQL, dll.)
• Laksanakan multi-agent orchestration dengan sub-agents
• Sediakan sandboxed environment untuk production
• Tambah hooks untuk logging dan guardrails