Agen pertama yang hanya membaca

Agen pertamamu sebaiknya hanya bisa membaca. Menulis tidak sulit, tetapi agen baca-saja memberimu semua pelajaran penting dengan risiko paling kecil: kamu belajar menulis tujuan, melihat bagaimana model memilih alat, membaca jejaknya, dan menghitung biayanya, tanpa ada yang bisa rusak.

Tugas yang cocok untuk agen baca-saja pertama: menyusun daftar keputusan dari setumpuk notulen, mencari semua tempat sebuah istilah dipakai di dokumen proyek, atau menjelaskan bagaimana sebuah folder kode tersusun. Semuanya butuh beberapa putaran, karena agen harus mencari, membuka, lalu membaca berkas sesuai temuannya. Karena itu tugas ini cocok untuk agen; satu prompt (perintah atau instruksi yang kamu tulis untuk AI) tidak cukup.

Untuk agen baca-saja, alat yang diberikan cukup tiga jenis: mencari berkas menurut nama, mencari teks di dalam berkas, dan membaca isi berkas. Tidak ada alat untuk menulis, menjalankan perintah, membuka internet, atau memulai subagen (subagent), yaitu agen kedua yang dipanggil agen utama. Setiap alat tambahan adalah kemampuan tambahan yang harus kamu awasi, jadi jangan berikan sebelum ada alasan.

Tempatkan agen di sandbox (lingkungan terisolasi) dari bab dua: folder berisi salinan dokumen, di mesin atau kontainer (container) yang tidak menyimpan berkas rahasia. Ingat, agen baca-saja tetap bisa membocorkan: apa pun yang ia baca masuk ke konteks, tercatat di jejak, dan dikirim ke penyedia model. Kalau di folder itu ada berkas berisi kunci atau kata sandi, membaca saja sudah cukup untuk membuatnya tersebar.

Batas dipasang sejak percobaan pertama, bukan setelah ada masalah. Ada tiga batas yang berbeda, dan ketiganya perlu:

• Batas putaran: jumlah maksimum siklus model memilih alat dan membaca hasilnya. Untuk tugas meringkas satu folder kecil, sepuluh sampai lima belas putaran biasanya cukup. Kalau batasnya tercapai, itu tanda tujuan kurang jelas atau tugasnya terlalu besar, bukan alasan menaikkan batas.
• Batas anggaran: biaya maksimum satu tugas dalam mata uang. Ini melindungimu dari putaran yang terus membaca berkas besar.
• Batas keluaran: jumlah token (potongan kata yang dihitung dan dibaca model) maksimum yang boleh ditulis model dalam satu jawaban. Jangan terlalu kecil: model penalaran (reasoning model) memakai sebagian anggaran ini untuk berpikir, dan batas yang terlalu ketat bisa menghasilkan jawaban kosong.

Selain batas, tetapkan tujuan yang bisa diperiksa dan bentuk hasil sebelum menjalankan: misalnya "daftar keputusan, satu baris per keputusan, dengan nama berkas sumbernya". Bentuk yang menyebut sumber membuatmu bisa mengecek setiap baris ke berkasnya. Tanpa itu, kamu hanya bisa percaya.

Sebagai contoh yang dikerjakan, ini agen baca-saja dengan Claude Agent SDK untuk Python (paket claude-agent-sdk). Opsi tools hanya menyediakan tiga alat baca bawaan, allowed_tools membiarkan ketiganya berjalan tanpa bertanya, dan permission_mode="dontAsk" menolak panggilan lain yang seharusnya bertanya. Tanpa tools, dontAsk saja masih meloloskan panggilan yang tidak butuh persetujuan, seperti perintah shell baca-saja dan memulai subagen. Opsi max_turns dan max_budget_usd memasang batas putaran dan anggaran, dan cwd menentukan folder kerjanya:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    options = ClaudeAgentOptions(
        tools=["Read", "Glob", "Grep"],
        allowed_tools=["Read", "Glob", "Grep"],
        permission_mode="dontAsk",
        max_turns=12,
        max_budget_usd=0.50,
        cwd="salinan-notulen",
    )
    tugas = "Saya perlu daftar keputusan dari notulen di folder ini, dengan nama berkas sumber tiap keputusan."
    async for message in query(prompt=tugas, options=options):
        if isinstance(message, ResultMessage):
            print(message.result)
            print("biaya", message.total_cost_usd, "putaran", message.num_turns)

asyncio.run(main())

Pesan terakhir dari query() adalah ResultMessage yang memuat hasil akhir, perkiraan biaya, dan jumlah putaran. Folder kerja bukan tembok: jalankan contoh ini di mesin atau kontainer yang hanya berisi salinan dokumen. Langkah khusus Anthropic; cek versi terbaru di dokumentasinya karena nama opsi bisa berubah.