Cara Membangun Claude Managed Agents dengan Claude Sonnet 5

Pernahkah Anda ingin menjalankan alur kerja ala Claude Code dari skrip Python, di mana model dapat bekerja di lingkungan terkelola dengan akses ke tools, file, skills, dan instruksi?

Claude Managed Agents dirancang untuk jenis alur kerja ini, membantu Anda membangun agen yang dapat menjalankan tugas multi-langkah dalam lingkungan yang terkontrol.

Dalam tutorial ini, saya akan menunjukkan cara menggunakan Claude Sonnet 5, model terbaru dari Anthropic yang dirancang untuk tugas penalaran tingkat lanjut, pengkodean, dan analisis data. Model ini mendukung kemampuan agen untuk memeriksa data, menggunakan tools, menulis dan mengeksekusi kode, serta menghasilkan output terstruktur.

Anda akan membuat Managed Agent, mengonfigurasi lingkungannya, mengunggah file CSV, dan memberi agen akses ke tools serta sebuah skill XLSX. 

Agen akan menganalisis data, menghasilkan file Python, JSON, dan Excel, memverifikasi hasilnya, serta menyediakan output yang sudah selesai untuk diunduh.

Jika Anda benar-benar baru dengan Claude, saya sarankan memeriksa terlebih dahulu kursus Claude Code 101.

Apa Itu Claude Managed Agents?

Claude Managed Agents adalah kerangka terkelola dari Anthropic untuk menjalankan Claude sebagai agen otonom. 

Alih-alih menulis loop sendiri untuk mengirim prompt, mengeksekusi panggilan tool, menyimpan hasil, dan mengelola runtime, Anda mendefinisikan agen dan membiarkan Anthropic menangani infrastrukturnya. 

Kerangka ini dirancang untuk tugas yang lebih panjang dan multi-langkah, di mana model mungkin perlu menggunakan beberapa tool sebelum menyelesaikan pekerjaan.

Managed Agents dibangun dengan empat bagian utama:

• Agent: konfigurasi yang dapat digunakan kembali yang berisi model, prompt sistem, tools, server MCP, dan skills.
• Environment: tempat agen berjalan, baik di cloud sandbox Anthropic maupun sandbox self-hosted Anda.
• Session: instance agen yang sedang berjalan untuk menjalankan tugas tertentu.
• Events: pesan, panggilan tool, hasil, dan pembaruan status yang dipertukarkan selama sesi berjalan.

1. Prasyarat untuk Workspace Claude Agent Anda

Untuk mengikuti tutorial ini, instal Python 3.12 atau lebih baru dan Jupyter Notebook di komputer Anda. Kita akan menggunakan Jupyter Notebook untuk membuat, menjalankan, dan memeriksa Managed Agent langkah demi langkah.

Anda juga memerlukan akun Anthropic Console. 

Buat kunci API baru di Console, tambahkan setidaknya $5 kredit API, dan simpan kunci tersebut dengan aman. 

Managed Agents dapat melakukan beberapa panggilan model dan tool dalam satu sesi, sehingga biayanya mungkin lebih tinggi dibanding permintaan API standar.

Simpan kunci tersebut sebagai variabel lingkungan ANTHROPIC_API_KEY alih-alih menambahkannya langsung ke notebook atau melakukan commit ke GitHub.

Untuk macOS, Linux, atau WSL, jalankan perintah ini di terminal Anda:

export ANTHROPIC_API_KEY="your-api-key-here"

Untuk Windows PowerShell, gunakan:

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

2. Menyiapkan Anthropic Python SDK

Sebelum membuat Managed Agent, instal Anthropic Python SDK resmi dan impor modul yang diperlukan untuk notebook ini. 

SDK menyediakan klien Anthropic, yang akan Anda gunakan untuk membuat agen, environment, file, dan sesi. 

%pip install -q --upgrade anthropic

Selanjutnya, muat kunci API Anthropic Anda dari variabel lingkungan. 

Menyimpan kunci di luar notebook lebih aman daripada menempatkannya langsung di kode, terutama jika Anda berencana membagikan proyek atau mendorongnya ke GitHub.

import os
from anthropic import Anthropic

api_key = os.environ.get("ANTHROPIC_API_KEY")
assert api_key, "Set ANTHROPIC_API_KEY in your environment or in a local .env file."

Managed Agents saat ini diakses melalui API beta Anthropic. Flag beta managed-agents-2026-04-01 mengaktifkan fitur ini, meskipun SDK resmi secara otomatis mengirim header beta yang diperlukan untuk permintaan Managed Agents. 

Kita menyimpan flag tersebut di notebook karena nanti dibutuhkan saat membuat daftar dan mengunduh file sesi. 

BETA_FLAG = "managed-agents-2026-04-01"

client = Anthropic(api_key=api_key)

Terakhir, buat kamus untuk menyimpan ID setiap resource yang dibuat selama tutorial. 

Ini mencakup agen, environment, file yang diunggah, dan sesi. Menyimpan ID ini memudahkan pembersihan di akhir, bahkan jika langkah selanjutnya gagal.

created = {"agent": None, "environment": None, "file": None, "session": None}
print("✓ Anthropic client initialized.")

Klien sekarang siap. 

3. Membuat Managed Agent

Managed Agent adalah konfigurasi yang dapat digunakan kembali untuk alur kerja Anda. 

Saat membuatnya, Anda memilih model Claude, menulis prompt sistem yang mendefinisikan peran dan instruksinya, serta melampirkan tools dan skills yang dapat digunakannya. 

Anda kemudian dapat menggunakan kembali agen yang sama di banyak sesi alih-alih membuat ulang konfigurasinya setiap kali. 

Kita akan menamai agen kita Sonnet 5 Data Analyst dan menggunakan claude-sonnet-5. 

Prompt sistem menginstruksikannya untuk berperilaku seperti analis data yang teliti: memeriksa file yang dipasang di /workspace, menggunakan eksekusi kode untuk analisis, menyajikan hasil secara ringkas, dan menyimpan file akhir ke /mnt/session/outputs.

agent = client.beta.agents.create(
    name="Sonnet 5 Data Analyst",
    model="claude-sonnet-5",
    system=(
        "You are a meticulous data analyst. When asked about data, always read the "
        "file mounted at /workspace, analyse it with the code execution tool, and "
        "report concise, numeric results. Use the XLSX skill for spreadsheet work. "
        "Save final artifacts to /mnt/session/outputs."
    ),
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
    skills=[{"type": "anthropic", "skill_id": "xlsx"}],
)

agent_toolset_20260401 memberi agen akses ke tools bawaan Anthropic dalam sebuah sesi, sementara skill xlsx menyediakan panduan tugas khusus untuk membuat dan menganalisis workbook Excel. 

Anthropic juga menyediakan skill siap pakai untuk alur kerja PowerPoint, Word, dan PDF.

Terakhir, simpan ID agen. 

Anda akan menggunakannya saat membuat sesi nanti, dan ini juga memungkinkan bagian pembersihan untuk mengarsipkan agen setelah tutorial selesai.

created["agent"] = agent.id
print(f"✓ Created agent: {agent.id}")

Anda akan melihat output serupa dengan:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Konfigurasi Anthropic Cloud Sandbox

Selanjutnya, kita akan membuat environment tempat Managed Agent berjalan selama sesi. 

Environment bertindak sebagai sandbox yang aman, memberikan agen ruang kerja terpisah untuk membaca file yang dipasang, menulis kode, dan menjalankan perintah.

Kita akan menggunakan environment cloud Anthropic dengan jaringan terbatas. Agen akan menggunakan sandbox ini nanti untuk menganalisis file CSV yang diunggah menggunakan Python.

environment = client.beta.environments.create(
    name="code-exec-sandbox",
    config={"type": "cloud", "networking": {"type": "limited"}},
)

created["environment"] = environment.id
print(f"✓ Created environment: {environment.id}")

Setelah menjalankan sel, Anda akan melihat ID environment serupa dengan:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Unggah Data dengan Anthropic Files API

Selanjutnya, kita akan mengunggah dataset yang akan dianalisis oleh agen. 

Managed Agents menggunakan Anthropic Files API untuk mengunggah file lokal, yang kemudian dapat dipasang di dalam environment sesi.

Untuk panduan ini, kita menggunakan dataset contoh 12 baris bernama sales_data.csv. 

Sebelum mengunggahnya, kita periksa bahwa file tersebut ada dan memastikan berisi jumlah baris data yang diharapkan.

from pathlib import Path

csv_path = Path("sales_data.csv")
assert csv_path.exists(), f"Missing input file: {csv_path.resolve()}"

row_count = sum(1 for _ in csv_path.open(encoding="utf-8")) - 1
assert row_count == 12, f"Expected 12 data rows, found {row_count}"

Kita lalu mengunggah file dan menyimpan ID-nya untuk pembersihan nanti.

uploaded = client.beta.files.upload(file=csv_path)

created["file"] = uploaded.id
print(f"✓ Uploaded {csv_path}: {uploaded.id} ({row_count} rows)")

Setelah menjalankan sel, Anda akan melihat output serupa dengan:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. Inisialisasi Session Eksekusi Agen

Sekarang, kita akan membuat sesi. 

Sesi menghubungkan agen, environment, dan resource yang dibutuhkan untuk tugas tertentu. Di sini, kita memasang file CSV yang diunggah di /workspace/sales_data.csv, sehingga agen dapat mengaksesnya dari dalam sandbox.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": uploaded.id,
            "mount_path": "/workspace/sales_data.csv",
        },
    ],
)

created["session"] = session.id
print(f"✓ Created session: {session.id}")

Anda akan melihat ID sesi serupa dengan:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. Streaming Respons Agen

Sekarang, kita akan mengirim tugas ke sesi dan melakukan streaming aktivitas agen saat bekerja. 

Membuat sesi hanya menyiapkan agen dan sandbox; agen mulai bekerja setelah menerima event user.message. 

Stream event memungkinkan kita melihat pesan agen, panggilan tool, dan status akhir sesi secara langsung. 

Prompt memberi tahu agen untuk menganalisis file CSV yang dipasang, menulis dan menjalankan skrip Python, membuat ringkasan JSON, dan membangun laporan Excel. 

Kita juga membuat tiga variabel untuk mengumpulkan teks agen, mencatat tools yang digunakan, dan memastikan apakah sesi selesai dengan sukses.

agent_text_parts = []
tools_used = []
final_status = None

with client.beta.sessions.events.stream(session.id) as stream:
    # Send the user message once the stream is open.
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": (
                            "Use the XLSX skill and analyze /workspace/sales_data.csv. "
                            "Write /mnt/session/outputs/analyze_sales.py, run that Python "
                            "script, and have it create /mnt/session/outputs/summary.json. "
                            "Also create /mnt/session/outputs/sales_report.xlsx with the "
                            "source data, monthly profit, and a summary sheet."
                        ),
                    }
                ],
            }
        ],
    )

    for event in stream:
        etype = getattr(event, "type", None)

        if etype == "agent.message":
            for block in event.content:
                txt = getattr(block, "text", None)
                if txt:
                    print(txt, end="")
                    agent_text_parts.append(txt)

        elif etype == "agent.tool_use":
            name = getattr(event, "name", "<tool>")
            print(f"\n[tool_use] {name}")
            tools_used.append(name)

        elif etype == "session.status_idle":
            final_status = "idle"
            print("\n\n✓ Agent finished; session is idle.")
            break

        elif etype == "session.status_error":
            final_status = "error"
            print("\n✗ Session reported an error.")
            break

print("Tools used:", tools_used)

Selama proses berjalan, Anda akan melihat event tool seperti read, bash, write, dan edit. 

Ini menunjukkan bahwa agen sedang memeriksa instruksi dan file yang tersedia, menulis skrip analisis, menjalankannya di dalam sandbox, serta memperbaiki masalah yang ditemukannya.

Sesi menjadi idle saat agen tidak memiliki pekerjaan lebih lanjut. Dalam contoh ini, session.status_idle menunjukkan bahwa tugas telah selesai, jadi kita berhenti mendengarkan stream. 

Anthropic mengelola eksekusi untuk tools bawaannya di dalam sandbox; Anda hanya perlu menangani hasil tool sendiri saat menggunakan custom tools. 

8. Mengambil File yang Dihasilkan dan Riwayat Event

Setelah sesi selesai, kita dapat memeriksa riwayat event yang tersimpan dan mengunduh file yang dibuat oleh agen. 

Riwayat event menyediakan catatan lengkap sesi, termasuk permintaan model, panggilan tool, hasil tool, dan perubahan status.

history = client.beta.sessions.events.list(session.id, order="asc")

print("--- Session event history ---")
for event in history.data:
    print(event.type)

print(f"({len(history.data)} events total)")

Selanjutnya, kita membuat daftar file yang terlampir pada sesi dan mengunduh file yang ditandai dapat diunduh. File disimpan secara lokal dalam folder outputs.

import os

os.makedirs("outputs", exist_ok=True)

files = client.beta.files.list(scope_id=session.id, betas=[BETA_FLAG])
downloadable = [f for f in files.data if f.downloadable]

print(f"Found {len(downloadable)} downloadable file(s) for this session.")

downloaded_paths = []

for f in downloadable:
    try:
        content = client.beta.files.download(f.id, betas=[BETA_FLAG])
        local_path = os.path.join("outputs", f.filename)

        content.write_to_file(local_path)
        downloaded_paths.append(local_path)

        print(f"  downloaded {f.id} -> {local_path}")
    except Exception as exc:
        print(f"  skip {f.id}: {exc}")

Terakhir, kita periksa bahwa semua output yang diharapkan berhasil diunduh:

expected_outputs = {"analyze_sales.py", "summary.json", "sales_report.xlsx"}
downloaded_names = {os.path.basename(path) for path in downloaded_paths}

assert expected_outputs <= downloaded_names, (
    f"Missing expected outputs: {sorted(expected_outputs - downloaded_names)}"
)

Skrip Python, ringkasan JSON, dan laporan Excel yang dihasilkan kini tersedia di folder lokal outputs.

9. Menganalisis Output Python, JSON, dan Excel

Setelah agen menyelesaikan tugas, file yang dihasilkan diunduh ke direktori lokal outputs/. 

File-file ini menunjukkan bahwa agen melakukan lebih dari sekadar mengembalikan respons teks: agen menulis dan mengeksekusi kode, membuat data terstruktur, serta menghasilkan laporan spreadsheet yang dapat ditinjau secara mandiri.

Tangkapan layar di bawah menunjukkan tiga artefak yang dihasilkan.

File ini berisi kode analisis yang ditulis dan dieksekusi agen, membuat alur kerja dapat direproduksi dan mudah diperiksa.

File ini menyimpan hasil dalam format terstruktur yang dapat digunakan oleh dasbor, API, atau program lainnya.

File Excel ini menyajikan perhitungan bulanan secara visual, dengan pendapatan, biaya, laba, margin, total, dan bagan.

Untuk 12 baris dalam sales_data.csv, hasil yang telah diverifikasi adalah:

• Total pendapatan: $32.900
• Total biaya: $14.750
• Total laba: $18.150
• Rata-rata laba bulanan: $1.512,50
• Bulan terbaik: Desember ($2.550 laba)
• Bulan terburuk: Januari ($400 laba)

Workbook didorong oleh rumus alih-alih hanya mengandalkan nilai yang di-hardcode. 

Selama proses, agen membaca instruksi skill XLSX yang dilampirkan, membuat workbook, menghitung ulang dengan LibreOffice, memeriksa rumus, dan memperbaiki masalah referensi melingkar sebelum menyelesaikan tugas.

10. Membersihkan Resource Managed Agent API

Resource Managed Agent tetap tersedia hingga Anda menghapusnya, jadi penting untuk membersihkannya setelah tugas selesai. 

Resource aktif, terutama sesi dan environment yang berjalan, dapat terus menimbulkan biaya jika dibiarkan berjalan.

Sesi harus dalam keadaan idle sebelum dapat dihapus. 

Pada langkah terakhir ini, kita menghapus sesi, file yang diunggah, dan environment, lalu mengarsipkan agen. 

Setiap tindakan pembersihan dibungkus dalam fungsi pembantu agar satu penghapusan yang gagal tidak menghentikan penghapusan resource lainnya.

def safe(label, fn):
    try:
        fn()
        print(f"✓ deleted {label}")
    except Exception as exc:
        print(f"· could not delete {label}: {exc}")

if created["session"]:
    safe("session", lambda: client.beta.sessions.delete(created["session"]))

if created["file"]:
    safe("file", lambda: client.beta.files.delete(created["file"]))

if created["environment"]:
    safe("environment", lambda: client.beta.environments.delete(created["environment"]))

if created["agent"]:
    safe("agent (archived)", lambda: client.beta.agents.archive(created["agent"]))

print("\n🎉 Cleanup complete. The agent is archived; other resources were deleted.")

Anda akan melihat output serupa dengan:

✓ deleted session
✓ deleted file
✓ deleted environment
✓ deleted agent (archived)

🎉 Cleanup complete. The agent is archived; other resources were deleted.

Proyek lengkap, termasuk notebook, file CSV contoh, dan instruksi penyiapan, tersedia di GitHub. 

Anda dapat mengkloning repositori dan menjalankan ulang notebook untuk mereplikasi hasil dari panduan ini.

Pemikiran Akhir

Saya mendapati Claude Managed Agents mudah disiapkan dan digunakan. 

Anda membuat agen, memberinya tools, skills, dan sandbox yang dibutuhkan, lalu menjalankannya melalui sebuah sesi. 

Dari sana, agen dapat menangani alur kerja lengkap, seperti menulis kode, membuat file, memeriksa outputnya sendiri, dan mengembalikan hasil akhir.

Awalnya saya mencoba menggunakan Modal Sandbox karena saya menginginkan environment eksternal yang lebih fleksibel. 

Namun, penyiapannya menjadi terlalu kompleks untuk cakupan panduan ini, jadi saya memutuskan untuk memfokuskan proyek ini pada cloud sandbox terkelola milik Anthropic.

Kekurangan utama bagi saya adalah biaya. Saya menjalankan contoh ini dua kali menggunakan file CSV kecil dengan hanya 12 baris, dan biayanya sekitar $0,25. 

Dasbor menampilkan biaya di bawah model, tetapi saya tidak dapat menemukan rincian yang lebih detail. Untuk tugas perhitungan sederhana dan pembuatan spreadsheet, itu terasa mahal dibanding opsi open-source berbiaya lebih rendah.

Secara keseluruhan, proyek ini menunjukkan alur kerja Managed Agent lengkap: membuat agen, mengunggah file CSV, menjalankan Python di dalam sandbox terkelola, menghasilkan laporan JSON dan Excel, memverifikasi output, mengunduh file, dan membersihkan resource setelahnya.