- Menyiapkan proyek dengan Agent SDK
- Membuat file dengan beberapa kode yang berisi bug
- Menjalankan agen yang menemukan dan memperbaiki bug secara otomatis
Prasyarat
- Node.js 18+ atau Python 3.10+
- Akun Anthropic (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
- TypeScript (proyek baru)
- TypeScript (proyek yang ada)
- Python (uv)
- Python (pip)
"type": "module" di package.json memungkinkan skrip agen Anda menggunakan await tingkat atas, dan tsx menjalankan file TypeScript secara langsung.TypeScript SDK menggabungkan biner Claude Code asli untuk platform Anda sebagai dependensi opsional, jadi Anda tidak perlu menginstal Claude Code secara terpisah.
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
- macOS / Linux
- Windows (PowerShell)
.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=1dan konfigurasikan kredensial AWS - Claude Platform on AWS: atur
CLAUDE_CODE_USE_ANTHROPIC_AWS=1danANTHROPIC_AWS_WORKSPACE_ID, kemudian konfigurasikan kredensial AWS - Google Cloud’s Agent Platform: atur variabel lingkungan
CLAUDE_CODE_USE_VERTEX=1dan konfigurasikan kredensial Google Cloud - Microsoft Azure: atur variabel lingkungan
CLAUDE_CODE_USE_FOUNDRY=1dan konfigurasikan kredensial Azure
Kecuali telah disetujui sebelumnya, Anthropic tidak mengizinkan pengembang pihak ketiga untuk menawarkan login claude.ai atau batas laju untuk produk mereka, termasuk agen 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. Buatutils.py di direktori my-agent dan tempel kode berikut:
calculate_average([])mogok dengan pembagian oleh nolget_user_name(None)mogok dengan TypeError
Bangun agen yang menemukan dan memperbaiki bug
Buatagent.py jika Anda menggunakan Python SDK, atau agent.ts untuk TypeScript. Gunakan agent.mts sebagai gantinya jika proyek yang ada Anda menggunakan CommonJS:
-
query: titik masuk utama yang membuat loop agentic. Ini mengembalikan iterator async, jadi Anda menggunakanasync foruntuk streaming pesan saat Claude bekerja. Lihat API lengkap di referensi SDK Python atau TypeScript. -
prompt: apa yang ingin Anda lakukan Claude. Claude mengetahui alat mana yang digunakan berdasarkan tugas. -
options: konfigurasi untuk agen. Contoh ini menggunakanallowedToolsuntuk pra-persetujuanRead,Edit, danGlob, danpermissionMode: "acceptEdits"untuk auto-persetujuan perubahan file. Opsi lainnya termasuksystemPrompt,mcpServers, dan lainnya. Lihat semua opsi untuk Python atau TypeScript.
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, percobaan ulang) sehingga Anda hanya 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:- TypeScript
- Python (uv)
- Python (pip)
agent.mts, jalankan npx tsx agent.mts sebagai gantinya.Done: success. Setelah menjalankan, periksa utils.py. Anda akan melihat kode defensif yang menangani daftar kosong dan pengguna null. Agen Anda secara mandiri:
- Membaca
utils.pyuntuk memahami kode - Menganalisis logika dan mengidentifikasi kasus tepi yang akan mogok
- Mengedit file untuk menambahkan penanganan kesalahan yang tepat
Jika Anda melihat “API key not found”, pastikan Anda telah menetapkan variabel lingkungan
ANTHROPIC_API_KEY di shell tempat Anda menjalankan agen Anda. SDK tidak memuat file .env secara otomatis. Lihat panduan pemecahan masalah lengkap untuk bantuan lebih lanjut.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:Bash diaktifkan, coba: "Write unit tests for utils.py, run them, and fix any failures"
Konsep kunci
Tools mengontrol apa yang dapat dilakukan agen Anda:
Permission modes mengontrol berapa banyak pengawasan manusia yang Anda inginkan:
Contoh di atas menggunakan mode
acceptEdits, yang auto-persetujuan operasi file sehingga agen dapat berjalan tanpa prompt interaktif. Jika Anda ingin meminta pengguna untuk persetujuan, gunakan mode default dan sediakan callback canUseTool yang mengumpulkan input pengguna. Untuk kontrol lebih lanjut, lihat Permissions.
Langkah berikutnya
Sekarang Anda telah membuat agen pertama Anda, pelajari cara memperluas kemampuannya dan menyesuaikannya dengan kasus penggunaan Anda:- 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