Bahasa Indonesia

Panduan Cepat

Mulai dengan Agent SDK Python atau TypeScript untuk membangun agen AI yang bekerja secara mandiri

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

Yang akan Anda lakukan:

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

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:

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

Mengatur "type": "module" di package.json memungkinkan skrip agen Anda menggunakan await tingkat atas, dan tsx menjalankan file TypeScript secara langsung.

npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

tsx menjalankan file TypeScript secara langsung. Jika proyek Anda menggunakan CommonJS, beri nama skrip agen Anda agent.mts alih-alih agent.ts. Ekstensi .mts membuat tsx memperlakukan file sebagai modul ES, sehingga await tingkat atas berfungsi tanpa mengonversi seluruh proyek Anda ke modul ES. Gunakan agent.mts sebagai pengganti agent.ts dalam langkah buat dan jalankan nanti dalam panduan cepat ini.

uv adalah pengelola paket Python yang cepat yang menangani lingkungan virtual secara otomatis:

uv init
uv add claude-agent-sdk

Buat dan aktifkan lingkungan virtual, kemudian instal paket.

Di macOS atau Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Di Windows:

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

Jika PowerShell memblokir Activate.ps1 dengan kesalahan kebijakan eksekusi, jalankan Set-ExecutionPolicy -Scope Process RemoteSigned terlebih dahulu.

Atur kunci API Anda

Dapatkan kunci API dari Claude Console, kemudian atur sebagai variabel lingkungan di shell tempat Anda akan menjalankan agen Anda:

export ANTHROPIC_API_KEY=your-api-key

$env:ANTHROPIC_API_KEY = "your-api-key"

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 Vertex AI: atur variabel lingkungan CLAUDE_CODE_USE_VERTEX=1 dan konfigurasikan kredensial Google Cloud
Microsoft Azure: atur variabel lingkungan CLAUDE_CODE_USE_FOUNDRY=1 dan konfigurasikan kredensial Azure

Lihat panduan penyiapan untuk Bedrock, Claude Platform on AWS, Vertex AI, atau Azure AI Foundry untuk detail selengkapnya.

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:

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. Gunakan agent.mts sebagai gantinya jika proyek yang ada Anda menggunakan CommonJS:

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"],  # Auto-approve these tools
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())

import { query } from "@anthropic-ai/claude-agent-sdk";

// Agentic loop: streams messages as Claude works
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Auto-approve these tools
permissionMode: "acceptEdits" // Auto-approve file edits
}
})) {
// Print human-readable output
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude's reasoning
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // Tool being called
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // Final result
}
}

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

Jalankan agen Anda

Agen Anda siap. Jalankan dengan perintah berikut:

npx tsx agent.ts

Jika Anda memberi nama skrip Anda agent.mts, jalankan npx tsx agent.mts sebagai gantinya.

uv run agent.py

Dengan lingkungan virtual Anda masih diaktifkan:

python agent.py

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:

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.

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"
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "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.",
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "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"
)

const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "acceptEdits"
}
};

Dengan 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:

Tools	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

Permission modes mengontrol berapa banyak pengawasan manusia yang Anda inginkan:

Mode	Perilaku	Kasus penggunaan
`acceptEdits`	Auto-persetujuan pengeditan file dan perintah sistem file umum, meminta tindakan lain	Alur kerja pengembangan terpercaya
`plan`	Menjalankan alat hanya-baca; pengeditan file tidak pernah auto-disetujui dan mencapai callback `canUseTool` Anda	Menentukan cakupan tugas sebelum menyetujui eksekusi
`dontAsk`	Menolak apa pun yang tidak ada di `allowedTools`	Agen headless terkunci
`auto` (TypeScript only)	Pengklasifikasi model menyetujui atau menolak setiap panggilan alat	Agen otonom dengan penjaga keamanan
`bypassPermissions`	Menjalankan setiap alat tanpa prompt, kecuali aturan `ask` eksplisit cocok	CI sandboxed, lingkungan yang sepenuhnya terpercaya
`default`	Memerlukan callback `canUseTool` untuk menangani persetujuan	Alur persetujuan kustom

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

agent-sdk/quickstart.md +36 −23

41 Instal paket Agent SDK untuk bahasa Anda:41 Instal paket Agent SDK untuk bahasa Anda:

42 42

43 <Tabs>43 <Tabs>

~~44 <Tab title="TypeScript">~~44 <Tab title="TypeScript (proyek baru)">

45 ```bash theme={null}45 ```bash theme={null}

46 npm init -y

47 npm pkg set type=module

46 npm install @anthropic-ai/claude-agent-sdk48 npm install @anthropic-ai/claude-agent-sdk

49 npm install --save-dev tsx

47 ```50 ```

52 Mengatur `"type": "module"` di `package.json` memungkinkan skrip agen Anda menggunakan `await` tingkat atas, dan [tsx](https://tsx.is) menjalankan file TypeScript secara langsung.

53 </Tab>

55 <Tab title="TypeScript (proyek yang ada)">

56 ```bash theme={null}

57 npm install @anthropic-ai/claude-agent-sdk

58 npm install --save-dev tsx

59 ```

61 [tsx](https://tsx.is) menjalankan file TypeScript secara langsung. Jika proyek Anda menggunakan CommonJS, beri nama skrip agen Anda `agent.mts` alih-alih `agent.ts`. Ekstensi `.mts` membuat tsx memperlakukan file sebagai modul ES, sehingga `await` tingkat atas berfungsi tanpa mengonversi seluruh proyek Anda ke modul ES. Gunakan `agent.mts` sebagai pengganti `agent.ts` dalam langkah buat dan jalankan nanti dalam panduan cepat ini.

48 </Tab>62 </Tab>

49 63

50 <Tab title="Python (uv)">64 <Tab title="Python (uv)">

85 </Step>99 </Step>

86 100

87 <Step title="Atur kunci API Anda">101 <Step title="Atur kunci API Anda">

~~88 Dapatkan kunci API dari [Claude Console](https://platform.claude.com/), kemudian buat file `.env` di direktori proyek Anda:~~102 Dapatkan kunci API dari [Claude Console](https://platform.claude.com/), kemudian atur sebagai variabel lingkungan di shell tempat Anda akan menjalankan agen Anda:

89 103

104 <Tabs>

105 <Tab title="macOS / Linux">

90 ```bash theme={null}106 ```bash theme={null}

~~91 ANTHROPIC_API_KEY=your-api-key~~107 export ANTHROPIC_API_KEY=your-api-key

92 ```108 ```

109 </Tab>

110

111 <Tab title="Windows (PowerShell)">

112 ```powershell theme={null}

113 $env:ANTHROPIC_API_KEY = "your-api-key"

114 ```

115 </Tab>

116 </Tabs>

117

118 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.

93 119

94 SDK juga mendukung autentikasi melalui penyedia API pihak ketiga:120 SDK juga mendukung autentikasi melalui penyedia API pihak ketiga:

95 121

133 Bangun agen yang menemukan dan memperbaiki bug159 Bangun agen yang menemukan dan memperbaiki bug

134</h2>160</h2>

135 161

136Buat `agent.py` jika Anda menggunakan Python SDK, atau `agent.ts` untuk TypeScript:162Buat `agent.py` jika Anda menggunakan Python SDK, atau `agent.ts` untuk TypeScript. Gunakan `agent.mts` sebagai gantinya jika proyek yang ada Anda menggunakan CommonJS:

137 163

138<CodeGroup>164<CodeGroup>

139 ```python Python theme={null}165 ```python Python theme={null}

218 ```bash theme={null}244 ```bash theme={null}

219 npx tsx agent.ts245 npx tsx agent.ts

220 ```246 ```

247

248 Jika Anda memberi nama skrip Anda `agent.mts`, jalankan `npx tsx agent.mts` sebagai gantinya.

221 </Tab>249 </Tab>

222 250

223 <Tab title="Python (uv)">251 <Tab title="Python (uv)">

235 </Tab>263 </Tab>

236</Tabs>264</Tabs>

237 265

238Setelah menjalankan, periksa `utils.py`. Anda akan melihat kode defensif yang menangani daftar kosong dan pengguna null. Agen Anda secara mandiri:266Saat 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:

239 267

2401. **Membaca** `utils.py` untuk memahami kode2681. **Membaca** `utils.py` untuk memahami kode

2412. **Menganalisis** logika dan mengidentifikasi kasus tepi yang akan mogok2692. **Menganalisis** logika dan mengidentifikasi kasus tepi yang akan mogok

244Inilah yang membuat Agent SDK berbeda: Claude menjalankan alat secara langsung alih-alih meminta Anda untuk mengimplementasikannya.272Inilah yang membuat Agent SDK berbeda: Claude menjalankan alat secara langsung alih-alih meminta Anda untuk mengimplementasikannya.

245 273

246<Note>274<Note>

247 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](/id/troubleshooting) untuk bantuan lebih lanjut.275 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](/id/troubleshooting) untuk bantuan lebih lanjut.

248</Note>276</Note>

249 277

250<h3 id="try-other-prompts">278<h3 id="try-other-prompts">

340**Permission modes** mengontrol berapa banyak pengawasan manusia yang Anda inginkan:368**Permission modes** mengontrol berapa banyak pengawasan manusia yang Anda inginkan:

341 369

343| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |371| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |

373| `plan` | Menjalankan alat hanya-baca; pengeditan file tidak pernah auto-disetujui dan mencapai callback `canUseTool` Anda | Menentukan cakupan tugas sebelum menyetujui eksekusi |

347| `bypassPermissions` | Menjalankan setiap alat tanpa prompt, kecuali aturan [`ask`](/id/agent-sdk/permissions#how-permissions-are-evaluated) eksplisit cocok | CI sandboxed, lingkungan yang sepenuhnya terpercaya |376| `bypassPermissions` | Menjalankan setiap alat tanpa prompt, kecuali aturan [`ask`](/id/agent-sdk/permissions#how-permissions-are-evaluated) eksplisit cocok | CI sandboxed, lingkungan yang sepenuhnya terpercaya |

349 378

350Contoh 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`](/id/agent-sdk/user-input) yang mengumpulkan input pengguna. Untuk kontrol lebih lanjut, lihat [Permissions](/id/agent-sdk/permissions).379Contoh 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`](/id/agent-sdk/user-input) yang mengumpulkan input pengguna. Untuk kontrol lebih lanjut, lihat [Permissions](/id/agent-sdk/permissions).

351 380

352<h2 id="troubleshooting">

353 Pemecahan masalah

354</h2>

~~355~~

356<h3 id="api-error-thinking-type-enabled-is-not-supported-for-this-model">

357 Kesalahan API `thinking.type.enabled` tidak didukung untuk model ini

358</h3>

~~359~~

360Claude Opus 4.7 menggantikan `thinking.type.enabled` dengan `thinking.type.adaptive`. Versi Agent SDK yang lebih lama gagal dengan kesalahan API berikut ketika Anda memilih `claude-opus-4-7`:

~~361~~

362```text theme={null}

363API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}

364```

~~365~~

366Tingkatkan ke Agent SDK v0.2.111 atau lebih baru untuk menggunakan Opus 4.7.

~~367~~

368<h2 id="next-steps">381<h2 id="next-steps">

369 Langkah berikutnya382 Langkah berikutnya

370</h2>383</h2>

agent-sdk/quickstart.md 2026-06-29 23:02 UTC to 2026-06-30 23:02 UTC

Panduan Cepat

Prasyarat

Penyiapan

Buat folder proyek

Instal SDK

Atur kunci API Anda

Buat file dengan bug

Bangun agen yang menemukan dan memperbaiki bug

Jalankan agen Anda

Coba prompt lain

Sesuaikan agen Anda

Konsep kunci

Langkah berikutnya