Panduan Cepat

Gunakan Agent SDK untuk membangun agen AI yang membaca kode Anda, menemukan bug, dan memperbaikinya, semuanya tanpa intervensi manual.

Yang akan Anda lakukan:

Siapkan proyek dengan Agent SDK
Buat file dengan beberapa kode yang berisi bug
Jalankan agen yang menemukan dan memperbaiki bug secara otomatis

Prasyarat

Node.js 18+ atau Python 3.10+
Akun Anthropic (daftar di sini)

Pengaturan

Buat folder proyek
Buat direktori baru untuk panduan cepat ini:
mkdir my-agent && cd my-agent
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.
Instal SDK
Instal paket Agent SDK untuk bahasa Anda:
Atur kunci API Anda
Dapatkan kunci API dari Claude Console, kemudian buat file .env di direktori proyek Anda:
ANTHROPIC_API_KEY=your-api-key
SDK juga mendukung autentikasi melalui penyedia API pihak ketiga:
- Amazon Bedrock: atur variabel lingkungan CLAUDE_CODE_USE_BEDROCK=1 dan konfigurasi kredensial AWS
- Google Vertex AI: atur variabel lingkungan CLAUDE_CODE_USE_VERTEX=1 dan konfigurasi kredensial Google Cloud
- Microsoft Azure: atur variabel lingkungan CLAUDE_CODE_USE_FOUNDRY=1 dan konfigurasi kredensial Azure
Lihat panduan pengaturan untuk Bedrock, Vertex AI, atau Azure AI Foundry untuk detail.
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 membangun 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:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)

def get_user_name(user):
    return user["name"].upper()

Kode ini memiliki dua bug:

calculate_average([]) mogok dengan pembagian oleh nol
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:

Kode ini memiliki tiga bagian utama:

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.
prompt: apa yang ingin Anda lakukan Claude. Claude mengetahui alat mana yang digunakan berdasarkan tugas.
options: konfigurasi untuk agen. Contoh ini menggunakan allowedTools untuk membatasi Claude ke Read, Edit, dan Glob, dan permissionMode: "acceptEdits" untuk auto-approve perubahan file. Opsi lainnya termasuk systemPrompt, mcpServers, dan lainnya. Lihat semua opsi untuk atau .

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, 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 pemfilteran, 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.

Jalankan agen Anda

Agen Anda siap. Jalankan dengan perintah berikut:

Setelah menjalankan, periksa utils.py. Anda akan melihat kode defensif menangani daftar kosong dan pengguna null. Agen Anda secara mandiri:

Membaca utils.py untuk memahami kode
Menganalisis logika dan mengidentifikasi kasus tepi yang akan mogok
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 "API key not found", pastikan Anda telah menetapkan variabel lingkungan ANTHROPIC_API_KEY di file .env atau lingkungan shell Anda. 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:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

Berikan Claude prompt sistem kustom:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines."
)

Jalankan perintah di terminal:

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)

Dengan Bash diaktifkan, coba: "Write unit tests for utils.py, run them, and fix any failures"

Konsep kunci

Alat mengontrol apa yang dapat dilakukan agen Anda:

Alat	Apa yang dapat dilakukan agen
`Read`, `Glob`, `Grep`	Analisis hanya-baca
`Read`, `Edit`, `Glob`	Analisis dan modifikasi kode
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	Otomasi penuh

Mode izin mengontrol berapa banyak pengawasan manusia yang Anda inginkan:

Mode	Perilaku	Kasus penggunaan
`acceptEdits`	Auto-approves file edits, asks for other actions	Alur kerja pengembangan terpercaya
`bypassPermissions`	Runs without prompts	Pipeline CI/CD, otomasi
`default`	Requires a `canUseTool` callback to handle approval	Alur persetujuan kustom

Contoh di atas menggunakan mode acceptEdits, yang auto-approve 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: deploy agen ke Docker, cloud, dan CI/CD
Example agents: lihat contoh lengkap: asisten email, agen penelitian, dan lainnya

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    # Agentic loop: streams messages as Claude works
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Tools Claude can use
            permission_mode="acceptEdits"            # Auto-approve file edits
        )
    ):
        # Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)              # Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")   # Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")      # Final result

asyncio.run(main())