Claude Agent SDK: masukkan Claude Code ke app dengan aman

Kalau kamu ingin memakai Claude Code bukan hanya sebagai asisten interaktif di terminal, tetapi juga di internal tool, CI, pre-review PR, QA konten, atau panel support, target saat ini adalah Claude Agent SDK.

Banyak contoh lama masih memakai @anthropic-ai/claude-code, claude-code-sdk, atau istilah “Claude Code SDK”. Per Juni 2026, dokumentasi resmi mengarahkan TypeScript ke @anthropic-ai/claude-agent-sdk dan Python ke claude-agent-sdk. Sebelum menyalin kode lama, cek Agent SDK overview dan Migration Guide.

Artikel ini bukan demo chatbot. Fokusnya adalah membuat agen yang dapat membaca file, mencari di repository, memanggil tool MCP, membuat perbaikan kecil dengan permission terbatas, menjalankan test tertentu, lalu mengembalikan hasil yang bisa direview manusia.

Cara memahami Agent SDK sekarang

Claude Agent SDK membawa agent loop dari Claude Code ke program TypeScript atau Python. Agent loop berarti Claude memilih aksi berikutnya, memanggil tool, membaca hasilnya, lalu memutuskan langkah berikutnya. Ini berbeda dari satu request chat API biasa.

Topik	Rekomendasi saat ini
Package TypeScript	@anthropic-ai/claude-agent-sdk
Package Python	claude-agent-sdk
CLI vs SDK	CLI untuk manusia, SDK untuk app dan otomasi
Client SDK vs Agent SDK	Client SDK perlu loop sendiri, Agent SDK memakai loop Claude Code
Risiko utama	Permission luas membuat agen kuat sekaligus berbahaya

SDK TypeScript biasanya membawa native binary Claude Code sebagai optional dependency, jadi CLI tidak selalu perlu diinstal terpisah. Jika package manager melewati optional dependencies, binary bisa tidak ditemukan. Perbaiki cara install, atau arahkan pathToClaudeCodeExecutable ke binary claude yang sudah ada.

Setup minimum yang bisa dicopy

Kita memakai TypeScript dan tsx supaya contoh bisa langsung dijalankan.

mkdir claude-agent-sdk-demo
cd claude-agent-sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript tsx @types/node

Atur package.json seperti ini:

{
  "type": "module",
  "scripts": {
    "audit": "tsx src/read-only-audit.ts",
    "runbook": "tsx src/runbook-agent.ts",
    "fix": "tsx src/safe-fix.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest"
  }
}

API key harus lewat environment variable. Jangan simpan di repository, artikel, screenshot, atau log CI.

export ANTHROPIC_API_KEY="sk-ant-..."

Di Windows PowerShell:

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Buat src/read-only-audit.ts. Agen pertama ini sengaja hanya bisa membaca dan mencari, tidak mengedit dan tidak menjalankan Bash.

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

const prompt = [
  "Inspeksi repository ini dalam mode read-only.",
  "Cari TODO comments, dependency lama, dan area dengan test lemah.",
  "Kembalikan daftar prioritas dengan referensi file konkret.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 4,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Jalankan:

npm run audit

Mulai dari read-only itu penting. Validasi dulu apakah output berguna, baru pertimbangkan Edit, Write, atau Bash.

Use case yang benar-benar masuk akal

Claude Agent SDK paling cocok ketika tugas butuh observasi, tool use, dan keputusan. Dalam workflow Masa untuk konten dan engineering, empat kasus ini paling realistis:

Use case	Tool	Output	Guardrail
Pre-review PR	Read, Glob, Grep	Risiko, test hilang, fokus review	Komentar final diposting manusia
Fix kecil yang aman	Read, Edit, Bash(npm test)	Diff minimal dan hasil test	Blokir push, deploy, delete
Triage incident	MCP runbook dan log search	Hipotesis dan next checks	Tool production read-only
QA artikel multibahasa	Read, Grep	mojibake, CTA hilang, link lama	Natural language direview manusia

Untuk konteks lanjutan, baca panduan permissions, panduan MCP server, dan tips produktivitas Claude Code.

Menambahkan Runbook tool dengan MCP

MCP adalah Model Context Protocol. Ini standar untuk mengekspos tool dan data source ke agen. Dokumentasi resmi MCP menunjukkan cara menghubungkan MCP server ke Agent SDK. Contoh di bawah membuat server kecil dalam proses yang sama.

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

const runbooks: Record<string, string> = {
  billing: "Cek failed payments, Stripe webhooks, dan deploy terbaru.",
  search: "Cek index time, Algolia task status, dan API limits.",
  content: "Cek CMS sync, locale slugs, dan keberadaan hero image.",
};

const lookupRunbook = tool(
  "lookup_runbook",
  "Mengembalikan runbook operasi read-only untuk sebuah service",
  { service: z.string().min(1) },
  async ({ service }) => {
    const text = runbooks[service] ?? "Runbook tidak ditemukan.";
    return { content: [{ type: "text", text }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: false } },
);

const runbookServer = createSdkMcpServer({
  name: "runbook",
  version: "1.0.0",
  tools: [lookupRunbook],
});

for await (const message of query({
  prompt: "Sarankan first checks untuk incident content publishing.",
  options: {
    mcpServers: { runbook: runbookServer },
    allowedTools: ["mcp__runbook__lookup_runbook"],
    maxTurns: 3,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Kesalahan umum ada di nama tool. Di allowedTools, tool MCP harus berbentuk mcp__serverName__toolName. Menulis lookup_runbook saja tidak cukup.

Mengizinkan edit tanpa membuka semua akses

Jika audit read-only berguna, kamu bisa memberi izin untuk perbaikan kecil. Baca dulu panduan resmi permissions sebelum memakai agen yang dapat menulis file atau menjalankan command.

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

const prompt = [
  "Perbaiki satu error TypeScript kecil di bawah src.",
  "Setelah itu jalankan npm test dan laporkan ringkasan diff.",
  "Jangan refactor besar dan jangan tambah dependency.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(npm test)",
    ],
    disallowedTools: [
      "Bash(git push)",
      "Bash(git commit)",
      "Bash(rm -rf *)",
    ],
    permissionMode: "default",
    maxTurns: 6,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype, message.result ?? "");
  }
}

Pola ini bukan izin bebas untuk agen. Tujuannya membuat diff kecil dan bukti test yang bisa direview.

Pitfall yang sering terjadi

Pitfall pertama adalah nama lama. Jika contoh memakai @anthropic-ai/claude-code atau ClaudeCodeOptions, cek apakah itu sebelum migrasi.

Pitfall kedua adalah Bash terlalu luas. Shell bebas bisa mencakup git, deploy, cleanup, install package, atau script dengan efek samping. Mulai dari Bash(npm test).

Pitfall ketiga adalah tidak menentukan cwd. Lokal, CI, dan worker bisa berjalan dari folder berbeda. Production code harus menunjuk repository target secara eksplisit.

Pitfall keempat adalah memperlakukan Agent SDK seperti chat SDK biasa. Agen bisa membaca banyak file dan memakai banyak tool turn. Baca cost tracking guide, log usage, dan batasi operasi.

Pitfall kelima adalah custom tool yang tidak jelas. Nama, deskripsi, schema, dan annotation harus memberi sinyal kapan tool dipakai dan apakah read-only.

Checklist, CTA, dan catatan verifikasi

• API key dan token tidak muncul di log.
• Run pertama hanya memakai Read, Glob, Grep.
• Agen yang bisa menulis punya cwd, batas tool, dan maxTurns.
• MCP memisahkan tool read-only dari aksi destruktif.
• Command test spesifik, bukan shell bebas.
• Manusia memeriksa diff dan test output sebelum merge.

Claude Agent SDK bukan tentang mengotomasi semuanya. Pertanyaan yang lebih sehat adalah apakah hasil otomatisasi bisa direview. Ini penting juga untuk monetisasi: CTA, product link, analytics event, dan form konsultasi bisa berubah bersama dalam satu run.

Untuk mulai sendiri, gunakan cheatsheet gratis. Untuk prompt dan template setup yang bisa dipakai ulang, lihat products. Untuk rollout tim, permissions, MCP, CI review gates, dan otomasi aman, gunakan training dan konsultasi Claude Code.

Dalam refresh ini saya mengecek official overview, TypeScript reference, MCP, permissions, migration, dan cost tracking docs. Perubahan paling praktis adalah contoh pertama dibuat read-only. Dengan npm run audit, pembaca bisa melihat perilaku agen dulu sebelum menambahkan MCP, edit, dan test execution.