Dulu, membuat aplikasi yang “bisa berpikir dan bertindak sendiri” berarti menulis banyak kode rumit: loop yang memanggil model AI berulang kali, kode untuk menjalankan alat, penyimpanan percakapan, sampai sistem izin. Sekarang sebagian besar pekerjaan itu sudah tersedia siap pakai dalam bentuk harness agent. Anda cukup menulis aplikasi tipis di atasnya: instruksi kerja, data bisnis, dan aturan keamanan.
Artikel ini memandu langkah demi langkah membuat satu aplikasi kecil di atas harness agent: Asisten Laporan Penjualan, yang membaca file penjualan, mengecek target lewat alat buatan sendiri, lalu menulis laporan. Contohnya memakai Claude Agent SDK dengan Python, tetapi pola pikirnya berlaku juga untuk harness lain.
Kalau istilah harness masih asing, baca dulu artikel kami: Mengenal Harness Agent. Singkatnya: Agen = Model + Harness. Model yang berpikir, harness yang menjalankan.
Ringkasan Singkat
| Hal | Keterangan |
|---|---|
| Yang dibuat | Aplikasi baris perintah “Asisten Laporan Penjualan” (sekitar 110 baris Python) |
| Harness yang dipakai | Claude Agent SDK, yaitu harness Claude Code yang dikemas sebagai library Python dan TypeScript |
| Syarat | Python 3.10 atau lebih baru, kunci API Anthropic |
| Yang Anda tulis sendiri | Instruksi kerja, satu alat khusus, aturan izin, batas putaran dan biaya |
| Yang disediakan harness | Loop agen, alat baca dan tulis file, manajemen konteks, sistem izin, catatan sesi |
| Status pengujian | Kode diperiksa terhadap SDK versi 0.2.184 dan dijalankan sampai tahap login (lihat bagian “Catatan Pengujian”) |
Gambaran Besarnya
Aplikasi di atas harness agent pada dasarnya terdiri dari tiga lapisan:
[Pengguna] --perintah--> [Aplikasi Anda]
- instruksi kerja
- data dan alat khusus bisnis
- aturan izin, batas biaya
|
v
[Harness agent (SDK)] <--> [Model AI]
- loop berpikir-bertindak
- alat bawaan (baca/tulis file, dll.)
- manajemen konteks
|
v
[Hasil: file laporan]
Yang membuat aplikasi Anda unik bukan modelnya, karena siapa pun bisa memakai model yang sama. Yang unik adalah tiga hal yang Anda tulis sendiri: instruksi yang sesuai proses bisnis, alat yang terhubung ke data Anda, dan pagar pengaman yang sesuai risiko Anda.
Pilihan Harness yang Bisa Dipakai
Beberapa penyedia AI kini merilis harness mereka sebagai SDK. Menurut Addy Osmani dalam tulisannya tentang harness engineering, Claude Agent SDK, Codex SDK, dan OpenAI Agents SDK sama-sama menyediakan loop, alat, manajemen konteks, hook, dan sandbox siap pakai yang tinggal Anda sesuaikan. Artikel ini memakai Claude Agent SDK karena dokumentasinya lengkap dan kami bisa memeriksa kodenya langsung terhadap paket yang terpasang.
Menurut dokumentasi resminya, Agent SDK memberi Anda alat, loop agen, dan manajemen konteks yang sama dengan yang menjalankan Claude Code, dan bisa diprogram dengan Python dan TypeScript. Bedanya dengan pilihan lain dari Anthropic:
| Pilihan | Cocok untuk |
|---|---|
| Agent SDK | Menanamkan agen Claude Code di aplikasi Python/TypeScript Anda sendiri, berjalan di server yang Anda kelola |
| Claude Code CLI | Pemakaian interaktif sehari-hari di terminal |
| Client SDK (Claude API) | Memanggil model langsung. Loop dan alat Anda tulis sendiri |
| Managed Agents | Agen yang loop dan sandbox-nya dijalankan Anthropic di cloud |
Langkah 1: Siapkan Proyek
Dokumentasi resmi mensyaratkan Python 3.10 ke atas. Buat folder proyek dan lingkungan virtual, lalu pasang SDK:
mkdir asisten-laporan
cd asisten-laporan
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
Paket ini sudah membawa program harness Claude Code di dalamnya, jadi umumnya Anda tidak perlu memasang Claude Code terpisah. Di Mac kami, paket versi 0.2.184 terpasang lengkap dengan binary bawaannya.
Langkah 2: Siapkan Kunci API
Ambil kunci API dari Claude Console (platform.claude.com), lalu pasang sebagai variabel lingkungan:
export ANTHROPIC_API_KEY=isi-kunci-anda
Dua hal penting dari dokumentasi resmi:
- SDK tidak membaca file
.envsecara otomatis. Kalau Anda menyimpan kunci di.env, muat sendiri, misalnya dengan paketpython-dotenv. - Aplikasi untuk orang lain wajib memakai kunci API, bukan login akun Claude pribadi. Anthropic menyatakan tidak mengizinkan pengembang pihak ketiga menawarkan login claude.ai atau memakai batas pemakaian langganan claude.ai di produk mereka tanpa persetujuan sebelumnya, termasuk agen yang dibangun dengan Agent SDK.
Selain kunci API langsung, SDK juga mendukung Amazon Bedrock, Google Cloud, Microsoft Foundry, dan Claude Platform on AWS lewat variabel lingkungan khusus. Rinciannya ada di dokumentasi quickstart.
Langkah 3: Siapkan Data Contoh
Buat folder kerja/ dan isi dengan file penjualan_oktober.csv. Data berikut fiktif, untuk latihan:
tanggal,produk,jumlah,harga_satuan
2026-10-01,Kopi Arabika 250g,12,85000
2026-10-01,Teh Melati 100g,5,25000
2026-10-03,Kopi Robusta 250g,20,60000
2026-10-05,Kopi Arabika 250g,9,85000
2026-10-08,Teh Melati 100g,14,25000
2026-10-10,Kopi Robusta 250g,31,60000
2026-10-12,Kopi Arabika 250g,15,85000
2026-10-15,Kopi Robusta 250g,18,60000
2026-10-17,Teh Melati 100g,9,25000
2026-10-20,Kopi Arabika 250g,22,85000
2026-10-22,Kopi Robusta 250g,27,60000
2026-10-24,Teh Melati 100g,11,25000
2026-10-27,Kopi Arabika 250g,18,85000
2026-10-29,Kopi Robusta 250g,24,60000
2026-10-31,Teh Melati 100g,16,25000
Langkah 4: Tulis Aplikasinya
Simpan kode berikut sebagai app_laporan.py di folder proyek (sejajar dengan folder kerja/):
"""Asisten Laporan Penjualan: contoh aplikasi sederhana di atas harness agent.
Cara pakai: python app_laporan.py penjualan_oktober.csv
"""
import asyncio
import sys
from pathlib import Path
from claude_agent_sdk import (
AssistantMessage,
ClaudeAgentOptions,
ClaudeSDKError,
ResultMessage,
TextBlock,
ToolUseBlock,
create_sdk_mcp_server,
query,
tool,
)
from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny
# 1. Folder kerja: agen hanya diarahkan bekerja di sini.
FOLDER = Path(__file__).parent.resolve() / "kerja"
FOLDER_LAPORAN = FOLDER / "laporan"
# 2. Data bisnis Anda sendiri. Di aplikasi nyata, ini bisa dari database.
TARGET_BULANAN = {
"Kopi Arabika 250g": 120,
"Kopi Robusta 250g": 150,
"Teh Melati 100g": 80,
}
# 3. Alat buatan sendiri yang bisa dipanggil agen.
@tool("target_bulanan", "Ambil target penjualan bulanan (unit) untuk satu produk", {"produk": str})
async def target_bulanan(args):
target = TARGET_BULANAN.get(args["produk"])
if target is None:
return {
"content": [{"type": "text", "text": f"Target untuk '{args['produk']}' tidak ditemukan."}],
"is_error": True,
}
return {"content": [{"type": "text", "text": f"Target {args['produk']}: {target} unit per bulan."}]}
toko = create_sdk_mcp_server(name="toko", tools=[target_bulanan])
# 4. Penjaga izin: agen hanya boleh MENULIS file .md di folder laporan/.
async def penjaga_izin(nama_alat, masukan, konteks):
if nama_alat == "Write":
tujuan = Path(masukan.get("file_path", ""))
if not tujuan.is_absolute():
tujuan = FOLDER / tujuan
tujuan = tujuan.resolve()
if tujuan.parent == FOLDER_LAPORAN and tujuan.suffix == ".md":
return PermissionResultAllow(updated_input=masukan)
return PermissionResultDeny(message="Hanya boleh menulis file .md di folder laporan/.")
return PermissionResultDeny(message=f"Alat {nama_alat} tidak diizinkan di aplikasi ini.")
# 5. Instruksi kerja (system prompt).
INSTRUKSI = """Anda adalah asisten laporan penjualan untuk sebuah toko kopi.
Tugas: baca file CSV penjualan yang diminta, hitung total unit dan omzet per produk,
bandingkan dengan target bulanan (pakai alat target_bulanan), lalu tulis laporan
singkat dalam Bahasa Indonesia ke folder laporan/ dengan format Markdown.
Laporan berisi: tabel per produk (unit, omzet, target, persen capaian),
total omzet, satu paragraf kesimpulan, dan dua saran yang realistis.
Tulis angka rupiah dengan format Rp1.234.567. Jangan mengarang data yang tidak ada di file."""
async def main(nama_file: str) -> None:
FOLDER_LAPORAN.mkdir(parents=True, exist_ok=True)
opsi = ClaudeAgentOptions(
cwd=str(FOLDER),
system_prompt=INSTRUKSI,
model="claude-opus-5-5",
tools=["Read", "Glob", "Write"], # hanya 3 alat bawaan ini yang tersedia
allowed_tools=["Read", "Glob", "mcp__toko__target_bulanan"], # boleh tanpa tanya
mcp_servers={"toko": toko},
can_use_tool=penjaga_izin, # Write diputuskan oleh penjaga_izin
max_turns=20, # batas putaran
max_budget_usd=0.50, # batas biaya per tugas
setting_sources=[], # jangan muat pengaturan Claude Code milik pengguna komputer
)
perintah = f"Buat laporan penjualan dari file {nama_file}. Simpan sebagai laporan/{Path(nama_file).stem}.md"
async for pesan in query(prompt=perintah, options=opsi):
if isinstance(pesan, AssistantMessage):
for blok in pesan.content:
if isinstance(blok, TextBlock) and blok.text.strip():
print(f"[agen] {blok.text.strip()}")
elif isinstance(blok, ToolUseBlock):
print(f"[alat] {blok.name} {blok.input}")
elif isinstance(pesan, ResultMessage):
biaya = f"${pesan.total_cost_usd:.4f}" if pesan.total_cost_usd is not None else "-"
status = "GAGAL" if pesan.is_error else "selesai"
print(f"\nStatus: {status} | putaran: {pesan.num_turns} | biaya: {biaya}")
if pesan.result:
print(pesan.result)
if __name__ == "__main__":
if len(sys.argv) != 2:
sys.exit("Pakai: python app_laporan.py <nama_file.csv>")
try:
asyncio.run(main(sys.argv[1]))
except ClaudeSDKError as e:
sys.exit(f"Gagal menjalankan agen: {e}")
Penjelasan Kode, Bagian demi Bagian
Bagian 1 dan 2: folder kerja dan data bisnis
FOLDER menjadi direktori kerja agen lewat opsi cwd. TARGET_BULANAN mewakili data bisnis Anda. Di aplikasi sungguhan, data ini bisa diambil dari database, spreadsheet, atau sistem kasir.
Bagian 3: alat buatan sendiri
Inilah cara aplikasi Anda menyambungkan agen ke data milik Anda. Dekorator @tool menerima tiga hal: nama alat, deskripsi (dibaca oleh model untuk memutuskan kapan memakainya), dan skema masukan. Fungsi create_sdk_mcp_server membungkus alat-alat itu menjadi server MCP yang berjalan di dalam aplikasi Anda sendiri.
Perhatikan cara penamaan saat alat didaftarkan: server dipasang dengan kunci "toko" di mcp_servers, sehingga alat target_bulanan dipanggil dengan nama mcp__toko__target_bulanan. Pola ini sesuai contoh di dokumentasi resmi. Kalau produk tidak ditemukan, alat mengembalikan "is_error": True supaya model tahu ada yang salah, bukan mengarang angka.
Bagian 4: penjaga izin
Ini bagian terpenting untuk keamanan. Fungsi penjaga_izin dipanggil setiap kali agen ingin memakai alat yang tidak otomatis diizinkan. Di contoh ini, agen hanya boleh menulis file berakhiran .md di dalam folder laporan/. Permintaan menulis ke tempat lain ditolak dengan pesan yang bisa dibaca model.
Ada jebakan yang perlu dipahami. Menurut dokumentasi SDK, can_use_tool tidak dipanggil untuk alat yang sudah tercantum di allowed_tools. Karena itu Write sengaja tidak dimasukkan ke allowed_tools, supaya setiap penulisan file melewati penjaga izin.
Bagian 5: instruksi kerja
System prompt berisi peran, tugas, format hasil, dan larangan (“jangan mengarang data”). Instruksi yang jelas dan spesifik adalah salah satu pengungkit kualitas terbesar di harness. Tulis seperti Anda memberi arahan kepada karyawan baru.
Opsi harness: pagar-pagar pengaman
| Opsi | Fungsinya di aplikasi ini |
|---|---|
tools |
Membatasi alat bawaan yang tersedia hanya Read, Glob, dan Write. Agen tidak bisa menjalankan perintah terminal karena Bash tidak tersedia |
allowed_tools |
Alat yang boleh dipakai tanpa bertanya. Menurut dokumentasi, opsi ini tidak membatasi alat. Yang membatasi adalah tools |
can_use_tool |
Penjaga izin untuk alat di luar allowed_tools |
max_turns |
Batas jumlah putaran agen supaya tidak berputar tanpa akhir |
max_budget_usd |
Menghentikan tugas ketika perkiraan biaya mencapai angka ini. Dokumentasi mengingatkan perkiraannya bisa sedikit melewati batas, jadi beri ruang |
setting_sources=[] |
Mencegah SDK memuat pengaturan Claude Code milik pengguna komputer (seperti file CLAUDE.md atau pengaturan di folder ~/.claude), supaya perilaku aplikasi sama di komputer mana pun |
model |
Model yang dipakai. Bisa diganti sesuai kebutuhan biaya dan kualitas |
Membaca hasil
Fungsi query() mengembalikan aliran pesan selama agen bekerja. AssistantMessage berisi teks penjelasan agen (TextBlock) dan permintaan memakai alat (ToolUseBlock). Di akhir, ResultMessage membawa status (is_error), jumlah putaran (num_turns), perkiraan biaya (total_cost_usd), dan teks jawaban akhir (result).
Langkah 5: Jalankan
python app_laporan.py penjualan_oktober.csv
Bila berjalan normal, alur kerjanya sesuai yang dirancang: agen membaca file CSV dengan alat Read, memanggil mcp__toko__target_bulanan untuk setiap produk, lalu meminta izin Write untuk menyimpan laporan/penjualan_oktober.md. Setiap langkah tercetak di terminal dengan awalan [alat] atau [agen], diakhiri baris status, jumlah putaran, dan biaya.
Kalau kunci API belum dipasang, aplikasi berhenti dengan pesan seperti ini. Inilah keluaran asli dari pengujian kami:
Status: GAGAL | putaran: 1 | biaya: $0.0000
Not logged in · Please run /login
Gagal menjalankan agen: Claude Code returned an error result: Not logged in · Please run /login (exit code: 1)
Pesan “Not logged in” berarti variabel ANTHROPIC_API_KEY belum terbaca di terminal tempat aplikasi dijalankan.
Catatan Pengujian
Kami ingin jujur soal batas pengujian artikel ini:
- Yang sudah diuji: SDK
claude-agent-sdkversi 0.2.184 terpasang di Python 3.10 (macOS). Semua nama fungsi, kelas, dan opsi yang dipakai dicocokkan dengan paket yang terpasang. Aplikasi dijalankan: SDK menerima semua opsi, server alat buatan sendiri terdaftar, harness menyala, lalu berhenti di tahap login karena mesin uji kami belum memiliki kunci API Anthropic. - Yang belum diuji: putaran penuh dengan model sungguhan, yaitu isi laporan yang dihasilkan, jumlah putaran, dan biayanya. Karena itu kami tidak menampilkan contoh laporan atau angka biaya, supaya tidak menyajikan hasil yang tidak pernah kami lihat sendiri.
Bila Anda mencobanya dan menemukan perilaku berbeda, beri tahu kami lewat halaman Feedback.
Mengembangkan Jadi Aplikasi Sungguhan
Ganti antarmuka
Fungsi main() bisa dipanggil dari mana saja: tombol di halaman web (misalnya dengan Flask atau FastAPI), bot Telegram atau WhatsApp, atau penjadwal yang berjalan tiap awal bulan. Inti aplikasinya tetap sama.
Tambah alat sesuai bisnis
Contoh alat yang berguna untuk usaha di Indonesia: cek stok dari sistem kasir, ambil pesanan dari WooCommerce, buat draf invoice, atau kirim ringkasan ke grup Telegram. Ingat saran Osmani: sepuluh alat yang fokus lebih baik daripada lima puluh alat yang tumpang tindih.
Pakai hook untuk aturan yang tidak boleh dilanggar
SDK mendukung hook, yaitu kode yang berjalan otomatis pada momen tertentu dalam siklus agen, misalnya sebelum alat dipakai. Hook cocok untuk aturan mutlak seperti “selalu catat setiap file yang diubah” atau “tolak perintah yang menghapus data”.
Jalankan di lingkungan terisolasi
Dalam contoh ini, penjaga izin hanya mengatur penulisan file. Alat Read diizinkan otomatis, sehingga secara teknis agen masih bisa membaca file di luar folder kerja bila memintanya. Untuk aplikasi yang dipakai orang lain, jalankan agen di dalam container (misalnya Docker) yang hanya berisi folder yang memang boleh dibaca. Dokumentasi SDK punya panduan hosting tersendiri untuk Docker, cloud, dan CI/CD.
Hal yang Wajib Diperhatikan Sebelum Dipakai Orang Lain
- Ketentuan layanan. Menurut dokumentasi resmi, pemakaian Claude Agent SDK, termasuk untuk produk yang Anda tawarkan ke pelanggan, tunduk pada Commercial Terms of Service Anthropic.
- Merek. Pedoman merek Anthropic membolehkan sebutan seperti “Claude Agent” atau “NamaAgenAnda Powered by Claude”, tetapi tidak membolehkan menyebut produk Anda “Claude Code” atau “Claude Code Agent”, maupun memakai tampilan yang meniru Claude Code.
- Biaya per tugas tidak tetap. Agen bisa mengambil sedikit atau banyak langkah. Selalu pasang
max_turnsdanmax_budget_usd, dan pantautotal_cost_usddari setiap tugas. - Hasil perlu dicek. Untuk perhitungan yang harus 100% tepat, seperti pajak atau gaji, lebih aman menghitungnya dengan kode biasa lalu menyerahkan angkanya ke agen untuk dijelaskan. Agen paling berguna untuk bagian yang memang butuh “berpikir”, seperti merangkum, menafsirkan, dan menyusun kalimat.
- Waspadai instruksi tersembunyi. Dokumen, email, atau halaman web yang diproses agen bisa berisi teks yang mencoba memerintah agen (prompt injection). Pagar izin dan pembatasan alat adalah pertahanan utamanya.
Analisis Redaksi
Analisis redaksi. Harness agent menurunkan biaya awal membuat aplikasi AI secara drastis. Tim kecil atau bahkan satu orang kini bisa membuat asisten yang bekerja dengan file dan data bisnis tanpa membangun mesin agen dari nol. Bagi pelaku usaha dan penyedia jasa IT di Indonesia, peluangnya ada pada lapisan tipis yang Anda tulis sendiri: instruksi yang paham proses bisnis lokal, alat yang terhubung ke sistem yang dipakai sehari-hari, dan pagar pengaman yang sesuai kebutuhan klien.
Saran kami: mulai dari satu tugas kecil yang sering diulang dan hasilnya mudah dicek, seperti contoh laporan penjualan ini. Ukur biaya dan ketepatannya, baru kembangkan.
Tinggalkan Komentar & Diskusi