Claude Code Agent SDK: Panduan Lengkap untuk Developer (2026)

Agent SDK dari Anthropic mengubah Claude Code dari asisten terminal menjadi agen AI yang dapat diprogram dan diotomatisasi, yang bisa Anda sematkan ke alur kerja Anda sendiri. Panduan ini membahas semuanya: instalasi, agent loop, integrasi tools, server MCP, orkestrasi subagent, dan kekurangan kapabilitas yang perlu Anda lengkapi untuk penggunaan produksi.

Apa itu Claude Code Agent SDK?

Claude Code Agent SDK yang juga disebut Claude Agent SDK atau Claude Code SDK adalah library Python dan TypeScript dari Anthropic untuk membangun agen AI otonom yang ditenagai Claude. SDK ini membungkus agent loop, sistem tools, dan lingkungan eksekusi terisolasi yang sama seperti yang dipakai Claude Code sebagai CLI, lalu menyediakannya sebagai SDK yang bisa Anda panggil dari kode Anda sendiri.

SDK ini dirilis pada awal 2026 sebagai bagian dari dorongan Anthropic untuk membuat agen AI menjadi dapat diprogram, bukan sekadar interaktif.

Apa bedanya dengan memakai Claude API secara langsung

Jika saat ini Anda memakai Claude API dan menulis agent loop sendiri dengan penanganan tools manual, Agent SDK menggantikan ratusan baris boilerplate.

Instalasi dan setup

Prasyarat

• Python 3.10+ atau TypeScript/Node.js 20+
• API key Anthropic atau langganan Claude Code Pro/Max/Enterprise
• Claude Code CLI terpasang, karena SDK menggunakannya sebagai runtime

Langkah 1: Pasang Claude Code CLI

npm install -g @anthropic-ai/claude-code

Atau gunakan installer native dari claude.ai/download.

Langkah 2: Pasang Agent SDK

Python:

pip install claude-agent-sdk

TypeScript:

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

Langkah 3: Autentikasi

claude login

Ikuti alur OAuth. API key Anda disimpan secara lokal dan digunakan otomatis oleh SDK.

Agen pertama Anda: pencari bug

Berikut agen Python minimal yang memindai direktori untuk mencari bug:

from claude_agent_sdk import Agent, tool

@tool
def read_file(path: str) -> str:
    """Membaca file dan mengembalikan isinya."""
    with open(path, 'r') as f:
        return f.read()

@tool  
def list_files(directory: str = ".") -> list:
    """Mencantumkan semua file dalam sebuah direktori."""
    import os
    return os.listdir(directory)

agent = Agent(
    system_prompt="Anda adalah code reviewer. Temukan bug dan sarankan perbaikan.",
    tools=[read_file, list_files],
    model="claude-sonnet-4-20250514"
)

result = agent.run("Tinjau kode di ./src untuk masalah keamanan")
print(result.output)

Apa yang terjadi di balik layar

1. Agen menerima tugas dan membaca system prompt Anda
2. Agen memanggil list_files("./src") untuk menemukan basis kode
3. Agen memanggil read_file(path) untuk setiap file sumber
4. Agen menganalisis kode menggunakan penalaran Claude
5. Agen mengembalikan temuan dengan nomor baris dan saran perbaikan

SDK menangani seluruh loop itu — Anda tidak perlu menulis logika plan-act-observe sendiri.

Konsep inti

Agent loop

Tugas → Rencana → Panggilan tools → Observasi hasil → Rencanakan ulang → ... → Jawaban akhir

Setiap iterasi:

1. Claude memutuskan apa yang harus dilakukan berikutnya
2. Claude memanggil tools sesuai kebutuhan
3. Claude menerima output tools
4. Claude memutuskan apakah lanjut atau selesai

SDK mengelola batas jendela konteks secara otomatis melalui kompaksi, yaitu merangkum turn lama, dan delegasi ke subagent.

Tools dan decorator tool

Tools adalah fungsi yang Anda ekspos ke agen. SDK menyediakan beberapa tools bawaan:

# Operasi file bawaan, tersedia otomatis
agent = Agent(
    tools=["read", "write", "edit", "glob", "grep", "bash", "task"]
)

Tools kustom memakai decorator @tool:

from claude_agent_sdk import tool

@tool
def search_docs(query: str, max_results: int = 5) -> str:
    """Mencari dokumentasi internal untuk kueri tertentu."""
    # Implementasi pencarian Anda
    return results

agent = Agent(tools=[search_docs])

Subagent: pemrosesan paralel

Subagent memungkinkan Anda menyalakan instance Claude independen untuk pekerjaan paralel:

agent = Agent(
    system_prompt="Anda adalah tech lead yang meninjau basis kode.",
    tools=["task"]  # mengaktifkan pembuatan subagent
)

result = agent.run("""
    Tinjau ./frontend/ dan ./backend/ secara paralel.
    Gunakan subagent untuk tiap direktori, lalu gabungkan temuannya.
""")

Subagent berjalan dalam konteks terisolasi dan mengembalikan hasil secara independen. Begitulah Claude Code menangani operasi skala besar.

Integrasi server MCP

SDK mendukung server Model Context Protocol, yaitu layanan eksternal yang mengekspos tools ke agen Anda:

agent = Agent(
    mcp_servers=[
        {
            "command": "npx",
            "args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
            "env": {"ALLOWED_DIRECTORIES": "/project"}
        }
    ]
)

Server MCP dapat menambahkan akses database, integrasi API, layanan pihak ketiga, dan lainnya.

Apa yang tidak bisa dilakukan Agent SDK dan cara menutup celahnya

Claude Code Agent SDK memberi agen Anda akses file, eksekusi shell, dan manipulasi kode. Tetapi ada lima kekurangan kapabilitas utama:

1. Pembuatan gambar

Agen Anda bisa menulis kode yang memanggil API gambar, tetapi tidak bisa langsung membuat atau melihat gambar. Untuk agen yang membangun UI, membuat prototipe desain, atau menyiapkan dokumentasi, ini adalah keterbatasan nyata.

Solusi: Berikan runtime kapabilitas yang menangani pembuatan gambar. Dengan satu baris konfigurasi, agen Anda bisa membuat gambar dari teks, mengiterasi desain, dan menyematkan hasilnya.

2. Pembuatan video

Video bahkan lebih jauh lagi. Agen Anda bisa menulis perintah ffmpeg, tetapi tidak bisa membuat konten video baru.

3. Pencarian web dengan hasil yang didukung sumber

Agen Claude Code bisa memakai curl atau API fetch, tetapi tidak bisa melakukan pencarian web semantik dengan hasil yang didukung sumber dan sitasi. Ini penting untuk agen riset, agen konten, dan alur kerja yang memerlukan informasi terbaru.

4. Penyimpanan cloud dan berbagi file

Akses sistem file pada SDK hanya lokal. Untuk agen yang perlu menyimpan output, membagikan file ke manusia, atau mempertahankan data lintas sesi, Anda memerlukan penyimpanan cloud.

5. Publikasi dan deployment

Agen Anda membangun artefak, tetapi untuk membuatnya online — halaman web, laporan yang bisa dibagikan, atau aplikasi yang di-deploy — Anda memerlukan infrastruktur terpisah.

Solusi satu perintah

Daripada mengonfigurasi lima server MCP terpisah, masing-masing dengan API key, beban pemeliharaan, dan overhead token sendiri, Anda bisa memakai runtime kapabilitas — satu alat CLI yang menggabungkan pembuatan gambar, video, pencarian web, penyimpanan cloud, dan publikasi di balik satu endpoint.

Misalnya, AnyCap memberi agen lima kapabilitas dalam satu CLI — pembuatan gambar, video, pencarian web, penyimpanan cloud, dan publikasi halaman — sehingga Anda hanya butuh menit untuk menyiapkan, bukan jam.

Pertimbangan produksi

Manajemen jendela konteks

Agent SDK otomatis menangani kompaksi konteks, tetapi untuk agen yang berjalan lama, lebih dari 100 turn, sebaiknya:

• Gunakan subagent untuk tugas paralel besar, bukan proses berurutan
• Jaga system prompt tetap ringkas — setiap token di system prompt menjadi overhead di setiap turn
• Hindari memuat file besar ke konteks jika tools bisa mengembalikan ringkasan

Kontrol biaya

Sesi agen tipikal dengan SDK menghabiskan sekitar 0,50 hingga 3,00 dolar tergantung kompleksitas tugas. Untuk mengendalikan biaya:

• Tetapkan max_turns untuk mencegah loop tak berujung
• Gunakan Haiku untuk subagent sederhana dan Sonnet untuk agen utama
• Pantau penggunaan melalui dashboard konsol Anthropic

Keamanan

SDK menjalankan perintah di sandbox, tetapi Anda tetap perlu:

• Membatasi akses sistem file dengan ALLOWED_DIRECTORIES
• Jangan pernah memberi agen produksi akses ke kredensial atau file .env
• Tinjau aksi agen dalam mode non-interaktif

Claude Code SDK vs Claude Agent SDK: apa bedanya?

Istilah-istilah ini sering dipakai bergantian, tetapi ada perbedaannya:

Dalam praktiknya, kebanyakan developer memakai Agent SDK sebagai titik awal. API SDK tingkat rendah digunakan untuk kasus lanjutan seperti manajemen sesi kustom.

Kapan memakai Agent SDK dibanding Claude Code CLI

Aturan praktisnya sederhana: jika Anda mengetik perintah, pakai CLI. Jika Anda menulis kode yang perlu memanggil Claude, pakai SDK.

Ringkasan

Claude Code Agent SDK mengubah Claude dari teman terminal menjadi runtime agen yang dapat diprogram. Dengan operasi file bawaan, akses shell, orkestrasi subagent, dan dukungan server MCP, SDK ini menangani pekerjaan berat infrastruktur agen.

Namun agen yang hanya bisa membaca file dan menjalankan bash hanyalah separuh agen. Untuk membangun agen yang bisa mencari web, membuat gambar dan video, menyimpan output di cloud, dan memublikasikan hasil, Anda memerlukan lapisan kapabilitas. SDK memberi agen Anda otak; runtime kapabilitas seperti AnyCap memberi mata, tangan, dan suara.