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:

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

mkdir my-agent
cd my-agent

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

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

uv init
uv add claude-agent-sdk

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

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

export ANTHROPIC_API_KEY=your-api-key

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

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:

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:

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:

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.

Jalankan agen Anda

Agen Anda siap. Jalankan dengan perintah berikut:

npx tsx agent.ts

uv run agent.py

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:

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.

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"

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 Agent SDK berdasarkan pesan yang tepat yang Anda lihat