Skip to main content
Gunakan Agent SDK untuk membangun agen AI yang membaca kode Anda, menemukan bug, dan memperbaikinya, semuanya tanpa intervensi manual. Yang akan Anda lakukan:
  1. Menyiapkan proyek dengan Agent SDK
  2. Membuat file dengan beberapa kode yang berisi bug
  3. Menjalankan agen yang menemukan dan memperbaiki bug secara otomatis

Prasyarat

  • Node.js 18+ atau Python 3.10+
  • Akun Anthropic. Jika Anda belum memilikinya, daftar di sini.

Penyiapan

1

Buat folder proyek

Buat direktori baru untuk panduan cepat ini:
Untuk proyek Anda sendiri, Anda dapat menjalankan SDK dari folder apa pun; SDK akan memiliki akses ke file di direktori tersebut dan subdirektorinya secara default.
2

Instal SDK

Instal paket Agent SDK untuk bahasa Anda:
Mengatur "type": "module" di package.json memungkinkan skrip agen Anda menggunakan await tingkat atas, dan tsx menjalankan file TypeScript secara langsung. npm mencetak added N packages ketika instalasi berhasil.
Baik SDK TypeScript maupun Python menggabungkan biner Claude Code asli, jadi sebagian besar instalasi tidak memerlukan instalasi Claude Code terpisah. Beberapa instalasi tidak memiliki biner yang digabungkan:
  • Jika pip menginstal distribusi sumber SDK Python alih-alih roda platform, misalnya di ARM64 Windows, tidak ada biner yang digabungkan. Instal Claude Code secara native. SDK Python menemukannya di PATH Anda.
  • SDK TypeScript menginstal binernya melalui dependensi opsional npm, jadi instalasi yang melewatkannya, misalnya npm ci --omit=optional, tidak mendapatkan biner bahkan di platform yang didukung. Instal ulang tanpa melewatkan dependensi opsional, atau instal Claude Code secara native dan atur pathToClaudeCodeExecutable ke jalurnya.
3

Atur kunci API Anda

Dapatkan kunci API dari Claude Console, kemudian atur sebagai variabel lingkungan di shell tempat Anda akan menjalankan agen Anda:
SDK membaca kunci dari lingkungan proses yang menjalankan agen Anda; SDK tidak memuat file .env secara otomatis. Jika Anda menyimpan kunci di file .env, muat sendiri, misalnya dengan paket dotenv, sebelum memanggil SDK.SDK juga mendukung autentikasi melalui penyedia API pihak ketiga:
  • Amazon Bedrock: atur variabel lingkungan CLAUDE_CODE_USE_BEDROCK=1 dan konfigurasikan kredensial AWS
  • Claude Platform on AWS: atur CLAUDE_CODE_USE_ANTHROPIC_AWS=1 dan ANTHROPIC_AWS_WORKSPACE_ID, kemudian konfigurasikan kredensial AWS
  • Google Cloud’s Agent Platform: atur variabel lingkungan CLAUDE_CODE_USE_VERTEX=1 dan konfigurasikan kredensial Google Cloud
  • Microsoft Foundry: atur variabel lingkungan CLAUDE_CODE_USE_FOUNDRY=1 dan konfigurasikan kredensial Azure
Lihat panduan penyiapan untuk Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform, atau Microsoft Foundry untuk detail selengkapnya.
Kecuali telah disetujui sebelumnya, Anthropic tidak mengizinkan pengembang pihak ketiga untuk menawarkan login claude.ai atau rate limit untuk produk mereka, termasuk agent yang dibangun di Agent SDK Claude. Silakan gunakan metode autentikasi kunci API yang dijelaskan dalam dokumen ini.

Buat file dengan bug

Panduan cepat ini memandu Anda melalui pembuatan agen yang dapat menemukan dan memperbaiki bug dalam kode. Pertama, Anda memerlukan file dengan beberapa bug yang disengaja untuk diperbaiki oleh agen. Buat utils.py di direktori my-agent dan tempel kode berikut:
Kode ini memiliki dua bug:
  1. calculate_average([]) mogok dengan pembagian oleh nol
  2. get_user_name(None) mogok dengan TypeError

Bangun agen yang menemukan dan memperbaiki bug

Buat agent.py jika Anda menggunakan Python SDK, atau agent.ts untuk TypeScript. Gunakan agent.mts sebagai gantinya jika proyek yang ada Anda menggunakan CommonJS:
Kode ini memiliki tiga bagian utama:
  1. query: titik masuk utama yang membuat loop agentic. Ini mengembalikan iterator async, jadi Anda menggunakan async for untuk streaming pesan saat Claude bekerja. Lihat API lengkap di referensi SDK Python atau TypeScript.
  2. prompt: apa yang ingin Anda lakukan Claude. Claude mengetahui alat mana yang digunakan berdasarkan tugas.
  3. options: konfigurasi untuk agen. Contoh ini menggunakan allowedTools untuk pra-persetujuan Read, Edit, dan Glob, dan permissionMode: "acceptEdits" untuk auto-persetujuan perubahan file. Opsi lainnya termasuk systemPrompt, mcpServers, dan lainnya. Lihat semua opsi untuk Python atau TypeScript.
Loop async for terus berjalan saat Claude berpikir, memanggil alat, mengamati hasil, dan memutuskan apa yang harus dilakukan selanjutnya. Setiap iterasi menghasilkan pesan: penalaran Claude, panggilan alat, hasil alat, atau hasil akhir. SDK menangani orkestrasi, eksekusi alat, manajemen konteks, dan percobaan ulang, sehingga Anda mengonsumsi aliran. Loop berakhir ketika Claude menyelesaikan tugas atau mengalami kesalahan. Penanganan pesan di dalam loop memfilter output yang dapat dibaca manusia. Tanpa penyaringan, Anda akan melihat objek pesan mentah termasuk inisialisasi sistem dan status internal, yang berguna untuk debugging tetapi berisik sebaliknya.
Contoh ini menggunakan streaming untuk menampilkan kemajuan secara real-time. Jika Anda tidak memerlukan output langsung (misalnya, untuk pekerjaan latar belakang atau pipeline CI), Anda dapat mengumpulkan semua pesan sekaligus. Lihat Streaming vs. single-turn mode untuk detail selengkapnya.

Jalankan agen Anda

Agen Anda siap. Jalankan dengan perintah berikut:
Jika Anda memberi nama skrip Anda agent.mts, jalankan npx tsx agent.mts sebagai gantinya.
Saat bekerja, agen mencetak penalarannya dan setiap alat yang dipanggilnya, diakhiri dengan Done: success. Setelah menjalankan, periksa utils.py. Anda akan melihat kode defensif yang menangani daftar kosong dan pengguna null. Agen Anda secara mandiri:
  1. Membaca utils.py untuk memahami kode
  2. Menganalisis logika dan mengidentifikasi kasus tepi yang akan mogok
  3. Mengedit file untuk menambahkan penanganan kesalahan yang tepat
Inilah yang membuat Agent SDK berbeda: Claude menjalankan alat secara langsung alih-alih meminta Anda untuk mengimplementasikannya.
Jika Anda melihat kesalahan autentikasi seperti Not logged in atau Invalid API key, pastikan Anda telah menetapkan variabel lingkungan ANTHROPIC_API_KEY di shell tempat Anda menjalankan agen Anda. SDK tidak memuat file .env secara otomatis.Untuk penyebab dan perbaikan di balik kesalahan autentikasi ini dan kesalahan lainnya, lihat Kesalahan autentikasi dalam referensi Kesalahan.

Coba prompt lain

Sekarang agen Anda sudah diatur, coba beberapa prompt berbeda:
  • "Add docstrings to all functions in utils.py"
  • "Add type hints to all functions in utils.py"
  • "Create a README.md documenting the functions in utils.py"

Sesuaikan agen Anda

Anda dapat mengubah perilaku agen dengan mengubah opsi. Berikut adalah beberapa contoh: Tambahkan kemampuan pencarian web:
Berikan Claude prompt sistem kustom:
Jalankan perintah di terminal:
Dengan Bash diaktifkan, coba: "Write unit tests for utils.py, run them, and fix any failures" Setiap snippet ini menetapkan bidang pada objek opsi yang sama. Untuk informasi lebih lanjut, lihat Konfigurasi agen Anda.

Konsep kunci

Tools mengontrol apa yang dapat dilakukan agen Anda: Permission modes mengontrol berapa banyak pengawasan manusia yang Anda inginkan. SDK mengevaluasi mode aktif bersama dengan aturan allow dan deny Anda dalam urutan tetap, dijelaskan dalam Bagaimana izin dievaluasi. Untuk daftar lengkap mode, perilakunya, dan kapan menggunakan masing-masing, lihat Permission mode dalam Bagaimana agent loop bekerja.

Langkah berikutnya

Sekarang Anda telah membuat agen pertama Anda, pelajari cara memperluas kemampuannya dan menyesuaikannya dengan kasus penggunaan Anda:
  • Konfigurasi agen Anda: susun objek opsi dan temukan halaman yang mencakup setiap pengaturan
  • Permissions: kontrol apa yang dapat dilakukan agen Anda dan kapan memerlukan persetujuan
  • Hooks: jalankan kode kustom sebelum atau sesudah panggilan alat
  • Sessions: bangun agen multi-turn yang mempertahankan konteks
  • MCP servers: terhubung ke database, browser, API, dan sistem eksternal lainnya
  • Hosting: sebarkan agen ke Docker, cloud, dan CI/CD
  • Example agents: lihat contoh lengkap: asisten email, agen penelitian, dan lainnya
  • Troubleshooting: perbaiki kesalahan ketika CLI gagal dimulai atau keluar, atau hasil tiba tanpa output terstruktur