Claude Code SDK

 (docs.anthropic.com)
1 poin oleh GN⁺ 2025-05-20 | 1 komentar | Bagikan ke WhatsApp
  • Claude Agent SDK memungkinkan kontrol atas eksekusi alat, loop agen, dan manajemen konteks Claude Code dari kode Python·TypeScript, sehingga dapat mengotomatisasi pembacaan file, eksekusi perintah, pencarian web, dan pengeditan kode
  • Menyediakan alat bawaan Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, sehingga mulai dari penelusuran codebase hingga pertanyaan konfirmasi kepada pengguna dapat ditangani tanpa lapisan eksekusi terpisah
  • Dengan menggabungkan hook, subagen, MCP, izin, dan sesi, dimungkinkan konfigurasi seperti log audit perubahan file, subagen khusus code review, otomasi browser berbasis Playwright, dan agen analisis hanya-baca
  • Instalasi dilakukan dengan @anthropic-ai/claude-agent-sdk atau claude-agent-sdk; Python memerlukan 3.10 atau lebih baru, dan SDK TypeScript menyertakan biner native Claude Code untuk platform sebagai dependensi opsional
  • Berbeda dari Anthropic Client SDK yang mengharuskan implementasi loop alat secara langsung, Agent SDK menyediakan eksekusi alat bawaan; dan tidak seperti Managed Agents, ia berjalan di proses dan infrastruktur pengguna, bukan di infrastruktur Anthropic

Cakupan Claude Agent SDK

  • Claude Agent SDK memungkinkan penggunaan alat, loop agen, dan manajemen konteks yang menjalankan Claude Code dari Python dan TypeScript
  • Agen dapat membaca file, menjalankan perintah, mencari di web, dan mengedit kode
  • Karena eksekusi alat bawaan sudah disertakan, agen dapat langsung mulai bekerja tanpa pengguna harus membangun lapisan eksekusi alat terpisah sendiri
  • Contoh dasar mengizinkan alat Read, Edit, dan Bash untuk mencari dan memperbaiki bug di auth.py

Instalasi dan alur autentikasi

  • Instalasi dilakukan melalui paket per bahasa
    • TypeScript: npm install @anthropic-ai/claude-agent-sdk
    • Python: pip install claude-agent-sdk
  • Paket Python memerlukan Python 3.10 atau lebih baru
    • Jika muncul error No matching distribution found for claude-agent-sdk, interpreter Anda mungkin versi yang lebih lama dari 3.10
    • Di macOS atau Linux, periksa dengan python3 --version; di Windows, gunakan py --version
  • SDK TypeScript menyertakan biner native Claude Code untuk platform sebagai dependensi opsional, jadi tidak perlu memasang Claude Code secara terpisah
  • API key diterbitkan dari Console dan diatur melalui variabel lingkungan ANTHROPIC_API_KEY
  • Autentikasi dengan penyedia API pihak ketiga juga didukung
    • Amazon Bedrock: atur CLAUDE_CODE_USE_BEDROCK=1 lalu konfigurasikan kredensial AWS
    • Claude Platform on AWS: atur CLAUDE_CODE_USE_ANTHROPIC_AWS=1, ANTHROPIC_AWS_WORKSPACE_ID, lalu konfigurasikan kredensial AWS
    • Google Vertex AI: atur CLAUDE_CODE_USE_VERTEX=1 lalu konfigurasikan kredensial Google Cloud
    • Microsoft Azure: atur CLAUDE_CODE_USE_FOUNDRY=1 lalu konfigurasikan kredensial Azure
  • Anthropic tidak mengizinkan developer pihak ketiga menyediakan login claude.ai atau rate limit untuk produk berbasis Claude Agent SDK tanpa persetujuan sebelumnya

Alat bawaan dan kemampuan agen

  • SDK memungkinkan fitur utama Claude Code diakses dari kode
    • alat bawaan
    • hook
    • subagen
    • MCP
    • izin
    • sesi
  • Alat bawaan utama menjalankan peran berikut
    • Read: membaca file di dalam direktori kerja
    • Write: membuat file baru
    • Edit: menerapkan pengeditan presisi pada file yang sudah ada
    • Bash: menjalankan perintah terminal, skrip, dan pekerjaan git
    • Monitor: memantau skrip latar belakang dan merespons setiap baris output sebagai event
    • Glob: mencari file dengan pola seperti **/*.ts, src/**/*.py
    • Grep: mencari isi file dengan regex
    • WebSearch: mencari informasi terbaru di web
    • WebFetch: mengambil dan mem-parsing konten halaman web
    • AskUserQuestion: mengajukan pertanyaan konfirmasi ke pengguna dengan opsi pilihan ganda
  • Contoh agen mengizinkan Read, Glob, dan Grep untuk menemukan dan merangkum komentar TODO dalam codebase

Hook, subagen, MCP

  • Hook menjalankan kode pengguna pada titik-titik penting dalam siklus hidup agen
    • Dengan fungsi callback, perilaku agen dapat divalidasi, dicatat, diblokir, atau ditransformasikan
    • Hook yang tersedia mencakup PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit, dan lainnya
    • Contohnya mendeteksi operasi Edit|Write di PostToolUse lalu mencatat perubahan file ke audit.log
  • Subagen adalah agen khusus yang menangani sub-tugas terfokus
    • Agen utama mendelegasikan tugas, lalu subagen mengembalikan hasilnya
    • Agen kustom didefinisikan dengan deskripsi, prompt, dan alat yang akan digunakan
    • Pemanggilan subagen dilakukan melalui alat Agent, jadi untuk persetujuan otomatis, Agent harus disertakan dalam allowedTools
    • Pesan di dalam konteks subagen menyertakan field parent_tool_use_id agar dapat dilacak ke eksekusi subagen mana pesan tersebut terkait
  • Dengan Model Context Protocol(MCP), agen dapat terhubung ke sistem eksternal seperti database, browser, dan API

Izin dan manajemen sesi

  • Pengaturan izin membatasi alat yang bisa digunakan agen
    • Pekerjaan aman dapat diizinkan, pekerjaan berisiko dapat diblokir, dan tindakan sensitif dapat memerlukan persetujuan
    • Contohnya, dengan hanya pra-menyetujui Read, Glob, dan Grep, dapat dibuat agen hanya-baca yang menganalisis kode tanpa memodifikasinya
  • Alat AskUserQuestion dan prompt persetujuan interaktif digunakan bersama dalam alur pemrosesan input pengguna
  • Sesi mempertahankan konteks di beberapa pertukaran
    • Claude mengingat file yang dibaca, analisis yang dilakukan, dan riwayat percakapan
    • Sesi yang sama dapat dilanjutkan nanti atau di-fork untuk mengeksplorasi pendekatan lain
    • Contohnya mendapatkan session_id pada kueri pertama, lalu melanjutkan konteks yang sama pada kueri kedua dengan resume=session_id

Dukungan konfigurasi Claude Code

  • SDK mendukung konfigurasi berbasis filesystem milik Claude Code
  • Pada opsi default, konfigurasi dimuat dari .claude/ di direktori kerja dan ~/.claude/
  • Untuk membatasi sumber konfigurasi yang dimuat, gunakan opsi setting_sources di Python dan settingSources di TypeScript
  • Fitur dan lokasi yang didukung adalah sebagai berikut
    • Skills: kemampuan khusus yang digunakan otomatis oleh Claude atau dipanggil dengan /name, .claude/skills/*/SKILL.md
    • Commands: perintah kustom dalam format lama, .claude/commands/*.md
    • Memory: konteks proyek dan instruksi, CLAUDE.md atau .claude/CLAUDE.md
    • Plugins: memperluas skills, agents, hooks, MCP servers; dikonfigurasi secara terprogram dengan opsi plugins

Perbedaan dengan alat Claude lainnya

  • Anthropic Client SDK menyediakan akses API langsung, dan pengguna mengirim prompt serta mengimplementasikan sendiri eksekusi alat
  • Di Agent SDK, Claude menangani pemrosesan alat secara otonom
    • Pada Client SDK, pengguna mengimplementasikan loop alat
    • Agent SDK menyediakan eksekusi alat bawaan untuk Claude
  • Kriteria pemilihan menurut penggunaan adalah sebagai berikut
    • Pengembangan interaktif: CLI
    • Pipeline CI/CD: SDK
    • Aplikasi kustom: SDK
    • Tugas sekali jalan: CLI
    • Otomasi produksi: SDK
  • Banyak tim menggunakan CLI untuk pengembangan sehari-hari dan SDK untuk produksi, dan workflow dapat dipindahkan langsung di antara keduanya
  • Managed Agents adalah REST API terkelola tempat Anthropic menjalankan agen dan sandbox
  • Agent SDK adalah library yang menjalankan loop agen di dalam proses pengguna
    • Lokasi eksekusi: Agent SDK berada di proses dan infrastruktur pengguna, Managed Agents di infrastruktur terkelola Anthropic
    • Antarmuka: Agent SDK adalah library Python atau TypeScript, Managed Agents adalah REST API
    • Target kerja: Agent SDK menangani file di infrastruktur pengguna, Managed Agents menggunakan sandbox terkelola per sesi
    • Status sesi: Agent SDK menggunakan JSONL di filesystem, Managed Agents menggunakan log event yang di-host Anthropic
    • Alat kustom: Agent SDK memakai fungsi Python atau TypeScript di dalam proses, Managed Agents membuat Claude memicu alat dan pengguna mengembalikan hasil eksekusinya
    • Kegunaan yang cocok: Agent SDK untuk prototyping lokal dan agen yang perlu akses langsung ke filesystem·layanan; Managed Agents untuk agen produksi tanpa mengoperasikan sandbox atau infrastruktur sesi, serta sesi asinkron jangka panjang
  • Jalur yang umum adalah membuat prototipe lokal dengan Agent SDK, lalu memindahkannya ke Managed Agents untuk produksi

Changelog, pelaporan bug, branding

  • Update SDK, perbaikan bug, dan fitur baru dapat dilihat di changelog masing-masing repositori
  • Bug atau isu dilaporkan melalui GitHub
  • Saat partner mengintegrasikan Claude Agent SDK, penggunaan branding Claude bersifat opsional
    • Diizinkan: “Claude Agent”, “Claude”, “Powered by Claude”
    • Dilarang: “Claude Code”, “Claude Code Agent”, ASCII art merek Claude Code, atau elemen visual yang meniru Claude Code
    • Produk harus mempertahankan branding sendiri dan tidak boleh terlihat seperti produk Claude Code atau Anthropic
  • Penggunaan Claude Agent SDK tunduk pada Anthropic’s Commercial Terms of Service
    • Pengecualian berlaku bila komponen atau dependensi tertentu menyatakan lisensi berbeda di file LICENSE komponen tersebut

Bacaan terkait

1 komentar

 
GN⁺ 2025-05-20
Komentar di Hacker News

  • Arah yang dituju Claude Code persis sesuai dengan yang saya inginkan dari alat coding berbasis agen, dan saya juga menyukai filosofinya yang “seperti alat Unix”
    Saya sudah memakainya sejak awal preview publik, dan arahnya sudah terlihat. Menurut saya kondisi akhir ideal untuk agen coding adalah ketika kita memberi permintaan fitur seperti tiket Jira, lalu ia membuat PR yang bisa ditinjau dan diberi masukan. Dalam arti itu, alat yang berpusat pada editor lokal seperti Cursor dan Windsurf mendekati jalan buntu karena tidak bisa berjalan di dalam CI. Jika codebase dirapikan agar cocok untuk AI dengan rules, MCP, dan sebagainya, kita seharusnya membidik teknologi yang bisa berlanjut sampai penggunaan headless. Claude Code mudah dipakai sebagai bagian dari otomatisasi melalui tool, jadi sekarang sudah menjadi default saat memikirkan agen coding; paket npm Codex juga mirip. Namun karena pekerjaan saya membantu perusahaan merapikan codebase agar cocok untuk pemanfaatan agen, saya mungkin bias ke arah alat yang mudah dikonfigurasi

    • Saya sulit setuju dengan “kondisi akhir ideal” itu. Bentuk yang saya inginkan adalah saya berada di ruangan, dikelilingi beberapa layar, sementara agen-agen AI melakukan coding, desain, dan testing, lalu saya di tengah mengarahkan dan menerapkan preferensi saya
      Saya berharap semuanya berlangsung lewat percakapan, dan 99% waktunya tidak perlu menyentuh keyboard
    • Menurut saya bukan begitu. Kondisi akhir yang “ideal” untuk agen coding adalah agen coding bebas dan open source yang berjalan di komputer saya atau mesin apa pun yang saya inginkan
      Bayangkan harus membayar setiap kali menjalankan perintah seperti ls, ps, atau kill di terminal; itu tidak masuk akal. LLM juga sama. Ini bukan berarti ingin melarang LLM proprietari, tetapi alat utama yang dipakai para hacker seperti dulu seharusnya alat yang bebas dan open source
    • Anthropic juga hari ini mengumumkan fitur beta dengan arah serupa: https://docs.anthropic.com/en/docs/claude-code/github-action...
    • Saya juga pernah mencoba pekerjaan seperti ini dengan Cursor dan MCP. Setelah sekitar satu hari, saya terkena batas penggunaan dan turun ke model yang paling lambat dan bodoh
      Saya juga mencobanya dengan Claude, tetapi batasnya cepat habis. PR yang langsung berada pada level “layak jalan” hanya sekitar 25%, dan sering kali lebih cepat mengerjakannya sendiri dengan benar daripada mencari di mana AI merusaknya
    • Saya paham maksudnya kondisi ketika diberi permintaan fitur lalu dibuatkan PR untuk ditinjau, tetapi itu berarti dalam pekerjaan perangkat lunak hanya tersisa bagian yang paling menggerogoti jiwa, yaitu tiket Jira, jadi terasa muram

  • Claude Code adalah cara memakai LLM untuk coding yang paling saya sukai
    Namun yang benar-benar dibutuhkan menurut saya adalah versi open source yang bisa diberi model apa pun, dan juga bisa membandingkan jawaban dari beberapa model. Aider atau alternatif lain tidak terasa senyaman Claude Code. Dari sisi Anthropic, mereka tentu tidak menginginkannya karena moat mereka akan hilang, tetapi dari sisi konsumen, saya hanya ingin memakai model terbaik tanpa terikat pada ekosistem tertentu. Mungkin inilah hal yang paling ditakuti para penyedia model LLM

    • OpenAI Codex mungkin alternatif yang paling mendekati. Ia open source dan bisa memakai model dari penyedia mana pun
      Saat ini belum sebagus Claude Code, tetapi sepertinya akan segera mengejar. https://github.com/openai/codex/tree/main
    • Proyek OpenCode mungkin sesuai dengan minat Anda: https://github.com/opencode-ai/opencode
      Masih dalam pengembangan, tetapi terlihat menjanjikan
    • Saya penasaran apa yang lebih baik dilakukan Claude Code dibanding Aider
    • Belakangan ini saya memang terlalu banyak promosi diri, tetapi kalau melihat komentar saya sebelumnya, ada layanan yang saya buat dengan Go. Itu memang menargetkan kebutuhan seperti ini
    • Setuju, tetapi bukankah model lain juga harus dilatih agar tahu cara bekerja dengan server MCP? Atau itu bukan masalah?

  • Aider sudah lama mendukung Python dan shell scripting [0]
    Dalam proses baru-baru ini menambahkan dukungan untuk 130 bahasa pemrograman baru, saya juga membuat screencast tentang melakukan scripting Bash spontan dengan Aider [1]. Ini bisa memberi gambaran seberapa kuat pendekatan seperti ini.
    [0] https://aider.chat/docs/scripting.html
    [1] https://aider.chat/docs/recordings/tree-sitter-language-pack...

    • Saya sangat menyukai Aider. MCP juga akan segera didukung, dan saya sedang menguji branch pengembangannya
      Dengan begitu, kita bisa memakai model yang kita percayai untuk melakukan pengembangan dari awal sampai akhir melalui PR, tiket, dan sebagainya
    • Saya penasaran seberapa dekat Aider bisa dibuat dengan Claude Code. Pengalaman pengguna Claude Code bagus, tetapi saya tidak memakainya karena lebih memilih Gemini 2.5 Pro
      Saya tidak terlalu ingin alat itu sampai melakukan commit; saya terutama menyukai rasa penggunaan Claude Code
    • Aider bisa menjadi jauh lebih baik jika memiliki workflow GitHub Actions yang dipoles dengan baik
      Cukup dengan menambahkan satu file ke repositori, lalu bisa bercakap-cakap dengan model apa pun melalui issue

  • Hal-hal yang dibahas lebih rinci oleh tim Claude Code: http://latent.space/p/claude-code
    Membaca transkripnya saja sudah cukup, tetapi secara pribadi saya terkesan bahwa karyawan Anthropic, meski memakai Claude tanpa batas, rata-rata hanya menghabiskan sekitar 6 dolar per hari; bahwa mereka melihat Claude Code headless seperti utilitas “Linux” yang bisa dipakai di CI di mana saja; bahwa mereka memandangnya sebagai platform yang dapat diperluas pengguna; bahwa fitur sandboxing, branching, dan perencanaan ada di roadmap mendatang; serta bahwa mereka melihat Sonnet 3.7 sebagai model agen yang persisten

    • Di tautan itu juga disebutkan ada insinyur internal Anthropic yang menghabiskan lebih dari 1.000 dolar dalam sehari
      Saya penasaran berapa P50, P75, dan P95 pengeluaran per karyawan
    • Mungkin saya yang memakainya dengan keliru, tetapi memakai Claude Code selama 2 jam dengan mudah menghabiskan lebih dari 20 dolar
      Terlalu mahal untuk proyek pribadi, jadi saya berhenti menggunakannya
    • Belakangan saya sangat menikmati podcast latent space. Menurut saya hampir tidak ada orang atau podcast yang mampu mempertahankan rasio signal-to-noise setinggi itu sambil menghasilkan output keseluruhan sebanyak ini
      Mengejutkan melihat jumlah dan nilai pekerjaan publiknya terus bertambah selama enam bulan terakhir atau beberapa tahun terakhir, sambil juga membesarkan beberapa bisnis. Semoga orang lain juga bisa menemukan kemiringan produktivitas yang serupa. Mereka memang berbagi kira-kira apa yang cocok, tetapi tidak mudah direplikasi. Yang terlintas di benak saya mungkin simonw dan gwern
    • Saya penasaran seberapa netral podcast itu, atau apakah itu sekadar promosi penjualan untuk produk ini

  • Kalau saya membuat AI code assistant, hal terakhir yang akan saya lakukan adalah mengikatnya ke penyedia model dasar tertentu
    Agar produk ini berhasil, asumsi yang diperlukan adalah bahwa performa model baru saja mencapai plateau, semua model dasar akan berkonvergensi ke performa dan kapabilitas yang hampir sama, lalu para integrator akan memilih berdasarkan kenyamanan kecil seperti SDK yang sudah familier

    • Selain perintah dan argumen, tidak banyak bagian yang benar-benar mengikat. Pada dasarnya hanya input dan output
      Tinggal diganti dengan yang lain atau diberi wrapper. Tidak banyak hal rumit di sini
    • Saat ini Claude Code adalah faktor diferensiasi software di ranah coding agentik
      Kami sedang membuat sesuatu terkait AI code assistant, dan mulai dengan mengutak-atik cara mengintegrasikan Claude Code. Itulah hal pertama yang ingin kami bangun di atasnya. Masih terlalu dini untuk mengkhawatirkan lock-in; kami butuh yang terbaik, jadi kami hanya akan membangun di sekitar yang terbaik

  • Claude Code sebenarnya sudah bisa dipakai dalam mode non-interaktif, sehingga bisa diintegrasikan ke aplikasi lain seperti utilitas command-line Unix lainnya
    SDK ini tampaknya saat ini hanya mendukung penggunaan command-line, jadi bukankah ini sama saja dengan yang sudah ada? Saya tidak tahu apa yang sebenarnya baru. Apa yang saya lewatkan?

    • Saya juga tidak tahu. Menurut saya aneh karena hampir tidak ada yang membicarakan poin ini

  • Saya juga merekomendasikan Codebuff(https://www.codebuff.com/). Ini CLI code assistant yang bagus, mirip Claude Code, dan bisa banyak menghemat biaya token
    Saya tidak terkait dengan proyek ini, hanya pengguna

  • Di ketentuannya tertulis bahwa layanan tidak boleh digunakan “untuk mengembangkan produk atau layanan yang bersaing dengan layanan, untuk mengembangkan atau melatih algoritma atau model kecerdasan buatan atau machine learning, atau untuk menjual kembali layanan”
    Saya penasaran, sebenarnya produk atau layanan software yang tidak bersaing dengan kecerdasan umum itu apa? Mereka menjual kecerdasan, lalu jika ditafsirkan secara ketat, memasang klausul hukum yang pada dasarnya melarang penggunaannya di mana pun. Apakah ini terlalu kabur sehingga tidak bisa ditegakkan? Kalau tidak boleh dipakai untuk bersaing dengan kecerdasan umum, bagaimana mungkin output-nya dimiliki? Apakah ini semacam “tidak ada yang peduli dengan ketentuan hukum”? Kalau tidak ada yang peduli, kenapa memasang larangan menyeluruh pada penggunaan layanan? Apakah untuk menerima hasil seperti ini kita juga harus menerima tanggung jawab kalah gugatan? Terlalu banyak pertanyaan

    • Beginilah jadinya kalau pengacara dibiarkan menulis sesuka hati
    • Karena “artificial” diganti menjadi “general”, maknanya tentu saja berubah

  • Adanya model lock-in menjadi kerugian besar dalam penggunaan. Jika seseorang merilis model terbaru dengan performa terbaik, sementara kita sudah berinvestasi di infrastruktur ini, kita akan terjebak
    Bahkan jika nanti dibuka, model tersebut kemungkinan besar telah dilatih khusus agar cocok dengan CLI itu, sehingga mungkin tidak bekerja dengan baik. Lihat saja Codex CLI: Gemini 2.5 Pro memang bisa dipakai, tetapi dibanding model OpenAI, ia jauh lebih sering berhenti atau gagal secara acak

  • GitHub Action baru ini persis fitur yang saya cari: https://docs.anthropic.com/en/docs/claude-code/github-action...
    Namun tampaknya tidak ada cara untuk memakainya dengan paket Max Claude Code. Sejauh yang saya lihat, sepertinya hanya menerima API key