Kebanyakan tim yang mencoba membangun AI agent dari nol akhirnya membangun ulang mekanisme yang sama: sebuah loop yang mengirim prompt ke model, menjalankan tool call yang dihasilkan, mengembalikan hasilnya ke model, lalu mengulang sampai model memberikan jawaban akhir. Claude Agent SDK melewati langkah itu. Ia adalah agent loop, eksekusi tool, dan manajemen konteks yang sama seperti yang menjalankan Claude Code, dikemas sebagai library yang bisa dipanggil dari Python atau TypeScript.
Tulisan ini adalah panduan praktis, bukan gambaran promosi. Isinya membahas bagian yang benar-benar penting saat mulai membangun sesuatu yang nyata: bagaimana perilaku loop tersebut, cara mendefinisikan dan membatasi tool, kapan subagent layak dipakai meski menambah kompleksitas, bagaimana mode izin menentukan apa yang berjalan tanpa konfirmasi, serta detail operasional yang membedakan sekadar demo dari agen operasional yang siap produksi.
Agent Loop, dan Mengapa Anda Tidak Perlu Menulisnya Sendiri
Dengan Anthropic API mentah, Anda yang mengimplementasikan loop-nya sendiri: mengirim pesan, memeriksa apakah alasan berhenti adalah pemakaian tool, menjalankan tool tersebut sendiri, mengirim hasilnya kembali, lalu mengulang. Agent SDK membalik urutan itu. Anda cukup memanggil query dengan sebuah prompt dan daftar tool yang diizinkan, lalu Claude membaca file, menjalankan perintah, dan mengedit kode secara otonom, sambil mengalirkan pesan kembali ke Anda seiring prosesnya berjalan.
Di baliknya, ini adalah mesin yang persis sama dengan yang dijalankan di dalam Claude Code: tool bawaan yang sama, manajemen konteks yang sama, dan model sesi yang sama. Hal ini penting lebih dari sekadar kedengarannya, karena artinya agen sudah tahu kapan harus berhenti, kapan harus bertanya untuk memperjelas sesuatu, dan kapan sebuah tugas benar-benar selesai, tanpa Anda perlu merancang sendiri aturan penghentian.
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find and fix the failing test in payments.ts",
options: {
allowedTools: ["Read", "Edit", "Bash", "Grep"],
},
})) {
if ("result" in message) console.log(message.result);
}Contoh di bawah ini mendekati agen paling minimal yang masih berguna. Ia diberi akses Read, Edit, Bash, dan Grep, lalu model dibiarkan mencari tahu sisanya: menemukan test yang gagal, memahami penyebabnya, dan menambal kodenya.
Mulailah setiap agen baru dengan daftar tool yang diizinkan seketat mungkin, bahkan saat masih prototipe. Jauh lebih mudah menyadari ada kemampuan yang kurang dibanding menyadari agen diam-diam menjalankan perintah yang sebenarnya tidak pernah Anda maksudkan untuk diizinkan.
Definisi Tool: Bawaan, Kustom, dan MCP
SDK ini dilengkapi tool bawaan yang sama seperti yang dipakai Claude Code sehari-hari, jadi Anda jarang perlu menulis sendiri tool untuk membaca file atau menjalankan shell. Kumpulan tool yang paling sering dipakai untuk agen coding atau operasional meliputi:
- Read, Write, dan Edit untuk operasi file yang presisi tanpa perlu logika diff buatan sendiri
- Bash untuk menjalankan skrip, operasi git, dan test suite
- Glob dan Grep untuk mencari file berdasarkan pola dan mencari isi file dengan regex
- WebSearch dan WebFetch untuk menarik informasi terkini yang belum dipelajari model saat pelatihan
Untuk kebutuhan di luar kumpulan tersebut, SDK terhubung ke sistem eksternal lewat Model Context Protocol. Arahkan ke MCP server untuk database, tool otomasi browser, atau API internal, dan tool-tool tersebut akan muncul di daftar tool yang sama seperti tool bawaan, tanpa Anda perlu menulis kode integrasi terpisah.
Subagent: Mendelegasikan Tanpa Mengotori Konteks
Satu percakapan agen yang berjalan lama akan menumpuk segala hal yang pernah dilakukannya: setiap file yang dibaca, setiap perintah yang dijalankan, setiap hasil antara. Untuk perbaikan bug yang terfokus, itu tidak masalah. Namun untuk review seluruh basis kode, artinya konteks agen utama Anda akan penuh dengan hal-hal yang sama sekali tidak relevan dengan jawaban akhirnya.
const options = {
allowedTools: ["Read", "Grep", "Glob", "Agent"],
agents: {
"code-reviewer": {
description: "Expert code reviewer for quality and security reviews.",
prompt: "Analyze code quality, flag security issues, suggest fixes.",
tools: ["Read", "Grep", "Glob"],
model: "sonnet",
},
"test-runner": {
description: "Runs and analyzes the test suite.",
prompt: "Run tests, report failures, and propose minimal fixes.",
tools: ["Bash", "Read", "Grep"],
},
},
};Subagent mengatasi hal ini dengan berjalan dalam konteks baru miliknya sendiri. Agen induk mendelegasikan sebuah subtugas, subagent mengeksplorasi dan bekerja secara terisolasi, dan hanya ringkasan akhirnya yang dikembalikan ke induknya. Karena setiap subagent bisa membawa system prompt dan daftar tool terbatasnya sendiri, Anda bisa membuat code reviewer yang hanya bisa membaca berdampingan dengan test runner yang punya akses shell, dan menjalankan keduanya secara bersamaan alih-alih berurutan.
Ketika sesi induk berjalan dalam mode bypassPermissions atau acceptEdits, setiap subagent yang dibuatnya mewarisi mode yang sama itu dan tidak bisa dibatasi secara individual. Subagent dengan system prompt yang lebih longgar dari agen utama Anda pun akan mendapat akses yang sama tanpa batasan. Jika Anda butuh satu subagent yang benar-benar terisolasi ketat, jaga sesi induk tetap di mode yang lebih ketat daripada mengandalkan daftar tool milik subagent itu sendiri.
Mode Izin: Menentukan Apa yang Berjalan Tanpa Bertanya
Setiap pemanggilan tool yang ingin dilakukan agen melewati pemeriksaan izin sebelum benar-benar dieksekusi. Daftar tool yang diizinkan dan aturan penolakan diperiksa lebih dulu, dan sisanya jatuh ke mode izin yang sedang aktif. Empat mode yang benar-benar akan Anda pakai dalam praktik berperilaku sangat berbeda satu sama lain:
| Mode | Perilaku | Kapan dipakai |
|---|---|---|
| default | Tidak ada persetujuan otomatis; apa pun yang tidak diizinkan secara eksplisit memicu callback persetujuan Anda | Sesi interaktif di mana seorang manusia sedang mengawasi dan menyetujui |
| acceptEdits | Edit file dan operasi berkas disetujui otomatis; tool lain tetap melalui pemeriksaan izin normal | Iterasi cepat di dalam direktori kerja terisolasi yang sudah Anda percaya |
| plan | Claude mengeksplorasi dan mengusulkan rencana; edit file tidak pernah disetujui otomatis, bahkan jika ada aturan izin yang cocok | Alur kerja review kode yang perubahannya perlu persetujuan manusia sebelum diterapkan |
| bypassPermissions | Setiap pemanggilan tool disetujui otomatis tanpa konfirmasi, kecuali ada aturan penolakan eksplisit | Hanya untuk lingkungan yang sepenuhnya terisolasi dan sekali pakai, bukan untuk mesin bersama |
Kesalahan yang perlu ditegaskan secara eksplisit: daftar tool yang diizinkan tidak mempersempit apa yang bisa dilakukan bypassPermissions. Hanya menyebutkan Read di daftar izin Anda sementara mode diatur ke bypassPermissions tetap membuat agen bisa menjalankan Bash, Write, dan Edit, karena daftar izin hanya menyetujui lebih awal tool yang disebutkan, bukan membatasi tool yang tidak disebutkan. Jika Anda butuh bypassPermissions tetapi ingin memblokir perintah tertentu, gunakan aturan penolakan eksplisit alih-alih memangkas daftar izin.
Merilis Agen Operasional ke Produksi
Jarak antara prototipe yang berfungsi dan sesuatu yang benar-benar Anda percayakan untuk berjalan di infrastruktur produksi sebagian besar soal pengaturan default, bukan soal fitur. Berikut daftar periksa singkat yang beberapa kali menyelamatkan saya dari penyesalan:
- Kunci versi model dan versi SDK secara eksplisit alih-alih mengikuti versi terbaru, agar pembaruan dari sisi penyedia tidak diam-diam mengubah perilaku agen
- Catat setiap pemanggilan tool beserta hasilnya ke jejak audit yang persisten, bukan hanya ke stdout, sebelum agen menyentuh apa pun yang berdampak nyata
- Gunakan aturan penolakan untuk pola shell yang destruktif, misalnya memblokir penghapusan rekursif pada path tertentu, alih-alih hanya mengandalkan penilaian model
- Batasi jumlah giliran agentic untuk proses yang berjalan tanpa pengawasan, sehingga agen yang kebingungan gagal secara jelas alih-alih berputar tanpa henti dan menghabiskan token
- Lanjutkan sesi yang sudah ada alih-alih memulai dari nol saat sebuah proses membutuhkan tindak lanjut yang disetujui manusia, agar konteks dari langkah sebelumnya tidak hilang
Tidak ada satu pun dari daftar ini yang eksotis. Ini adalah disiplin operasional yang sama seperti yang akan Anda terapkan pada sistem otomatis mana pun yang bisa menjalankan perintah dan mengedit file tanpa pengawasan, hanya saja diterapkan pada sistem yang langkah berikutnya dipilih oleh model alih-alih skrip yang tetap.
Paket TypeScript-nya dirilis sebagai @anthropic-ai/claude-agent-sdk di npm, dan ia menyertakan binary Claude Code native sebagai dependensi opsional, sehingga instalasi baru tidak memerlukan instalasi Claude Code terpisah di mesin tersebut.
Kapan Memilih SDK Alih-alih API Mentah
Agent SDK bukan alat yang tepat untuk setiap jenis integrasi. Ia benar-benar berguna khususnya saat tugasnya mendapat manfaat dari pemakaian tool bertahap secara otonom:
- Agen coding yang perlu membaca, mencari, dan mengedit basis kode nyata di banyak file dalam satu sesi
- Agen operasional dan support yang merangkai beberapa pemanggilan tool sebelum menghasilkan jawaban yang berguna
- Segala hal yang biasanya Anda prototipekan sebagai alur kerja Claude Code lalu perlu dijalankan tanpa antarmuka di CI atau sebagai layanan backend
Jika kebutuhan Anda hanya satu prompt dengan satu respons yang diharapkan tanpa pemakaian tool, Anthropic client SDK biasa jauh lebih sederhana dan permukaan keamanannya lebih kecil untuk diamankan. Pilih Agent SDK ketika nilainya justru ada pada loop itu sendiri, bukan sekadar keluaran model.